Functions to control a GSM/GPRS modem

(only available for certain terminals with a suitable serial aynchronous interface, and a special firmware)

Note: Since we never managed to get the GSM/GPRS modem's internal FTP client running properly (without hardware handshake), we abandoned the support for GSM/GPRS modems in the MKT-View terminal completely. Sorry about that, but we had more important things to do. If you think you need something with a full TCP/IP protocol stack, buy a device with embedded Windows or Linux ;-)

This document describes how the terminal can be connected to an external GSM/GPRS modem through the serial interface. For this purpose, certain terminal firmware variants have built-in support for such modems.

Note: Only very few terminals support this optional function - see Feature Matrix : "GSM modem") !
Furthermore, this feature must be unlocked (by the manufacturer, or via password) before using it .

Contents

Overview of interpreter functions and -procedures to control the GSM/GPRS modem
Interpreter functions to communicate with the modem: Function overview, enter PIN, voice calls, ...

The Modem Configuration File

The terminal must know a lot of things about your SIM card, about your GSM/GPRS service provider, and how the modem shall connect to the internet (one fine day). This information is usually stored in a special modem configuration file ("modem.cfg"), located on the compact flash card (or, during software development, in the directory of the programming tool).

Here is an example for such a file. Of course, YOU must provide all required data ! Use a plain text editor to write your own configuration. The phone numbers for most GSM/GPRS services can be found on the homepage of your wireless service provider (hopefully ... the author had some trouble to find all required info ! ). A few notes about the syntax of the modem configuration file follow after this example :

; GSM/GPRS modem configuration file for MKT-view .
; Modify this according to your SIM card / service provider !
; Save the modified file as "modem.cfg" ON THE COMPACT FLASH CARD .

Encryption=0              ; 0 if this file is NOT scrambled

[SIM_Card]
PIN=0815                  ; first PIN of the SIM card
MyNr=0123456789           ; "my phone number"

[Provider]
.... still a lot of work to do here .... ;-)

[GPRS]

[SMS]

[Email]

[FTP_Up]

Notes:

A semicolon in the modem configuration file begins a remark until the end of that line. Remarks are not required, but they are nice to have when you need to modify a configuration file without this manual.
The SIM card's phone number and the SIM PIN in the example above are pure fiction. You don't need to try ;-)
Many of the values in the config file look like numbers, but instead they are strings which may contain special characters

Overview of interpreter functions and -procedures for the GSM/GPRS modem

Modem control commands and -functions in alphabetical order:

gsm.accept, gsm.baud, gsm.cfg, gsm.hup, gsm.login, gsm.my_nr, gsm.off, gsm.on, gsm.pin,
gsm.rcvd, gsm.regd, gsm.ringing, gsm.roam, gsm.tx, gsm.vc

Configuration of the serial interface (baudrate)

gsm.baud: get or set the baudrate for the serial port, when "occupied" by the external GSM modem. Unit is bit per second. Allowed values are 1200, 2400, 4800, 9600, 19200, and sometimes 38400 (bit/second). Caution, some targets don't support 38400 bit/sec. Example:
@gsm.baud=4800sets the baudrate of the serial port to 4800 bit/sec (this is the maximum supported by most of MKT's programmable terminals).

gsm.cfg: to be specified.

Network Registration


gsm.pin: returns the SIM PIN (read from a configuration file) as a string. The modem driver must know this pin when logging into the GSM network, and on a few other occasions. The terminal usually reads the SIM PIN from a configuration file, if such a file was found on the CF memory card. Without such a config file, your application must set the SIM PIN before executing the login command !
gsm.login: Command for the modem to register into the GSM network. Requires SIM PIN .
gsm.regd: Function to check if the modem is registered into the network (result=1) or not (result=0). To register into the network, use the login command .
gsm.roam: Function to check if the modem is "roaming" at the moment (result=1) or not (result=0).
If you don't know what this is, consult Wikipedia on "Roaming".
Caution: Roaming usually means you will be charged with additional costs ! It may be wise to display the roaming status in your terminal application for this reason, especially before trying to send megabytes of data through a roaming data connection ;-)

Voice calls

Many GSM modems can be used as mobile phones for voice calls too. They usually have a standard audio connector for this purpose. The following interpreter commands can be used to make outgoing voice calls, and accept incoming voice calls. Of couse, they only work if the modem is registered ("logged into") the GSM network.

gsm.vc(<dialing string>): Makes a voice call (outgoing) to the specified number.
gsm.ringing: This flag is set to 1 (ONE) while the phone rings from an incoming call, and 0 (ZERO) otherwise.
Your display application can poll this flag if you want to receive incoming voice calls through the GSM modem.
If the phone rings (event: gsm.ringing==1), use the command "gsm.accept" to accept the incoming call.
gsm.accept: Accepts the incoming voice call. Only works while the phone is ringing !
gsm.hup: Hang up. Use this command to terminate a connection (incoming or outgoing call).

Other modem control commands

gsm.off: Command to turn the modem power off. Also causes the modem to log off from the GSM network of course !
gsm.tx("xxxxx"): Sends any string (usually an AT command) to the modem. Only required for special modem functions which are not directly supported by the terminal firmware.

Appendix

Sample application for the GSM / GPRS modem

There is a small test file for the MKT-View which demonstrates some of the modemr functions. You can load it from \programs\gsm_test.cvt .

On this screen of the test application, some of the modem control functions are shown, along with the results when testing it with a modem and (SIM card properly installed).

The baudrate or the serial interface between terminal and modem is displayed. The SIM PIN and the SIM's own phone number are made unreadable here for privacy.

"Registered" means the modem is logged into the GSM network; which means it can accept calls and make outgoing calls.
"Connected" means the modem is involved in a connection (voice or data) at the moment.
"Roaming" means the modem is currently using a foreign provider. This is not possible with all SIM cards ! Caution: International roaming can cause high additional costs, so it may be a good idea to include a similar indicator in your own terminal application too, so the operator can see what's going on (don't blame us for an enormous telephone bill - you are responsible for what your application does with the modem ! ).

The "gsm.rcvd" function shows the last response received from the modem. This is often one of the URC's (Unsolicited Result Code) which are explained in your modem manufacturer's manual (often called something like "AT Command Set", though URCs are no AT-commands). Some examples for such URCs are here.

Notes on conflicting usage of the serial interface

Originally, the serial port was exclusively used to download the terminal application ("user program") through the PC's RS-232 interface. Since the serial port may now be occupied by the GPS receiver or a GSM modem, the terminal cannot (always) listen for commands from the PC. Why ?

The program download between PC and Terminal uses a block-oriented protocol for the serial port called "3964R". When you select "Send application to the terminal through the serial port", but the serial port is occupied by the application (as described in this document), the 3964R-handler may be passive to avoid interference with the protocol which your terminal-application uses (through appropriate interpreter commands). The PC will therefore never receive the expected response from the terminal .... and your terminal application will, at least, be "irritated" by the characters received from the serial port.

So what to do in this case, when your application occupies the terminal's serial port, but you want to download a new application through just this port ? The solution is:

First, enter the terminal's "Main" system menu (by pressing the two keys), then
select the function "Receive from RS232", then
Start the program transfer on the PC

The terminal will reprogram the serial port for communication with the PC in this case, which includes the initialisation of the 3964R-protocol.

If the serial port is not occupied by the terminal-application or the GPS-decoder (which is the default, see gps.prot), you don't necessarily have to use the system menu to activate the download.

File: ..?..\uptwin1\help\modem_01.htm
Author: W.Büscher, MKT Systemtechnik
Last modified: 2006-06-07 (ISO8601, YYYY-MM-DD)