Update for recent build tools

[mdsms.git] / mdsms.1.in

.TH MDSMS 1 "30 Oct 1999" ~     VERSION ~ "MDSMS Manual"

.\~ $Id$

.SH NAME
mdsms \- Mobile Device SMS tool

.SH SYNOPSIS
.BR "mdsms --send" [ -mobildock ]
.RB options...
.RB [ "\-f" ]
.BR "<dest. phone>"
.BR "<msg text>"
.br
.BR "mdsms --receive"
.RB options...
.BR "<command name>"
.br
.BR "mdsms --logo-send"
.RB options...
.BR "<dest. phone>"
.BR "<logo filename>"
.RB [ "<GSMnet id>" ]
.br
.BR "mdsms --ring-send"
.RB options...
.BR "<dest. phone>"
.BR "<ring filename>"
.br
options:
.RB [ "-c <cfgfile>" ]
.RB [ "-d <device>" ]
.RB [ "-L <file>" ]
.RB [ "-b <rate>" ]
.RB [ "-l <lockfile>" ]
.RB [ "-s <smsc #>" ]
.RB [ "-m <#>" ]
.RB [ "-r <sec>" ]
.RB [ "-t <msec>" ]
.RB [ "-T <msec>" ]
.RB [ "-w <sec>" ]
.RB [ "\-vhV" ]

.SH DESCRIPTION
Program sends one SmartMessaging SMS through one of the supported mobile
device connected through the serial port. Currently supported:
.RS
.TP
.B Nokia Communicator 9000/9000i
All modes except \fB--logo-send\fP/\fB--ring-send\fP supported.
.TP
.B Nokia Communicator 9110
All modes supported. This is the only device with \fB--logo-send\fP/\fB--ring-send\fP capability for now.
.TP
.B Siemens A1
Firmware revision 2.0 required. All modes except \fB--logo-send\fP/\fB--ring-send\fP supported.
These modes \fBcould\fP be supported for this device but unfortunately
.B mdsms
currently does not support it.
.TP
.B Siemens M20, M1
All modes except \fB--logo-send\fP/\fB--ring-send\fP supported.
These modes \fBcould\fP be supported for this device but unfortunately
.B mdsms
currently does not support it.
.RE

