ie.ncl.sms.modem
Class GsmModem

java.lang.Object
  ie.ncl.msg.impl.SimpleConnection
      ie.ncl.sms.modem.GsmModem

All Implemented Interfaces:

AttributeNames, Connection, Receiver, Sender, MessageAttributeNames, java.lang.Runnable

public class GsmModem
extends ie.ncl.msg.impl.SimpleConnection
implements Sender, Receiver, java.lang.Runnable, MessageAttributeNames

This class is used to establish a connection with a GSM modem device, which can be used to send and receive short messages.

IMPORTANT: Unless you are performing some GSM Modem specific operation it is best to use the ie.ncl.msg.Factory class to create instances of the GsmModem. This allows you to dynamically create transport independent software applications.

The Factory properties used by GsmModem configuration are:-

NAME	VALUE	DEFAULT
class	The name of the implementing class - ie.ncl.sms.modem.GsmModem	mandatory
pin	The PIN of the cellular device (string).	optional
type	The type of cellular device (string). This can be one of; m20 tc35 mc35 premicell nokiacard a2 sonye 6310 s45 sl45 gm29 6310i	mandatory
deliveryReports	Are delivery reports turned on	optional - false by default
sendRetries	Number of times a message should be retried if sending it fails (number).	optional - 3 retries by default
sendRetryPauseSeconds	The pause between retries (number of seconds)	optional - 1 second by default
signalStrengthThreshold	Specifies the signal strength threshold (number). A warning is printed if the strength goes below this value.	optional - defaults to 10 of 30.
smsc	Specifies the SMSC address (number)	optional
ownNumber	Specifies the number of the modem.	mandatory
loopbackAllowed	Specifies if a loop-back messages are allowed (true/false). Sometimes it can be dangerous to allow an application to send a message to itself as an infinite loop may occur which can be costly.	mandatory
defaultTon	The default type of number (TON) set on out going messages addresses (number)	optional - not used by default
defaultNpi	The default number plan indicator (NPI) set on out going messages addresses (number)	optional - not used by default
type	The type of connection. This can be 'serial' in which case direct RS232 communication is established, or 'ip' in which case RAS server is used and accessed over IP.	mandatory
host, port	Only if type is 'ip'. This specifies the host and port of the RAS server	depends on type
device, speed	Only if type is 'serial'. This specifies the device such as COM1, COM2 (or /dev/ttyS0, /dev/ttyS1 for Linux) and the baud speed such as 9600, 19200 etc.	depends on type

GSM modem devices must be GSM 07.07 and GSM 07.05 compliant. See ETSI for more information on these specifications.

The class implements the SMSSender and SMSReceiver interfaces, so applications can achieve transport independence from the underlying devices used.

Both the Siemens M20 and the Falcom A1 terminal devices implement the necessary ETSI specifications for this object to interoperate with. Specification are available from the respective device manufacturers. The specifications (like the forementioned ETSI specifications) detail the AT command structures used to communicate SMSs to/from the device.

IMPORTANT: to use the GsmModem(pin,host,port) you must have a TCP/IP to RS232 gateway software. See NCL's ComGate communication gateway software.

Note some discrepancies were found using the Sent PDU (DeliverSM) mode. On the Siemens M20 no service centre address needs be specified in the at+cmgs command. On the Falcom A1 it was indicated that it should be a 'zero length' 4.11 address. But all zero length addresses are 2 bytes minimum! (1 byte to indicate the length is zero, the other byte indicates the type of address).

See Also:

Factory

Field Summary

static int	INIT_TIMER
int	resetTimeout
int	RESPONSE_TIMEOUT
static int	SEND_RESPONSE_TIMEOUT
static int	SIGNAL_STRENGTH_MAX Maximum signal strength is index 31 (-51 DBs).
static int	SIGNAL_STRENGTH_MIN Minimum signal strength is index 0 (-113 DBs).
static int	SIGNAL_STRENGTH_UNKNOWN Unknown signal strength value.
static ie.ncl.sys.ModuleLog	staticLog

Fields inherited from interface ie.ncl.msg.Connection

CONNECTED, NOT_CONNECTED, NOT_USED, RECONNECTING

Fields inherited from interface ie.ncl.sms.MessageAttributeNames

CC, DCS, EOT_GSM_ESCAPE_CHARACTER, PID, PRIORITY, RECEIPT, RECEIPT_BYTES, RECEIPT_STATUS, RECEIPT_TEXT, REGISTERED, REPLACE, REPLY_PATH, SCA, SCHEDULE, SUBMIT_ERROR, TIMESTAMP, UDH, UDHI, VALIDITY

Constructor Summary

GsmModem()

