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