mdsms.1.in

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