Interfacing GSM Modems
Interfacing GSM Modems
Interfacing GSM Modems
Features
Interface to GSM modems. Implementation of AT-Command set. PDU string compression and decompression. SMS transmission, how to send and receive.
1 Introduction
The GSM net used by cell phones provides a low cost, long range, wireless communication channel for applications that need connectivity rather than high data rates. Machinery such as industrial refrigerators and freezers, HVAC, vending machines, vehicle service etc. could benefit from being connected to a GSM system. Take a given example. A garage offers a very special package to their customers. Based on the mechanics knowledge and the given vehicle, tailored service intervals can be specified. A part of the service agreement is installation of a GSM modem in the vehicle. An onboard service application can then notify the garage when the vehicle approaches its service interval. The garage will schedule an appointment and inform the customer. The customer will benefit from a reliable and well-serviced vehicle at a minimum cost. The garage on the other hand can provide excellent customer support, vehicle statistics, efficient work scheduling, and minimum stocks. This application note describes how to use an AVR to control a GSM modem in a cellular phone. The interface between modem and host is a textual protocol called Hayes AT-Commands. These commands enable phone setup, dialing, text messaging etc. This particular application connects an AVR Butterfly and Siemens M65 cellular phone using a RS232 based data cable. Most cellular phones could be used, except Nokia phones using F or M-bus. Figure 1-1. Interconnection phone vs. AVR
Rev. 8016A-AVR-02/06
2 Theory of operation
The protocol used by GSM modems for setup and control is based on the Hayes ATCommand set. The GSM modem specific commands are adapted to the services offered by a GSM modem such as: text messaging, calling a given Phone number, deleting memory locations etc. Since the main objective for this application note is to show how to send and receive text messages, only a subset of the AT-Command set needs to be implemented. The European Telecommunication Standard Institute (ETSI) GSM 07.05 defines the AT-Command interface for GSM compatible modems. From this document some selected commands are chosen, and presented briefly in this section. This command subset will enable the modem to send and receive SMS messages. For further details, please consult GSM 07.05.
Before continuing, the following formats are used in Table 2-2 through 2-9: Character string in quotation marks is the actual text sent to modem. Optional commands and response parameters are enclosed in brackets.
2.1.1 Status (AT) The AT command is a status request used for testing if a compatible modem is connected and that the serial interface is working properly.
AVR323
8016A-AVR02/06
AVR323
Table 2-2. AT command and possible responses
Command AT Response OK ERROR Comment Connected and working Serial line OK, modem error
2.1.2 Echo off (ATE0) The ATE0 command is used to config the communication. By default, GSM modems are set to echo any received command back with an acknowledgement. An example of this is shown below.
AT\r\n AT\r\nOK\r\n //Command sent to modem //Response from modem with echo enabled
After sending AT, the modem replies with AT\r\rOK\r\n. With echo off, ATE0, the modem would have answered \r\nOK\r\n when executing AT. The echo off command will reduce traffic on the serial line. The ATE1 command will enable echo again. Table 2-3. ATE0 command and possible responses
Command ATE0 Response (echo off) OK ERROR Comment Echo off Could not turn echo off
2.1.3 New Message Indication (AT+CNMI) AT+CNMI configures how the modem signals arrival of new messages to the connected terminal device and how they are stored in the modem. This feature is useful when it comes to reading new messages. Instead of polling the modem periodically for arrival of new messages, AT+CNMI can tell when a new message has arrived. The AVR will catch such indication, and set a flag. This ensures that the modem only takes up CPU resources when necessary. Table 2-4. AT+CNMI command and possible responses
Command AT+CNMI=[mode] ,[mt] ,[bm] ,[ds] ,[bfr]
1 2 3 4 5
Response OK ERROR
Notes:
1. [mode] integer type: how messages are buffered. 2. [mt] integer type: indication of new SMS, set to 1. 3. [bm] integer type: Not in use. 4. [ds] integer type: Not in use. 5. [bfr] integer type: Not in use.
3
8016A-AVR-02/06
What values [mode], [mf], [bm], [ds] and [bfr] could take will be different from modem to modem. This should be tested off line with modem connected to the PC. An example is given below:
AT+CNMI=?\r\n +CNMI: (0,1),(0,1),(0,2),(0,2),(1) OK //Possible value request //Possible parameter values //Command executed OK
2.1.4 Preferred Message Storage (AT+CPMS) The AT+CPMS command sets the target memory location for storing sent, read, deleted and received SMS messages. Most modems have multiple storage types: SM: SIM card memory. ME: Mobile Equipment storage. Dedicated storage within the modem for text messages only. MT: Collection of all storage connected to the modem: SM, ME or others. The phone will chose one appropriate if this option is enabled. Table 2-5. AT+CPMS command and possible responses
Command 1 2 3 AT+CPMS=[M1] ,[M2] ,[M3] Response +CPMS:[used1],[total1],[used2], [total2],[used3],[total3] \r\rOK\r\n +CMS ERROR Notes: Error 1. [M1] string type: Memory from which messages are read and deleted. 2. [M2] string type: Memory to which messages are written and sent. 3. [M3] string type: Memory in which received messages are stored, if forwarding to pc is not set. [used] integer type: is number of messages currently in x. [total] integer type: is total number of message locations in x. Comment Memory configured OK
2.1.5 Message format(AT+CMGF) The AT+CMGF command is used to set input and output format of SMS messages. Two modes are available: PDU mode: reading and sending SMS is done in a special encoded format. Text mode: reading and sending SMS is done in plain text. PDU mode is described later in section 2.2. This compressed format saves message payload and is default on most modems. PDU mode is implemented in the source code for this application note, it is possible to use text mode to reduce code footprint if the connected modem supports this. In text mode header fields as sender address, message length, validation period etc. can be read out in plain text together with the sent message. Please consult GSM 4
AVR323
8016A-AVR-02/06
AVR323
07.05 for more about reading messages in text mode. This is not the main target for this application. Table 2-6. AT+CMGF command and possible responses
Command AT+CMGF=[mode] Notes:
1
Response OK ERROR
2.1.6 Read Message(AT+CMGR) The AT+CMGR command is used to read a message from a given memory location. Execution of AT+CMGR returns a message at [index] from selected memory [M1] (See section 2.1.4 for memory setup). The status of the message and the entire compressed message (PDU) is returned. To get any useful information out of the compressed message it should be decompressed. The PDU format and the compression and decompression is described in section 2.2.2. Table 2-7. AT+CMGR command and possible responses
Command AT+CMGR=[index]
1
Notes:
1. [index] integer type: Read message from location [index]. 2. [stat]: integer type: Status of message in memory: READ, UNREAD, SENT and UNSENT. 3. [alpha] integer type: Manufacturer specific field. Not used. 4. [length] integer type: Length of compressed message. 5. [pdu] string type: Compressed message.
2.1.7 Send Message(AT+CMGS) This command enables the user to send SMS messages. Section 2.2.3 describes how to build such messages. How to include user defined text and recipient telephone number. After the user defined fields are set, the message can be compressed and sent using the AT+CMGS command. An example usage of AT+CMGS is given in section 2.2.3.
5
8016A-AVR-02/06
1. [length] integer type: Length of message. 2. CR = Carriage return 3. [pdu] string type: Compressed message 4. Ctrl-Z: Command terminator. ASCII character 26 (dec).
2.1.8 Delete Message(AT+CMGD) This command is used to delete a received stored message from [M1] (See Table 25). Table 2-9. AT+CMGD command and possible responses
Command AT+CMGD=[index] Notes:
1
Response OK ERROR
This concludes the presentation of the implemented AT-Command set. More commands are discussed in ETSI standard GSM 07.05, and proposed as a reference when working with applications interfacing GSM compatible modems together with manufacturers datasheet.
2.1.9 Error codes Many of the commands in the implemented subset can terminate with an error message related to the modem or network. These could be errors such as: Memory failure. Invalid recipient number. Network timeout. SIM busy or wrong. Operation not allowed. No network service. These error messages can be useful, and could be implemented as a part of the application. It is possible to extend the handling of the error codes, but this is beyond the scope of this application note. We will just catch the ERROR message, and repeat the command. If more advanced error handling is desired one should refer to the modem datasheet.
AVR323
8016A-AVR-02/06
AVR323
2.2 PDU format explained
There are two ways of sending and receiving SMS messages: by text mode and by PDU (Protocol Description Unit) mode. By default most phones and modems are setup to send SMS messages using a special compression format (PDU-mode). Some modems supports text-mode, in which any information and the message itself can be read as plain text. Note however that not all phones and modems support text-mode.
2.2.1 Special data types and compression/decompression PDU-mode uses three special data types: Octet: Group of 8 bits in hexa-decimal encoding (0x00 0xFF). Example: E8. Semi-octet: Group of 8 bits in decimal encoding (0 153). Example: 11. Septet: Group of 7 bits in integer encoding (0->127). Example: 126. The default GSM alphabet uses 7 bits to represent characters. The message hello consists of five characters called septets, when represented with seven bits each. The septet string has to be encoded into an octet stream for SMS transfer (See Table 2-10). Table 2-10. Compressing septet string into octet stream
Value Decimal Hex Septet 8-bit Octet Notes: h 104 0x68 1101000 11101000 E8 e 101 0x 65 1100101 00110010 32 l 108 0x 6C 1101100 10011011 9B l 108 0x 6C 1101100 11111101 FD o 111 0x 6F 1101111 00000110 06
The first septet (h) is turned into an octet by adding the rightmost bit of the second septet (Bold). Inserted at the left this gives: 1 + 1101000 = 11101000 ("E8"). The second char (septet) then receives two bits (bold) from the third septet, so the second character (e) become an octet: 00 + 110010 = 00110010 ("32"). The five first bits of the last char (o) is padded with zeros (bold).
Messages encoded this way can then be added as payload to AT+CMGS command described in section 2.1.7. When receiving a new message, AT+CMGR can be used to read from the memory location where it resides. An octet stream will be returned from the modem. To extract any useful information from this stream a decompression method is needed. Table 2-11 shows an example decoding the octet representation of hello back into septets.
7
8016A-AVR-02/06
To become a septet, the first octet looses its leading 1(Bold) to the second octet. Here it is added at the back, meanwhile the two leading zeros are discarded. The last octet (06) looses its leading zero padding and copies (1111) received from the 4th octet at its end.
Figure 2-1 shows flowcharts for both routines as implemented in the source code. Algorithms are based on heuristic methods, since no such is specified in GSM 03.38 or GSM 03.40. Figure 2-1. Compress and decompress flowchart
Compress
NO
decompress
8
Last Char in array?
AVR323
NO
Read 2 chars Make 8 bit representati on
YES
array pointer % 8 == 0
YES
Return
Return
R e s e t c h a r c o u n t e r
N O
S t o r e c a r r y
8016A-AVR-02/06
AVR323
2.2.2 Receiving a message in PDU mode A SMS string consists of mainly three parts: length of header, header and the PDU string. When reading a message from the modem using AT+CMGR, a SMS string should be received:
AT+CMGR=42 //Read out SMS from message storage 42
+CMGR: 0,,42 //Received from phone //SMS string: 0791446742949940040ED0C5BAFC2D0ED3CB00005040623194914019E8329BFD06B5 40A06B10EA2A56A54F61905A740D9F4D OK //Acknowledge from phone. AT+CMGR returned OK.
To most people the above code snippet does not contain any readable information at all. Table 2-12 shows how to extract details from the returned SMS string. For a thorough presentation of all fields, code schemes, alphabets etc., please consult GSM 03.40. Table 2-12. Details in SMS string.
Description 07 Header 91 446742949940 Description Number of octets in header, 0x07 = 7 Numbering plan. 91 is international Service center number as semi-octet and reversed. Real number is +447624499904 First octet of SMSDeliver. Message sent from service center to GSM modem. Length of address 0x0E = 14 Address type Sender: Eurobate, octet string Protocol identifier Coding scheme Timestamp, semi-octets: 26.04.05 13:49:19 GMT+1,00 Length of user data. 0x19 = 25 septets User defined text: helloWAP.EUROBATE.COM.
04
0E D0 C5BAFC2D0ED3CB 00 00 50406231949140
PDU-String
19 E8329BFD06B540A06B10EA2A56A54F61905A740D9F4D
9
8016A-AVR-02/06
2.2.3 Building and sending a message in PDU mode The SMS message, as specified by the ETSI organization, can be up to 160 septets long. The maximal user payload is then restricted to 140 octets, together with additional fields in the PDU protocol. These additional fields are crucial since they contain information about receivers-address, address length, validity-period, type of address, data coding scheme, protocol identifier etc. A message sent from modem to a service center is called an SMS-SUBMIT message. Table 2-12 shows how to build such messages. To avoid any problems with manufacturer specific meta-data, the modem is set to do this using the 00 option. Rest of the protocol stack is defined according to GSM 03.40. Table 2-13. SMS-SUBMIT message fields.
Octet 00 Header Description Number of octets in meta data, 0 means that modem should use stored meta. First octet in SMSSUBMIT Message reference, 00 means that the modem sets the reference number. Address length: 0x0A = 10 Number type, international type Address of receiver: +4712345678 Protocol identifier Data coding scheme Expire time: 4 days Septet count: 0x05 = 5 septets. User defined text: hello.
11 00
In advance of sending our string, we need to calculate its length. Counting the number of octets, excluding the leading meta-information, gives a total length of 17 octets for the SMS string in Table 2-13. Using a terminal application, the following could be sent to the modem.
AT+CMGS = 18 //Send a message containing 18 octets, excluding //the two initial zeros
The modem will now delay for a while and get ready to receive the 18 octets long SMS string. A \r\n> will be displayed on the screen when the modem is ready to append your payload. See code below. 10
AVR323
8016A-AVR-02/06
AVR32 3
> //Promt given from phone when ready to send 0011000A9174214365870000AA05E8329BFD06<ctrl-z> //SMS string to send
The modem should now return OK, meaning that the message is sent. Using a Cellular Phone this could be verified as a new entry in the Sent Items folder. Most error messages for AT+CMGS originate from using the wrong message length, so this should be checked twice. Remember to omit counting any leading zeros in the header!
1
8016A-AVR-02/06
Now the connected system should enable sending AT-Commands from the terminal window. Test with AT to verify this. Connecting the same RS232 data cable to the AVR Butterfly, a suitable adapter has to be made. Outputs from the level-shifter on the AVR Butterfly are routed to a 3x1 header, and not directly compatible with the RS232 cable. An adapter is easily made out of a male DSUB9 connector and two 2-wire cables (Supplied with the STK500). Pin-out and wiring for such an adapter is shown in Table 3-1and Figure 3-2. Table 3-1. Pin chart for USART connection.
D-sub 9 male pin number 2 3 5 (GND) AVR Butterfly RX TX GND Comment Twist with TX Twist with RX GND
12
AVR323
8016A-AVR-02/06
AVR323
Figure 3-2. Schematics for serial adapter
AT
AT OK ERROR
Modem present, compatible with Commands Phone not connected Echo off
and AT-
ATE0
ATE0 OK ERROR
AT+CPMS=ME,ME,ME
+CPMS: OK ERROR
13
8016A-AVR-02/06
AT+CNMI=1,1,0,0,1
OK ERROR
Table 3-2 Shows how to setup the connected modem using a terminal application. Type the contents in the Command Sent column, appending CR+LF at the end. If you receive any error messages, check your command for exact spelling and parameters. The datasheet for the connected modem may contain more information about the error messages, and be a great tool when debugging. In Figure 3-3 details from modem setup using Bray Terminal application can be viewed.
14
AVR323
8016A-AVR-02/06
AVR32 3
Figure 3-3. Screen dump from modem setup
5
8016A-AVR-02/06
4 Implementation
This application note is accompanied with an implementation source code. This source code is made as an example of how to: Setup modem for new message indication. Send SMS messages containing user-defined text. Mechanism for identification of new message received. Read SMS message from a given memory location. Any AVR with sufficient memory capabilities (See section 4.3 for code foot print) and a UART is able to run this application. The source code is contained in five files and their headers. Together this forms a library that enables most Atmel AVRs to benefit the services from the GSM net. Source code files: AVRGSM_api.c: File containing api functions to init, delete, send and read from modem. AVRGSM_com.c: Low level USART driver. AVR_SMS_tools.c: Code for extracting important parameters in modem reply. AVR_SMS_zip.c: Compress and decompress functions for PDU-string. Further information can be obtained from the Doxygen documentation found in the source code directory.
16
AVR323
8016A-AVR-
02/06
AVR32 3
Sending AT-Commands in this manner the application code can safely determine the modem state. Continuing with the modem setup, one need to send ATE0 to turn echo off. If the modem acknowledges with OK everything is fine, and next command from Table 3- 2 can be executed. If any error occurs the setup routine returns an error code. See Figure 4-1 for complete flowchart for API_modem_init() method found in AVRGSM_api.c. Figure 4-1. API_modem_init() flow chart
in it P h o n e ( )
ATE0()
ret> 0
YES AT_CNMI()
NO
ret> 0
NO
YES
AT_CNMI()
Return -1 NO ret> 0
YES Return 1
7
8016A-AVR-02/06
NO
Return YES
readSMS( intindex_ )
Return -1
NO
YES
getPDU()
18
AVR323
8016A-AVR02/06
AVR32 3
4.3 Code footprint and compiler settings
In Table 4-1 the code footprint for the five source files is presented with optimization enabled and disabled. Table 4-1. Code footprint with and without optimization
File AVRGSM_api.c AVRGSM_com.c AVRGSM_tools.c AVRGSM_zip.c Total code size: Optimization enabled 479 bytes 602 bytes 154 bytes 557 bytes 1792 byes Optimization disabled 687 bytes 785 bytes 274 bytes 669 bytes 2415 bytes
The following settings need to be defined in the dialog window found under Project Options. Note that all settings are already defined in the example application. Table 4-2. Required compiler settings Category Tab Set to General Target Set Processor configuration to match target AVR.
Example
-cpu=m169, Atmega169
Set Memory model to Small. Library Configuration Check Enable bit definitions in I/O-include files. Define output file format such that the file can be opened in AVRStudio. Set to ubrof 8.
XLINK
Output
Ubrof 8 (forced)
5 Known Issues
This application note has been written for a Siemens M65 cellular phone. The code will work for this device as is. Any other GSM modem supporting the AT-Commands interface can also be used, but be aware of the following issues: Try the AT+CNMI command on your GSM modem. Some modems do not support empty parameter fields: AT+CNMI=1,1,,,1 (,,, represents three empty fields where the modem should use default settings). Check the modem datasheet for correct command terminator. Some modems can manage with just \r as terminator, other need \r\n. To find and verify the settings for the modem at hand, connect it to a PC as described in chapter 3. Go through all commands that your application need and check how they work and how they respond. Use this as a starting point to modify the application note source code.
1 9
8016A-AVR-02/06
6 References
Following documents from www.etsi.org: GSM 03.38 GSM 03.40 GSM 07.05 Utilized software: pduspy.exe: Used for verification of SMSstrings. http://www.nobbi.com/download.htm Terminal by Bray: Very stable terminal application. http://bray.velenje.cx/avr/terminal
20
AVR323
8016A-AVR02/06
Atmel Corporation
2325 Orchard Parkway San Jose, CA 95131, USA Tel: 1(408) 441-0311 Fax: 1(408) 487-2600
Atmel Operations
Memory
2325 Orchard Parkway San Jose, CA 95131, USA Tel: 1(408) 441-0311 Fax: 1(408) 436-4314
RF/Automotive
Theresienstrasse 2 Postfach 3535 74025 Heilbronn, Germany Tel: (49) 71-31-67-0 Fax: (49) 71-31-67-2340 1150 East Cheyenne Mtn. Blvd. Colorado Springs, CO 80906, USA Tel: 1(719) 576-3300 Fax: 1(719) 540-1759
Regional Headquarters
Europe
Atmel Sarl Route des Arsenaux 41 Case Postale 80 CH1705 Fribourg Switzerland Tel: (41) 26-426-5555 Fax: (41) 26-426-5500
Microcontrollers
2325 Orchard Parkway San Jose, CA 95131, USA Tel: 1(408) 441-0311 Fax: 1(408) 436-4314 La Chantrerie BP 70602 44306 Nantes Cedex 3, France Tel: (33) 2-40-18-18-18 Fax: (33) 2-40-18-19-60
ASIC/ASSP/Smart Cards
Zone Industrielle 13106 Rousset Cedex, France Tel: (33) 4-42-53-60-00 Fax: (33) 4-42-53-60-01 1150 East Cheyenne Mtn. Blvd. Colorado Springs, CO 80906, USA Tel: 1(719) 576-3300 Fax: 1(719) 540-1759 Scottish Enterprise Technology Park Maxwell Building East Kilbride G75 0QR, Scotland Tel: (44) 1355-803-000 Fax: (44) 1355-242-743
Asia
Room 1219 Chinachem Golden Plaza 77 Mody Road Tsimshatsui East Kowloon Hong Kong Tel: (852) 2721-9778 Fax: (852) 2722-1369
Japan
9F, Tonetsu Shinkawa Bldg. 1-24-8 Shinkawa Chuo-ku, Tokyo 1040033 Japan Tel: (81) 3-3523-3551 Fax: (81) 3-3523-7581
Literature Requests
www.atmel.com/literature
Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN ATMELS TERMS AND CONDITIONS OF SALE LOCATED ON ATMELS WEB SITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Atmels products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.
Atmel Corporation 2006. All rights reserved. Atmel, logo and combinations thereof, Everywhere You Are, AVR, AVR
Studio and others, are the registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others.
8 0 1 6 A A V R 0 2 / 0 6