python-gsmmodem-new

python-gsmmodem-new

GSM modem module for Python

python-gsmmodem is a module that allows easy control of a GSM modem attached to the system. It also includes a couple of useful commandline utilities for interacting with a GSM modem.

Its features include:

• simple methods for sending SMS messages, checking signal level, etc
• easy-to-use API for starting and responding to USSD sessions and making voice calls
• handling incoming phone calls and received SMS messages via callback methods
• support for SMS PDU and text mode
• support for tracking SMS status reports
• wraps AT command errors into Python exceptions by default
• modular design; you easily issue your own AT commands to the modem (with error checking), or read/write directly from/to the modem if you prefer
• comprehensive test suite

Bundled utilities:

• GSMTerm: an easy-to-use serial terminal for communicating with an attached GSM modem. It features command completion, built-in help for many AT commands, history, context-aware prompt, etc.
• sendsms.py: a simple command line script to send SMS messages
• identify-modem.py: simple utility to identify attached modem. Can also be used to provide debug information used for development of python-gsmmodem.

How to use this package

Go to examples/ directory in this repo.

Requirements

• Python 3.3 or later
• pySerial

How to install this package

There are multiple ways to install python-gsmmodem-new package:

Automatic installation of the latest "stable" release from PyPI

::

    pip install python-gsmmodem-new

`pip <http://www.pip-installer.org>`_ will automatically download and install
all dependencies, as required. You can also utilise ``easy_install`` in the
same manner as using ``pip`` above.  

If you are utilising ``python-gsmmodem-new`` as part of another project,
add it to your ``install_requires`` section of your ``setup.py`` file and
upon your project's installation, it will be pulled in automatically.

Manual installation of the latest "stable" release from PyPI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Download a ``python-gsmmodem-new`` archive from `PyPI
<https://pypi.python.org/pypi/python-gsmmodem-new>`_, extract it and install the package with command::

    python setup.py install

Note that ``python-gsmmodem-new`` package relies on ``pySerial`` for serial communications: 
https://github.com/pyserial/pyserial

Installation of the latest commit from GitHub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clone from GitHub::

    git clone https://github.com/babca/python-gsmmodem.git
    cd python-gsmmodem/
    python setup.py install

Note that ``python-gsmmodem-new`` package relies on ``pySerial`` for serial communications: 
https://github.com/pyserial/pyserial

Testing the package
-------------------

.. |Build Status| image::  https://travis-ci.org/babca/python-gsmmodem.svg?branch=master
.. _Build Status: https://travis-ci.org/babca/python-gsmmodem

.. |Coverage Status| image:: https://coveralls.io/repos/github/babca/python-gsmmodem/badge.svg?branch=master
.. _Coverage Status: https://coveralls.io/github/babca/python-gsmmodem?branch=master

|Build Status|_ |Coverage Status|_

To run all unit tests, do::

    python setup.py test

Unit test code coverage information may be generated by using `coverage
<https://pypi.python.org/pypi/coverage/>`_. You can execute it directly from
setup.py by doing::

    python setup.py coverage

This will run all unit tests and report on code coverage statistics.


Building documentation
----------------------

This package contains `Sphinx <http://sphinx-doc.org>`_-based documentation.
To manually build or test the documentation locally, do the following::

   git clone https://github.com/babca/python-gsmmodem.git
   cd python-gsmmodem
   pip install .[doc]
   cd doc
   make html

For true isolation, you may wish to run the above commands within a
`virtualenv <http://www.virtualenv.org/>`_, which will help you manage
this development installation.


License information
-------------------

Copyright (C) 2013 Francois Aucamp  
See AUTHORS for all authors and contact information. 

License: GNU Lesser General Public License, version 3 or later; see COPYING
         included in this archive for details.

FAQ
---

List all modem ports
~~~~~~~~~~~~~~~~~~~~

You can simply list all ttyUSB devices before and after pluging the modem in.

  ls /dev/ttyUSB*


Device or resource busy error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Check running processes. The device could be occupied by another program or another instance of gsmmodem which is still running in the background. Run ``sudo lsof | grep tty``, try to locate the problematic process and ``sudo kill <PID>``.