mdsms.1.in

   1 .TH MDSMS 1 "17 May 1999" ~     VERSION ~ "SendSMS Manual"
   2
   3 .\~ $Id$
   4 .\~
   5 .\~ $Log$
   6 .\~ Revision 1.3  1999/06/03 11:46:41  short
   7 .\~ Logging (--log) implemented.
   8 .\~
   9 .\~ Revision 1.2  1999/06/03 10:38:52  short
  10 .\~ Implemented remaining communication timeouts and maximum retry count.
  11 .\~
  12 .\~ Revision 1.1.1.1  1999/05/26 13:06:26  short
  13 .\~ First alpha release.
  14 .\~
  15
  16 .SH NAME
  17 mdsms \- send SMSes through MobilDock
  18
  19 .SH SYNOPSIS
  20 .B mdsms
  21 .RB [ "-c <cfgfile>" ]
  22 .RB [ "-d <device>" ]
  23 .RB [ "-L <file>" ]
  24 .RB [ "-l <lockfile>" ]
  25 .RB [ "-s <smsc #>" ]
  26 .RB [ "-m <#>" ]
  27 .RB [ "-r <sec>" ]
  28 .RB [ "-t <msec>" ]
  29 .RB [ "-T <msec>" ]
  30 .RB [ "\-vhV" ]
  31 .RB [ "<dest. phone>" ]
  32 .RB [ "<msg text>" ]
  33
  34 .SH DESCRIPTION
  35 Program sends one SMS message through MobilDock device.
  36
  37 .SH OPTIONS
  38 .TP
  39 .BR -c | --config\  < cfgfile >
  40 Process recursively this file and read all options from it. See the section
  41 .B CONFIGURATION
  42 for more information.
  43 .TP
  44 .BR -d | --device\  < device >
  45 Specify serial device to communicate with MobilDock. If only bare name is
  46 specified, "\fB/dev/\fP" is prepended automatically. This device name is used
  47 subsequently with
  48 .BR -l | --lockfile
  49 option, see below.
  50 .TP
  51 .BR -L | --log\  < file >
  52 Log all important messages to this file preceded by timestamp, machine hostname
  53 etc., similar to output of
  54 .BR syslogd (8).
  55 If set to empty string (which is default - ~\fB DEF_LOGNAME     \fP~), nothing
  56 is logged anywhere.
  57 .TP
  58 .BR -l | --lockfile\  < lockfile >
  59 Prior to accessing serial device specified above the lockfile should be
  60 acquired for correct concurrent processes behaviour. Although this name
  61 can be given as direct filename more common method is to use pattern
  62 with embedded "\fB%s\fP" where this mark is replaced by actual basename
  63 (last component of pathname with all preceding directory names stripped)
  64 of serial device used.
  65 Default name for lockfile is ~\fB       DEF_LOCKFILE    \fP~.
  66 .TP
  67 .BR -s | --smsc\  < smsc\ # >
  68 Specify custom SMS center number. If not specified (or overriden as empty
  69 string by \fB-s ""\fP)
  70 .B mdsms
  71 asks by "\fBAT+CSCA?\fP"
  72 Siemens A1 for its default SMS center. Situation with undeterminable SMS center
  73 is unrecoverable and casues immediate fail. It is a common practice to use
  74 plus sign ("\fB+\fP") to indicate international number type.
  75 Known SMS centers as of May 1999:
  76 .RS
  77 .TP
  78 .BR "CZ Paegas " ( "230 01" "): " +420603052000
  79 .TP
  80 .BR "CZ EuroTel " ( "230 02" "): " +420602909909
  81 .RE
  82 .TP
  83 .BR -m | --maxretry\  < # >
  84 Maximum retries of any \fBAT\fP-style command during the session. All the
  85 retries are summed during one run of
  86 .B mdsms
  87 and no more retries of the command are permitted. After exceeding this
  88 value the program is terminated.
  89 .TP
  90 .BR -r | --readtime\  < sec >
  91 Maximum response read timeout before give up.
  92 .B mdsms
  93 sends the requested \fBAT\fP-style command to
  94 .B MobilDock
  95 and expects response. Unfortunately when the voice call is in progress,
  96 .B MobilDock
  97 will block any serial device communication and it is impossible to differentiate
  98 between calling
  99 .B MobilDock
 100 and stucked/disconnected one. After exceeding this time interval,
 101 .B mdsms
 102 is terminated immediately,
 103 .B maxretry
 104 parameter notwithstanding. Standard value is
 105 .BR DEF_READTIME
 106 seconds and should be enough for any voice call.
 107 .TP
 108 .BR -t | --chartime\  < msec >
 109 Although the fixed used baudrate of
 110 .B 19200
 111 is pretty low, MobilDock/Siemens A1 couple
 112 .RB "aren't"
 113 able to accept steady
 114 stream of data at this speed. Even the used XON/XOFF handshaking is just not
 115 enough. The only possible workaround is to slowdown the communication by
 116 waiting a bit after character sent to give relax time to these devices.
 117 When full rate communication was used, occasional longer SMS data corruption
 118 was observed. Argument is given in milliseconds and its default value is
 119 .BR DEF_CHARTIME ms.
 120 .TP
 121 .BR -T | --cmdtime\  < msec >
 122 This delay is given before sending any
 123 .B AT-style
 124 command to MobilDock/Siemens A1.
 125 Its primary purpose is to let any previous entered commands to finish and
 126 to clear any input before actually sending our own command. Also all Siemens
 127 devices are known that they strongly dislike fast edge-to-edge communication
 128 and to satisfy these requirements this delay was considered as the best
 129 approach. The default value is
 130 .BR DEF_CMDTIME ms.
 131 .TP
 132 .BR -v | --verbose
 133 Increase verbosity level by one. Currently the maximum defined level is
 134 .BR 3 ,
 135 the default value is
 136 .BR 0 .
 137 .TP
 138 .BR -h | --help
 139 Give short parameters description to
 140 .I stderr
 141 (standard error output stream).
 142 .TP
 143 .BR -v | --version
 144 Print the version number and exit.
 145 .TP
 146 .RB < "dest. phone" >
 147 This mandatory parameter specifies the telephone number of the recipient
 148 of SMS message. International prefix character plus
 149 .RB ( + )
 150 is supported the national mode without plus
 151 .RB ( + )
 152 prefix is supported and the meaning is specific to the GSM operator currently
 153 being roamed in (NOT the native
 154 .RB "'home'"
 155 operator of the SIM card!).
 156 This number can be made default in system configuration files, see below
 157 for section
 158 .BR CONFIGURATION .
 159 .TP
 160 .RB < "msg text" >
 161 Here you write the exact body of the message. This parameter should be
 162 specified only as one component, although if more found they are concatenated
 163 with separating space (" "). But this practice is discouraged as
 164 your shell will probably remove any multiple spaces found and also other
 165 metacharacters may be incorrectly interpreted. To prevent any escaping
 166 mess, you may prefer to omit this parameter and the the message text is
 167 then read from
 168 .I stdin
 169 (standard input stream).
 170
 171 .SH CONFIGURATION
 172 .B mdsms
 173 reads ~\fB      CONFIG_MAIN     \fP~ followed by ~\fB$HOME      CONFIG_HOME     \fP~
 174 configuration files. The content of these files (and also any file read by
 175 .BR -c | --config
 176 option)
 177 has the usual
 178 .BR getopt (3)
 179 syntax with dashes. Newlines are taken as whitespace, both double ("\fB~\fP")
 180 and single ("\fB'\fP")
 181 quoting is supported. Embedded quote characters can be escaped by backslash
 182 ("\fB\\\fP").
 183 Arguments are processes in order as specified in configuration files and
 184 finally the command-line of the program itself, overriding any previous
 185 values.  Although the order of
 186 .BR -c | --config
 187 options on one line is preserved the first file is read AFTER all of the
 188 current options are processed. Recursive use of
 189 .B -c
 190 is permitted and the files are read in LIFO (Last-In First-Out, AKA stack)
 191 order. You should use "\fB-v -v\fP"
 192 to see details of option processing with more complex configuration setups.
 193
 194 .SH OPERATION
 195 Upon startup
 196 .B mdsms
 197 locks the port (see option
 198 .BR -l | --lockfile
 199 for details) and opens the serial device with hardcoded parameters of
 200 19200 baud, software handshaking (XON/XOFF style), 8 bits, no parity.
 201 Then issues the following commands:
 202 .TP
 203 .BR AT <CTRL-Z>
 204 .B AT
 205 is used to fool MobilDock and pass the following
 206 .B <CTRL-Z>
 207 (ascii decimal code 26) character to Siemens A1 and break it from eventual
 208 .B AT+CMGS
 209 mode in which it may errorneously remain from previous sessions.
 210 .TP
 211 .B AT
 212 Test the responsiveness of Siemens A1.
 213 .TP
 214 \fBAT+CSCA="\fPsmc # from user\fB"\fP
 215 This command is omitted if
 216 .B "smsc #"
 217 is not specified by user (or specified/overriden as empty string \fB""\fP
 218 .TP
 219 \fBAT+CSCA?\fP
 220 Query the currently set SMC center number to include it later to the
 221 header of SMS PDU format where it is required. If \fBAT+CSCA="\fP...\fB"\fP
 222 was issued before, this number should match it but no sanity checks are
 223 currently do so.
 224 .TP
 225 \fBAT+CMGF=0\fP
 226 Set the default SMS message format to PDU type. Currently Siemens A1
 227 .RB "doesn't"
 228 support any other SMS format anyway.
 229 .TP
 230 \fBAT+CMGS=\fP# chars
 231 This command physically sends the message and the resulting "\fB+CMGS:\fP" output
 232 is catched and returned as
 233 .B MR
 234 (message reference) number to the user.
 235 .TP
 236 \fBAT\fP
 237 Check that Siemens A1 survived the sending of the message.
 238
 239 .SH SEE ALSO
 240 .TP
 241 .B GSM 03.40
 242 ETSI documentation for SMS messages in GSM networks
 243 .TP
 244 .B "Developers'" Guide: SMS with the A1
 245 Tech note on PDU SMS format etc:
 246 .B http:/               /www.siemens.se/telefoner/ovrigtgsm/fragorsvar/a1_sms.pdf
 247 .TP
 248 .B Technical Description of the Siemens A1
 249 Siemens A1 command description
 250 .B http:/               /www.siemens.se/telefoner/ovrigtgsm/fragorsvar/a1_manual.pdf
 251
 252 .SH FILES
 253 .TP
 254 \fB     CONFIG_MAIN     \fP
 255 Main configuration file
 256 .TP
 257 \fB$HOME        CONFIG_HOME     \fP
 258 User personalized local configuration file
 259
 260 .SH AUTHOR
 261 .B mdsms
 262 was written by Jan Kratochvil who should be responsible for all the bugs
 263 included. Please see the file "\fBAUTHORS\fP"
 264 shipped with the original distribution archive for more details.