adammck / pygsm Goto Github PK

class GsmModem(__builtin__.object)
 |  pyGSM is a Python module which uses pySerial to provide a nifty
 |  interface to send and receive SMS via a GSM Modem. It was ported
 |  from RubyGSM, and provides (almost) all of the same features. It's
 |  easy to get started:
 |
 |    # create a GsmModem object:
 |    >>> modem = pygsm.GsmModem(port="/dev/ttyUSB0")
 |
 |    # harass Evan over SMS:
 |    # (try to do this before 11AM)
 |    >>> modem.send_sms(*REDACTED*, "Hey, wake up!")
 |
 |    # check for incoming SMS:
 |    >>> print modem.next_message()
 |    <pygsm.IncomingMessage from *REDACTED*: "Leave me alone!">
 |
 |  pyGSM is distributed via GitHub:
 |  http://github.com/adammck/pygsm
 |
 |  Bug reports (especially for
 |  unsupported devices) are welcome:
 |  http://github.com/adammck/pygsm/issues
 |
 |
 |
 |
 |  Methods defined here:
 |
 |
 |  __init__(self, *args, **kwargs)
 |      Create a GsmModem object. All of the arguments are passed along
 |      to serial.Serial.__init__ when GsmModem.connect is called. For
 |      all of the possible configration options, see:
 |
 |      http://pyserial.wiki.sourceforge.net/pySerial#tocpySerial10
 |
 |      Alternatively, a single 'device' kwarg can be passed, which
 |      overrides the default proxy-args-to-pySerial behavior. This is
 |      useful when testing, or wrapping the serial connection with some
 |      custom logic.
 |
 |      NOTE: The serial connection isn't created until GsmModem.connect
 |      is called. It might still fail (but should raise GsmConnectError
 |      when it does so.)
 |
 |
 |  boot(self, reboot=False)
 |      (Re-)Connect to the modem and configure it in an (often vain)
 |      attempt to standardize the behavior of the many vendors and
 |      models. Should be called before reading or writing.
 |
 |      This method isn't called during __init__ (since 5f41ba6d), since
 |      it's often useful to create GsmModem objects without writing to
 |      the modem. To compensate, this method returns 'self', so it can
 |      be easily chained onto the constructor, like so:
 |
 |        >>> gsm = GsmModem(port="whatever").boot()
 |
 |      This is exactly the same as:
 |
 |        >>> gsm = GsmModem(port="whatever")
 |        >>> gsm.boot()
 |
 |
 |  command(self, cmd, read_term=None, read_timeout=None, write_term='\r', raise_errors=True)
 |      Issue an AT command to the modem, and return the sanitized
 |      response. Sanitization removes status notifications, command
 |      echo, and incoming messages, (hopefully) leaving only the actual
 |      response to the command.
 |
 |      If Error 515 (init or command in progress) is returned, the
 |      command is automatically retried up to 'GsmModem.max_retries'
 |      times.
 |
 |
 |  connect(self, reconnect=False)
 |      Connect to the modem via pySerial, using the args and kwargs
 |      provided to the constructor. If 'reconnect' is True, and the
 |      modem is already connected, the entire serial.Serial object is
 |      destroyed and re-established.
 |
 |      Returns self.device, or raises GsmConnectError
 |
 |
 |  disconnect(self)
 |      Disconnect from the modem.
 |
 |
 |  hardware(self)
 |      Return a dict of containing information about the modem. The
 |      contents of each value are entirely manufacturer-dependant, and
 |      can vary wildly between devices.
 |
 |
 |  next_message(self, ping=True, fetch=True)
 |      Returns the next waiting IncomingMessage object, or None if the
 |      queue is empty. The optional 'ping' and 'fetch' args control
 |      whether the modem is pinged (to allow new messages to be
 |      delivered instantly, on those modems which support it) and
 |      queried for unread messages in storage, which can both be
 |      disabled in case you're already polling in a separate thread.
 |
 |
 |  ping(self)
 |      Send the "AT" command to the device, and return true if it is
 |      acknowledged. Since incoming notifications and messages are
 |      intercepted automatically, this is a good way to poll for new
 |      messages without using a worker thread like RubyGSM.
 |
 |
 |  query(self, cmd, prefix=None)
 |      Issue an AT command to the modem, and returns the relevant part
 |      of the response. This only works for commands that return a
 |      single line followed by "OK", but conveniently, this covers
 |      almost all AT commands that I've ever needed to use. Example:
 |
 |        >>> modem.query("AT+CSQ")
 |        "+CSQ: 20,99"
 |
 |      Optionally, the 'prefix' argument can specify a string to check
 |      for at the beginning of the output, and strip it from the return
 |      value. This is useful when you want to both verify that the
 |      output was as expected, but ignore the prefix. For example:
 |
 |        >>> modem.query("AT+CSQ", prefix="+CSQ:")
 |        "20,99"
 |
 |      For all unexpected responses (errors, no output, or too much
 |      output), returns None.
 |
 |
 |  query_list(self, cmd, prefix=None)
 |      Issue a single AT command to the modem, checks that the last
 |      line of the response is "OK", and returns a list containing the
 |      other lines. An empty list is returned if a command fails, so
 |      the output of this method can always be assumed to be iterable.
 |
 |      The 'prefix' argument can optionally specify a string to filter
 |      the output lines by. Matching lines are returned (sans prefix),
 |      and the rest are dropped.
 |
 |      Most AT commands return a single line, which is better handled
 |      by GsmModem.query, which returns a single value.
 |
 |
 |  reboot(self)
 |      Disconnect from the modem, reconnect, and reboot it (AT+CFUN=1,
 |      which clears all volatile state). This drops the connection to
 |      the network, so it's wise to call _GsmModem.wait_for_network_
 |      after rebooting.
 |
 |
 |  send_sms(self, recipient, text)
 |      Send an SMS to 'recipient' containing 'text'. Some networks will
 |      automatically split long messages into multiple parts, and join
 |      them upon delivery -- but some will silently drop them. pyGSM
 |      does nothing to avoid this (for now), so try to keep 'text'
 |      under 160 characters.
 |
 |
 |  signal_strength(self)
 |      Return an integer between 1 and 99, representing the current
 |      signal strength of the GSM network, False if we don't know, or
 |      None if the modem can't report it.
 |
 |
 |  wait_for_network(self)
 |      Block until the signal strength indicates that the device is
 |      active on the GSM network. It's a good idea to call this before
 |      trying to send or receive anything.
 |
 |
 |
 |
 |  Data descriptors defined here:
 |
 |
 |  network
 |      Return the name of the currently selected GSM network.
 |
 |
 |  service_center
 |      Get or set the service center address currently in use by the
 |      modem. Returns None if the modem does not support the AT+CSCA
 |      command.