-
Notifications
You must be signed in to change notification settings - Fork 57
/
Copy pathREADME
186 lines (186 loc) · 6.79 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
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.