GsmModem(java.lang.String pin, java.io.InputStream in, java.io.OutputStream out, boolean testing)
Create a new Gsm Modem object specifying the input and output streams.

GsmModem(java.lang.String pin, java.lang.String host, int port)
Create a new Gsm Modem object specifying a the IP address of a TCP/IP to RS232 gateway.

GsmModem(java.lang.String pin, java.lang.String comPortDevice, java.lang.String speed)
Create a new Gsm Modem object specifying a the IP address of a TCP/IP to RS232 gateway.

GsmModem(java.lang.String pin, java.lang.String comPortDevice, java.lang.String speed, boolean testing)

Method Summary

void	acknowledge(Message m, boolean success) Acknowledge messages - Not implemented as messages are acknowledged immediately.
static java.lang.String	clean(java.lang.String s)
void	close() Close down the connection with the GsmModem device.
void	connect() Connect with the device.
ie.ncl.util.bin.Bytes	constructPDU(Message m)
static ie.ncl.util.bin.Bytes	constructSmsDeliver(Message m)
static ie.ncl.util.bin.Bytes	constructSmsSubmit(Message m)
static ie.ncl.util.bin.Bytes	constructTpud(Message m)
static GsmModemConfiguration[]	detect()
void	enableDeliveryReporting()
static GsmModemConfiguration[]	find()
GsmModemConfiguration	getConfiguration()
static GsmModem	getDefault() Get the default GsmModem object.
boolean	getDefaultToGsmAlphabet() This indicates that the Gsm Default Alphabet is used when encoding 7bit messages (in accordance with data coding scheme).
java.lang.String	getIMEI() Get the modem model.
boolean	getLoopbackAllowed() This attribute allows the modem to send messages to itself.
java.lang.String	getMake()
java.lang.String	getMakeModel() Get the modem make and model concatenated with a single space in between.
java.lang.String	getModel() Get the modem model.
Address	getOwnNumber() Get this modem's telephone number.
int	getSendRetries() This is used to specify how many times to attempt sending a message if an error occurs.
int	getSendRetryPause() This is used to specify how many times to attempt sending a message if an error occurs.
int	getSignalStrength() This returns the signal strength which is a decibel reading between SIGNAL_STRENGTH_MIN and SIGNAL_STRENGTH_MAX or is SIGNAL_STRENGTH_UNKNOWN if this is not defined.
int	getSignalStrengthThreshold() Set the signal strength threshold.
java.lang.String	getVersion() Get the modem version.
void	init(java.util.Properties props) Initialise the object with settings specified in the properties.
boolean	isMakeModel(java.lang.String mm) Check to see that this make an model matches the one specified.
static void	main(java.lang.String[] args)
void	receive(ReceiverListener receiver) Receive messages asynchronously.
void	run()
void	send(Message m, SenderListener listener) Send a message asynchronously.
static void	setDebugMode(boolean on) Turn debug on (true) or off (false).
static void	setDefault(GsmModem f) Set the default GsmModem object.
void	setDefaultToGsmAlphabet(boolean val) This indicates that the Gsm Default Alphabet is used when encoding 7bit messages (in accordance with data coding scheme).
void	setGPRS(GPRSSettings gprs)
void	setLoopbackAllowed(boolean yn) This allows the modem to send messages to itself.
void	setOwnNumber(Address dest) Sets this modem's telephone number.
void	setReceiverListener(ReceiverListener listener) Receive messages asynchronously.
void	setSendRetries(int newval) This is used to specify how many times to attempt sending a message if an error occurs.
void	setSendRetryPause(int newval) This is used to specify how many times to attempt sending a message if an error occurs.
void	setSignalStrengthThreshold(int sst) Get the signal strength threshold.
void	setSmsc(java.lang.String addr) Set the SMSC message centre number.
void	shutdown() Shutdown the connection.

Methods inherited from class ie.ncl.msg.impl.SimpleConnection

connected, getConnectionStatus, getErrorListener, getName, getTypeDefaults, init, mergeDefaultAttributes, putTypeDefaults, setErrorListener, setName

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ie.ncl.msg.Connection

connected, getConnectionStatus, getTypeDefaults, init, putTypeDefaults, setErrorListener

Field Detail

SIGNAL_STRENGTH_MAX

public static final int SIGNAL_STRENGTH_MAX

Maximum signal strength is index 31 (-51 DBs).

See Also:

getSignalStrength(), Constant Field Values

SIGNAL_STRENGTH_MIN

public static final int SIGNAL_STRENGTH_MIN

Minimum signal strength is index 0 (-113 DBs).

See Also:

getSignalStrength(), Constant Field Values

SIGNAL_STRENGTH_UNKNOWN

