samsemd - a Short Message sender and receiver daemon
samsemd -C configfile [-l logfile] [-V] [-F] [-d]
samsemd is a daemon sending and receiving GSM short messages (SMS). It uses a subset of AT+C command set of your GSM device. (See http://www.sztaki.hu/~kissg/gsm.) You need a GSM device like Siemens M20, Falcom A2, Nokia Card Phone or other.
This program may be used to build a bidirectional E-mail-SMS gateway.
If you want only to send a lot of messages but not receive you may use
the more robust command line utility
samsem(1) instead of this daemon.
Upon startup program forks. The parent process is called master the child is the slave.
Master process exits or keeps the controlling terminal. See OPTIONS below.
Slave process detaches itself from the controlling
terminal and acquires the serial line as new controlling
terminal. In that way slave receives a hangup signal when GSM box
has a power fail or serial cable is disconnected. Note: You
have to instruct your GSM box manually via a terminal emulator program
to keep Carrier Detect line always high. Usually this can be done by
AT&C0 command. (Don't forget to make this change permanent
After the initialization steps the daemon waits for status reports from the GSM device. These reports usually indicate incoming messages. The program waits until
a status report comes from the GSM device, or
it receives a USR1 signal (tipically from the spooler program), or
60 seconds of time passes.
In any case the program checks the spool directory (see Spooldir), it processes all the job files found there (see JOB FILES below), finally it processes the status reports of GSM devices. Then the program restarts the waiting.
The name of configuration file. See CONFIGURATION FILE below.
The name of the logfile. This option overrides the logfile given in config file.
Foreground mode. The master process does not exit but holds the controlling terminal. It accepts keyboard generated signals and delivers them to the slave. Slave process directs diagnostic messages to the master's controlling terminal.
Same as -F -l
/dev/tty -F. (Obsoleted option.)
Verbose operation. Produces a lot of log including the serial port traffic. It is just for debugging purposes.
The configuration file contains various parameters of your hardware and software environment, GSM network, and other options.
Blank lines and lines whose first character is a pound-sign (#) are ignored. Other lines are of the form,
keyword = value
Keywords are case insensitive. Any whitespace characters around keyword and value are ignored. The possible keywords are
Type of your GSM module like siemensm1, siemensa1, falcoma1, falcoma2, nokiaphonecard, nokiadatacard or auto. See samsem.pl for the actual list and further details.
The number of SMS center. This number is given by your network operator.
Call the Help Desk if you don't know it. This number must be
in international format, i.e. it must begin with +country_code.
You may put any number of spaces and dashes (-) between the digits
to increase the readability. E.g.
+36 30 9-888-000.
The serial port where your GSM device is connected. E.g.
NOTE: always use the callout logical device (e.g. /dev/cua0)
instead of its callin counterpart (/dev/ttyS0).
The speed of your serial port in bps. The default value is 9600. NOTE: Some devices (e.g. FALCOM A1) cannot recognize the DTE speed automatically and you must ensure the matching speed of your computer and GSM device.
The Personal Identification Number of your SIM card.
The daemon checks PIN settings at every startup and enters PIN
if necessary. NOTE: Your device usually requires the PIN after every
power-on but you may discard this feature using the
The time interval till the SMS center holds your message before
discarding. If the destination of the message is unreachable the SMS
center stores the message until it becames deliverable or the specified
period passes. In theory the validity period may be from 5 minutes
up to 63 weeks but SMS centers usually limits this time much lower.
(Ask your network operator for the actual upper limit.) The value
is a real number followed immedialy by one of the
letters. (They means minutes, hours, days, weeks respectively.)
3.5d. This parameter is just a default for spooled messages
whose validity period is not specified by the spooler program.
If neither the spooled job nor the config file specifies the validity
period the global setting of the SMS center will be applied.
The directory where the daemon looks for spooled outgoing messages. You must create this dir before starting the daemon and you must ensure write access to this dir for the daemon as well as the spooler program. (Actually I didn't think over yet how could more than one user send messages safely. So some security problems may arise about access rights.) The daemon puts his pidfile into the spool directory so the spooler program can figure out the daemon's PID and can send signals to it.
Your GSM device can receive and store incoming messages while the daemon is not running. At startup time the daemon scans the memory for these old messages and process them as they were fresh ones unless this option is set to no or false (case insensitively). NOTE: messages marked as STORED UNSENT and STORED SENT are not affected by this operation.
An external program that will be started every time when a message is arrived. It will run with the rights of the daemon. The daemon sets four environment variables before executing the program. Variables SMS_TIME, SMS_FROM, SMS_MSG hold the time stamp of the message (in the form of yyyy/mm/dd hh:mm:ss), the sender's phone number, and the message itself respectively. The message is subject of some character transformation. See functions map_chars() and unmap_chars() in file sms.pl for details. The value of the fourth variable SMS_STATUS may be OLD or NEW depending on whether the message found in the memory of the GSM device at startup time or just arrived. See Cleanup. A sample entry:
User_Hook=echo t=$SMS_TIME f=$SMS_FROM m=$SMS_MSG >> /tmp/sms
The command line will be passed to
sh(1) so it will undergo the usual
things: variable expansion, command substitution, quote removal, etc.
The daemon logs messages and other major events into this file. No logging allowed if this parameter omitted.
Name of the phonebook file. It should contain an absolute path. Phonebook file is a plain text file. Lines beginning with # are ignored as well as blank lines. Other lines must contains
pairs. Names cannot contain whitespaces and are case insensitive. A number from the job file will be searched in the left column of the phonebook and it will be replaced with the rest of the line if matches.
Outgoing messages have to be put into job files in the spool directory.
The file names must match regular expression
These files contain lines with keyword value pairs those are
separated with whitespace(s). Keywords are case sensitive.
Known keywords are
The message class. It may be 0, 1, 2, 3 or default. Delivery mode of the message depends on this value and the receiver GSM phone. As far as I know the following classes are defined:
class0: immediate display class1: Mobile Equpment specific class2: SIM specific class3: Terminal Equipment specific
Tests show that different mobile phones deliver messages of different classes in a different way. E.g. message is displayed immediately but not stored, or message is stored silently without any sound signal. This the mode of delivery heavily depends on the type of destination phone too. Therefore using other than the default class is discouraged except if you know what do you do.
The destination number. It may be a phone number in international or national format or it may be a name from the phone book.
Currently has no effect.
Validity period for this message. This item overrides the global VP specified in the configuration file. See the syntax and semantics at Valid.
The message itself. This entry must be the last one in the job file.
Any lines up to the end of file included in the message. Continuation
lines will be separated by
CR LF pairs.
Syntax of the job files is quite rigid. Fortunately you have not to create them manually. There is a command line utility called spoolmsg to make job files.
Warning: Do NOT run samsem while samsemd is running. Concurrent access to GSM device causes unpredictable result.
After creating the job file with the well-formed (and unique) name spoolmsg sends a USR1 signal to the daemon indicating that there is a new job in the spool. However this is not required because the daemon checks the spool at least once per 60 seconds. So you may spool job files of your own.
samsemd.conf.sample Sample configuration file phonebook.sample Sample phonebook file SPOOLDIR/samsemd.pid Pidfile SPOOLDIR/send.* Job files chat3.pl Modified chat2.pl sms.pl SMS related subroutines samsem.pl Other subroutines
I found, that under certain circumstances Siemens M1 (and maybe other devices) can hang up. No I/O operations are executed in this frozen state. The daemon detects this situation and aborts after logging the error. You have to turn off the GSM module to reset it. Be careful if you want to use this hardware in mission critical applications.
This manual is written in Tarzan-English.
Gabor Kiss <email@example.com>
This software is copylefted.
This software is in the public domain. This software is distributed with no warranty whatever. The author takes no responsibility for the consequences of its use.