adammck / Pygsm

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.