New option -w|--waittime as requested by Markus Widauer
[mdsms.git] /
1 .TH MDSMS 1 "30 Oct 1999" ~     VERSION ~ "MDSMS Manual"
3 .\~ $Id$
6 mdsms \- Mobile Device SMS tool
9 .BR "mdsms --send" [ -mobildock ]
10 .RB options...
11 .RB [ "\-f" ]
12 .BR "<dest. phone>"
13 .BR "<msg text>"
14 .br
15 .BR "mdsms --receive"
16 .RB options...
17 .BR "<command name>"
18 .br
19 .BR "mdsms --logo-send"
20 .RB options...
21 .BR "<dest. phone>"
22 .BR "<logo filename>"
23 .RB [ "<GSMnet id>" ]
24 .br
25 .BR "mdsms --ring-send"
26 .RB options...
27 .BR "<dest. phone>"
28 .BR "<ring filename>"
29 .br
30 options:
31 .RB [ "-c <cfgfile>" ]
32 .RB [ "-d <device>" ]
33 .RB [ "-L <file>" ]
34 .RB [ "-b <rate>" ]
35 .RB [ "-l <lockfile>" ]
36 .RB [ "-s <smsc #>" ]
37 .RB [ "-m <#>" ]
38 .RB [ "-r <sec>" ]
39 .RB [ "-t <msec>" ]
40 .RB [ "-T <msec>" ]
41 .RB [ "-w <sec>" ]
42 .RB [ "\-vhV" ]
45 Program sends one SmartMessaging SMS through one of the supported mobile
46 device connected through the serial port. Currently supported:
47 .RS
48 .TP
49 .B Nokia Communicator 9000/9000i
50 All modes except \fB--logo-send\fP/\fB--ring-send\fP supported.
51 .TP
52 .B Nokia Communicator 9110
53 All modes supported. This is the only device with \fB--logo-send\fP/\fB--ring-send\fP capability for now.
54 .TP
55 .B Siemens A1
56 Firmware revision 2.0 required. All modes except \fB--logo-send\fP/\fB--ring-send\fP supported.
57 These modes \fBcould\fP be supported for this device but unfortunately
58 .B mdsms
59 currently does not support it.
60 .TP
61 .B Siemens M20, M1
62 All modes except \fB--logo-send\fP/\fB--ring-send\fP supported.
63 These modes \fBcould\fP be supported for this device but unfortunately
64 .B mdsms
65 currently does not support it.
66 .RE
69 .TP
70 .BR -c | --config\  < cfgfile >
71 Process recursively this file and read all options from it. See the section
73 for more information.
74 .TP
75 .BR -d | --device\  < device >
76 Specify serial device to communicate with your mobile. If only bare name is
77 specified, "\fB/dev/\fP" is prepended automatically. This device name is used
78 consequently with
79 .BR -l | --lockfile
80 option, see below.
81 .TP
82 .BR -L | --log\  < file >
83 Log all important messages to this file preceded by timestamp, machine hostname
84 etc., similar to output of
85 .BR syslogd (8).
86 If set to empty string (which is default - ~\fB DEF_LOGNAME     \fP~), nothing
87 is logged anywhere.
88 .TP
89 .BR -l | --lockfile\  < lockfile >
90 Prior to accessing serial device specified above the lockfile should be
91 acquired for correct concurrent processes behaviour. Although this name
92 can be given as direct filename more common method is to use pattern
93 with embedded "\fB%s\fP" where this mark is replaced by actual basename
94 (last component of pathname with all preceding directory names stripped)
95 of serial device used.
96 Default name for lockfile is ~\fB       DEF_LOCKFILE    \fP~.
97 .TP
98 .BR -b | --baud\  < rate >
99 Sets custom baudrate for accessing Nokia modem. Supported speeds are currently:
100 \fB2400\fP,
101 \fB4800\fP,
102 \fB9600\fP,
103 \fB19200\fP,
104 \fB38400\fP,
105 \fB57600\fP. Default is \fB     DEF_BAUD        \fP.
106 .TP
107 .BR -x | --xonxoff
108 Turns handshaking mode to \fBXON/XOFF\fP (also called \fBsoftware handshaking\fP).
109 Use this mode if you are using only 3-wire serial cable. Device should be
110 configured in "\fBAT+IFC=1,1\fP" mode, if \fBAT+IFC\fP command supported. When
111 possible, you should rather use \fBRTS/CTS\fP handshaking described in the
112 following paragraph. This mode is the default one.
113 .TP
114 .BR -C | --rtscts
115 Turns handshaking mode to \fBRTS/CTS\fP (also called \fBhardware handshaking\fP).
116 Use this mode if you are using full 7-wire (approx.) serial cable. Device should be
117 configured in "\fBAT+IFC=2,2\fP" mode, if \fBAT+IFC\fP command supported. Try
118 to use this mode whenever possible (instead of the default \fBXON/XOFF\fP mode described
119 in the previous paragraph). This mode may not be available in your UNIX flavour.
120 .TP
121 .BR -M | --smsmode
122 Forces the SMS mode to use - either \fBpdu\fP or \fB text\fP mode. By default
123 .B mdsms
124 tries to detect mode to use automatically, \fBPDU\fP mode is preferred. When
125 your modem is capable of both modes and you need for some reasone \fBtext\fP
126 mode, you may use \fB--smsmode text\fP argument to force it. \fBPDU\fP mode
127 is recommended for unattended operation, on the other side \fBtext\fP mode
128 should be more compatible when you have compatibility problems with unsupported
129 GSM modem. It is recommended to force the exact mode you will be using in
130 unattanded operaton. By such way you will prevent failures caused by the other
131 mode after possible random communication glitches (and therefore automatic
132 .B mdsms
133 switchover).
134 .TP
135 .BR -P | --pdusmscmode
136 Forces SMS center prepending mode for \fBPDU mode\fP operation. By default
137 .B mdsms
138 tries sequentially all the described modes, you should lock it for
139 unattanded operation to prevent vain switchovers from random communication
140 glitches (also you will notice faster response for "\fBcount-out\fP" or
141 "\fBnone\fP" modes):
142 .RS
143 .TP
144 .BR count-in
145 The default mode, SMS center is prepended to the \fBPDU\fP and SMS
146 .RB "center's"
147 length is taken into account during length calculation for "\fBAT+CMGS=\fP#".
148 .TP
149 .BR count-out
150 SMS center is prepended to the \fBPDU\fP but SMS
151 .RB "center's"
152 length is omitted
153 during length calculation for "\fBAT+CMGS=\fP#".
154 .TP
155 .BR none
156 SMS center is \fBNOT\fP prepended to the \fBPDU\fP, SMS center to use by
157 GSM modem is taken from the one set by
158 \fBAT+CSCA="\fPsmsc # from user\fB"\fP
159 command.
160 .RE
161 .TP
162 .BR -s | --smsc\  < smsc\ # >
163 Specify custom SMS center number. If not specified (or overriden as empty
164 string by \fB-s ""\fP)
165 .B mdsms
166 asks by "\fBAT+CSCA?\fP"
167 for the current default SMS center. Situation with undeterminable SMS center
168 is unrecoverable and causes immediate fail. Please contact your GSM operator
169 customer service if you are in trouble. It is a common practice to use
170 plus sign ("\fB+\fP") to indicate international number type.
171 Known SMS centers as of April 2001:
172 .RS
173 .TP
174 .BR "CZ Paegas  " ( "230 01" "): " +420603052000
175 .TP
176 .BR "CZ EuroTel " ( "230 02" "): " +420602909909
177 .TP
178 .BR "CZ Oskar   " ( "230 03" "): " +420608005681
179 .RE
180 .TP
181 .BR -m | --maxretry\  < # >
182 Maximum retries of any \fBAT\fP-style command during the session. All the
183 retries are summed during one run of
184 .B mdsms
185 and no more retries of the command are permitted. After exceeding this
186 value the program is terminated. Exception is \fB--receive\fP which is never
187 quit after the initial initialisation has been successfuly negotiated.
188 .TP
189 .BR -r | --readtime\  < sec >
190 Maximum response read timeout before command retry.
191 .B mdsms
192 sends the requested \fBAT\fP-style command to the device and expects response.
193 After exceeding this time interval,
194 .B mdsms
195 reissues the last command until the maximum retry count (\fBmaxretry\fP) is exhausted.
196 Standard value is
198 seconds and should be enough for standard
199 .B mobiles
200 responses. This is the only point where
201 .B --send-mobildock
202 differs the behaviour from regular
203 .B --send
204 option. Unfortunately when
205 .B MobilDock
206 has a voice call in progress, it will block any serial device
207 communication with \fBSiemens A1\fP and it is impossible to differentiate between call-in-progress
208 .B MobilDock
209 and stucked/disconnected one, so the parameter
210 .B readtime
211 has very large value, see further. After exceeding this time interval,
212 .B mdsms
213 is terminated immediately,
214 .B maxretry
215 parameter notwithstanding. Standard value of this parameter is
217 seconds and should be enough for any voice call.
218 .TP
219 .BR -t | --chartime\  < msec >
220 \fB(This paragraph\fP
221 .BR "doesn't"
222 \fBapply to Nokia 9110 or similiar smart devices but the functionality has been
223 retained just to be on the safe side.)\fP
224 Although the fixed used baudrate of
225 .B 19200
226 is pretty low, MobilDock/Siemens A1 couple
227 .RB "aren't"
228 able to accept steady
229 stream of data at this speed. Even the used XON/XOFF handshaking is just not
230 enough. The only possible workaround is to slowdown the communication by
231 waiting a bit after character sent to give relax time to these devices.
232 When full rate communication was used, occasional longer SMS data corruption
233 was observed. Argument is given in milliseconds and its default value is
235 .TP
236 .BR -T | --cmdtime\  < msec >
237 \fB(This paragraph\fP
238 .BR "doesn't"
239 \fBapply to Nokia 9110 or similiar smart devices but the functionality has been
240 retained just to be on the safe side.)\fP
241 This delay is given before sending any
242 .B AT-style
243 command to the device.
244 Its primary purpose is to let any previous entered commands to finish and
245 to clear any input before actually sending our own command. Also all Siemens
246 devices are known that they strongly dislike fast edge-to-edge communication
247 and to satisfy these requirements this delay was considered as the best
248 approach.
249 The default value is
251 .TP
252 .BR -w | --waittime\  < sec >
253 This delay is maximum time allowed silently waiting for incoming data.
254 After approx 30 minutes of waiting for Nokia 9110 data it will turn off
255 its FaxModem feature disabling any further reading of messages.
256 After such idle time \fBmdsms\fP will also reinitialize the modem to
257 handle the case where the modem was silently powercycled in the meanwhile
258 loosing its initial settings done by \fBmdsms\fP during its startup.
259 The default value is
261 .TP
262 .BR -f | --file
263 When parameter <\fBmsg text\fP> has been specified, by using this option
264 \fBmdsms\fP will read the file with the <\fBmsg text\fP> filename instead
265 and send its \fBcontents\fP as the SMS message.
266 This parameter is applicable only together with \fB--send\fP or \fB--send-mobildock\fP mode.
267 .TP
268 .BR -v | --verbose
269 Increase verbosity level by one. Currently the maximum defined level is
270 .BR 3 ,
271 the default value is
272 .BR 0 .
273 .TP
274 .BR -h | --help
275 Give short parameters description to
276 .I stderr
277 (standard error output stream).
278 .TP
279 .BR -V | --version
280 Print the version number and exit.
281 .TP
282 .RB < "dest. phone" >
283 This mandatory parameter specifies the telephone number of the recipient
284 of SmartMessaging message. International prefix character plus
285 .RB ( + )
286 is supported the national mode without plus
287 .RB ( + )
288 prefix is supported and the meaning is specific to the GSM operator currently
289 being roamed in (NOT the native
290 .RB "'home'"
291 operator of the SIM card!).
292 This number can be made default in system configuration files, see below
293 for section
295 .TP
296 .RB < "msg text" >
297 Here you write the exact body of the message. This parameter should be
298 specified only as one component, although if more found they are concatenated
299 with separating space (" "). But this practice is discouraged as
300 your shell will probably remove any multiple spaces found and also other
301 metacharacters may be incorrectly interpreted. To prevent any escaping
302 mess, you may prefer to omit this parameter and the the message text is
303 then read from
304 .I stdin
305 (standard input stream).
306 This parameter is applicable only together with \fB--send\fP or \fB--send-mobildock\fP mode.
307 .TP
308 .RB < "logo filename" >
309 Here you specifify the filename of the logo file to be uploaded. Currently
310 recognized file formats are \fBNOL\fP (Nokia logo?) and \fBNGG\fP (Nokia
311 Group Graphics). These formats are proprietary by \fBKESSLER Wireless Design\fP
312 and \fBmdsms\fP currently "can't" edit them.
313 This parameter is applicable only together with \fB--logo send\fP mode.
314 More info can be found on:
315 .RS
316 .B http:/       /
317 .RE
318 .TP
319 .RB < "GSMnet id" >
320 Specify GSM network code to be set on the logo being uploaded. Upon upload to
321 Nokia phone each operator logo has a GSM network code binded with it. When
322 you are registered (even roamed) into such network the logo is displayed on
323 the phone. Current Nokia mobile phones can handle only one logo loaded
324 simultaneously, it will be rewritten by any other upload. You can also
325 specify string ~\fB     WORD_GROUP      \fP~ to send the logo as group graphics
326 (even from \fBNOL\fP format) or string ~\fB     WORD_NET        \fP~ to force detection
327 of network code from \fBNOL\fP. The default if this parameter is not specified
328 is ~\fB WORD_NET        \fP~ for \fBNOL\fP files and ~\fB       WORD_GROUP      \fP~ for
329 \fBNGG\fP files.
330 This parameter is applicable only together with \fB--logo send\fP mode.
333 .B mdsms
334 reads ~\fB      CONFIG_MAIN     \fP~ followed by ~\fB$HOME      CONFIG_HOME     \fP~
335 configuration files. The content of these files (and also any file read by
336 .BR -c | --config
337 option)
338 has the usual
339 .BR getopt (3)
340 syntax with dashes. Newlines are taken as whitespace, both double ("\fB~\fP")
341 and single ("\fB'\fP")
342 quoting is supported. Embedded quote characters can be escaped by backslash
343 ("\fB\\\fP").
344 Arguments are processes in order as specified in configuration files and
345 finally the command-line of the program itself, overriding any previous
346 values.  Although the order of
347 .BR -c | --config
348 options on one line is preserved the first file is read AFTER all of the
349 current options are processed. Recursive use of
350 .B -c
351 is permitted and the files are read in LIFO (Last-In First-Out, AKA stack)
352 order. You should use "\fB-v -v\fP"
353 to see details of option processing with more complex configuration setups.
356 Upon startup
357 .B mdsms
358 locks the port (see option
359 .BR -l | --lockfile
360 for details) and opens the serial device with specified baudrate (default
361 \fB     DEF_BAUD        \fP baud), software handshaking (XON/XOFF style), 8 bits,
362 no parity. Then issues the following commands:
363 .TP
365 .B AT
366 is used to fool
367 .B MobilDock
368 (if present, otherwise it is harmlesss anyway) and pass the following
370 (ascii decimal code 27 followed by 26) characters to the device and break it from eventual
371 .B AT+CMGS
372 mode in which it may errorneously remain from previous sessions.
373 .TP
374 .B AT
375 Test the responsiveness of the device.
376 .TP
377 \fBAT+CSCA="\fPsmsc # from user\fB"\fP
378 This command is omitted if
379 .B "smsc #"
380 is not specified by user (or specified/overriden as empty string \fB""\fP
381 .TP
382 \fBAT+CSCA?\fP
383 Query the currently set SMS center number to include it later to the
384 header of SMS PDU format where it is required. If \fBAT+CSCA="\fP...\fB"\fP
385 was issued before, this number should match it but no sanity checks are
386 currently do so. Also it is used to detect possibly unset SMS center.
387 .TP
388 .RB "Mode-dependent."
389 Here are executed the commands listed for each of the specified operation
390 mode separately.
391 .TP
392 \fBAT\fP
393 Check that the mobile survived our torture.
395 .TP
396 The following operations are dependant on the operation:
397 .TP
398 .BR --send / --send-mobildock :
399 .RS
400 .TP
401 \fBAT+CMGF=0\fP, if fails \fBAT+CMGF=1\fP
402 Set the default SMS message format to PDU type (preferred) or text mode (if
403 PDU not available). Next \fB+CMGS\fP command is dependant on the mode selected
404 by this one.
405 .TP
406 \fBAT+CMGS=\fP# chars if \fB+CMGF=0\fP
407 This command physically sends the message and the resulting "\fB+CMGS:\fP" output
408 is catched and returned as
409 .B MR
410 (message reference) number to the user. \fB# chars\FP corresonds to total data
411 bytes sent to the phone (so the half of the hex-string, SMSC is included).
412 SMSC number is preceding the rest of PDU to be conformant with GSM Phase 2
413 specification. Siemens M1 or Siemens M20 rev. 1.x are known that
414 .RB "don't"
415 like this SMSC number, I have to get in touch with such device to be able to autodetect
416 it properly (mail me if you want to be helpful).
417 .TP
418 \fBAT+CMGS="\fPphone # from user\fB"\fP if \fB+CMGF=1\fP
419 The same as the previous command except that the message is text as pure text
420 terminated with \fB<CTRL-Z>\fP character. SMSC number is not present anywhere
421 in this mode.
422 .RE
423 .TP
424 .BR --logo-send / --ring-send :
425 .RS
426 .TP
427 \fBAT+CSMP=81,,0,245\fP
428 Sets PDU type to 81 (\fBSMS-SUBMIT\fP + integer-type for \fBvalidity\fP
429 + \fBUDHI\fP - user data header indicator), PID (protocol identifier) to
430 0 (standard non-converted SMS) and DCS (data coding scheme) to 0xF5
431 (\fBdata coding\fP/\fBmessage class\fP, \fB8-bit data\fP + \fBmobile-equipment\fP
432 specific).
433 .TP
434 \fBAT+CMGS="\fPphone # from user\fB"\fP
435 This command physically sends the message and the resulting "\fB+CMGS:\fP" output
436 is catched and returned as
437 .B MR
438 (message reference) number to the user.
439 .TP
440 \fBAT+CSMP=17,,0,0\fP
441 Resets back PDU type to 17 (\fBSMS-SUBMIT\fP + integer-type for \fBvalidity\fP),
442 PID (protocol identifier) to 0 (standard non-converted SMS) and DCS (data coding
443 scheme) to 0 (\fBalphabet indication\fP, \fBdefault 7-bit alphabet\fP).
444 .RE
445 .TP
446 .BR --receive :
447 Receiving of messages is performed using direct routing of incoming data to TE (Terminal Equipment).
448 No SMSes are stored to SIM card/device memory and then read back as one may expect.
449 There are slight advantages of better response times (SIM card access is very slow) and
450 saving EEPROM writes to SIMcard. Unfortunately there is one big advantage that when
451 .B mdsms
452 suddenly stops/crashes without switching the device back to SIM-store mode, messages
453 being consequently received are lost on the dead end of serial port.
454 .B mdsms
455 tries very hard to restore the device state before its termination but sometimes it just
456 .RB "isn't"
457 possible. Due to this fact \fBnever kill mdsms with SIGKILL (-9) signal\fP, use standard
458 SIGTERM instead, please. Also one fact resulting of this behaviour is that messages
459 with Class-2 (SIM store) specific routing are really stored to SIM card and as such are
460 not processed in any way by
461 .BR mdsms .
462 Safer SIM store/retrieve mechanism may be implemented in future versions. Command sequence used in
463 .B --receive
464 mode follows:
465 .RS
466 .TP
467 \fBAT+CMGF=0\fP, if fails \fBAT+CMGF=1\fP
468 Set the default SMS message format to PDU type (preferred) or text mode (if
469 PDU mode not available).
470 .TP
471 \fBAT+CNMI=,2\fP
472 Set the message routing to go directly to TE (Terminal Equipment), see the discussion
473 in paragraph above for more. Also right before starting attempt to send this command,
474 \fBAT+CNMI=,0\fP is set to be tried before finishing
475 .BR mdsms
476 to restore the original device behaviour.
477 .TP
478 \fBAT+CSDH=0\fP
479 We
480 .RB "aren't"
481 really much interested in additional non-standard values of
482 PID (Protocol IDentifier), DCS (Data Coding Scheme) etc.
483 .TP
484 data wait
485 In this point the device lock file is removed, retry count is set to infinite value
486 (see discussion in
487 .B --maxretry
488 parameter) and
489 .B mdsms
490 starts to passively listen for any incoming data. Possible dial-out mode is being
491 detected afterwards, otherwise message receive sequence follows as described below.
492 .TP
493 \fB+CMT:\fP read
494 Any waiting \fB+CMT\fP incoming message indications are read and processed. Format
495 being processed (text/PDU) depends on the actual value of \fBAT+CMGF\fP set before. Any
496 possible \fB+CMTI:\fP input is discarded as we are not interested in SIM-store
497 directed messages.
498 .TP
499 receive restart
500 After processing all the messages, the whole initialization sequence is restarted as
501 the device configuration may have changed or lost during the data wait phase.
502 .RE
505 .TP
506 .B GSM 03.40
507 ETSI documentation for SMS messages in GSM networks
508 .TP
509 .B GNokii, tools and drivers for Nokia mobile phones
510 Nokia logo data format was read from its sources:
511 .B http:/
512 .TP
513 .B "Developers'" Guide: SMS with the A1
514 Tech note on PDU SMS format etc:
515 .B http:/               /
516 .TP
517 .B Technical Description of the Siemens A1
518 Siemens A1 command description
519 .B http:/               /
522 .TP
523 \fB     CONFIG_MAIN     \fP
524 Main configuration file
525 .TP
526 \fB$HOME        CONFIG_HOME     \fP
527 User personalized local configuration file
530 .B mdsms
531 was written by Jan Kratochvil who should be responsible for all the bugs
532 included. Please see the file "\fBAUTHORS\fP"
533 shipped with the original distribution archive for more details.