public static final int SIGNAL_STRENGTH_UNKNOWN

Unknown signal strength value.

See Also:

getSignalStrength(), Constant Field Values

RESPONSE_TIMEOUT

public int RESPONSE_TIMEOUT

SEND_RESPONSE_TIMEOUT

public static final int SEND_RESPONSE_TIMEOUT

See Also:

Constant Field Values

INIT_TIMER

public static final int INIT_TIMER

See Also:

Constant Field Values

resetTimeout

public int resetTimeout

staticLog

public static ie.ncl.sys.ModuleLog staticLog

Constructor Detail

GsmModem

public GsmModem(java.lang.String pin,
                java.lang.String comPortDevice,
                java.lang.String speed)
         throws java.io.IOException,
                GsmModemException

Create a new Gsm Modem object specifying a the IP address of a TCP/IP to RS232 gateway.

Throws:

java.io.IOException

GsmModemException

GsmModem

public GsmModem(java.lang.String pin,
                java.lang.String comPortDevice,
                java.lang.String speed,
                boolean testing)
         throws java.io.IOException,
                GsmModemException

Throws:

java.io.IOException

GsmModemException

GsmModem

public GsmModem()

GsmModem

public GsmModem(java.lang.String pin,
                java.lang.String host,
                int port)
         throws java.io.IOException,
                GsmModemException

Create a new Gsm Modem object specifying a the IP address of a TCP/IP to RS232 gateway.

Throws:

java.io.IOException

GsmModemException

GsmModem

public GsmModem(java.lang.String pin,
                java.io.InputStream in,
                java.io.OutputStream out,
                boolean testing)
         throws java.io.IOException,
                GsmModemException

Create a new Gsm Modem object specifying the input and output streams. This constuctor should be used when dealing with a RS232 serial device directly.

To communicate directly with a RS232 device you will need the JavaComm 2.0 package (or later) available from java.sun.com.

Throws:

java.io.IOException

GsmModemException

Method Detail

enableDeliveryReporting

public void enableDeliveryReporting()

setLoopbackAllowed

public void setLoopbackAllowed(boolean yn)

This allows the modem to send messages to itself. The modem address must be set for this to be effective. While this is OK for testing in theory it is dangerous particularly in an application that automatically replies to messages. Such an application could potentially end up in an infinite loop transmitting messages continually to at considerable expense.

See Also:

getLoopbackAllowed(), getOwnNumber()

getLoopbackAllowed

public boolean getLoopbackAllowed()

This attribute allows the modem to send messages to itself. The modem address must be set for this to be effective. While this is OK for testing in theory it is dangerous particularly in an application that automatically replies to messages. Such an application could potentially end up in an infinite loop transmitting messages continually to at considerable expense.

See Also:

setLoopbackAllowed(boolean), setOwnNumber(ie.ncl.msg.Address)

setDefaultToGsmAlphabet

public void setDefaultToGsmAlphabet(boolean val)

This indicates that the Gsm Default Alphabet is used when encoding 7bit messages (in accordance with data coding scheme).

getDefaultToGsmAlphabet

public boolean getDefaultToGsmAlphabet()

This indicates that the Gsm Default Alphabet is used when encoding 7bit messages (in accordance with data coding scheme).

init

public void init(java.util.Properties props)
          throws ConnectionException

Description copied from interface: Connection

Initialise the object with settings specified in the properties. The properties will be implementation specific.

Specified by:

init in interface Connection

Throws:

ConnectionException

connect

public void connect()
             throws ConnectionException

Connect with the device.

Specified by:

connect in interface Connection

Throws:

ConnectionException

setOwnNumber

public void setOwnNumber(Address dest)

Sets this modem's telephone number. This will be used to as the destination of each received message. It will be also used to detect loopback messages.

See Also:

getOwnNumber(), getLoopbackAllowed()

getOwnNumber

public Address getOwnNumber()

Get this modem's telephone number. This will be used to as the destination of each received message. It will be also used to detect loopback messages.

See Also:

setOwnNumber(ie.ncl.msg.Address), setLoopbackAllowed(boolean)

getConfiguration

public GsmModemConfiguration getConfiguration()

getDefault

public static GsmModem getDefault()

Get the default GsmModem object.

setDefault

public static void setDefault(GsmModem f)

Set the default GsmModem object.

setDebugMode

public static void setDebugMode(boolean on)

Turn debug on (true) or off (false).

clean

public static java.lang.String clean(java.lang.String s)

setGPRS

public void setGPRS(GPRSSettings gprs)
             throws java.io.IOException

Throws:

java.io.IOException

getIMEI

public java.lang.String getIMEI()
                         throws GsmModemException,
                                java.io.IOException

Get the modem model.

