1 .TH MDSMS 1 "30 Oct 1999" ~ VERSION ~ "MDSMS Manual"
6 mdsms \- Mobile Device SMS tool
9 .BR "mdsms --send" [ -mobildock ]
19 .BR "mdsms --logo-send"
25 .BR "mdsms --ring-send"
31 .RB [ "-c <cfgfile>" ]
35 .RB [ "-l <lockfile>" ]
44 Program sends one SmartMessaging SMS through one of the supported mobile
45 device connected through the serial port. Currently supported:
48 .B Nokia Communicator 9000/9000i
49 All modes except \fB--logo-send\fP/\fB--ring-send\fP supported.
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.
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
58 currently does not support it.
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
64 currently does not support it.
69 .BR -c | --config\ < cfgfile >
70 Process recursively this file and read all options from it. See the section
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
81 .BR -L | --log\ < file >
82 Log all important messages to this file preceded by timestamp, machine hostname
83 etc., similar to output of
85 If set to empty string (which is default - ~\fB DEF_LOGNAME \fP~), nothing
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~.
97 .BR -b | --baud\ < rate >
98 Sets custom baudrate for accessing Nokia modem. Supported speeds are currently:
104 \fB57600\fP. Default is \fB DEF_BAUD \fP.
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.
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.
121 Forces the SMS mode to use - either \fBpdu\fP or \fB text\fP mode. By default
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
134 .BR -P | --pdusmscmode
135 Forces SMS center prepending mode for \fBPDU mode\fP operation. By default
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
144 The default mode, SMS center is prepended to the \fBPDU\fP and SMS
146 length is taken into account during length calculation for "\fBAT+CMGS=\fP#".
149 SMS center is prepended to the \fBPDU\fP but SMS
152 during length calculation for "\fBAT+CMGS=\fP#".
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
161 .BR -s | --smsc\ < smsc\ # >
162 Specify custom SMS center number. If not specified (or overriden as empty
163 string by \fB-s ""\fP)
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:
173 .BR "CZ Paegas " ( "230 01" "): " +420603052000
175 .BR "CZ EuroTel " ( "230 02" "): " +420602909909
177 .BR "CZ Oskar " ( "230 03" "): " +420608005681
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
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.
188 .BR -r | --readtime\ < sec >
189 Maximum response read timeout before command retry.
191 sends the requested \fBAT\fP-style command to the device and expects response.
192 After exceeding this time interval,
194 reissues the last command until the maximum retry count (\fBmaxretry\fP) is exhausted.
197 seconds and should be enough for standard
199 responses. This is the only point where
201 differs the behaviour from regular
203 option. Unfortunately when
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
208 and stucked/disconnected one, so the parameter
210 has very large value, see further. After exceeding this time interval,
212 is terminated immediately,
214 parameter notwithstanding. Standard value of this parameter is
215 .BR DEF_READTIME_MOBILDOCK
216 seconds and should be enough for any voice call.
218 .BR -t | --chartime\ < msec >
219 \fB(This paragraph\fP
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
225 is pretty low, MobilDock/Siemens A1 couple
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
235 .BR -T | --cmdtime\ < msec >
236 \fB(This paragraph\fP
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
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
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.
258 Increase verbosity level by one. Currently the maximum defined level is
264 Give short parameters description to
266 (standard error output stream).
269 Print the version number and exit.
271 .RB < "dest. phone" >
272 This mandatory parameter specifies the telephone number of the recipient
273 of SmartMessaging message. International prefix character plus
275 is supported the national mode without plus
277 prefix is supported and the meaning is specific to the GSM operator currently
278 being roamed in (NOT the native
280 operator of the SIM card!).
281 This number can be made default in system configuration files, see below
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
294 (standard input stream).
295 This parameter is applicable only together with \fB--send\fP or \fB--send-mobildock\fP mode.
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:
305 .B http:/ /www.kessler-design.com/wireless/operatorlogo.php3
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
319 This parameter is applicable only together with \fB--logo send\fP mode.
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
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
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
337 options on one line is preserved the first file is read AFTER all of the
338 current options are processed. Recursive use of
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.
347 locks the port (see option
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:
353 .BR AT <ESCAPE><CTRL-Z>
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
361 mode in which it may errorneously remain from previous sessions.
364 Test the responsiveness of the device.
366 \fBAT+CSCA="\fPsmsc # from user\fB"\fP
367 This command is omitted if
369 is not specified by user (or specified/overriden as empty string \fB""\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.
377 .RB "Mode-dependent."
378 Here are executed the commands listed for each of the specified operation
382 Check that the mobile survived our torture.
385 The following operations are dependant on the operation:
387 .BR --send / --send-mobildock :
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
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
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
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).
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
413 .BR --logo-send / --ring-send :
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
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
427 (message reference) number to the user.
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).
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
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.
444 tries very hard to restore the device state before its termination but sometimes it just
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
451 Safer SIM store/retrieve mechanism may be implemented in future versions. Command sequence used in
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).
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
465 to restore the original device behaviour.
470 really much interested in additional non-standard values of
471 PID (Protocol IDentifier), DCS (Data Coding Scheme) etc.
474 In this point the device lock file is removed, retry count is set to infinite value
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.
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
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.
496 ETSI documentation for SMS messages in GSM networks
498 .B GNokii, tools and drivers for Nokia mobile phones
499 Nokia logo data format was read from its sources:
500 .B http:/ www.gnokii.org/
502 .B "Developers'" Guide: SMS with the A1
503 Tech note on PDU SMS format etc:
504 .B http:/ /www.siemens.se/telefoner/ovrigtgsm/fragorsvar/a1_sms.pdf
506 .B Technical Description of the Siemens A1
507 Siemens A1 command description
508 .B http:/ /www.siemens.se/telefoner/ovrigtgsm/fragorsvar/a1_manual.pdf
513 Main configuration file
515 \fB$HOME CONFIG_HOME \fP
516 User personalized local configuration file
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.