FreeCalypso > hg > freecalypso-tools

comparison doc/User-phone-tools @ 450:b5235f8240b9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/User-phone-tools: update for SMS PDU mode working on all targets
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 07 Feb 2019 21:22:27 +0000
parents b1864e3f8fb4
children a43c5dc251dc
comparison
equal deleted inserted replaced
449:b1864e3f8fb4 450:b5235f8240b9
72 * As a dirty hack, one can run FreeCalypso GSM fw on some alien hw targets, 72 * As a dirty hack, one can run FreeCalypso GSM fw on some alien hw targets,
73 currently Motorola C1xx and Pirelli DP-L10. In this hacked-up configuration 73 currently Motorola C1xx and Pirelli DP-L10. In this hacked-up configuration
74 there is no dedicated UART available for a standard AT command interface, but 74 there is no dedicated UART available for a standard AT command interface, but
75 there is a hack that allows a limited subset of AT commands to be passed over 75 there is a hack that allows a limited subset of AT commands to be passed over
76 the RVTMUX binary packet interface provided by the running FreeCalypso GSM fw. 76 the RVTMUX binary packet interface provided by the running FreeCalypso GSM fw.
77 Our fcup-* tools can work with such targets to a limited extent. 77 Our fcup-* tools can work with this alternate target interface option and
78 thereby support these crippled targets.
78 79
79 The AT-over-RVTMUX mechanism was originally invented back in 2015 as a 80 The AT-over-RVTMUX mechanism was originally invented back in 2015 as a
80 development aid, and was never intended for production use or to support any 81 development aid, and was never intended for production use or to support any
81 kind of end user functionality. One of the limitations of its original 82 kind of end user functionality. One of the limitations of its original
82 incarnation was that the strings that are sent to ATI via this interface were 83 incarnation was that the strings that are sent to ATI via this interface were
84 requires longer strings. As of early 2019, this limitation has been lifted: 85 requires longer strings. As of early 2019, this limitation has been lifted:
85 our Magnetite and Selenite firmwares from 20190109 onward support an extended 86 our Magnetite and Selenite firmwares from 20190109 onward support an extended
86 version of our AT-over-RVTMUX hack that allows longer strings to be sent in 87 version of our AT-over-RVTMUX hack that allows longer strings to be sent in
87 pieces, and the present version of our FC User Phone Tools suite will send the 88 pieces, and the present version of our FC User Phone Tools suite will send the
88 strings it generates via this extended mechanism whenever they exceed the old 89 strings it generates via this extended mechanism whenever they exceed the old
89 254 character limit. However, please be aware that FC firmware for Mot C1xx 90 254 character limit. The new mechanism works correctly starting with the
90 phones is still a purely unsupported offering for the sake of the community, it 91 20190128 firmware release for modem products and the 20190129 fw release for
91 is NOT our main project direction, and this fw configuration does *not* receive 92 Mot C1xx phones, thus when the present version of FC User Phone Tools is used
92 the same level of development support and testing as our FCDEV3B modem product. 93 to communicate with our current firmwares, both target interface options provide
93 A test of SMS sending functionality via the newly extended AT-over-RVTMUX 94 equivalent functionality on all supported targets.
94 interface on a Mot C139 phone using our current (as of this writing) 20190109
95 firmware revealed that something is still broken, and we do not currently have
96 a business case to justify allocating more developer time to investigate those
97 issues. In contrast, our FCDEV3B modem running our current 20190112 firmware
98 is rock solid, and all SMS functions work flawlessly going through the standard
99 AT command interface on the dedicated UART.
100 95
101 All fcup-* tools take the following common command line options for selecting 96 All fcup-* tools take the following common command line options for selecting
102 the AT command target interface: 97 the AT command target interface:
103 98
104 -B baud Valid only when -p is also given; selects a different baud rate 99 -B baud Valid only when -p is also given; selects a different baud rate
143 The model adopted for FreeCalypso is that incoming (and possibly saved outgoing) 138 The model adopted for FreeCalypso is that incoming (and possibly saved outgoing)
144 messages initially accumulate in the SIM storage as they come in, and then the 139 messages initially accumulate in the SIM storage as they come in, and then the
145 user periodically transfers them to her larger host computer, simultaneously 140 user periodically transfers them to her larger host computer, simultaneously
146 deleting them from the SIM storage to reclaim the limited space. The retrieval 141 deleting them from the SIM storage to reclaim the limited space. The retrieval
147 of stored SMS from FreeCalypso GSM devices is accomplished with our fcup-smdump 142 of stored SMS from FreeCalypso GSM devices is accomplished with our fcup-smdump
148 utility; unlike SMS sending/writing, this operation works exactly the same 143 utility; like all SMS operations with the current tools+firmware combination,
149 whether the FC GSM device offers a full-featured AT command interface or only 144 this operation works exactly the same whether the FC GSM device offers a full-
150 AT over RVTMUX. SMS retrieval is always done in PDU mode, and the output from 145 featured AT command interface or only AT over RVTMUX. SMS retrieval is always
151 fcup-smdump contains raw SMS PDUs in the form of long hex strings. A separate 146 done in PDU mode, and the output from fcup-smdump contains raw SMS PDUs in the
152 utility called sms-pdu-decode then does what its name says. 147 form of long hex strings. A separate utility called sms-pdu-decode then does
148 what its name says.
153 149
154 The intended mode of usage is something like this: 150 The intended mode of usage is something like this:
155 151
156 fcup-smdump -d >> long-term-sms-log 152 fcup-smdump -d >> long-term-sms-log
157 153
221 unpacked septets. 217 unpacked septets.
222 218
223 Composing and sending outgoing SMS 219 Composing and sending outgoing SMS
224 ================================== 220 ==================================
225 221
226 [2019 update: this section has not yet been updated for the new reality that 222 When used in the default PDU mode (which now works on all targets with our
227 sending maximum-length SMS in PDU mode over RVTMUX is now possible, but please 223 current firmware and tools), the primary SMS sending/writing tool fcup-smsend
228 see the earlier notes about this functionality still not working quite right 224 offers the following capabilities:
229 when tested on a Mot C139 phone. Until further updates, please stick to using
230 PDU mode over the classic AT command channel over the dedicated UART on
231 FCDEV3B hardware.]
232
233 When used with a FreeCalypso GSM device that offers the full AT command
234 interface (currently only the FCDEV3B modem), the primary SMS sending/writing
235 tool fcup-smsend offers the following capabilities:
236 225
237 * Sending outgoing messages in either GSM7 or UCS-2 encoding; 226 * Sending outgoing messages in either GSM7 or UCS-2 encoding;
238 * Sending either single or long (concatenated) SMS; 227 * Sending either single or long (concatenated) SMS;
239 * Message body input in ASCII, ISO 8859-1 or UTF-8; 228 * Message body input in ASCII, ISO 8859-1 or UTF-8;
240 * Message body input either on the command line or on stdin; 229 * Message body input either on the command line or on stdin;
245 234
246 The default and preferred AT command interface mode for sending/writing SMS is 235 The default and preferred AT command interface mode for sending/writing SMS is
247 PDU mode, which works great when the GSM device provides a proper AT command 236 PDU mode, which works great when the GSM device provides a proper AT command
248 interface. However, when a message of maximum or near-maximum length is being 237 interface. However, when a message of maximum or near-maximum length is being
249 submitted to the modem in PDU mode, the hex string that needs to be sent is 238 submitted to the modem in PDU mode, the hex string that needs to be sent is
250 longer than what the crippled AT-over-RVTMUX mechanism can handle, thus if you 239 quite long, and at the time when our FC User Phone Tools were first designed
251 are using crippled Motorola or Pirelli hardware, you need to give the -t option 240 and written, our AT-over-RVTMUX mechanism could not handle such long strings.
252 to fcup-smsend or fcup-sendmult, telling these tools to use text mode instead 241 Because we sought to have at least limited SMS sending and writing support for
253 of PDU mode on the AT command interface. In this text (-t) mode the following 242 crippled Motorola and Pirelli targets, we also implemented text mode support in
254 restrictions apply: 243 fcup-smsend and fcup-smsendmult, enabled with the -t option. In this text (-t)
244 mode the following restrictions apply:
255 245
256 * Only single SMS can be sent, not concatenated; 246 * Only single SMS can be sent, not concatenated;
257 * Only GSM7-encoded messages can be sent, not UCS-2; 247 * Only GSM7-encoded messages can be sent, not UCS-2;
258 * No multiline messages can be sent, i.e., no newlines in the message body; 248 * No multiline messages can be sent, i.e., no newlines in the message body;
259 * ASCII characters [\]^ and {|}~ won't be sent correctly - GSM 07.05 text mode 249 * ASCII characters [\]^ and {|}~ won't be sent correctly - GSM 07.05 text mode
260 drops them. 250 drops them.
261 251
262 But if you have to use FreeCalypso on crippled hardware, the -t option does 252 Now that we have extended our AT-over-RVTMUX mechanism to support longer strings
263 allow you to send GSM7-encoded SMS of the full maximum length of 160 characters. 253 and gained full support for PDU mode on all targets, the above -t mode is no
264 If you attempt to use PDU mode (no -t option) with an AT-over-RVTMUX back-end 254 longer necessary for any use case, as the default PDU mode is a proper superset
265 (-R option), the send or write operation will fail if the generated PDU is 255 in functionality. However, support for this -t mode has been retained, as
266 longer than 127 octets; the length of the generated PDU depends not only on the 256 removing software functionality for no good reason is not the way of FOSS.
267 message body length, but also on the length of the destination address.
268 257
269 The invokation syntax is as follows: 258 The invokation syntax is as follows:
270 259
271 fcup-smsend [options] dest-addr [message] 260 fcup-smsend [options] dest-addr [message]
272 261
356 345
357 <dest addr><white space><message body> 346 <dest addr><white space><message body>
358 347
359 -t, -u, -U, -w and -W command line options are unchanged from fcup-smsend. 348 -t, -u, -U, -w and -W command line options are unchanged from fcup-smsend.
360 349
361 If you have to use FreeCalypso on crippled hardware, fcup-smsendmult -t can be 350 This fcup-smsendmult method of sending batched SMS was originally envisioned as
362 a viable alternative to sending concatenated SMS, as each message in the batch 351 an alternative to concatenated SMS for crippled hw targets that couldn't support
363 can be up to the maximum limit of 160 characters. 352 sending SMS in PDU mode, but that limitation has now been lifted. Because we
353 do not remove already-implemented functionality for no good reason, the tool
354 currently remains in search of new potential use cases.
364 355
365 fcup-smsendpdu 356 fcup-smsendpdu
366 ============== 357 ==============
367 358
368 This utility sends out SMS PDUs that have been prepared externally; it only 359 This utility sends out SMS PDUs that have been prepared externally; it only
369 works in PDU mode, which limits its usefulness to high-end FreeCalypso hardware 360 works in PDU mode - originally it was limited to high-end FreeCalypso hardware
370 with a full AT command interface. The PDUs to be sent out are read from stdin, 361 with a full AT command interface, but now we've got PDU mode working on all
371 one long hex string PDU per line; one can send either a single message or a 362 targets. The PDUs to be sent out are read from stdin, one long hex string PDU
372 batch. Because the destination address and all content details are encoded in 363 per line; one can send either a single message or a batch. Because the
373 the PDU, the tool does not care if the messages are going to the same recipient 364 destination address and all content details are encoded in the PDU, the tool
374 or to different recipients, nor does it care if they constitute a concatenated 365 does not care if the messages are going to the same recipient or to different
375 SMS transmission or not. -w and -W options work the same way as in fcup-smsend 366 recipients, nor does it care if they constitute a concatenated SMS transmission
376 and fcup-smsendmult. 367 or not. -w and -W options work the same way as in fcup-smsend and
368 fcup-smsendmult.
377 369
378 fcup-smwrite 370 fcup-smwrite
379 ============ 371 ============
380 372
381 This utility is a debug and development tool; it differs from fcup-smsendpdu in 373 This utility is a debug and development tool; it differs from fcup-smsendpdu in