Throws:

GsmModemException

java.io.IOException

getMake

public java.lang.String getMake()
                         throws GsmModemException,
                                java.io.IOException

Throws:

GsmModemException

java.io.IOException

getVersion

public java.lang.String getVersion()
                            throws GsmModemException,
                                   java.io.IOException

Get the modem version.

Throws:

GsmModemException

java.io.IOException

getModel

public java.lang.String getModel()
                          throws GsmModemException,
                                 java.io.IOException

Get the modem model.

Throws:

GsmModemException

java.io.IOException

getMakeModel

public java.lang.String getMakeModel()
                              throws GsmModemException,
                                     java.io.IOException

Get the modem make and model concatenated with a single space in between.

Throws:

GsmModemException

java.io.IOException

See Also:

isMakeModel(java.lang.String)

isMakeModel

public boolean isMakeModel(java.lang.String mm)
                    throws GsmModemException,
                           java.io.IOException

Check to see that this make an model matches the one specified.

Throws:

GsmModemException

java.io.IOException

send

public void send(Message m,
                 SenderListener listener)
          throws MessageException,
                 ConnectionException

Send a message asynchronously.

Specified by:

send in interface Sender

Throws:

MessageException

ConnectionException

See Also:

SenderListener, Message

receive

public void receive(ReceiverListener receiver)
             throws ConnectionException

Receive messages asynchronously.

Specified by:

receive in interface Receiver

Throws:

ConnectionException

See Also:

Message

setReceiverListener

public void setReceiverListener(ReceiverListener listener)
                         throws ConnectionException

Receive messages asynchronously.

Specified by:

setReceiverListener in interface Receiver

Throws:

ConnectionException

See Also:

Message

acknowledge

public void acknowledge(Message m,
                        boolean success)

Acknowledge messages - Not implemented as messages are acknowledged immediately.

Specified by:

acknowledge in interface Receiver

setSendRetries

public void setSendRetries(int newval)

This is used to specify how many times to attempt sending a message if an error occurs.

See Also:

getSendRetries()

getSendRetries

public int getSendRetries()

This is used to specify how many times to attempt sending a message if an error occurs.

See Also:

setSendRetries(int)

setSendRetryPause

public void setSendRetryPause(int newval)

This is used to specify how many times to attempt sending a message if an error occurs.

See Also:

getSendRetryPause()

getSendRetryPause

public int getSendRetryPause()

This is used to specify how many times to attempt sending a message if an error occurs.

See Also:

setSendRetryPause(int)

getSignalStrengthThreshold

public int getSignalStrengthThreshold()

Set the signal strength threshold.

setSignalStrengthThreshold

public void setSignalStrengthThreshold(int sst)

Get the signal strength threshold.

getSignalStrength

public int getSignalStrength()

This returns the signal strength which is a decibel reading between SIGNAL_STRENGTH_MIN and SIGNAL_STRENGTH_MAX or is SIGNAL_STRENGTH_UNKNOWN if this is not defined.

constructSmsSubmit

public static ie.ncl.util.bin.Bytes constructSmsSubmit(Message m)
                                                throws ie.ncl.net.pdu.EncoderException,
                                                       MessageException

Throws:

ie.ncl.net.pdu.EncoderException

MessageException

constructSmsDeliver

public static ie.ncl.util.bin.Bytes constructSmsDeliver(Message m)
                                                 throws ie.ncl.net.pdu.EncoderException,
                                                        MessageException

Throws:

ie.ncl.net.pdu.EncoderException

MessageException

constructTpud

public static ie.ncl.util.bin.Bytes constructTpud(Message m)
                                           throws ie.ncl.net.pdu.EncoderException,
                                                  MessageException

Throws:

ie.ncl.net.pdu.EncoderException

MessageException

constructPDU

public ie.ncl.util.bin.Bytes constructPDU(Message m)
                                   throws GsmModemException,
                                          MessageException

Throws:

GsmModemException

MessageException

setSmsc

public void setSmsc(java.lang.String addr)
             throws GsmModemException,
                    java.io.IOException

Set the SMSC message centre number.

Throws:

GsmModemException

java.io.IOException

close

public void close()

Close down the connection with the GsmModem device.

Specified by:

close in interface Connection

Specified by:

close in class ie.ncl.msg.impl.SimpleConnection

shutdown

public void shutdown()

Description copied from interface: Connection

Shutdown the connection. This is used to shutdown a connection ungracefully.

Specified by:

shutdown in interface Connection

run

public void run()

Specified by:

run in interface java.lang.Runnable

find

public static GsmModemConfiguration[] find()

detect

public static GsmModemConfiguration[] detect()

main

public static void main(java.lang.String[] args)