.SH OPTIONS
.TP
.BR -c | --config\  < cfgfile >
Process recursively this file and read all options from it. See the section
.B CONFIGURATION
for more information.
.TP
.BR -d | --device\  < device >
Specify serial device to communicate with your mobile. If only bare name is
specified, "\fB/dev/\fP" is prepended automatically. This device name is used
consequently with
.BR -l | --lockfile
option, see below.
.TP
.BR -L | --log\  < file >
Log all important messages to this file preceded by timestamp, machine hostname
etc., similar to output of
.BR syslogd (8).
If set to empty string (which is default - ~\fB DEF_LOGNAME     \fP~), nothing
is logged anywhere.
.TP
.BR -l | --lockfile\  < lockfile >
Prior to accessing serial device specified above the lockfile should be
acquired for correct concurrent processes behaviour. Although this name
can be given as direct filename more common method is to use pattern
with embedded "\fB%s\fP" where this mark is replaced by actual basename
(last component of pathname with all preceding directory names stripped)
of serial device used.
Default name for lockfile is ~\fB       DEF_LOCKFILE    \fP~.
.TP
.BR -b | --baud\  < rate >
Sets custom baudrate for accessing Nokia modem. Supported speeds are currently:
\fB2400\fP,
\fB4800\fP,
\fB9600\fP,
\fB19200\fP,
\fB38400\fP,
\fB57600\fP. Default is \fB     DEF_BAUD        \fP.
.TP
.BR -x | --xonxoff
Turns handshaking mode to \fBXON/XOFF\fP (also called \fBsoftware handshaking\fP).
Use this mode if you are using only 3-wire serial cable. Device should be
configured in "\fBAT+IFC=1,1\fP" mode, if \fBAT+IFC\fP command supported. When
possible, you should rather use \fBRTS/CTS\fP handshaking described in the
following paragraph. This mode is the default one.
.TP
.BR -C | --rtscts
Turns handshaking mode to \fBRTS/CTS\fP (also called \fBhardware handshaking\fP).
Use this mode if you are using full 7-wire (approx.) serial cable. Device should be
configured in "\fBAT+IFC=2,2\fP" mode, if \fBAT+IFC\fP command supported. Try
to use this mode whenever possible (instead of the default \fBXON/XOFF\fP mode described
in the previous paragraph). This mode may not be available in your UNIX flavour.
.TP
.BR -M | --smsmode
Forces the SMS mode to use - either \fBpdu\fP or \fB text\fP mode. By default
.B mdsms
tries to detect mode to use automatically, \fBPDU\fP mode is preferred. When
your modem is capable of both modes and you need for some reasone \fBtext\fP
mode, you may use \fB--smsmode text\fP argument to force it. \fBPDU\fP mode
is recommended for unattended operation, on the other side \fBtext\fP mode
should be more compatible when you have compatibility problems with unsupported
GSM modem. It is recommended to force the exact mode you will be using in
unattanded operaton. By such way you will prevent failures caused by the other
mode after possible random communication glitches (and therefore automatic
.B mdsms
switchover).
.TP
.BR -P | --pdusmscmode
Forces SMS center prepending mode for \fBPDU mode\fP operation. By default
.B mdsms
tries sequentially all the described modes, you should lock it for
unattanded operation to prevent vain switchovers from random communication
glitches (also you will notice faster response for "\fBcount-out\fP" or
"\fBnone\fP" modes):
.RS
.TP
.BR count-in
The default mode, SMS center is prepended to the \fBPDU\fP and SMS
.RB "center's"
length is taken into account during length calculation for "\fBAT+CMGS=\fP#".
.TP
.BR count-out
SMS center is prepended to the \fBPDU\fP but SMS
.RB "center's"
length is omitted
during length calculation for "\fBAT+CMGS=\fP#".
.TP
.BR none
SMS center is \fBNOT\fP prepended to the \fBPDU\fP, SMS center to use by
GSM modem is taken from the one set by
\fBAT+CSCA="\fPsmsc # from user\fB"\fP
command.
.RE
.TP
.BR -s | --smsc\  < smsc\ # >
Specify custom SMS center number. If not specified (or overriden as empty
string by \fB-s ""\fP)
.B mdsms
asks by "\fBAT+CSCA?\fP"
for the current default SMS center. Situation with undeterminable SMS center
is unrecoverable and causes immediate fail. Please contact your GSM operator
customer service if you are in trouble. It is a common practice to use
plus sign ("\fB+\fP") to indicate international number type.
Known SMS centers as of April 2001:
.RS
.TP
.BR "CZ Paegas  " ( "230 01" "): " +420603052000
.TP
.BR "CZ EuroTel " ( "230 02" "): " +420602909909
.TP
.BR "CZ Oskar   " ( "230 03" "): " +420608005681
.RE
.TP
.BR -m | --maxretry\  < # >
Maximum retries of any \fBAT\fP-style command during the session. All the
retries are summed during one run of
.B mdsms
and no more retries of the command are permitted. After exceeding this
value the program is terminated. Exception is \fB--receive\fP which is never
quit after the initial initialisation has been successfuly negotiated.
.TP
.BR -r | --readtime\  < sec >
Maximum response read timeout before command retry.
.B mdsms
sends the requested \fBAT\fP-style command to the device and expects response.
After exceeding this time interval,
.B mdsms
reissues the last command until the maximum retry count (\fBmaxretry\fP) is exhausted.
Standard value is
.BR DEF_READTIME
seconds and should be enough for standard
.B mobiles
responses. This is the only point where
.B --send-mobildock
differs the behaviour from regular
.B --send
option. Unfortunately when
.B MobilDock
has a voice call in progress, it will block any serial device
communication with \fBSiemens A1\fP and it is impossible to differentiate between call-in-progress
.B MobilDock
and stucked/disconnected one, so the parameter
.B readtime
has very large value, see further. After exceeding this time interval,
.B mdsms
is terminated immediately,
.B maxretry
parameter notwithstanding. Standard value of this parameter is
.BR DEF_READTIME_MOBILDOCK
seconds and should be enough for any voice call.
.TP
.BR -t | --chartime\  < msec >
\fB(This paragraph\fP
.BR "doesn't"
\fBapply to Nokia 9110 or similiar smart devices but the functionality has been
retained just to be on the safe side.)\fP
Although the fixed used baudrate of
.B 19200
is pretty low, MobilDock/Siemens A1 couple
.RB "aren't"
able to accept steady
stream of data at this speed. Even the used XON/XOFF handshaking is just not
enough. The only possible workaround is to slowdown the communication by
waiting a bit after character sent to give relax time to these devices.
When full rate communication was used, occasional longer SMS data corruption
was observed. Argument is given in milliseconds and its default value is
.BR DEF_CHARTIME ms.
.TP
.BR -T | --cmdtime\  < msec >
\fB(This paragraph\fP
.BR "doesn't"
\fBapply to Nokia 9110 or similiar smart devices but the functionality has been
retained just to be on the safe side.)\fP
This delay is given before sending any
.B AT-style
command to the device.
Its primary purpose is to let any previous entered commands to finish and
to clear any input before actually sending our own command. Also all Siemens
devices are known that they strongly dislike fast edge-to-edge communication
and to satisfy these requirements this delay was considered as the best
approach.
The default value is
.BR DEF_CMDTIME ms.
.TP
.BR -w | --waittime\  < sec >
This delay is maximum time allowed silently waiting for incoming data.
After approx 30 minutes of waiting for Nokia 9110 data it will turn off
its FaxModem feature disabling any further reading of messages.
After such idle time \fBmdsms\fP will also reinitialize the modem to
handle the case where the modem was silently powercycled in the meanwhile
loosing its initial settings done by \fBmdsms\fP during its startup.
The default value is
.BR DEF_WAITTIME s.
.TP
.BR -f | --file
When parameter <\fBmsg text\fP> has been specified, by using this option
\fBmdsms\fP will read the file with the <\fBmsg text\fP> filename instead
and send its \fBcontents\fP as the SMS message.
This parameter is applicable only together with \fB--send\fP or \fB--send-mobildock\fP mode.
.TP
.BR -v | --verbose
Increase verbosity level by one. Currently the maximum defined level is
.BR 3 ,
the default value is
.BR 0 .
.TP
.BR -h | --help
Give short parameters description to
.I stderr
(standard error output stream).
.TP
.BR -V | --version
Print the version number and exit.
.TP
.RB < "dest. phone" >
This mandatory parameter specifies the telephone number of the recipient
of SmartMessaging message. International prefix character plus
.RB ( + )
is supported the national mode without plus
.RB ( + )
prefix is supported and the meaning is specific to the GSM operator currently
being roamed in (NOT the native
.RB "'home'"
operator of the SIM card!).
This number can be made default in system configuration files, see below
for section
.BR CONFIGURATION .
.TP
.RB < "msg text" >
Here you write the exact body of the message. This parameter should be
specified only as one component, although if more found they are concatenated
with separating space (" "). But this practice is discouraged as
your shell will probably remove any multiple spaces found and also other
metacharacters may be incorrectly interpreted. To prevent any escaping
mess, you may prefer to omit this parameter and the the message text is
then read from
.I stdin
(standard input stream).
This parameter is applicable only together with \fB--send\fP or \fB--send-mobildock\fP mode.
.TP
.RB < "logo filename" >
Here you specifify the filename of the logo file to be uploaded. Currently
recognized file formats are \fBNOL\fP (Nokia logo?) and \fBNGG\fP (Nokia
Group Graphics). These formats are proprietary by \fBKESSLER Wireless Design\fP
and \fBmdsms\fP currently "can't" edit them.
This parameter is applicable only together with \fB--logo send\fP mode.
More info can be found on:
.RS
.B http:/       /www.kessler-design.com/wireless/operatorlogo.php3
.RE
.TP
.RB < "GSMnet id" >
Specify GSM network code to be set on the logo being uploaded. Upon upload to
Nokia phone each operator logo has a GSM network code binded with it. When
you are registered (even roamed) into such network the logo is displayed on
the phone. Current Nokia mobile phones can handle only one logo loaded
simultaneously, it will be rewritten by any other upload. You can also
specify string ~\fB     WORD_GROUP      \fP~ to send the logo as group graphics
(even from \fBNOL\fP format) or string ~\fB     WORD_NET        \fP~ to force detection
of network code from \fBNOL\fP. The default if this parameter is not specified
is ~\fB WORD_NET        \fP~ for \fBNOL\fP files and ~\fB       WORD_GROUP      \fP~ for
\fBNGG\fP files.
This parameter is applicable only together with \fB--logo send\fP mode.

.SH CONFIGURATION
.B mdsms
reads ~\fB      CONFIG_MAIN     \fP~ followed by ~\fB$HOME      CONFIG_HOME     \fP~
configuration files. The content of these files (and also any file read by
.BR -c | --config
option)
has the usual
.BR getopt (3)
syntax with dashes. Newlines are taken as whitespace, both double ("\fB~\fP")
and single ("\fB'\fP")
quoting is supported. Embedded quote characters can be escaped by backslash
("\fB\\\fP").
Arguments are processes in order as specified in configuration files and
finally the command-line of the program itself, overriding any previous
values.  Although the order of
.BR -c | --config
options on one line is preserved the first file is read AFTER all of the
current options are processed. Recursive use of
.B -c
is permitted and the files are read in LIFO (Last-In First-Out, AKA stack)
order. You should use "\fB-v -v\fP"
to see details of option processing with more complex configuration setups.

.SH OPERATION
Upon startup
.B mdsms
locks the port (see option
.BR -l | --lockfile
for details) and opens the serial device with specified baudrate (default
\fB     DEF_BAUD        \fP baud), software handshaking (XON/XOFF style), 8 bits,
no parity. Then issues the following commands:
.TP
.BR AT <ESCAPE><CTRL-Z>
.B AT
is used to fool
.B MobilDock
(if present, otherwise it is harmlesss anyway) and pass the following
.B <ESCAPE><CTRL-Z>
(ascii decimal code 27 followed by 26) characters to the device and break it from eventual
.B AT+CMGS
mode in which it may errorneously remain from previous sessions.
.TP
.B AT
Test the responsiveness of the device.
.TP
\fBAT+CSCA="\fPsmsc # from user\fB"\fP
This command is omitted if
.B "smsc #"
is not specified by user (or specified/overriden as empty string \fB""\fP
.TP
\fBAT+CSCA?\fP
Query the currently set SMS center number to include it later to the
header of SMS PDU format where it is required. If \fBAT+CSCA="\fP...\fB"\fP
was issued before, this number should match it but no sanity checks are
currently do so. Also it is used to detect possibly unset SMS center.
.TP
.RB "Mode-dependent."
Here are executed the commands listed for each of the specified operation
mode separately.
.TP
\fBAT\fP
Check that the mobile survived our torture.

.TP
The following operations are dependant on the operation:
.TP
.BR --send / --send-mobildock :
.RS
.TP
\fBAT+CMGF=0\fP, if fails \fBAT+CMGF=1\fP
Set the default SMS message format to PDU type (preferred) or text mode (if
PDU not available). Next \fB+CMGS\fP command is dependant on the mode selected
by this one.
.TP
\fBAT+CMGS=\fP# chars if \fB+CMGF=0\fP
This command physically sends the message and the resulting "\fB+CMGS:\fP" output
is catched and returned as
.B MR
(message reference) number to the user. \fB# chars\FP corresonds to total data
bytes sent to the phone (so the half of the hex-string, SMSC is included).
SMSC number is preceding the rest of PDU to be conformant with GSM Phase 2
specification. Siemens M1 or Siemens M20 rev. 1.x are known that
.RB "don't"
like this SMSC number, I have to get in touch with such device to be able to autodetect
it properly (mail me if you want to be helpful).
.TP
\fBAT+CMGS="\fPphone # from user\fB"\fP if \fB+CMGF=1\fP
The same as the previous command except that the message is text as pure text
terminated with \fB<CTRL-Z>\fP character. SMSC number is not present anywhere
in this mode.
.RE
.TP
.BR --logo-send / --ring-send :
.RS
.TP
\fBAT+CSMP=81,,0,245\fP
Sets PDU type to 81 (\fBSMS-SUBMIT\fP + integer-type for \fBvalidity\fP
+ \fBUDHI\fP - user data header indicator), PID (protocol identifier) to
0 (standard non-converted SMS) and DCS (data coding scheme) to 0xF5
(\fBdata coding\fP/\fBmessage class\fP, \fB8-bit data\fP + \fBmobile-equipment\fP
specific).
.TP
\fBAT+CMGS="\fPphone # from user\fB"\fP
This command physically sends the message and the resulting "\fB+CMGS:\fP" output
is catched and returned as
.B MR
(message reference) number to the user.
.TP
\fBAT+CSMP=17,,0,0\fP
Resets back PDU type to 17 (\fBSMS-SUBMIT\fP + integer-type for \fBvalidity\fP),
PID (protocol identifier) to 0 (standard non-converted SMS) and DCS (data coding
scheme) to 0 (\fBalphabet indication\fP, \fBdefault 7-bit alphabet\fP).
.RE
.TP
.BR --receive :
Receiving of messages is performed using direct routing of incoming data to TE (Terminal Equipment).
No SMSes are stored to SIM card/device memory and then read back as one may expect.
There are slight advantages of better response times (SIM card access is very slow) and
saving EEPROM writes to SIMcard. Unfortunately there is one big advantage that when
.B mdsms
suddenly stops/crashes without switching the device back to SIM-store mode, messages
being consequently received are lost on the dead end of serial port.
.B mdsms
tries very hard to restore the device state before its termination but sometimes it just
.RB "isn't"
possible. Due to this fact \fBnever kill mdsms with SIGKILL (-9) signal\fP, use standard
SIGTERM instead, please. Also one fact resulting of this behaviour is that messages
with Class-2 (SIM store) specific routing are really stored to SIM card and as such are
not processed in any way by
.BR mdsms .
Safer SIM store/retrieve mechanism may be implemented in future versions. Command sequence used in
.B --receive
mode follows:
.RS
.TP
\fBAT+CMGF=0\fP, if fails \fBAT+CMGF=1\fP
Set the default SMS message format to PDU type (preferred) or text mode (if
PDU mode not available).
.TP
\fBAT+CNMI=,2\fP
Set the message routing to go directly to TE (Terminal Equipment), see the discussion
in paragraph above for more. Also right before starting attempt to send this command,
\fBAT+CNMI=,0\fP is set to be tried before finishing
.BR mdsms
to restore the original device behaviour.
.TP
\fBAT+CSDH=0\fP
We
.RB "aren't"
really much interested in additional non-standard values of
PID (Protocol IDentifier), DCS (Data Coding Scheme) etc.
.TP
data wait
In this point the device lock file is removed, retry count is set to infinite value
(see discussion in
.B --maxretry
parameter) and
.B mdsms
starts to passively listen for any incoming data. Possible dial-out mode is being
detected afterwards, otherwise message receive sequence follows as described below.
.TP
\fB+CMT:\fP read
Any waiting \fB+CMT\fP incoming message indications are read and processed. Format
being processed (text/PDU) depends on the actual value of \fBAT+CMGF\fP set before. Any
possible \fB+CMTI:\fP input is discarded as we are not interested in SIM-store
directed messages.
.TP
receive restart
After processing all the messages, the whole initialization sequence is restarted as
the device configuration may have changed or lost during the data wait phase.
.RE

.SH SEE ALSO
.TP
.B GSM 03.40
ETSI documentation for SMS messages in GSM networks
.TP
.B GNokii, tools and drivers for Nokia mobile phones
Nokia logo data format was read from its sources:
.B http:/       www.gnokii.org/
.TP
.B "Developers'" Guide: SMS with the A1
Tech note on PDU SMS format etc:
.B http:/               /www.siemens.se/telefoner/ovrigtgsm/fragorsvar/a1_sms.pdf
.TP
.B Technical Description of the Siemens A1
Siemens A1 command description
.B http:/               /www.siemens.se/telefoner/ovrigtgsm/fragorsvar/a1_manual.pdf

.SH FILES
.TP
\fB     CONFIG_MAIN     \fP
Main configuration file
.TP
\fB$HOME        CONFIG_HOME     \fP
User personalized local configuration file

.SH AUTHOR
.B mdsms
was written by Jan Kratochvil who should be responsible for all the bugs
included. Please see the file "\fBAUTHORS\fP"
shipped with the original distribution archive for more details.