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