Cellular Development with Telit GSM Module and Python
Introduction
Telit produces a series of cellular modules that can be used to add advanced communication abilities to any project. Some units come with a Python interpreter that makes it possible to access the advanced features and even control external equipment. I am not a Python expert, but the real challenge isn’t learning Python. It is understanding the AT commands needed to run the module. This article will provide some background to help understand how to get started developing Python scripts for this family of devices.
Background
I just completed a project involving monitoring and control of equipment for a remote FM radio transmitter site. We used the terminus device by Janus Remote Communications as the basis for this project. The exact product I used is available here.
Other companies such as Sparkfun provide breakout options, but the Terminus Terminal device I used works as an all in one enclosed system. GPS capable units are also available. Some units do now have Python capabilities, so be careful when ordering. Also, these are cell phones, so an active SIM card is needed in order to use the cellular functions.
Initial Setup
The module requires use of the Telit Python package. The editor is not the greatest, but will provide limited and buggy debugging capability. I used my own Python capable editor and just complied/downloaded the code with the Telit Python version. Once installed, all you need to do to load a script to the unit is right click on the file and compile it, then with the unit connected, right click on the .pyo file and download. The unit can use .py files, but more complex scripts tend to slow down without compiling them into .pyo files.
To activate a script, we use an AT command:
AT#ESCRIPT[="script_name]
Example:
at#escript?
#ESCRIPT: "test.pyo"
OK
Setting the ESCRIPT determines what script will be used at startup. Another command is used to determine if it will startup and how long it will wait.
AT#STARTMODESCR=<start mode>, [script name]
at#startmodescr?
#STARTMODESCR: 1,10
OK
This command has two parameters, mode and timeout.
Three options exist for mode:
- Option 0: No script at startup
- Option 1: Script will run unless AT command is issued by user at startup
- Option 2: Script will run after timeout no matter what.
Option 2 is dangerous unless you have access to more than one serial port on the device. However, it can be overcome with the use of the CMUX function that will be covered later.
Timeout is in seconds. It should be noted that the device takes ~5s to boot, then the timer starts, so a setting of 10 seconds will result in a bootup time before script execution of ~15 seconds.
Telit has a ton of documentation that is poorly organized and sometimes hard to understand. This article will cover most of the Python specific functions as well as debugging, but future articles may include certain topics more in-depth on how to do more functions with the module itself, such as sending an SMS or email.
CMUX
CMUX is buggy and hard to use, but when you get it to work, it’s a life saver and makes program development a lot easier.
CMUX is the ability for the module to multiplex several functions onto one serial port. For my project, I used CMUX to watch the Python print statements and send serial commands to an external device using a program called serialmon. It also gives you access to the second AT interface for issuing commands while a script is running.
I’ll explain how to set it up then tell you how I got around some of the crazy problems with it.
Two commands are needed:
AT+CMUX
AT#CMUXSCR
AT+CMUX has two parameters, but only one option for each one. Just confirm that it is set to 0,0 with the AT+CMUX? command.
AT+CMUXSCR controls the speed and activates the CMUX prototcol. To activate the interface with a speed of 115200 baud, use the following command:
AT#CMUXSCR=1,115200
Now comes the complex part. You need the PC based software from Telit. It can be downloaded from here.
Configure the software from the setup option in the main program:
Make sure the virtual ports do not conflict with real ports on your computer. The main port is the actual connection you will be using to talk to the module.
I used a terminal program that Round Solutions makes for the Telit modules. It can be found here.
It has a lot of specific shortcuts for the modules and a logging function. Any terminal program will work fine.
Now comes the hard part. When connecting to the device that is running Python code, you need to give it time to startup and begin running. For my situation, this took ~15s. I setup a timer, and when I powered the device on and waited at least 15 seconds, I could connect with no trouble. Using your terminal program with Telitserialportmux, you can open a connection to the appropriate virtual port. It is important to note that the Python debugger is on virtual port #4 and the first AT instance is on port #1 by default.
Connecting to virtual port #4 after the script has started will activate the mux, and the icon in the system tray will turn blue. Now you should see any print statements that are executed in your script. Make sure to close the connections before powering off the unit, or you will have to close and restart all your programs. The mux program does not support suddenly losing connection that well.
This is the hardest part to figure out and may not work for everyone. I mentioned this before but the interface is buggy, and if you don’t need it, don’t bother, but it helps to debug the scripts as you run them.
Python
It’s helpful to realize that the Python side of the module does not control the module directly; it is essentially just a fancy way to automatically send it AT commands. If your situation allows, you can just use a PC or microcontroller based system to send it AT commands so that it can be done that way, but if you want a standalone system, Python is the way to go.
Telit has several custom libraries that make things a lot easier:
- MDM
- MDM2
- SER
- SER2
- GPIO
- MOD
- SPI
- IIC
- GPS
The most used libraries are the MDM interfaces. These are used to send commands to and from the module. MDM and MDM2 use different AT instances. The device can be controlled from either one. For my project, it came in handy to multitask a bit by using MDM to send Telnet packets directly to the SER interface while reading the connection status on the MDM2 interface.
SER interfaces are the hardware serial interfaces. Each one connects to a UART on the module, and depending on your hardware interface, these may be connected to a USB port or serial port. The one I used had SER1 connected to a RS232 port, and SER2 was 3.3volt TTL available on the large header connector on the bottom. AT commands can be sent directly into the SER, and data can be routed out from the SER interface.
GPIO is for controlling the limited I/O available on the module.
MOD is important because this has functions such as sleep and the watchdog timers.
SPI, IIC, and GPS are designed to control their respective functions. Just a quick explanation for those unfamiliar; SPI and IIC are chip level communication protocols, and are only useful if interfacing to other hardware.
Any library can be used by importing them at the beginning of the script.
import MDM
import SER
import GPIO
MDM/MDM2
These libraries are identical, but just access different AT instances. The really important parts of these two are the send and receive commands.
MDM.send(string,timeout)
The send command is used to send AT commands to the unit for instance.
A = MDM.send(‘AT+CMGR=1\r’,5)
It returns a 1 if successful, or a -1 if the timeout is reached. The timeout is in 1/10th of a second. So the example would wait 0.5s before timing out.
It will not return what the AT interface returned; to read this, you will need the receive command:
b = MDM.receive(10)
This will assign b with the receive buffer after a timeout of 1.0s. The library has functions to support sending and receiving individual bytes as well. The Python side is the easy part to learn. Learning the hundreds of AT commands the device responds to will take the longest. With the MDM interfaces and the SER interfaces to interact with the hardware, you’re on your way to starting a project. Future articles will cover more specific functions such as opening a telnet session or sending an SMS message, but for now, these are the fundamentals needed to add cellular functionality to your next project.
For lists of AT commands and more specifics on all the functions discussed here, a good resource is the Telit website. All documentation relevant to the GC864-Quad which is the module I used can be found here.
