Project

General

Profile

GSM class manual

Design of the serialPort class (used by the GSM handler scripts to communicate to cellphones)

Creating the the serialPort object [serialPort(portAddress, baudRate, timeout)]

To create an object of serialPort class one would type: cellPhone1 = GSMClass.serialPort('/dev/ttyUSB0', 19200, 10), where '/dev/ttyUSB0' is the port you define; 19200 is the baud rate speed on which you communicate with the device; and 10 is the timeout defined in seconds for how long the serial port should wait for a message to receive from the cellphone (this way you can avoid a deadlock, one should experimentally determine the waiting time since it depends of the GSM system and your cellphone).

Initializing the serial port [portInit()]

After creating the object (the code above this topic) we need to tell the object to try to open the defined port (in our example it is the port /dev/ttyUSB0). Make sure the cellphone is connected and has a soft modem installed. We initialize the port by calling the portInit() function. The portInit() function will first check does the defined serial port exist using the following Linux command, dmesg | grep portName, e.g. dmesg | grep /dev/ttyUSB0. If the port exists, it will proceed with the communication test by sending the most basic AT command, i.e. 'AT' and a carriage return, and wait for the respond of the cellphone. The function will return you one of the following values:

0, if the port doesn't exist on the system (check your port name definition)
1, if the port was successfully opened and the cellphone is communicating and fully operational
2, if the port exists and the cellphone communicates to the system but doesn't give an OK message after the AT command (might be a problem with the baud rate, serial port settings, e.g. byte size, stop bit, etc)
3, if an unknown error happened, set in the class debugMode = 1 to see a full traceback and description of the error
TIMEOUT, if the cellphone doesn't respond within our predefined timeout time

Calling a number from your GSM device [callNumber(numberToCall)]

After we successfully connected to our GSM device, i.e. cellphone, we would like to make a call to another GSM device, SIP or etc. This can be easily done by calling the callNumber(numberToCall) function, where numberToCall is an integer value containing the phone number we want to call. It will return you one of the following values:

0, if the port doesn't exist, you didn't initialize the port correctly (look at portInit())
1, if the GSM device called the number
3, if there is an unknown error, set in the class debugMode = 1 to see a full traceback and description of the error
4, if the GSM device received the command for calling a number but didn't respond with an OK

Hanging up a call [hangUp()]

After we have established a call one needs to hang up the connection. This can be easily done by using the hangUp() function of our class. The function will try to hang up the call and it will return you one of the following values:

0, if the port doesn't exist, you didn't initialize the port correctly (look at portInit())
1, if the hang up was successful inside of a call but also if there was no active connecition (e.g. during dialing or waiting state)
2, if the GSM device returned an error, it can mean that the other side already hang up before you did
3, if there is an unknown error, set in the class debugMode = 1 to see a full traceback and description of the error
4, if the GSM device returned neither OK or ERROR message

Closing the serial port [closePort()]

When you finish using the serial port to communicate to the GSM device, the best thing to do is to close the serial port. To close the port one would call the closePort() function. The function will return you one of the following integer values:

0, if the port doesn't exist, you didn't initialize the port correctly (look at portInit())
1, if it succeeded in closing the port
3, if there is an unknown error, set in the class debugMode = 1 to see a full traceback and description of the error

Getting signal quality of your call [getSignalQuality()]

When we establish a call, the user might be interested in the signal strength on his GSM device. We can easily retrieve the signal quality by just calling a simple function, getSignalQuality(). After the function has been executed, it will return you an integer value:

0, if the port doesn't exist, you didn't initialize the port correctly (look at portInit())
1, if it succeeded in reading the signal quality, the signal strength value is stored in the signalStrength variable
2, if the GSM device didn't return an OK after the execution of the AT command for signal quality, AT+CSQ (one possible error, there could be a timeout)
3, if there is an unknown error, set in the class debugMode = 1 to see a full traceback and description of the error
4, if it received correctly the AT command for signal strength but couldn't return you the signal quality

Receiving calls [receiveCall()]

We have to receive calls as well. Once when you know that you should receive a call, one should go to the receive call mode. This can be easily done by executing the receiveCall() function. The function will return you one of the following integer values:

0, if the port doesn't exist, you didn't initialize the port correctly (look at portInit())
1, if it successfully received the call, but it also means we have an active connection between our GSM device and the caller
2, if the GSM device didn't send the RING response but rather some other command (one possible error, there could be a timeout, i.e. waited to receive a call longer than our predefined timeout)
3, if there is an unknown error, set in the class debugMode = 1 to see a full traceback and description of the error
4, if it received correctly the AT command for receiving the call, i.e. ATA, but couldn't return you an OK message (timeout could have happened or in the mean time the caller hanged up so there is not really a call to receive)

Getting the state of the current call [currentCall()]

We want to find out what is happening with our current call. Is the call :

0, if the port doesn't exist, you didn't initialize the port correctly (look at portInit())
1, if we have an active call in progress or it was active, i.e. the other side hang up but we are not yet aware of it
2, if the GSM device is not in a call state
3, if there is an unknown error, set in the class debugMode = 1 to see a full traceback and description of the error
FOR THE FOLLOWING RETURN MESSAGES, REFER TO [[http://lab.ks.uni-freiburg.de/attachments/download/253/s35i_c35i_m35i_atc_commandset_v01.pdf]] , page #22.
5, if the call is held
6, if the GSM device is dialing
7, if the GSM device is alerting
8, if we have an incoming call
9, if we are in the waiting state
OTHERWISE, if the cellphone didn't return what it should

Receiving data from the GSM device [receiveData()]

This is a private function and doesn't require to be explained in details. It is responsible for receiving messages from the GSM device, i.e. what the GSM device sends the computer. The timeout timer is used in this procedure, if the timeout handler raises an exception it means the procedure didn't receive a correct output from the GSM device. In that case, it will return the following string, 'TIMEOUT'. This way we avoid a deadlock and forever waiting in a loop to get a message from the GSM device.

Example code of using the Server class

import GSMClass

caller = GSMClass.serialPort('/dev/ttyUSB0', 19200, 10)
receiver = GSMClass.serialPort('/dev/ttyUSB1', 19200, 10)
print 'initialize caller', caller.portInit()
print 'initialize receiver', receiver.portInit()

print 'call 455', caller.callNumber(455)

recCall = receiver.receiveCall()
if recCall == 1:
        print 'I got signal quality', receiver.getSignalQuality()
        print 'I got signal quality', caller.getSignalQuality()

        print 'Signal quality on rec phone', receiver.signalStrength
        print 'Signal quality on caller phone', caller.signalStrength

        print 'ask caller is the connection working', caller.currentCall()
        print 'disconnect receiver', receiver.hangUp()
        print 'disconnect caller', caller.hangUp()
elif recCall == 'TIMEOUT':
        print 'timeout'

#print 'call 447', receiver.callNumber(447)
#
#recCall = caller.receiveCall()
#if recCall == 1:
#       print 'I got signal quality', caller.getSignalQuality()
#       print 'I got signal quality', receiver.getSignalQuality()
#
#       print 'Signal quality on rec phone', caller.signalStrength
#       print 'Signal quality on caller phone', receiver.signalStrength
#
#       print 'ask caller is the connection working', receiver.currentCall()
#       print 'disconnect receiver', caller.hangUp()
#       print 'disconnect caller', receiver.hangUp()
#elif recCall == 'TIMEOUT':
#       print 'timeout'
#sleep(10)
print 'close port caller', caller.closePort()
print 'close port receiver', receiver.closePort()

Code of the GSMClass

The code for the GSMClass can be found in the repository under the name GSMClass.py