Telit+python Tutorial

This page gives a overview of programing python on a Teilit module. The following toolchain has been developed to help this process if you are using a UNIX based OS like Linux or MacOsx. It also includes a collection of python modules that allow for local simulation of your python code before uploading it on to the Telit module.

Overview

On selected models of Telit GSM modules a built in python interpreter allows for programming and running python scripts directly on the Telit module. The first resource you should take a look at is the Telit Python overview:

http://www.telit.org/en/products/python.php

User Manual found here:

http://www.telit.com/module/infopool/download.php?id=617

Windows

For windows Telit provides a GUI based program that allows you to upload code etc. I have not had experience with it since I don't run a Windows OS. If you have knowledge and want to contribute on this subject please contact us.

UNIX

If you are using a Unix based system the below tool chain will allow you to upload and locally simulate your python scripts. The tool chain has three components:

1. A makefile that allows you to type in commands like:
           make uploadAll
     which will upload all files to the Telit

2. A collection of python modules (TELIT-LOADER) that work 
   with the makefile to load and manage your code on the Telit.
   
3. A collection of python modules (TELIT-SIMULATOR) that 
   allow you to run the python scripts locally on your 
   host computer before uploading to the Telit to test them out.

Tools

The telit-Loader and telit-Simulator modules are based off of work done by: Josh Levinger (http://jlev.media.mit.edu/Projects/GeoTracker) who started the Telit-simulator, there were further modifications by Lucas Vickars and then into the hands of Justin Downs from GroundLab who took it to the present form.

Overview

Overview: These tools allow you to locally test python code for the Telit and upload it accordingly. The tools are based around the use of a makefile on the command line which calls python modules. To use the makefile you must be located in the same directory as the file, this is the main directory you can download from GroundLab.

A overview of the contents and use of the main directory:

makefile        -> This is the makefile that gets called 
                   when you give a command such as 
                   "make checkPort".

ProtoCode       -> This is the directory where all the python 
                   code you are testing locally before uploading
                   goes.

readMe.txt      -> Just a readme for gitHub.  

TELITLOADER     -> This is the directory that holds all the files
                   used to load python scripts onto the Telit. It
                   has one special file you modify where you set 
                   all your serial connection settings called:
                   TELITLOADER/settings.txt                   

TELIT-SIMULATOR -> This is the directory where all the files 
                   that are used to run Telit python code locally
                   are located. 

UploadCode      -> This is the directory which you upload files 
                   from to the Telit module. It is the directory 
                   that make looks in when you specify a command
                   such as: "make upload FILE=myfile.py"
                   

So your work flow would be something like this:

  1. Start writing a python script in the ProtoCode directory using the Telit-simulator to test it (see TELIT-SIMULATOR below for more details).
  2. Next after you finished writing and testing it locally copy the working files you want to upload into the UploadCode directory and take out the include header in the appropriate files (as described in the Telit-simulator section below).
  3. Then cd into the main directory and use the make utility to erase old files on the telit and upload the new files from the UploadCode folder(as described in the Make Utility section below).

How to Install

The tool chain requires a couple of things to be installed on your host computer to run the code.

1.You need to have a python interpreter running on your OS.
  
2.You need the pyserial module downloaded and installed.

3.You need a version of make preferably (GNU) 

python interpreter

1.First is you need a version of python running on your OS, most Os's come with a interpreter installed to check if you have python and what version just go to the command line (open terminal in Mac or Unix your local command line utility) and type:

python (and hit enter) 

(This should output something like this)

[stullLinux@stullLinux ~]$ python
Python 2.6.2 (r262:71600, Jun  4 2010, 18:28:04) 
[GCC 4.4.3 20100127 (Red Hat 4.4.3-4)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> 

If not you need to go here and install python:

http://www.python.org/download/

pyserial

2.Once you have python on your system you need to get a special python module that handles serial connections using your USB bus.

It is called “pyserial” and the main page is here:

http://pyserial.sourceforge.net/

and the download and install instructions are here:

http://pypi.python.org/pypi/pyserial

Make Utility

3. Is to get a version of make on your computer, if you are running a Linux system you should have it. If you are running a mac with OSX if you installed Xcode you will have it. To check to see if it is installed you can go to a terminal and type:

which make (ENTER)

(and you should get something like this)

[yourName@yourcomputer ~]$ which make
/usr/bin/make

(which means your good to go)

(If you get something like this)

/usr/bin/which: no make in (/usr/lib/qt-3.3/bin:/usr/local/bin:
/usr/bin:/bin:/usr/local/sbin:/usr/sbin)

It means you need to install make on your system.

For Linux you can use your package manager RPM or Yum or whatever your OS uses, so you would type:

yum search make

and you should see this package pop up there:

make.i686   

Then just do:

yum install make.i686

or install it from source and compile it yourself: http://www.gnu.org/software/make/

For OSX you need to install Xcode or get it from darwinports which makes you install Xcode anyway. You can do that from your OS disks that came with your system or you can get it from:

http://developer.apple.com/technologies/xcode.html

once you have done that type:

[yourName@yourcomputer ~]$ which make

and this time you should see

[yourName@yourcomputer ~]$ which make
/usr/bin/make

which means your good to go.

GroundLab Code

You now have everything installed but the code, to get that you go to the GroundLab gitHub site here:

https://github.com/GROUNDLAB/Telit-Loader

Once there, download all the code as a tar.gz or zip file:

Move the compressed file to the directory location you want to use it in and then decompress it (do it with drag and drop and then double click on the compressed file in the finder).

or command line:

So now you should have a folder named something like:

GROUNDLAB-Telit-Loader-220f2f9

with all the files from gitHub located somewhere on your Computer. The last part of the directory name will change with updates to the code, but the rest should stay the same. If you list the files in the directory you just decompressed you should see these files:

To test that all the tools you just installed work you can send some test commands. To do this all the tool chain commands are given on the command line, so you need to open up a command line tool (OSX use the terminal application, Linux/UNIX you probably know what to do)

1. Open a terminal and cd into the directory you just decompressed,
   so if you put the decompressed directory on the desktop in a 
   subdirectory(folder) named TelitTools it would be at: 
   
        ~/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9 
   
   so we say at the command prompt cd myPath and press Enter EG:
   
        cd ~/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9
   
   then to check all the files are there list with ls EG.
   
        ls 
        
        

Next is to check out the functionality of the tools, so first we will check to see “make” is working then check that python and the pyserial module are installed correctly.

2. To check make on the command line type 
   
   make help
   
   and you should see the

If you don't see that, first check you are in the main directory that you decompressed and not one of the sub directories like TELIT-SIMULATOR. If that doesn't work go back and try again to reinstall make.

Once that is going the next step is to test your python and pyserial.

3. To check pyserial and python make sure you are in
   the main directory of the decompressed directory
   then type on the command line: 
   
   make checkPort

and you should see this:

Even though it says error it means the modules are properly installed if you get anyother type of errors about missing files or something is not declared it means you have to go backand reinstal the pyserial or python.

Hardware setup

You need a way to talk to the Telit module to upload code and run python scripts. The most accessible way to do this is with a serial port connection. I use a FTDI chip FT232R on a Sparkfun breakout-board:

to connect it to the Telit you have to connect:

FT232R               TELIT
GND         ->        GND
TX          ->        TXD
RX          ->        RXD

The only thing to watch for is a good ground connection.

Once you have it set up you need to find what USB port you are connected to, what I do is type:

tail -F /var/log/messages 

Which outputs this when I connect the FTDI to my computer.

Jan  6 21:09:10 stullLinux kernel: usb 4-1: Detected FT232RL
Jan  6 21:09:10 stullLinux kernel: usb 4-1: Number of endpoints 2
Jan  6 21:09:10 stullLinux kernel: usb 4-1: Endpoint 1 MaxPacketSize 64
Jan  6 21:09:10 stullLinux kernel: usb 4-1: Endpoint 2 MaxPacketSize 64
Jan  6 21:09:10 stullLinux kernel: usb 4-1: Setting MaxPacketSize 64
Jan  6 21:09:10 stullLinux kernel: usb 4-1: FTDI USB Serial Device 
converter now attached to ttyUSB0

So I know that I am connected to /dev/ttyUSB0

If your running osx you can just list your tty devices using the command line before you plug in the device and then after and you will see which is new. So you would open the terminal application and type the below on it

EG:

ls /dev/tty*

plug in device

ls /dev/tty*

see which is new

The next step is to change what port your using in the “TELITLOADER/settings.txt” file:

TELITLOADER/settings.txt file:

#To set your serial, enter with the format:
#PORT(SPACE)"portName"(RETURN)
#BAUD(SPACE)baud#(RETURN)
#as shown
PORT /dev/ttyUSB0
BAUD 115200

Keep the BAUD setting but replace your port here.

Terminal apps

Once you have your hardware set up it is a good thing to have a terminal application that can open a serial connection over your FTDI device. You don't need it to run the Simulator or code Upload but it is handy for debugging and to send AT commands to the Telit.

On Linux

Minicom or Cutecom Work well.

On OSX

Zterm or CoolTerm Work well.

Telit-Simulator

As described in the Tools:Overview section the Telit-Simulator allows you to write code and run it locally. The download comes with code examples that you can use to test out the tool chain. The Code in the ProtoCode directory is called WORKINGTEST.py:

#####TAKE ME OUT BEFORE UPLOADING!!!!!!!##########
import sys 
import fileinput
sys.path.append('../TELIT-SIMULATOR')
#####END TAKE OUT#################################
 
import GPS 
import SER 
import MDM 
import MOD 
 
SER.set_speed('9600')
while 1:
        SER.send('hello world!')
        MOD.sleep(30)

The first part of the code is important, it is a couple lines to tell where the modules we are using below are defined (which is located one directory above then into the TELIT-SIMULATOR directory). It needs to be in your main file before any other imports are done, otherwise the python interpreter will not find the modules.

#####TAKE ME OUT BEFORE UPLOADING!!!!!!!##########
import sys 
import fileinput
sys.path.append('../TELIT-SIMULATOR')
#####END TAKE OUT#################################

!!!This code should only be in when testing locally!!! You need to comment these lines out or take them out completely if you upload this code. If it is left in when you transfer the code onto the Telit it prevent the Telit from compiling the code and your script will not work.

import GPS 
import SER 
import MDM 
import MOD

The next section shows some of the modules that are defined in the Telit python library and are redefined locally in the TELIT-SIMULATOR folder for local testing.

If you haven't read over the Telit python easy script reference you should do so to get an idea of how their python library works, there are many difference that you need to be aware of before programming.

modules

A quick run down of the telit modules and how the simulator handles them.

import GPS -> This module handles GPS on the Telit

The GPS module allows you to get GPS coordinates from the device. The Telit simulator handles this in the TELIT-SIMULATOR/GPS.py file. The Simulator GPS.getActualPosition() returns a dummy gps string to you with a variable number of satellites and lock accuracy.

import SER -> This is the serial module that sends 
              and receives serial on the Telit module.

The SER module in the simulator is located in the TELIT-SIMULATOR/SER.py and just prints to screen the sent serial and the SER.receive(timeout) function takes user input from stdin on the command line and returns the input in the python program. The timeout works but notifys if a timeout occurs after the user puts in all the input, this is in the simulator only on the telit after the time out the next command is executed.

import MDM -> This module sends AT commands directly to 
              the Telit ME from the onboard python script 
              and receives the reply.

The MDM module in the simulator sends AT commands directly to the Telit module over the serial port. This is really a big help, it lets you get real time debug info without having to go through the process of uploading code over and over. When the MDM is imported into the python script with “import MDM”, the module starts up a connection to the serial port defined in the “TELITLOADER/settings.txt” file.

TELITLOADER/settings.txt file:

#To set your serial, enter with the format:
#PORT(SPACE)"portName"(RETURN)
#BAUD(SPACE)baud#(RETURN)
#as shown
PORT /dev/ttyUSB0
BAUD 115200

Keep the BAUD setting but look up what port your using and replace it here. If you want to make it not automatically start up with import go into the →TELIT-SIMULATOR/MDM.py file and take out the following lines.

119 #OPEN PORT AUTOMATICALY WITH IMPORT
120 getSerialSettings()
121 port = serial.Serial(PORTName,BAUD,timeout=1,bytesize=8,stopbits=1,parity='N',writeTimeout=1)
122 port.open()
123 heartBeat()

import MOD → This controls the telits modules miscellaneous functions. It is mostly used for dely and timing functionality, it is pretty self explanatory and you can read through it in the →TELIT-SIMULATOR/MOD.py file.

There are also MDM2 and GPIO scripts in the TELIT-SIMULATOR they too are self explanatory and you can read over them to get an idea.

Here is a complete listing of all the modules available for the telit, if you add one in please send it to us and we will add it in:

MDM   interface between Python and the module AT command handling.
MDM2  second interface between Python and the module AT command handling.
SER   interface between Python and the module serial port ASC0 direct handling.
SER2  interface between Python and the module internal serial port ASC1 direct
      handling.
GPIO  interface between Python and the module internal general purpose input output
      direct handling.
MOD   interface between Python and the module miscellaneous functions.
IIC   custom Inter IC bus software that can be mapped on creation over. 
      almost any GPIO pin available.    
SPI   custom Serial Protocol Interface bus software that can be mapped on creation
      over almost any GPIO pin available.
GPS  interface between Python and the module internal GPS controller.

running code

To run the code locally using the Telit simulator you need to set up two things before running the script.

  1. You must put in what Serial port you are using in the “TELITLOADER/settings.txt” file. See the above hardware section for how to find your Port and put it in the settings.txt file.
  2. You must append the path of the TELIT-SIMULATOR directory to the search path of the python interpreter with this:
#####TAKE ME OUT BEFORE UPLOADING!!!!!!!##########
import sys 
import fileinput
sys.path.append('../TELIT-SIMULATOR')
#####END TAKE OUT#################################

You only need to do this in the main file you are using before you import anything else or the interpreter can't find the right modules.

Once you have those two things going all you need to do is turn on your Telit and cd into the ProtoCode directory, then run the py file EG.

and that's it, you can run your py files using the command line python interpreter and when you are done just take out the import sys lines in the main file and move the code to the UploadCode folder you can then use the make utility to upload it to the Telit.

Upload Code

To upload code to the Telit module the make utility is used to run the makefile. The makefile calls different combinations of the python modules found in the TELITLOADER directory. In this way you can upload code, list what code is on the device, delete files and more.

The way the make utility works is by calling the makefile and reading it, the way we do that is to be in the same directory as the file and giving it a command on the command line. A good place to start is the help command, it gives you the syntax for the rest of the commands EG:

Take a look to make sure we are in the same directory as the make file

[stullLinux@stullLinux GROUNDLAB-Telit-Loader-220f2f9]$ ls
makefile  ProtoCode  readMe.txt  TELITLOADER  TELIT-SIMULATOR  UploadCode

Type in the command it always starts with make.

[stullLinux@stullLinux GROUNDLAB-Telit-Loader-220f2f9]$ make help
HELP:
To use loader just type "make" and the command you want 
EG: make upload FILE=myfile.py
COMMANDS: 
checkPort 			: checks the serial connection and 
                                sees if the telits responding. 
list 				: lists all files loaded on the telit. 
find FILE=myfile.py 		: finds file on Telit, you must type 
                                "FILE=something" to pass file name.
read FILE=myfile.py 		: reads the specified file. 
delete FILE=myfile.py 		: deletes file from telit. 
deleteAll 			: deletes all files on telit 
upload FILE=myfile.py		: loads specified file onto telit 
uploadAll			: loads all files from the Upload directory onto telit.
uploadCheck FILE=myfile.py	: loads file then reads it back off Telit 
                                to make sure it is there 
enable FILE=myfile.py		: enables the specified file as the main file to 
                                execute on  Telit  
checkEnable			: checks which file is enabled on Telit  

So you can see the different commands you can use with the loader the syntax is always make followed by the command:

make list

or if you need to specify a file you need to pass it by saying in all caps FILE=somefile.py

make upload FILE=somefile.py
code organization

Before that you need to know how Telit compiles and runs python scripts on its modules. The best thing to do is first read the telit python manual:

http://www.telit.com/module/infopool/download.php?id=617

From the manual:

The steps required to have a script running by the Python engine of the module are:
   1.   write the Python script;
  
   **   compile the Python script (optional);
  
   2.   download the (compiled) Python script into the module NVM;
  
   3.   enable the Python script;
  
   4.   execute the Python script.
  

The telit takes a long, I mean long time to compile the code, I have waited 15 minutes on a medium size script. To get around this, it is best to have a main.py file that calls a runner.py file with a import statement, where the runner.py is your file that calls all your other modules. The reason for this is the Telit stores all compiled files as .pyo files on the module and doesn't recompile the .py file unless the .pyo file is missing or the .py file is registered as the main executable. So if the main executable file just has one import statement the file compiles down much quicker.

                      
                        someother.py
                     /
 main.py-> runner.py
                     \
                        someotherother.py

Another thing to remember is the names of the files are case sensitive so myFile.py is not the same as myfile.py.

So here is a run through of the above steps using the TELITLODER:

walk through

1. First is to write the code with the simulator as described above, then take out the header and move all the code files into the UploadCode directory.

2. Then we need to Upload the code onto the Telit, make sure it is turned on and you have a good serial connection see the Hardware section for reference. Then we go into the main directory and type

make list

on the command line, this will give us all the files on the telit module.

 [stullLinux@stullLinux GROUNDLAB-Telit-Loader-220f2f9]$ make list
#######################################################################################
##YOUR CURRENT WORKING DIR IS: 
/home/stullLinux/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9/TELITLOADER/
##YOUR CURRENT UPLOAD DIRECTORY IS:
/home/stullLinux/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9/UploadCode/
####################################################################################### 
OPENING SERIAL CONNECTION#######
Port: /dev/ttyUSB0
Baud: 115200
################################
Telit replied, communications OK.....
Listing current files:
Sending: AT#LSCRIPT
AT#LSCRIPT
#LSCRIPT: free bytes: 1982688

OK

and you should see something like this, which tells us there are no files on the module and it has free room to upload.

We then can say:

make uploadAll

And you should see something like this:

[stullLinux@stullLinux GROUNDLAB-Telit-Loader-220f2f9]$ make uploadAll

#######################################################################################
##YOUR CURRENT WORKING DIR IS: 
/home/stullLinux/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9/TELITLOADER/
##YOUR CURRENT UPLOAD DIRECTORY IS:
/home/stullLinux/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9/UploadCode/
####################################################################################### 
Opening:/home/stullLinux/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9/
UploadCode/WORKINGTEST.py
OPENING SERIAL CONNECTION#######
Port: /dev/ttyUSB0
Baud: 115200
################################
Telit replied, communications OK.....
DELETING .py file:
Sending: AT#DSCRIPT=WORKINGTEST.py
didn't find .py file: WORKINGTEST.py
ERROR
DELETING .pyo file:
Sending: AT#DSCRIPT=WORKINGTEST.pyo
didn't find .pyo file: WORKINGTEST.py
ERROR
writing file:
WORKINGTEST.py
118
Sending:AT#WSCRIPT=WORKINGTEST.py,118
OPENING SERIAL CONNECTION#######
Port: /dev/ttyUSB0
Baud: 115200
################################
Telit replied, communications OK.....
START FILE#########
loaded OK
END FILE###########

What this does is first looks for any old compiled (.pyo) files with the same name as the file being uploaded and then removes them if they are there. Otherwise the new .py file that just got uploaded won't compile.Then it goes through and loads all your files up in the UploadCode directory.

If you type:

make list 

again you should see the file listed now.

[stullLinux@stullLinux GROUNDLAB-Telit-Loader-220f2f9]$ make list

#######################################################################################
##YOUR CURRENT WORKING DIR IS: 
/home/stullLinux/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9/TELITLOADER/
##YOUR CURRENT UPLOAD DIRECTORY IS:
/home/stullLinux/Desktop/TelitTools/GROUNDLAB-Telit-Loader-220f2f9/UploadCode/
####################################################################################### 
OPENING SERIAL CONNECTION#######
Port: /dev/ttyUSB0
Baud: 115200
################################
Telit replied, communications OK.....
Listing current files:
Sending: AT#LSCRIPT
AT#LSCRIPT

#LSCRIPT: "WORKINGTEST.py",118

#LSCRIPT: free bytes: 1982770

OK

3. Now we need to enable the script, we do that simply by by saying:

make enable FILE=WORKINGTEST.py

This will set WORKINGTEST.py as the main script that the Telit will execute from (remember file names are case sensitive so workingtest.py is not the same as WORKINGTEST.py)

A note from Telit about enabling:

NOTE:
There is no error return value for non existing script name in the module memory typed
in command AT#ESCRIPT. For this reason it’s recommended to double check the name
of the script that you want to execute. On the other hand this characteristic permits
additional possibilities: like enabling the Python script before downloading it on the
module or non having to enable the same script name every time the script has been
changed, deleted and replaced with another script but with the same name. Note also
that the file extension must be .py.
For example:
    AT#ESCRIPT=”a.py”
Wait for enable result: OK.

and last you can check what script is enabled by typing:

make checkEnable

4. Next to run the script you need to toggle the power of the Telit on and off and start it up with the DTR line pulled to VCC,

From Telit:

The Python script you have downloaded to module and enabled is executed at every
module power on if the DTR line is sensed LOW (2.8V at the module DTR pin - RS232
signals are inverted -) at start-up, (in this case no AT command interface is connected
to the modem port) and if the script name you enabled matches with one of the script
names of the scripts you downloaded. 21
In order to gain again the AT command interface on the modem physical port (for
example to update locally a new script) the module shall be powered on with the DTR
line HIGH (0V at the module DTR pin) so that the script is not executed and the Python
engine is stopped.

NOTE:
See AT#STATMODESCR and AT#EXECSCR commands description for further Python
script execution modes.
The real execution of the Python script is delayed from the power on due to the time
needed by Python to parse the not compiled script. The longer is the script, the longer
is this delay. The real execution of compiled Python scripts (.pyo) is faster just opening
and reading the file from NVM.

You can toggle the power by sending the Telit a AT#reboot over minicom or Zterm or manually turning the switch on then off.

After that your Telit will turn back on and compile the script it may take a while but be patient. Open a serial connection to the telit using minicom or Zterm or cutecom or whatever you are using and after awhile you should see “Hello world!” pop up.

Navigation
Print/export
Toolbox