JBL Application Guidex Software Guide 3500 Ag

Application Software Guide 3500-ag USR :: USR3500 M2M 3G Cellular Modem

User Manual: JBL Application Software Guide USR :: Product

Open the PDF directly: View PDF PDF.
Page Count: 224 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Courier M2M 3G Cellular Modem
USR3500
Application Guide
R24.0794.00(
ii
Revision History
Date
Reason For Changes
Version
1/28/14
Initial Release
2/25/14
Cosmetic updates
Copyright
© 2014 USRobotics. All rights reserved.
Trademarks
USRobotics®, CourierTM and the USRobotics logo are registered trademarks of
U.S. Robotics Corporation.
Contact Information
Web:
http://www.usr.com/contact
Consult our website for up-to-date product descriptions, documentation, application
notes, firmware upgrades, and troubleshooting tips: http://www.usr.com/support/3500
iii
1!OVERVIEW ............................................................................................................................................................ 13!
1.1!DEFINITIONS ..................................................................................................................................................... 13!
1.2!DESIGN PRINCIPLES .......................................................................................................................................... 13!
2!NETWORK CONFIGURATIONS ........................................................................................................................... 14!
2.1!PRIVATE IP WITH VPN ....................................................................................................................................... 14!
2.2!PRIVATE IP ....................................................................................................................................................... 15!
!Mobile Originated .................................................................................................................................... 15!2.2.1
!Mobile Originated with SMS wake up (Server initiated) ......................................................................... 15!2.2.2
2.3!PUBLIC IP BASED ............................................................................................................................................... 16!
2.4!STATIC VS DYNAMIC IP ADDRESSES .................................................................................................................... 17!
2.5!CONNECTION METHODOLOGY ............................................................................................................................. 18!
2.6!DATA CONNECTION ........................................................................................................................................... 18!
3!NVM QUEUE .......................................................................................................................................................... 19!
4!PROTOCOL OVERVIEW ....................................................................................................................................... 19!
4.1!PROTOCOL ....................................................................................................................................................... 19!
4.2!ASCII FORMAT ................................................................................................................................................. 19!
4.3!ASCII COMMAND/RESPONSE TYPES ................................................................................................................... 21!
5!STRING TOKENS .................................................................................................................................................. 24!
5.1!STRINGSEND EVENTS .................................................................................................................................... 26!
5.2!AT$STRINGTOKENS ..................................................................................................................................... 27!
!Action Command .................................................................................................................................... 27!5.2.1
!Read Command ...................................................................................................................................... 27!5.2.2
5.3!AT$STRINGTEST .......................................................................................................................................... 27!
!Action Command .................................................................................................................................... 28!5.3.1
!Example .................................................................................................................................................. 28!5.3.2
5.4!AT$STRINGSENDEMAIL ............................................................................................................................... 28!
!Action Command .................................................................................................................................... 28!5.4.1
!Read Command ...................................................................................................................................... 29!5.4.2
!Example .................................................................................................................................................. 30!5.4.3
5.5!AT$STRINGSENDSMS .................................................................................................................................. 31!
!Action Command .................................................................................................................................... 31!5.5.1
!Read Command ...................................................................................................................................... 32!5.5.2
!Example .................................................................................................................................................. 33!5.5.3
5.6!AT$STRINGSEND .......................................................................................................................................... 33!
!Action Command .................................................................................................................................... 33!5.6.1
!Read Command ...................................................................................................................................... 34!5.6.2
!Example 1: Send Email ......................................................................................................................... 35!5.6.3
!Example 2: Serial to TCP Endpoint Connection .................................................................................... 35!5.6.4
6!SYSTEM VARIABLES ........................................................................................................................................... 37!
6.1!VARIABLE IDENTIFIERS ....................................................................................................................................... 37!
6.2!STRING TOKENS ................................................................................................................................................ 37!
6.3!EVENTS ............................................................................................................................................................ 37!
6.4!LIST OF STATUS VARIABLES ............................................................................................................................... 38!
6.5!AT$VARIABLESTATUS ................................................................................................................................. 39!
!Read Command ...................................................................................................................................... 39!6.5.1
6.6!AT$VARIABLETHRESHOLD ......................................................................................................................... 40!
!Set Command ......................................................................................................................................... 40!6.6.1
!Delete Command .................................................................................................................................... 40!6.6.2
!Read Command ...................................................................................................................................... 40!6.6.3
!Example .................................................................................................................................................. 41!6.6.4
6.7!AT$VARIABLECOMPARE ............................................................................................................................. 41!
!Set Command ......................................................................................................................................... 42!6.7.1
!Delete Command .................................................................................................................................... 42!6.7.2
iv
!Read Command ...................................................................................................................................... 42!6.7.3
!Example .................................................................................................................................................. 43!6.7.4
6.8!AT$VARIABLESET ........................................................................................................................................ 43!
!Set Command ......................................................................................................................................... 43!6.8.1
!Delete Command .................................................................................................................................... 43!6.8.2
!Read Command ...................................................................................................................................... 44!6.8.3
!Example .................................................................................................................................................. 45!6.8.4
6.9!AT$VARIABLESEND ..................................................................................................................................... 45!
!Set Command ......................................................................................................................................... 45!6.9.1
!Delete Command .................................................................................................................................... 46!6.9.2
!Read Command ...................................................................................................................................... 46!6.9.3
!Example .................................................................................................................................................. 47!6.9.4
7!EVENTS ................................................................................................................................................................. 47!
7.1!EVENT TYPES ................................................................................................................................................... 48!
7.2!EVENT LABELS .................................................................................................................................................. 50!
7.3!SYSTEM EVENTS ............................................................................................................................................... 50!
7.4!EVENT LABEL COMMAND .................................................................................................................................... 51!
!AT$EVENTLABEL .................................................................................................................................. 51!7.4.1
7.5!EVENT DISPLAY COMMAND ................................................................................................................................ 52!
!AT$EVENTDISPLAY .............................................................................................................................. 52!7.5.1
Action command ............................................................................................................................................. 52!
Read command .............................................................................................................................................. 53!
Unsolicited response ...................................................................................................................................... 53!
7.6!EVENT FILTERS ................................................................................................................................................. 53!
7.7!EVENTS ............................................................................................................................................................ 53!
!AT$EVENTFILTER ................................................................................................................................. 54!7.7.1
Action Command ............................................................................................................................................ 54!
Read Command .............................................................................................................................................. 54!
Example .......................................................................................................................................................... 54!
7.8!EVENT SEQUENCES ........................................................................................................................................... 55!
7.9!EVENTS ............................................................................................................................................................ 55!
!AT$EVENTSEQUENCE ......................................................................................................................... 55!7.9.1
Action Command ............................................................................................................................................ 56!
Read Command .............................................................................................................................................. 56!
Example .......................................................................................................................................................... 57!
7.10!AT$EVENTGEN ........................................................................................................................................... 57!
8!POWER MANAGEMENT ....................................................................................................................................... 58!
8.1!EVENTS ............................................................................................................................................................ 58!
8.2!STRING TOKENS ................................................................................................................................................ 58!
8.3!AT$LOWPOWERON ...................................................................................................................................... 59!
!Action Command .................................................................................................................................... 59!8.3.1
!Delete Configuration ............................................................................................................................... 59!8.3.2
!Read Command ...................................................................................................................................... 59!8.3.3
!Example .................................................................................................................................................. 60!8.3.4
8.4!AT$LOWPOWEROFF .................................................................................................................................... 60!
!Action Command .................................................................................................................................... 60!8.4.1
!Delete Configuration ............................................................................................................................... 60!8.4.2
!Immediate Disable .................................................................................................................................. 61!8.4.3
!Read Command ...................................................................................................................................... 61!8.4.4
!Example .................................................................................................................................................. 61!8.4.5
9!IDENTIFICATION COMMANDS ............................................................................................................................ 63!
9.1!EVENTS ............................................................................................................................................................ 63!
9.2!STRING TOKENS ................................................................................................................................................ 63!
9.3!GET APPLICATION VERSION COMMAND ............................................................................................................... 64!
!AT$APPVERSION .................................................................................................................................. 64!9.3.1
Read Command .............................................................................................................................................. 64!
v
9.4!GET FIRMWARE VERSION COMMAND ................................................................................................................... 64!
!AT$FWVERSION ................................................................................................................................... 65!9.4.1
9.5!GET MODEM ID COMMAND ................................................................................................................................. 65!
!AT$MODEMID ........................................................................................................................................ 65!9.5.1
Read Command .............................................................................................................................................. 65!
9.6!GET SUBSCRIBER ID COMMAND ......................................................................................................................... 66!
!AT$SUBSCRIBERID .............................................................................................................................. 66!9.6.1
Read Command .............................................................................................................................................. 66!
9.7!DEVICE IDENTIFICATION ..................................................................................................................................... 66!
!AT$DEVICEID ........................................................................................................................................ 67!9.7.1
Action Command/Response ........................................................................................................................... 67!
Read Command/Response ............................................................................................................................ 67!
9.8!GET BUILD FEATURES ........................................................................................................................................ 67!
!AT$FEATURE ........................................................................................................................................ 68!9.8.1
Read Command .............................................................................................................................................. 68!
10!TIME ..................................................................................................................................................................... 69!
10.1!EVENTS .......................................................................................................................................................... 69!
10.2!STRING TOKENS .............................................................................................................................................. 69!
!Using a Stored Timestamp ................................................................................................................... 70!10.2.1
Example .......................................................................................................................................................... 70!
10.3!MANUALLY SET AND GET DEVICE CLOCK ........................................................................................................... 71!
!AT$TIME ............................................................................................................................................... 71!10.3.1
Action Command/Response ........................................................................................................................... 71!
Read Command/Response ............................................................................................................................ 71!
10.4!AUTOMATICALLY SET DEVICE CLOCK ................................................................................................................ 72!
!AT$AUTOTIME ..................................................................................................................................... 72!10.4.1
Action Command/Response ........................................................................................................................... 72!
Read Command/Response ............................................................................................................................ 72!
10.5!TIMERS ........................................................................................................................................................... 73!
!Timer Events ......................................................................................................................................... 73!10.5.1
!AT$TIMERSTART ................................................................................................................................ 73!10.5.2
Action Command ............................................................................................................................................ 73!
Restart Timer .................................................................................................................................................. 74!
Delete Timer ................................................................................................................................................... 74!
Read Command .............................................................................................................................................. 74!
Unsolicited Response ..................................................................................................................................... 74!
Example .......................................................................................................................................................... 75!
!AT$TIMERSTOP .................................................................................................................................. 75!10.5.3
Action Command ............................................................................................................................................ 75!
Delete Timer ................................................................................................................................................... 75!
Read Command .............................................................................................................................................. 76!
Example .......................................................................................................................................................... 76!
!Watchdog Examples ............................................................................................................................. 76!10.5.4
Server Connection Watchdog ......................................................................................................................... 76!
TCP Server Data Watchdog ........................................................................................................................... 77!
Serial Endpoint Data Watchdog ...................................................................................................................... 77!
10.6!ALARM CLOCK ................................................................................................................................................ 78!
!Alarm Clock Events .............................................................................................................................. 78!10.6.1
!AT$ALARMCLOCK .............................................................................................................................. 78!10.6.2
Action command ............................................................................................................................................. 78!
Read command .............................................................................................................................................. 79!
11!DEVICE CONFIGURATION ................................................................................................................................. 80!
11.1!SYSTEM VARIABLES ......................................................................................................................................... 80!
11.2!STRING TOKENS .............................................................................................................................................. 80!
11.3!SIGNAL QUALITY ............................................................................................................................................. 80!
!AT$CSQ ............................................................................................................................................... 80!11.3.1
Test command ................................................................................................................................................ 80!
vi
Action command ............................................................................................................................................. 80!
Parameter command ...................................................................................................................................... 81!
Read command .............................................................................................................................................. 81!
11.4!SMS FORWARDING BEHAVIOR ......................................................................................................................... 81!
!AT$SMSFORWARD ............................................................................................................................. 81!11.4.1
Action Command ............................................................................................................................................ 81!
Read Command .............................................................................................................................................. 82!
11.5!DEVICE RESET ................................................................................................................................................ 82!
!AT$RESET ........................................................................................................................................... 82!11.5.1
Action Command ............................................................................................................................................ 83!
Read command .............................................................................................................................................. 83!
Example .......................................................................................................................................................... 83!
11.6!DEVICE SHUTOFF ......................................................................................................................................... 84!
!AT$SHUTOFF ...................................................................................................................................... 84!11.6.1
11.7!DEVICE EVENT REPORTING .............................................................................................................................. 84!
!AT$REPORT ........................................................................................................................................ 85!11.7.1
Action Command ............................................................................................................................................ 85!
Read Command .............................................................................................................................................. 85!
!Unsolicited $REPORT .......................................................................................................................... 85!11.7.2
Unsolicited Response ..................................................................................................................................... 85!
12!CELLULAR COMMUNICATIONS ....................................................................................................................... 86!
12.1!GPRS EVENTS ............................................................................................................................................... 86!
12.2!STRING TOKENS .............................................................................................................................................. 87!
12.3!GPRS SETTINGS ............................................................................................................................................. 87!
!AT$CGDCONT ..................................................................................................................................... 87!12.3.1
Action Command ............................................................................................................................................ 87!
Delete Command ............................................................................................................................................ 88!
Read Command .............................................................................................................................................. 88!
12.4!NETWORK IP .................................................................................................................................................. 89!
!AT$IP .................................................................................................................................................... 89!12.4.1
Read Command .............................................................................................................................................. 89!
Parameters ..................................................................................................................................................... 89!
12.5!PING .............................................................................................................................................................. 89!
!AT$PING .............................................................................................................................................. 90!12.5.1
Action Command ............................................................................................................................................ 90!
Unsolicited Response ..................................................................................................................................... 90!
13!ETHERNET .......................................................................................................................................................... 91!
13.1!EVENTS .......................................................................................................................................................... 91!
13.2!SYSTEM VARIABLES ......................................................................................................................................... 91!
13.3!STRING TOKENS .............................................................................................................................................. 91!
13.4!ETHERNET INTERFACE ..................................................................................................................................... 91!
!AT$ENABLEETHERNET ...................................................................................................................... 92!13.4.1
Action Command ............................................................................................................................................ 92!
Read Command .............................................................................................................................................. 92!
13.5!ETHERNET IP .................................................................................................................................................. 93!
!GETETHERNETIP ................................................................................................................................ 93!13.5.1
!AT$ETHERNETIP ................................................................................................................................ 93!13.5.2
Read Command .............................................................................................................................................. 93!
13.6!DHCP SERVER ............................................................................................................................................... 94!
!AT$DHCPS ........................................................................................................................................... 94!13.6.1
Action Command ............................................................................................................................................ 94!
Read Command .............................................................................................................................................. 94!
!AT$DHCPDNS ..................................................................................................................................... 95!13.6.2
Action command ............................................................................................................................................. 95!
Read command .............................................................................................................................................. 95!
13.7!STATIC IP ADDRESS ........................................................................................................................................ 96!
!AT$STATICIP ....................................................................................................................................... 96!13.7.1
vii
Action Command ............................................................................................................................................ 96!
Read Command .............................................................................................................................................. 96!
13.8!NETWORK ADDRESS TRANSLATION (NAT) ......................................................................................................... 97!
!AT$NAT ................................................................................................................................................ 97!13.8.1
Action Command ............................................................................................................................................ 97!
Read Command .............................................................................................................................................. 97!
13.9!PORT FORWARDING ......................................................................................................................................... 98!
!AT$PORTFORWARD ........................................................................................................................... 98!13.9.1
Action Command ............................................................................................................................................ 98!
Read Command .............................................................................................................................................. 98!
13.10!EXAMPLE: HOW TO SETUP AN ETHERNET BRIDGE ............................................................................................. 99!
14!REMOTE AT COMMAND SUPPORT ................................................................................................................ 101!
14.1!TELNET PORT SETTINGS .............................................................................................................................. 101!
!System Variables ................................................................................................................................ 101!14.1.1
!String Tokens ...................................................................................................................................... 101!14.1.2
!Telnet Port Events .............................................................................................................................. 102!14.1.3
!AT$TELNETPORT ............................................................................................................................. 102!14.1.4
Action Command .......................................................................................................................................... 102!
Read Command ............................................................................................................................................ 102!
Example ........................................................................................................................................................ 103!
14.2!SMS COMMAND INTERFACE ........................................................................................................................... 104!
!AT$SMS ............................................................................................................................................. 104!14.2.1
Action Command .......................................................................................................................................... 104!
Read Command ............................................................................................................................................ 105!
Example ........................................................................................................................................................ 106!
15!ENDPOINT / BRIDGE: “PASS THROUGH” ROUTING SUPPORT ................................................................. 106!
15.1!EVENTS ........................................................................................................................................................ 107!
!Serial Endpoint Events ....................................................................................................................... 107!15.1.1
!TCP/UDP Endpoint Events ................................................................................................................. 108!15.1.2
15.2!SYSTEM VARIABLES ....................................................................................................................................... 108!
15.3!STRING TOKENS ............................................................................................................................................ 109!
15.4!ENDPOINT SETTINGS ...................................................................................................................................... 109!
!AT$ENDPOINT ................................................................................................................................... 110!15.4.1
Action Command .......................................................................................................................................... 110!
Read Command ............................................................................................................................................ 111!
!Examples ............................................................................................................................................ 114!15.4.2
15.5!BRIDGE (ROUTE) SETTINGS ............................................................................................................................. 115!
!Bridge Events ..................................................................................................................................... 115!15.5.1
!AT$BRIDGECREATE ......................................................................................................................... 116!15.5.2
Action Command .......................................................................................................................................... 116!
Immediate Command ................................................................................................................................... 116!
Delete Command .......................................................................................................................................... 116!
Read Command ............................................................................................................................................ 117!
!AT$BRIDGEDELETE ......................................................................................................................... 118!15.5.3
Action Command .......................................................................................................................................... 118!
Delete Command .......................................................................................................................................... 118!
Read Command ............................................................................................................................................ 118!
15.6!ENDPOINT SERVER ........................................................................................................................................ 119!
!AT$ESERVER .................................................................................................................................... 119!15.6.1
Action Command .......................................................................................................................................... 119!
Read Command ............................................................................................................................................ 119!
15.7!ONLINE DATA MODE ...................................................................................................................................... 120!
!AT$ONLINE ........................................................................................................................................ 121!15.7.1
15.8!FILTERING ENDPOINTS ................................................................................................................................... 121!
!Strip ETX/DLE .................................................................................................................................... 122!15.8.1
Example ........................................................................................................................................................ 122!
!Compress/Decompress ...................................................................................................................... 123!15.8.2
viii
Example 1 ..................................................................................................................................................... 123!
Example 2 ..................................................................................................................................................... 124!
16!AT PARSER ENDPOINTS ................................................................................................................................. 125!
16.1!EVENTS ........................................................................................................................................................ 125!
16.2!ASCII COMMANDS ........................................................................................................................................ 125!
!Action Command ................................................................................................................................ 125!16.2.1
!Read Command .................................................................................................................................. 126!16.2.2
!Example .............................................................................................................................................. 127!16.2.3
17!SMS ENDPOINTS ............................................................................................................................................. 127!
17.1!ENDPOINT CONFIGURATION ............................................................................................................................ 128!
17.2!EVENTS ........................................................................................................................................................ 128!
17.3!ASCII COMMANDS ........................................................................................................................................ 128!
!Action Command ................................................................................................................................ 128!17.3.1
!Read Command .................................................................................................................................. 129!17.3.2
18!FTP ENDPOINTS ............................................................................................................................................... 131!
18.1!CONFIGURATIONS .......................................................................................................................................... 131!
18.2!EVENTS ........................................................................................................................................................ 131!
!FTP GET ............................................................................................................................................. 131!18.2.1
!FTP PUT ............................................................................................................................................. 132!18.2.2
18.3!ASCII COMMANDS ........................................................................................................................................ 132!
!Action Command ................................................................................................................................ 132!18.3.1
!Read Command .................................................................................................................................. 133!18.3.2
18.4!GET EXAMPLE .............................................................................................................................................. 134!
18.5!PUT EXAMPLE .............................................................................................................................................. 134!
19!HTTP ENDPOINTS ............................................................................................................................................ 135!
19.1!CONFIGURATIONS .......................................................................................................................................... 135!
19.2!EVENTS ........................................................................................................................................................ 135!
!HTTP GET .......................................................................................................................................... 135!19.2.1
!HTTP PUT .......................................................................................................................................... 136!19.2.2
!HTTP POST ........................................................................................................................................ 136!19.2.3
19.3!ASCII COMMANDS ........................................................................................................................................ 136!
!Action Command ................................................................................................................................ 136!19.3.1
!Read Command .................................................................................................................................. 137!19.3.2
19.4!GET EXAMPLE ............................................................................................................................................... 139!
19.5!PUT EXAMPLE ............................................................................................................................................... 140!
20!EMAIL ENDPOINTS .......................................................................................................................................... 140!
20.1!CONFIGURATIONS .......................................................................................................................................... 140!
20.2!EVENTS ........................................................................................................................................................ 141!
!POP Endpoint ..................................................................................................................................... 141!20.2.1
!SMTP Endpoint ................................................................................................................................... 141!20.2.2
20.3!AT$ENDPOINT .......................................................................................................................................... 141!
!Action Command ................................................................................................................................ 141!20.3.1
!Read Command .................................................................................................................................. 142!20.3.2
20.4!EMAIL HEADER .............................................................................................................................................. 143!
!AT$EMAILHDR ................................................................................................................................... 143!20.4.1
Action Command .......................................................................................................................................... 143!
Read Command ............................................................................................................................................ 144!
20.5!EXAMPLE ...................................................................................................................................................... 144!
21!OFFLINE DATA MODE ..................................................................................................................................... 146!
21.1!EVENTS ........................................................................................................................................................ 146!
21.2!AT$ENDPOINT .......................................................................................................................................... 146!
!Action Command ................................................................................................................................ 146!21.2.1
!Read Command .................................................................................................................................. 147!21.2.2
ix
21.3!AT$EPWRITE ............................................................................................................................................. 147!
!Action Command ................................................................................................................................ 148!21.3.1
21.4!AT$EPREAD .............................................................................................................................................. 149!
!Action Command ................................................................................................................................ 149!21.4.1
21.5!OFFLINE DATA UNSOLICITED RESPONSES: ....................................................................................................... 150!
22!FTP OPERATIONS ............................................................................................................................................ 152!
22.1!FTP COMMAND EVENTS ................................................................................................................................ 152!
22.2!FTP COMMANDS ........................................................................................................................................... 152!
22.3!AT$FTPOPEN ............................................................................................................................................ 153!
!Action Command ................................................................................................................................ 153!22.3.1
!Immediate Command ......................................................................................................................... 153!22.3.2
!Delete OPEN parameters ................................................................................................................... 153!22.3.3
!Read Command .................................................................................................................................. 154!22.3.4
!Examples ............................................................................................................................................ 154!22.3.5
22.4!AT$FTPCLOSE .......................................................................................................................................... 155!
22.5!AT$FTPMKDIR ........................................................................................................................................... 155!
!Action Command ................................................................................................................................ 155!22.5.1
!Immediate Command ......................................................................................................................... 155!22.5.2
!Delete MKDIR parameters .................................................................................................................. 155!22.5.3
!Read Command .................................................................................................................................. 156!22.5.4
!Examples ............................................................................................................................................ 156!22.5.5
22.6!AT$FTPCWD .............................................................................................................................................. 157!
22.7!AT$FTPDELDIR ......................................................................................................................................... 157!
22.8!AT$FTPDEL ............................................................................................................................................... 157!
!Action Command ................................................................................................................................ 157!22.8.1
!Immediate Command ......................................................................................................................... 158!22.8.2
!Delete DEL parameters ...................................................................................................................... 158!22.8.3
!Read Command .................................................................................................................................. 158!22.8.4
!Examples ............................................................................................................................................ 159!22.8.5
22.9!AT$FTPREN ............................................................................................................................................... 159!
!Action Command ................................................................................................................................ 159!22.9.1
!Immediate Command ......................................................................................................................... 160!22.9.2
!Delete REN parameters ...................................................................................................................... 160!22.9.3
!Read Command .................................................................................................................................. 160!22.9.4
!Examples ............................................................................................................................................ 161!22.9.5
23!SMS ALERTING ................................................................................................................................................ 161!
23.1!SMS ALERTING EVENTS ................................................................................................................................ 162!
23.2!COMMANDS .................................................................................................................................................. 162!
23.3!AT$STRINGLIST ........................................................................................................................................ 162!
!Action Command ................................................................................................................................ 162!23.3.1
!Delete ................................................................................................................................................. 162!23.3.2
!Read Command .................................................................................................................................. 162!23.3.3
!Examples ............................................................................................................................................ 163!23.3.4
23.4!AT$SENDSMSLIST .................................................................................................................................... 163!
!Action Command ................................................................................................................................ 164!23.4.1
!Immediate Command ......................................................................................................................... 164!23.4.2
!Delete ................................................................................................................................................. 164!23.4.3
!Read Command .................................................................................................................................. 164!23.4.4
!Examples ............................................................................................................................................ 165!23.4.5
24!TAG FILE SYSTEM ........................................................................................................................................... 166!
24.1!TAG EVENTS ................................................................................................................................................. 166!
24.2!SYSTEM VARIABLES ....................................................................................................................................... 167!
24.3!STRING TOKENS ............................................................................................................................................ 167!
24.4!ENDPOINT CONFIGURATION ............................................................................................................................ 167!
!Tag Endpoint Events .......................................................................................................................... 168!24.4.1
!AT$ENDPOINT ................................................................................................................................... 169!24.4.2
x
Action Command .......................................................................................................................................... 169!
Read Command ............................................................................................................................................ 169!
24.5!TAG COMMANDS ........................................................................................................................................... 171!
24.6!TAG FORMAT ................................................................................................................................................ 171!
!AT$TAGFORMAT ............................................................................................................................... 171!24.6.1
Action Command .......................................................................................................................................... 171!
24.7!TAG RECOMPACT .......................................................................................................................................... 172!
!AT$TAGRECOMPACT ....................................................................................................................... 172!24.7.1
Action Command .......................................................................................................................................... 172!
24.8!TAG INSTALL ................................................................................................................................................. 173!
!AT$TAGINSTALL ............................................................................................................................... 173!24.8.1
Action Command .......................................................................................................................................... 173!
Read Command ............................................................................................................................................ 174!
Examples ...................................................................................................................................................... 174!
24.9!TAG WRITE ................................................................................................................................................... 175!
!AT$TAGWRITE .................................................................................................................................. 175!24.9.1
Action Command .......................................................................................................................................... 175!
Example ........................................................................................................................................................ 176!
24.10!TAG CLOSE ................................................................................................................................................. 176!
!AT$TAGCLOSE ............................................................................................................................... 176!24.10.1
Action Command .......................................................................................................................................... 176!
Read Command ............................................................................................................................................ 177!
Examples ...................................................................................................................................................... 178!
24.11!TAG DELETE ............................................................................................................................................... 178!
!AT$TAGDELETE .............................................................................................................................. 178!24.11.1
Action Command .......................................................................................................................................... 178!
Read Command ............................................................................................................................................ 179!
Examples ...................................................................................................................................................... 179!
24.12!TAG READ .................................................................................................................................................. 180!
!AT$TAGREAD .................................................................................................................................. 180!24.12.1
Action Command .......................................................................................................................................... 180!
24.13!TAG SYSTEM INFORMATION .......................................................................................................................... 181!
!AT$TAGSYSINFO ............................................................................................................................ 181!24.13.1
Action Command .......................................................................................................................................... 181!
24.14!TAG LIST ALL .............................................................................................................................................. 182!
!AT$TAGLISTALL .............................................................................................................................. 182!24.14.1
Action Command .......................................................................................................................................... 182!
24.15!TAG CREATE ............................................................................................................................................... 182!
!AT$TAGCREATE ............................................................................................................................. 183!24.15.1
Action Command .......................................................................................................................................... 183!
Read Command ............................................................................................................................................ 183!
Examples ...................................................................................................................................................... 184!
24.16!TAG DOWNLOAD .......................................................................................................................................... 184!
!AT$TAGDOWNLOADFTP and AT$TAGDOWNLOADHTTP ........................................................... 185!24.16.1
Action Command .......................................................................................................................................... 185!
Read Command ............................................................................................................................................ 186!
Examples ...................................................................................................................................................... 187!
!Firmware Upgrade (FOTA) ............................................................................................................... 188!24.16.2
Example ........................................................................................................................................................ 188!
24.17!TAG UPLOAD .............................................................................................................................................. 188!
!AT$TAGUPLOADFTP and AT$TAGUPLOADHTTP ........................................................................ 189!24.17.1
Action Command .......................................................................................................................................... 189!
Read Command ............................................................................................................................................ 189!
Examples ...................................................................................................................................................... 191!
25!GPIO .................................................................................................................................................................. 191!
25.1!EVENTS ........................................................................................................................................................ 192!
25.2!STRING TOKENS ............................................................................................................................................ 192!
25.3!AT$GPIOCONFIG ...................................................................................................................................... 192!
xi
!Action Command ................................................................................................................................ 192!25.3.1
!Read Command .................................................................................................................................. 193!25.3.2
25.4!AT$GPIOREAD .......................................................................................................................................... 194!
!Action Command ................................................................................................................................ 194!25.4.1
!Read Command .................................................................................................................................. 194!25.4.2
25.5!AT$GPIOWRITE ........................................................................................................................................ 194!
!Action Command ................................................................................................................................ 194!25.5.1
!Read Command .................................................................................................................................. 195!25.5.2
25.6!AT$GPIOACTION ...................................................................................................................................... 195!
25.7!AT$GPIOACTIONMULTI ............................................................................................................................ 195!
25.8!EXAMPLES .................................................................................................................................................... 196!
26!VOICE CALL SYSTEM ...................................................................................................................................... 197!
26.1!OVERVIEW .................................................................................................................................................... 197!
26.2!EVENT IDS .................................................................................................................................................... 197!
26.3!AT$VOICECALL ......................................................................................................................................... 198!
!Action Command/Response ............................................................................................................... 198!26.3.1
!Read Command/Response ................................................................................................................ 198!26.3.2
!Test Command/Response .................................................................................................................. 198!26.3.3
!Unsolicited response .......................................................................................................................... 198!26.3.4
26.4!AT$CALLSTART ........................................................................................................................................ 199!
!Action Command/Response ............................................................................................................... 199!26.4.1
!Read Command/Response ................................................................................................................ 199!26.4.2
................................................................................................................................................................. 200!26.4.3
26.5!AT$CALLANSWER .................................................................................................................................... 200!
!Action Command/Response ............................................................................................................... 201!26.5.1
!Read Command/Response ................................................................................................................ 201!26.5.2
................................................................................................................................................................. 201!26.5.3
26.6!AT$CALLHANGUP ..................................................................................................................................... 202!
!Action Command/Response ............................................................................................................... 202!26.6.1
!Read Command/Response ................................................................................................................ 202!26.6.2
................................................................................................................................................................. 202!26.6.3
26.7!VOICE CALL EXAMPLES .................................................................................................................................. 203!
27!DTMF TONE SYSTEM ...................................................................................................................................... 205!
27.1!OVERVIEW .................................................................................................................................................... 205!
27.2!DTMF EVENT IDS ......................................................................................................................................... 205!
27.3!AT$DTMFPLAY .......................................................................................................................................... 206!
!Action Command/Response ............................................................................................................... 206!27.3.1
!Read Command/Response ................................................................................................................ 206!27.3.2
27.4!AT$DTMFDETECT ..................................................................................................................................... 207!
!Action Command/Response ............................................................................................................... 208!27.4.1
!Read Command/Response ................................................................................................................ 208!27.4.2
!Unsolicited Response ......................................................................................................................... 208!27.4.3
27.5!DTMF TONE EXAMPLES ................................................................................................................................. 209!
28!GPS TRACKING ................................................................................................................................................ 210!
28.1!OVERVIEW .................................................................................................................................................... 210!
28.2!GPS EVENTS ................................................................................................................................................ 210!
28.3!SYSTEM VARIABLES ....................................................................................................................................... 210!
!Example .............................................................................................................................................. 211!28.3.1
28.4!STRING TOKENS ............................................................................................................................................ 211!
28.5!GPS CONFIGURATION ................................................................................................................................... 212!
!AT$GPS .............................................................................................................................................. 212!28.5.1
Action Command .......................................................................................................................................... 212!
Read Command ............................................................................................................................................ 212!
28.6!LOCATION MONITORING ................................................................................................................................. 213!
!AT$LOCATE ....................................................................................................................................... 213!28.6.1
Action Command .......................................................................................................................................... 213!
xii
Read Command ............................................................................................................................................ 214!
Unsolicited Response ................................................................................................................................... 214!
28.7!EXTENDED LOCATION MONITORING ................................................................................................................. 215!
!AT$LOCATEEXT ................................................................................................................................ 215!28.7.1
Action Command .......................................................................................................................................... 215!
Read Command ............................................................................................................................................ 215!
28.8!NMEA OUTPUT ............................................................................................................................................ 216!
!AT$NMEA ........................................................................................................................................... 216!28.8.1
Action Command .......................................................................................................................................... 216!
Read Command ............................................................................................................................................ 216!
28.9!GEOFENCE CONTROL ................................................................................................................................ 217!
!AT$GEOFENCE ................................................................................................................................. 217!28.9.1
Action Command .......................................................................................................................................... 217!
Read Command ............................................................................................................................................ 218!
Unsolicited Response ................................................................................................................................... 218!
28.10!SPEED MONITORING .................................................................................................................................. 218!
!AT$SPEED ....................................................................................................................................... 219!28.10.1
Action Command .......................................................................................................................................... 219!
Read Command ............................................................................................................................................ 219!
29!CONFIGURATION SYSTEM ............................................................................................................................. 220!
29.1!OVERVIEW .................................................................................................................................................... 220!
29.2!AT$CONFIG ............................................................................................................................................... 220!
30!FIRMWARE AND SOFTWARE UPDATES ....................................................................................................... 221!
30.1!DOWNLOADING MODEM FIRMWARE .................................................................................................................. 221!
30.2!DOWNLOADING APPLICATION SOFTWARE .......................................................................................................... 221!
31!APPENDIX A STATUS CODES ..................................................................................................................... 222!
31.1!<STATUS> PARAMETER .................................................................................................................................. 222!
31.2!STANDARD CME ERRORS .............................................................................................................................. 224!
13
1 Overview
The Courier M2M software is a platform for building robust M2M solutions that must
communicate with a server. A few of Courier M2M software’s more important features
include cellular modem control, bearer management, device management, GPS device
control, and asset tracking functionality. The purpose of this document is to describe
these features and AT command communication protocol of the Courier M2M software.
1.1 Definitions
In this document, the USR3500 executing the Courier M2M software is referred to as
the ‘device’. The remote node communicating with the device is referred to as the
‘server’.
The following table shows the acronyms used in this document and their meanings:
Abbreviation
Description
ADC
A to D Converter
APN
Access Point Name
ASCII
American Standard Code for Information
Interchange
DHCP
Dynamic Host Configuration Protocol
DNS
Domain Name System
FOTA
Firmware Upgrade Over The Air
GPRS
General Packet Radio Service
IP
Internet Protocol
NAT
Network Address Translator
NVM
Non-Volatile Memory (Flash)
PDP
Packet Data Protocol
SMS
Short Message Service
TCP
Transmission Control Protocol
UDP
User Datagram Protocol
USB
Universal Serial Bus
WD
Watchdog
1.2 Design Principles
This document is laid out to show the device interface for each individual subsystem or
feature. Within a subsystem or feature section, each “command” is defined and the
ASCII command is specified. Examples are provided as appendixes.
14
2 Network Configurations
Different network configurations can be used when communicating to a remote device.
The wireless provider (carrier) assigns the device an IP address when the device
connects to the wireless network’s data services. Depending on the network provider
and desired protocol, one of the following network configurations would be used:
Private IP with Virtual Private Network (VPN)
Private IP Network
Public IP Network
2.1 Private IP with VPN
Network configuration used when the device is assigned a private IP address by the
carrier. The device is behind the carrier’s NAT/Firewall and thus is assigned a private IP
address, which is not accessible by a remote server. But if bidirectional UDP or mobile
terminated TCP connections are required, then a server can use a Virtual Private
Network (VPN) tunnel so it can communicate inside the firewall. This way the server and
the device would be able to access each other’s private IP addresses.
In this configuration both the device and the server can originate and terminate IP based
messages (TCP or UDP).
If your system requires the server to originate connections to the modem, and you don’t
wish to rely on SMS to initiate those connections, then this is a good option. The
remaining option is to have the server and modem use public IP addresses.
15
2.2 Private IP
Network configuration used when the server has a public IP address, but the device is
assigned a private IP address. In this configuration the device can originate any IP
based messages (TCP or UDP).
Mobile Originated 2.2.1
The device is behind the carriers NAT/Firewall and thus is assigned a private IP
address that is not accessible from the rest of the internet. In this scenario, the private
IP address would not be accessible by a remote server.
Unfortunately, the only way IP based bidirectional communications are possible is if the
modem originates a TCP connection to the server. This way the NAT will be able to
manage the TCP connection so packets coming back from the server are received by
the modem.
The following figure illustrates a mobile originated use case.
Mobile Originated with SMS wake up (Server initiated) 2.2.2
The server cannot originate TCP connections or send UDP messages to the modem.
Because UDP is a connectionless protocol, UDP packets are blocked even if they are
responses to packets sent by the modem. Therefore, when the server needs to initiate
communications to the device, it would have to use cellular based SMS messages.
The following figure illustrates the use case for SMS messages.
16
This system is very common. It allows the modem to be protected behind the carrier’s
firewall. Also, if your system doesn’t require the server to initiate communications with
the modem then this will work well. If you do require server initiated communications,
then you must support two communication paths, GPRS and SMS.
2.3 Public IP based
Network configuration used when both the device and the server have publicly
accessible IP addresses. In this configuration both the device and the server are aware
of each other’s IP address.
17
When both the device and the server use public IP addresses, then both TCP and UDP
messages can be transmitted in both directions between the remote server and the
device.
This scenario is simple but security must be built into the system to ensure that access
to the modem is restricted to only those you wish to communicate with your device.
Without such security, a malicious attack could result in sensitive material being lost, the
device being disabled, and/or a very high data bill.
2.4 Static vs Dynamic IP Addresses
In all three scenarios above the service can either include static or dynamic IP
addressing for the modems. Static IP addresses are great because you can simplify
your server application by building a static look-up table to keep track of which IP
address goes with which device.
The other option is dynamic IP addresses. In this case, each time your modem activates
a GPRS context, the modem may be given a different IP address. Also, the IP address
may be changed from time to time even when connected to the network. Courier M2M
software has the ability to help a server keep a dynamic look-up table of devices in a
dynamic IP environment.
18
2.5 Connection Methodology
There are two methodologies for a device to communicate with a server; push or pull.
Which methodology you employ will depend on your network configuration and your IP
address configuration. Courier M2M software supports both methodologies.
Using the serial port, you can configure Courier M2M before you ship the device to be
installed. This interface is ideal for writing a TCL, Python or Perl script. For example, if
you configure Courier M2M software for an asset tracking application, you would set
how often you wish the device to update the server with position information and you
would need to set the IP address of the server with which you wish to communicate.
Once the device is in the field, there are two ways the device can operate. First, the
device can be configured to always initiate the connection with the server, send data
and then close the socket. This is the push methodology. You can also design your
system so the device never initiates communications. Instead your server always
initiates the connection by opening the socket, sending data to the device and then
closing the socket once the transfer has completed. This is the pull methodology. Lastly,
you can design your system to work with both push and pull. In all cases, there is no
need to keep sockets open any longer than it takes to complete the data transfer
initiated by either the device or the server.
2.6 Data Connection
Enter AT+WOPEN=1 to start the Courier M2M application. A startup banner will display.
Lib Version 1.9.1
Courier M2M Wireless Device
Application Started
If the application is already started, the startup banner will not display and an OK
response will be given.
To use IP data services, you need to configure an APN. Your cellular account needs to
have data services, and the cellular provider must provide you with an APN string.
Enter AT$CGDCONT=1,”<cellular.apn.string>” to set the APN. Use AT+CGREG? to
verify GPRS registration.
AT+CGREG?
+CGREG: 0,1
OK
A response with 0,1 indicates that your device is registered on the GPRS network. A
response of 0,0 would indicate not registered. Once you are registered, Courier M2M
will automatically activate a PDP context. Enter AT$IP to verify the device’s IP address.
AT$IP
$IP: "<deviceID>",0,"203.0.113.1"
OK
19
3 NVM Queue
Because of the nature of wireless technologies, where the network connection may be
lost from time to time, Courier M2M software has a Non-Volatile Memory Queue where
all outgoing data packets are stored before transmission. This way, important data will
not be lost. If, for example, the connection is lost when sending a GPS based Geofence
violation message, the data will be sent immediately when the network connection is
regained.
Also, if you’ve set any watchdog timers or a periodic reboot timer, then the stored data
survives reboots as well.
4 Protocol Overview
4.1 Protocol
This document describes the different interfaces that can be used to setup and control
the device via AT Command formatted messages.
The ASCII protocol is designed to be simple and human readable and is available for
setting up the device either on-site via the device’s serial port (USB/RS232) or remotely
through raw sockets, telnet session, or SMS messages. The ASCII protocol is an AT
Command (Hayes modem) based command and response interface. The advantage of
the ASCII protocol is that it is human readable, simple to read and therefore, quick to
implement. The ASCII commands can be sent to the UARTS, USB or Telnet ports. The
commands may also be sent via SMS messages if that option is configured using the
AT$SMS command. The response to the AT command is sent back to the same port
from which the command was received.
4.2 ASCII Format
The ASCII protocol is designed to work across all communication bearers. It can be
used over SMS, TCP/UDP or a serial interface. The interface is based on the AT
command protocol (V.250 specification). Using this design principle, the same protocol
can be used for communication between the server and the device, communications
with a service technician over a serial interface and used at manufacturing time to test
the device.
The command’s intermediate and final responses are sent from the device in response
to the command. In the case of “events”, unsolicited responses are sent over the bearer
that initiated the command. Commands are described as “Read”, “Action” and “Test”.
20
The Read commands are used to query a setting on the device. Use an ASCII “?” as the
last character of the command to denote a Read command.
Action commands are used to assign values to settings on the device. The command
containing an ASCII “=” is used to denote a Parameter command. The “=” can be
followed by 0 or more parameters, depending on which parameters are required and
which are optional.
Action commands are used to initiate an action. When the command doesn’t include
parameters, the “=” or “?” after the command then it is an action command.
Test commands are used to verify the syntax of a particular command. The ASCII string
“=?” as the command’s last characters is used to show the syntax of a command.
Please refer to the V.250 specification for more background on the structure of the
ASCII protocol.
21
4.3 ASCII Command/Response Types
The following table defines the AT command based messages.
Type
Description
Events
AT$EVENTLABEL
Encode and decode Event Labels
AT$EVENTDISPLAY
Display events when they are generated
AT$EVENTFILTER
Configure a list of events to subscribe to for use in other event
capable commands
AT$EVENTSEQUENCE
Define a list of events to match to trigger a sequence event.
AT$EVENTGEN
Used to generate system or user defined events manually
Identification
AT$APPVERSION
Get the application and hardware version
AT$FWVERSION
Get the modem firmware version
AT$MODEMID
Return the modem ID, usually the IMEI
AT$SUBSCRIBERID
Return the subscriber ID, usually the IMSI
AT$DEVICEID
Set and Get the Device Id
AT$FEATURE
Gets the build features
Time
AT$TIME
Set and Get the current time
AT$AUTOTIME
Set and Get the Autotime Mode
AT$TIMERSTART
Start a timer
AT$TIMERSTOP
Stop a timer
AT$ALARMCLOCK
Configure or delete an alarm
Device Control
AT$SMSFORWARD
Set and Get SMS Forward Mode
AT$RESET
Reset the device
AT$REPORT
Configures which unsolicited reports are generated by the device
and report various device statuses
AT$LOWPOWERON
Enable low power mode
AT$LOWPOWEROFF
Disable low power mode
Communications
AT$CGDCONT
Set and Get PDP context
AT$IP
Returns the network IP address of the device
AT$PING
Allows a device to ping a remote server
Ethernet
AT$ENABLEETHERNET
Enable/Disable the Ethernet interface
AT$ETHERNETIP
Returns the Ethernet IP address of the device
AT$DHCPS
Set and Get DHCP settings for Ethernet Interface
AT$STATICIP
Set and Get static IP for Ethernet Interface
22
Type
Description
AT$DHCPDNS
Set and get DNS settings for the DHCP server
Endpoint / Bridge
AT$ENDPOINT
Set and Get Endpoint used for “Pass through” routing
AT$BRIDGECREATE
Query or Connect 2 endpoints completing a “Pass through” route
AT$BRIDGEDELETE
Define or query bridge DELETE parameters.
AT$ONLINE
Return serial endpoint to online data mode.
AT$EPWRITE
Write data to an Offline Data Mode Endpoint
AT$EPREAD
Read data from an Offline Data Mode Endpoint
Email
AT$ESERVER
Define and query Endpoint Server settings
AT$EMAILHDR
Define and query Email Header settings
Remote AT Commands
AT$TELNETPORT
Set and Get telnet port used for AT
AT$SMS
Set and Get SMS AT command configuration
FTP Commands
AT$FTPOPEN
Open an FTP session.
AT$FTPCLOSE
Close an FTP session.
AT$FTPMKDIR
Make a directory.
AT$FTPCWD
Change working directory.
AT$FTPDELDIR
Delete a directory.
AT$FTPDEL
Delete a file.
AT$FTPREN
Rename a file.
Tag File System
AT$TAGFORMAT
Format the Tag file system.
AT$TAGRECOMPACT
Recompact the FLASH containing the Tag file system.
AT$TAGINSTALL
Install a Tag file as either new cellular modem firmware or
software application.
AT$TAGDELETE
Delete a Tag.
AT$TAGCREATE
Create an empty tag file.
AT$TAGWRITE
Write data to a Tag.
AT$TAGCLOSE
Close a Tag file.
AT$TAGREAD
Read data from a Tag.
AT$TAGSYSINFO
Display system information on Tag file system.
AT$TAGLISTALL
List all Tag files in the file system.
AT$TAGDOWNLOADFTP
Download from FTP server to tag file.
AT$TAGDOWNLOADHTTP
Download from HTTP server to tag file.
AT$TAGUPLOADFTP
Upload from tag file to FTP server.
AT$TAGUPLOADHTTP
Upload from tag file to HTTP server.
GPIO
AT$GPIOCONFIG
Allocate, deallocate, save and delete from flash and view the
23
Type
Description
status and capabilities of GPIOs
AT$GPIOREAD
Read one or more GPIOs
AT$GPIOWRITE
Write to one or more GPIOs
AT$GPIOACTION
Allow multiple events to operate on one GPIO
AT$GPIOACTIONMULTI
Allow multiple GPIOs to be manipulated by one event.
GPS Tracking
AT$LOCATE
Set unsolicited locate time and get current location
AT$GEOFENCE
Set and get parameters for Geofence tracking
AT$SPEED
Set and get speed settings and status
AT$LOCATEEXT
Set and get extended location filter assignments
SENSOR
AT$SENSORCONFIG
Define a sensor driver.
AT$SENSORCALIBRATE
Define a calibration table for a sensor channel.
AT$SENSORTRIGGER
Define trigger events for reading a sensor channel.
AT$SENSORREAD
Read a sensor channel.
Config System
AT$CONFIG
Set and get configuration settings
System Variables
AT$VARIABLETHRESHOLD
Configure a variable threshold.
AT$VARIABLECOMPARE
Configure a variable comparison.
AT$VARIABLESET
Configure a variable to be modified.
AT$VARIABLESEND
Send a variable to an endpoint.
24
5 String Tokens
String tokens are placeholder variables that may be placed in any string that is passed
in to any software command. At runtime the string tokens are evaluated and replaced
with the appropriate values. This allows for creating dynamic strings that can be used
for file and directory names, or for SMS and email messages.
String tokens are inserted into a string with a percent sign (%) before and after the
name. For example, if a string contains the string token %year%, then it will be
replaced with "2013". The name is case sensitive. If a string token name is not
recognized, it is replaced with “%?%”. To include a percent sign in the string without
referring to a string token, insert “%%”.
The token name can be used with a prefix and/or postfix number to modify its meaning.
For example, if the string token “FILL” is inserted in a string as %10FILL46%, then it will
be replaced with 10 of the ASCII character 46 (period), or “……….”. If either number is
not included, it is assumed to be 0. Not all string tokens use the numbers.
String token processing can be enabled or disabled. When disabled, the original string
is not modified.
The table below lists all the string tokens. The current list can be queried with the
AT$STRINGTOKENS? Command.
Name
Description
Prefix #
Postfix #
system
%%
Insert a single percent sign
CR
Carriage return (default count=1)
count
CRLF
Carriage return, line feed (default count=1)
count
HT
Horizontal tab (default count=1)
count
LF
Line feed (default count=1)
count
FILL
Fill string with characters (default count=1)
count
character
lowpwr
Low power mode (0=disabled, 1=enabled)
time
year
Year (4 digits)
Min width
counter
month
Month
Min width
counter
monthname
Month name
counter
day
Day of the month
Min width
counter
dow
Day of the week (1=Sun, 7=Sat)
Min width
counter
downame
Day of the week name
counter
hourint
Hour in 24 hour format
Min width
counter
hourus
Hour in 12 hour format
Min width
counter
ampm
AM or PM
counter
25
Name
Description
Prefix #
Postfix #
minute
Minutes (2 digits)
counter
second
Seconds (2 digits)
counter
identification
mfg
Modem manufacturer
model
Modem model
subid
Subscriber Id
modemid
Modem id
deviceid
Device id
modulefirmver
Modem firmware version
appver
Software application version
platver
Software platform version
hwver
Modem hardware version
projname
Name of the project build.
features
Feature bitmap in hex.
counter
counter
General purpose counter. N=1-20
N
nvcounter
General purpose NVM counter. N=1-20
N
gpio
gpio
Status of GPIO pin
pin
endpoint
epbyteswritten
Bytes written to endpoint X buffer
X
eptransactions
Transactions written to endpoint X buffer
X
epbytesread
Bytes written to endpoint X buffer
X
ip
telnet
Telnet server status. 0=off, 1=on, 2=client connected
tcpserver
TCP server status. 0=off, 1=on, 2=client
connected
udpserver
UDP server status. 0=off, 1=on
ethernet
etheron
Ethernet on (0-1)
etherlink
Ethernet link status (cable connected)
gatewayip
Static IP address of the local ethernet interface
network
apn
Access Point Name for Context ID (1-4)
ID
sig
Signal strength
wanip
IP address from the cellular network
tag
26
Name
Description
Prefix #
Postfix #
tagmemtotal
Tag memory total bytes
tagmemdel
Tag memory deleted bytes
tagmemfree
Tag memory free bytes
tagrecompact
Tag recompact flag.
1=Recompact on next reset.
gps
longitudeF
GPS longitude, Float format
Min width
Decimal
places
latitudeF
GPS latitude, Float format
Min width
Decimal
places
speedF
GPS speed, Float format
Min width
Decimal
places
headingF
GPS heading, Float format
Min width
Decimal
places
altitudeF
GPS altitude, Float format
Min width
Decimal
places
accuracyF
GPS accuracy, Float format
Min width
Decimal
places
mileageF
GPS miles between updates, Float format
Min width
Decimal
places
latitude
Latitude (deg*1000000)
longitude
Longitude (deg*1000000)
heading
Heading (deg*10)
speed
Current speed (mph*10)
altitude
Altitude (feet*10)
numsat
Number of GPS satellites
accuracy
Accuracy (miles*1000000)
mileage
Miles between updates (*1000)
odometer
Accumulated miles *1000
fixtime
Fix time, secs since 1/1/1970
sensor
sensor
The current sensor stored value. Postfix # X = (Id*16)
+ channel.
X
5.1 STRINGSEND Events
These events are generated by the STRINGSEND commands. The EventType is 9.
The ObjectId for the event is the StringSend ID. See section 7 for more about events.
Name
EventId
Description
Started
1
A STRINGSEND transfer has started.
Done
2
A STRINGSEND transfer has completed.
27
Error
3
A STRINGSEND transfer encountered an error.
Aborted
4
A STRINGSEND transfer was aborted.
5.2 AT$STRINGTOKENS
This Command enables or disables the string token processing, and lists all string
tokens.
Action Command 5.2.1
The following shows the command (in bold) to enable or disable string token
processing.
AT$STRINGTOKENS=<mode>
$STRINGTOKENS: ”<deviceId>”,<status>
(OK | ERROR)
Read Command 5.2.2
The following shows the command (in bold) to list all string tokens with a brief
description.
AT$STRINGTOKENS?
$STRINGTOKENS: ”<deviceId>”,<status>,<mode>
$STRINGTOKENS: ”<deviceId>”,<status>,%name%,”Description”
…...(list of all string tokens)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<mode>
0 Disable processing
1 – Enable processing
<status>
Description
0
Success
1050
Invalid <mode>.
5.3 AT$STRINGTEST
28
This Command is used to test the formatting of the dynamic string tokens. A string that
contains string tokens is entered and is processed. Its replacement string is displayed.
This provides an aid for developing dynamic strings to be used in other system
commands.
Action Command 5.3.1
The following shows the command (in bold) to test a string.
AT$STRINGTEST="<string with tokens>"
$STRINGTOKENS: ”<deviceId>”,<status>,”<replacement string>”
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<status>
Description
0
Success
1050
Invalid string
Example 5.3.2
AT$STRINGTEST="Current date and time: %downame% %month%/%day%/%year%
%hourus%:%minute%:%second% %ampm%"
$STRINGTEST: "327004000672",0,"Current date and time: Wednesday 6/20/2012
5:38:36 PM"
OK
5.4 AT$STRINGSENDEMAIL
This Command is used to send an email with a string that may contain string tokens.
This command creates a temporary SMTP Email endpoint to send the email. The email
may be sent immediately, or triggered by any event.
The command parameters are saved to NVM and restored after power cycles, unless
there are no events specified. If the command is entered to be executed immediately,
then nothing is saved to NVM.
Action Command 5.4.1
The following shows the command (in bold) to send a string.
29
AT$STRINGSENDEMAIL=<strSendId>,<eServerId>,<emailHdrId>,"<msgString>"
[,<attachTagId>[,<compress>[,<eventLabel>[...,<eventLabel>]]]]
$STRINGSENDEMAIL: ”<deviceId>”,<status>
(OK | ERROR)
The above command response indicates the status of the command and its parameters.
If successful, then when triggered by an <eventLabel>, a connection will be established
with the SMTP email server, and the <msgString> will be sent. Unsolicited messages
will be output to indicate the progress:
$STRINGSENDEMAIL: ”<deviceId>”,<status>,< strSendId >,<transferStatus>
To delete a STRINGSENDEMAIL Id, enter the command with the StringSend Id as the
only parameter:
AT$STRINGSENDEMAIL=< strSendId >
Read Command 5.4.2
The following shows the command (in bold) to query the STRINGSENDEMAIL settings.
AT$STRINGSENDEMAIL?
$STRINGSENDEMAIL: ”<deviceId>”,<status>,<strSendId>,<eServerId>,<emailHdrId>,
"<msgString>",<attachTagId>,<compress>,<eventLabel>...,<eventLabel>
…...(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<strSendId >
StringSendEmail identifier (1-20).
<eServerId>
Endpoint Server Id. The Eserver contains the SMTP
server’s IP address, and optional port, username, and
password.
emailHdrId
Email Header Id. The Email header contains the sender
and recipient information.
<msgString>
The body of the email, which may contain string tokens.
The tokens will be evaluated when the email transfer is
triggered to begin.
30
<tagId>
Not currently supported. Tag file to be attached to the
email.
<compress>
Not currently supported.
Type of compression performed on the tag file before
attaching to the email:
0 = None (default)
1 = zlib
2 = bzip
<eventLabel>
EventLabel in hex. This defines the event(s) that trigger
the sending of the email. There may be from 0 to 10
values. A null or 0 value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
<transferStatus >
Status of the transfer process:
1 = Transfer has started.
2 = Email was sent successfully.
3 = An error was encountered.
4 = Transfer was aborted.
<status>
Description
0
Success
1050
Invalid StringSend Id
1052
Already in use
1055
Invalid Eserver Id
1056
Invalid EmailHdr Id
1100
Invalid Tag Id
Example 5.4.3
The following example sets up StringSendEmail Id 3 to send an email when timer 1
expires. The <eventLabel> for Timer 1 expiration is 00020103 (see section 10.5.1).
Event Type = 2 for Timers
Object Id = 1 for Timer 1
Event Id = 3 for Timer Expiration
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=2,1,3
$EVENTLABEL: "327004000672",0,"00020103"
OK
AT$ESERVER=1,"smtp.mail.example.com",587,"myemailid@example.com","mypasswd",2
AT$EMAILHDR=1,"myemailid@example.com","My Name","someone@example.com", ,,"My
Subject"
31
AT$STRINGSENDEMAIL=3,1,1,"Email body sent at %hourus%:%minute%:%second%
%ampm%",0,0,00020103
To test, this command creates Timer 1 with a duration of 30 seconds:
AT$TIMERSTART=1,300
Another alternative for triggering the email is to have it sent every time the modem
acquires a GPRS connection. For that, use the event for IP Address Changed (see
section 12.1):
Event Type = 50 for Network
Object Id = 0 (not used)
Event Id = 1 for IP Changed
AT$EVENTLABEL=50,0,1
$EVENTLABEL: "327004000672",0,"00320001"
AT$STRINGSENDEMAIL=3,1,1,"GPRS acquired at %hourus%:%minute%:%second%
%ampm%",0,0,00320001
5.5 AT$STRINGSENDSMS
This Command is used to send an SMS message with a string that may contain string
tokens. This command creates a temporary SMS endpoint to send the message. The
SMS may be sent immediately, or triggered by any event.
The command parameters are saved to NVM and restored after power cycles, unless
there are no events specified. If the command is entered to be executed immediately,
then nothing is saved to NVM.
Action Command 5.5.1
The following shows the command (in bold) to send a string.
AT$STRINGSENDSMS=<strSendId>,"<smsPhoneNum>","<msgString>"[,<eventL
abel> [...,<eventLabel>]]
$STRINGSENDSMS: ”<deviceId>”,<status>
(OK | ERROR)
The above command response indicates the status of the command and its parameters.
If successful, then when triggered by an <eventLabel>, the <msgString> will be sent.
Unsolicited messages will be output to indicate the progress:
32
$STRINGSENDSMS: ”<deviceId>”,<status>,<strSendId>,<transferStatus>
To delete a STRINGSENDSMS Id, enter the command with the StringSend Id as the
only parameter:
AT$STRINGSENDSMS=<strSendId>
Read Command 5.5.2
The following shows the command (in bold) to query the STRINGSENDSMS settings.
AT$STRINGSENDSMS?
$STRINGSENDSMS:
”<deviceId>”,<status>,<strSendId>,<smsPhoneNum>,"<msgString>",
<eventLabel>...,<eventLabel>
…...(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<strSendId >
StringSendSms identifier (1-20).
<smsPhoneNum>
SMS Phone Number. This number must be a valid
destination phone number.
<msgString>
The content of the SMS message, which may contain
string tokens. The tokens will be evaluated when the
message is sent.
<eventLabel>
EventLabel in hex. This defines the event(s) that trigger
the sending of the SMS. There may be from 0 to 10
values. A null or 0 value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
<transferStatus >
Status of the transfer process:
1 = Transfer has started.
2 = SMS was sent successfully.
3 = An error was encountered.
4 = Transfer was aborted.
<status>
Description
33
0
Success
1050
Invalid StringSend Id
1052
Already in use
Example 5.5.3
The following example sets up StringSendSms Id 2 to send an SMS when timer 1
expires. The <eventLabel> for Timer 1 expiration is 00020103 (see section 10.5.1).
Event Type = 2 for Timers
Object Id = 1 for Timer 1
Event Id = 3 for Timer Expiration
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=2,1,3
$EVENTLABEL: "327004000672",0,"00020103"
OK
AT$STRINGSENDSMS=2,”9195551234”,"SMS body sent at %hourint%:%minute%:
%second%",00020103
To test, this command creates Timer 1 with a duration of 30 seconds:
AT$TIMERSTART=1,300
5.6 AT$STRINGSEND
This Command is used to send a string that may contain string tokens to an existing
endpoint. The transfer may be triggered immediately, or by any event.
The command parameters are saved to NVM and restored after power cycles, unless
there are no events specified. If the command is entered to be executed immediately,
then nothing is saved to NVM.
Action Command 5.6.1
The following shows the command (in bold) to send a string.
AT$STRINGSEND=<strSendId>,<endpointId>,"<msgString>"[,<eventLabel>
[...,<eventLabel>]]
$STRINGSEND: ”<deviceId>”,<status>
(OK | ERROR)
34
The above command response indicates the status of the command and its parameters.
If successful, then when triggered by an <eventLabel>, the <msgString> will be sent to
the specified endpoint. Unsolicited messages will be output to indicate the progress:
$STRINGSEND: ”<deviceId>”,<status>,< strSendId >,<transferStatus>
To delete a STRINGSEND Id, enter the command with the StringSend Id as the only
parameter:
AT$STRINGSEND=< strSendId >
Read Command 5.6.2
The following shows the command (in bold) to query the STRINGSEND settings.
AT$STRINGSEND?
$STRINGSEND: ”<deviceId>”,<status>,<strSendId>,<endpointId>,"<msgString>",
<eventLabel>...,<eventLabel>
…...(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<strSendId >
StringSend identifier (1-20).
<endpointId>
Endpoint Id. This endpoint must already exist.
<msgString>
The string to be sent, which may contain string tokens.
The tokens will be evaluated when the message is sent.
<eventLabel>
EventLabel in hex. This defines the event(s) that trigger
the sending of the string. There may be from 0 to 10
values. A null or 0 value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
<transferStatus >
Status of the transfer process:
1 = Transfer has started.
2 = String was sent successfully.
3 = An error was encountered.
4 = Transfer was aborted.
<status>
Description
35
0
Success
1050
Invalid StringSend Id
1052
Already in use
1090
Invalid Endpoint Id
1091
Endpoint Id out of range
Example 1: Send Email 5.6.3
The following example sets up StringSend Id 4 to send the given string to endpoint 8
(which is an SMTP email endpoint) when timer 1 expires. The <eventLabel> for Timer 1
expiration is 00020103 (see section 10.5.1).
Event Type = 2 for Timers
Object Id = 1 for Timer 1
Event Id = 3 for Timer Expiration
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=2,1,3
$EVENTLABEL: "327004000672",0,"00020103"
OK
AT$ESERVER=1,"smtp.mail.example.com",587,"myemailid@example.com","mypasswd",2
AT$EMAILHDR=1,"myemailid@example.com","My Name","someone@example.com", ,,"My
Subject"
AT$ENDPOINT=8,8,1,1
AT$STRINGSEND=4,8,"String was sent at %hourint%:%minute%: %second%",00020103
To test, this command creates Timer 1 with a duration of 30 seconds:
AT$TIMERSTART=1,300
Example 2: Serial to TCP Endpoint Connection 5.6.4
This example shows how a string can be sent to a TCP server when the connection is
first made. A pass-through connection is established between a serial endpoint and a
TCP endpoint. Every time the TCP endpoint connects to the remote server, a string is
sent to the server.
The following commands set up StringSend Id 5 to send a string to TCP endpoint 6
when the TCP connection is opened to its remote server. This uses the TCP Open
event as the trigger to send the string. The <eventLabel> for endpoint 6 Open is
00650101 (see section 15.1.2).
36
Event Type = 101 for TCP endpoints
Object Id = 6 for endpoint 6
Event Id = 1 for TCP Open
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=101,1,1
$EVENTLABEL: "327004000672",0,"00650101"
OK
AT$STRINGSEND=5,6,"Connected %hourint%:%minute%:%second%%CRLF%Version
%appver%%CRLF%",00650101
Then the pass-through connection is set up between serial port 1 and the TCP server at
www.example.com, port 2025:
AT$ENDPOINT=6,1,2025,www.example.com
AT$BRIDGECREATE=1,1,6,2
AT$ENDPOINT=1,3,1
After a power cycle, or any other time the TCP connection is established, the TCP
server receives the string:
Connected 14:08:10
Version 1.00
37
6 System Variables
The System Variables subsystem manages two types of system variables:
1. Configuration – Configuration settings which are constant. These settings are
non-volatile and stored in NVM.
2. Status – Dynamic values that change during runtime. These values may or may
not be non-volatile.
System variables are signed 32-bit values, unless stated otherwise.
Events can be generated based on generic conditions such as when a variable
changes, or crosses a threshold value. This subsystem also provides the ability to do
generic work on any status variable at a regular interval.
6.1 Variable Identifiers
Every system variable has a unique identifier that is used manage that variable. The
identifier is a 24 bit value, with the most significant 16 bits specifying the parent
subsystem. The subsystem is the same as the Event Type field used by events (see
Table 7.1). The lower 8-bits specify the specific variable in the subsystem.
6.2 String Tokens
Each variable’s runtime value can be used in a string token. The name of the variable
doubles as its string token name. This permits the value to be used in any context that
accepts a string token.
In addition to each variable, the following string tokens are available:
Name
Description
Prefix #
Postfix #
varthreshold
Current state of the requested variable
threshold
thresholdId–
varcompare
Current state of the requested variable
comparison
compareId–
6.3 Events
The events below are generated by the system variables subsystem. They may be
used to trigger any action in the software that accepts events.
See Table 7.1 for the Event Type.
Name
EventType
ObjectId
EventId
Description
SENT
System
sendId
1
Variables were sent.
38
Variable
SEND ERROR
System
Variable
sendId
2
An error occurred during
send.
THRESHOLD_FALSE
System
Variable
thresholdId
3
Threshold became false.
THRESHOLD_TRUE
System
Variable
thresholdId
4
Threshold became true.
COMPARE_FALSE
System
Variable
compareId
5
Compare became false.
COMPARE_TRUE
System
Variable
compareId
6
Compare became true.
STATUS_CHANGED
variableId
128
Status variable was
modified.
CONFIG_CHANGED
variableId
129
Config variable was
modified.
6.4 List of Status Variables
The table below lists all the status variables in the system. The current list can be
queried with the AT$VARIABLESTATUS? Command.
Identifier
(hex)
Name
Description
nonVolatile
autoUpdt
endpoint
005A00+X
epbyteswrittenX
Bytes written to endpoint X
yes
005B00+X
eptransactionsX
Transactions written to
endpoint X
yes
005C00+X
epbytesreadX
Bytes read from endpoint X
yes
gpio
gpio
Status of GPIO pin
ip
003401
telnet
Telnet server status. 0=off,
1=on, 2=client connected
yes
003402
tcpserver
TCP server status. 0=off, 1=on,
2=client connected
yes
003403
udpserver
UDP server status. 0=off, 1=on
yes
ethernet
003501
etherlink
Ethernet link status (cable
connected)
yes
network
003201
sig
Signal strength
yes
counter
001000 +
N
counterN
General purpose counter. N=1-
20
39
Identifier
(hex)
Name
Description
nonVolatile
autoUpdt
001014 +
N
nvcounterN
Non-volatile counter. N=1-15
yes
tag
000C01
tagmemtotal
Tag memory total bytes
yes
000C02
tagmemdel
Tag memory deleted bytes
yes
000C03
tagmemfree
Tag memory free bytes
yes
000C04
tagrecompact
Tag recompact flag.
1=Recompact on next reset.
Yes
yes
gps
00C801
longitude
Longitude (deg*1000000)
yes
00C802
latitude
Latitude (deg*1000000)
yes
00C803
heading
Heading (deg*10)
yes
00C804
speed
Current speed (mph*10)
yes
00C805
altitude
Altitude (feet*10)
yes
00C806
numsat
Number of GPS satellites
yes
00C807
accuracy
Accuracy (miles*1000000)
yes
00C808
mileage
Miles between updates (*1000)
yes
00C809
odometer
Accumulated miles * 1000
yes
yes
00C80A
fixtime
Fix time, secs since 1/1/1970
(unsigned)
yes
sensor
0087MN
sensorX
The current sensor channel
reading for sensor M, channel
N. X=(M*16)+N
yes
6.5 AT$VARIABLESTATUS
This AT command displays a listing of all status variables in the system.
Read Command 6.5.1
The following shows the command (in bold) to query all status variables.
AT$VARIABLESTATUS?
$VARIABLESTATUS: ”<deviceId>”,<status>,<variableId>,”<variableName>”,
”<variableDesc>”,<nonVolatile>,<autoUpdt>,<avgNum>,<currentValue>
…...(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
40
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<variableId>
Variable identifier
<variableName>
Short ASCII name for the variable.
<variableDesc>
Brief description of the variable.
<nonVolatile>
1 = Saved in NVM. 0 = Not saved in NVM
<autoUpdt>
1 = Updated automatically. 0 = Not updated automatically.
<avgNum>
Number of readings in rolling average.
0 – No averaging.
<currentValue>
The current value of the variable.
6.6 AT$VARIABLETHRESHOLD
This AT command configures variable thresholds. Every time the variable’s value
changes, it is compared with the configured threshold for the chosen condition. An
event is generated when the test changes between true and false. There can be more
than one threshold configured for a variable.
To prevent multiple events from being generated when a variable is teetering on the
threshold value, a margin can be configured. After a threshold becomes true and
generates the event, it will not generate a false event until the threshold becomes false
by more than the margin amount, and vice versa from false to true.
Set Command 6.6.1
The following shows the command (in bold) to configure a variable threshold.
AT$VARIABLETHRESHOLD=<thresholdId>,<variableId>,<thresholdValue>,
<compareType>[,<margin>]
$VARIABLETHRESHOLD: ”<deviceId>”,<status>
(OK | ERROR)
Delete Command 6.6.2
If <thresholdId> is the only parameter given, the threshold is deleted.
AT$VARIABLETHRESHOLD=<thresholdId>
$VARIABLETHRESHOLD: ”<deviceId>”,<status>
(OK | ERROR)
Read Command 6.6.3
The following shows the command (in bold) to query all variable thresholds.
AT$VARIABLETHRESHOLD?
41
$VARIABLETHRESHOLD: ”<deviceId>”,<status>,<thresholdId>,<variableId>,
<thresholdValue>,<compareType>,<margin>,<compareState>
…...(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<thresholdId>
Threshold identifier
<variableId>
Variable identifier
<thresholdValue>
Threshold value to be compared with the variable
<compareType>
Type of comparison:
1 – Variable < Threshold
2 – Variable <= Threshold
3 – Variable = Threshold
4 – Variable >= Threshold
5 – Variable > Threshold
<margin>
Margin value. New events are not generated until the
comparison differs by this amount. This prevents multiple
events when a threshold is teetering between true and
false. Default = 0.
<compareState>
1 = The comparison is true. 0 = false
Example 6.6.4
The following example sets a threshold for the signal strength variable (0x3201) to be
greater than or equal to 20, with a margin of 3.
AT$VARIABLETHRESHOLD=1,3201,20,4,3
When the signal strength rises to 20 or more, the comparison will be true and the TRUE
event will be generated. The signal strength will have to fall to 17 or below in order to
change the comparison to false and generate the FALSE event.
6.7 AT$VARIABLECOMPARE
This AT command configures variable comparisons. The values of two variables are
compared for the chosen condition. An event is generated when the test changes
between true and false. There can be more than one comparison configured for a
variable. The comparison is reevaluated every time either variable changes.
42
To prevent multiple events from being generated when the variable values are making
the comparison teeter between true and false, a margin can be configured. After a
comparison becomes true and generates the event, it will not generate a false event
until the comparison becomes false by more than the margin amount, and vice versa
from false to true.
Set Command 6.7.1
The following shows the command (in bold) to configure a variable comparison.
AT$VARIABLECOMPARE=<compareId>,<variableId1>,<variableId2>,<compareTy
pe> [,<margin>]
$VARIABLECOMPARE: ”<deviceId>”,<status>
(OK | ERROR)
Delete Command 6.7.2
If <compareId> is the only parameter given, the comparison is deleted.
AT$VARIABLECOMPARE=<compareId>
$VARIABLECOMPARE: ”<deviceId>”,<status>
(OK | ERROR)
Read Command 6.7.3
The following shows the command (in bold) to query all variable comparisons.
AT$VARIABLECOMPARE?
$VARIABLECOMPARE:
”<deviceId>”,<status>,<compareId>,<variableId1>,<variableId2>,
<compareType>,<margin>,<compareState>
…...(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<compareId>
Comparison identifier
<variableId1>
First variable identifier
<variableId2>
Second variable identifier
<compareType>
Type of comparison:
1 – Variable1 < Variable2
2 – Variable1 <= Variable2
3 – Variable1 = Variable2
43
4 – Variable1 >= Variable2
5 – Variable1 > Variable2
<margin>
Margin value. New events are not generated until the
comparison differs by this amount. This prevents multiple
events when a comparison is teetering between true and
false. Default = 0.
<compareState>
1 = The comparison is true. 0 = false
Example 6.7.4
The following example sets a comparison between counter1 and counter 2. The
comparison will be true if counter1 (0x1001) is less than counter 2 (0x1002), with a
margin of 5.
AT$VARIABLECOMPARE=1,1001,1002,1,5
When the counter1 is less than counter 2, the comparison will be true and the TRUE
event will be generated. Counter1 will have to be 5 or more greater than counter2 in
order to change the comparison to false and generate the FALSE event.
6.8 AT$VARIABLESET
This AT command changes the value of a variable whenever an event occurs. This can
also be used as a counter of events by setting the command to add one each time.
The command parameters are saved to NVM and restored after power cycles, unless
there are no events specified. If the command is entered to be executed immediately,
then nothing is saved to NVM.
Set Command 6.8.1
The following shows the command (in bold) to configure a variable update.
AT$VARIABLESET=<setId>,<variableId>,<operation>,<operand>[,<eventLabel>
[…,<eventLabel>]]
$VARIABLESET: ”<deviceId>”,<status>
(OK | ERROR)
Delete Command 6.8.2
If <setId> is the only parameter given, the update object is deleted.
AT$VARIABLESET=<setId>
$VARIABLESET: ”<deviceId>”,<status>
(OK | ERROR)
44
Read Command 6.8.3
The following shows the command (in bold) to query all update objects.
AT$VARIABLESET?
$VARIABLESET: ”<deviceId>”,<status>,<setId>,<variableId>,<operation>,<operand>,
<eventLabel>…,<eventLabel>
…...(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<setId>
Set identifier
<variableId>
Variable identifier in hex.
<operation>
Operation to perform on the variable:
1 = Set to the <operand>
2 = Add <operand >
3 = Subtract <operand >
4 = Multiply by <operand >
5 = Divide by <operand >
6 = Mod by <operand>
7 = AND with <operand>
8 = OR with <operand>
9 = XOR with <operand>
10 = NOT (<operand> is ignored)
Values 11-20 are the same as above, except the
<operand> is interpreted as another variableId from which
the value is taken.
21 = Force evaluation of COMPAREs and THRESHOLDs,
and trigger an event. This is intended to be used during
startup.
22 = Load the current UNIX timestamp (<operand> is
ignored)
<operand>
The value of the operation may be either an actual value, or
another variableId that will supply the value, depending on
the operation:
If operation = 1-10 this is the value for the operation.
If operation = 11-20 this is variableId2 to supply the value.
<eventLabel>
EventLabel in hex. This defines the event(s) that trigger the
45
update. There may be from 0 to 10 values. A null or 0
value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
Example 6.8.4
The following example shows how to keep a count of the number of system resets. The
counter nvcounter1 (0x1015) is saved in NVM so it survives power cycles. For each
system reset event, the count is incremented by 1.
The <eventLabel> for system reset is 00010002 (see section 7.3).
Event Type = 1 for System
Object Id = 0 (not used)
Event Id = 2 for Normal Start Up
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=1,0,2
$EVENTLABEL: "327004000672",0,"00010002"
OK
AT$VARIABLESET=1,1015,2,1,00010002
The counter can be manually reset to 0 with an “immediate” form of the command:
AT$VARIABLESET=1,1015,1,0
6.9 AT$VARIABLESEND
This AT command sends variables to an existing endpoint. The transfer may be
triggered immediately, or by any event.
The command parameters are saved to NVM and restored after power cycles, unless
there is no event specified. If the command is executed immediately, then nothing is
saved to NVM.
Set Command 6.9.1
The following shows the command (in bold) to configure a variable send object.
AT$VARIABLESEND=<sendId>,<endpointId>,<endFile>,<eventLabel>,<variableId
> […,<variableId>]
46
$VARIABLESEND: ”<deviceId>”,<status>
(OK | ERROR)
The above command response indicates the status of the command and its parameters.
If successful, then when triggered by the <eventLabel>, the <variableId> list will be sent
to the specified endpoint. An unsolicited message will be output to indicate the status:
$VARIABLESEND: ”<deviceId>”,<status>,<sendId>,<transferStatus>
Delete Command 6.9.2
If <sendId> is the only parameter given, the send object is deleted.
AT$VARIABLESEND=<sendId>
$VARIABLESEND: ”<deviceId>”,<status>
(OK | ERROR)
Read Command 6.9.3
The following shows the command (in bold) to query all variable send objects.
AT$VARIABLESEND?
$VARIABLESEND:
”<deviceId>”,<status>,<sendId>,<endpointId>,<endFile>,<eventLabel>,<variableId>
…,<variableId>
……(list of all valid records)
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<sendId>
Variable Send identifier
<endpointId>
Destination Endpoint Id.
<endFile>
0 = Do not close file after the Send.
1 = Close the destination file after each Send (default).
<eventLabel>
EventLabel in hex. This defines the event that triggers the
transfer. A null or 0 value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
<variableId>…
Variable identifier(s) in hex to be sent to the endpoint.
There may be from 1 to 10 variables in this list.
<transferStatus >
Status of the send:
47
1 = String was sent successfully.
2 = An error was encountered.
Example 6.9.4
The following example sets up VariableSend Id 1 to send two status variables via
endpoint 3 (which is a TCP client endpoint) when timer 2 expires. The two variables are
“counter5” with Id 1005 and “sig” with Id 3201.
The <eventLabel> for Timer 2 expiration is 00020203 (see section 10.5.1).
Event Type = 2 for Timers
Object Id = 2 for Timer 2
Event Id = 3 for Timer Expiration
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=2,2,3
$EVENTLABEL: 327004000672,0,00020203
OK
AT$ENDPOINT=3,1,2025,www.example.com
AT$VARIABLESEND=1,3,1,20203,1005,3201
To test, this command creates Timer 2 with a duration of 30 seconds:
AT$TIMERSTART=2,300
7 Events
The Event subsystem is one of the two backbones of the software (along with Endpoints
and Bridges, described later). Every subsystem in The software is built on the event
backplane. This allows all subsystems to generate events and listen for events from any
other subsystem.
Every Event has 3 components:
Event
Listen
Generate
Event
Event Backplane
Timers
GPIO
Endpoint
GPS
48
Event Type – This value describes which subsystem the event came from. For
example, was the event generated by a timer, GPIO, Endpoint, etc.
Object ID – Each subsystem has a predefined number of available Object ID on
which Actions may be performed or which trigger events. In some cases, like
GPIOs, the system has already defined the GPIO numbers, which are also
interpreted as Object IDs. In some subsystems, for example Timers, the user is
allowed to define one or more objects that may generate an event or execute an
action (which may in turn, also generate events). This specifies which object ID
generated the event.
Event ID – The identifier for the event that occurred within a subsystem. The
namespace for Event IDs are based on Event Type. In this document, Event IDs
for each subsystem are defined in each section.
Below are the definitions used when discussing events:
Event – A notification to the system that a system state has changed or that an
action has occurred. Examples: Timer has expired or Device registered to the
Network.
Action – A definition of system setting change or process to execute. Examples:
Write level high to GPIO23 or Start timer 1.
TriggerThe act of generating an Event.
Example 1: (Action) Write level high to GPIO 23 when (Event) timer 1 expires, which
Triggers
Example 2: (Action) Start timer 1 when (Event) network registration occurs
7.1 Event Types
Each subsystem in the software has an Event Type number associated with it. This
value is used to interpret the context for the Object ID and Event ID.
Event Type Name
Event Type Number
System
1
Timer
2
Event System
3
GPIO
4
SIM
6
Voice Call
7
DTMF
8
49
String Token
9
Identity
10
Sequence
11
Tag
12
System Variable
15
Counter
16
SMS
17 (0x11)
Network
50
Network CSQ
51
Socket
52
Ethernet
53
TCP Client
54
FTP Server
55 (0x37)
Endpoint bytes written
90 (0x5A)
Endpoint transactions
91 (0x5B)
Endpoint bytes read
92 (0x5C)
Bridge
98 (0x62)
Endpoint General
100
Endpoint TCP
101
Endpoint UDP
102
Endpoint Serial
103
Endpoint SMS
104
Endpoint HTTP GET
105
Endpoint HTTP PUT
106
Endpoint HTTP POST
107
Endpoint EMAIL SMTP
108
Endpoint EMAIL POP
109
Endpoint FTP GET
110
Endpoint SSL TCP
111
Endpoint SSL HTTP GET
112
Endpoint SSL HTTP PUT
113
Endpoint SSL HTTP POST
114
Endpoint SSL FTP GET
115
Endpoint X-Modem
116
Endpoint Tag-Write
117
Endpoint SPI
118
Endpoint I2C
119
Endpoint FTP PUT
120
Endpoint SSL FTP PUT
121
Endpoint Tag Read
122
Endpoint Binary Parser
123
Endpoint AT Parser
124
Endpoint Filter
125
50
Endpoint Offline Data
126
Endpoint Binary Command Parser
127
Endpoint TCP Server Client Created
130
Endpoint TCP Server Client Deleted
131
Sensor Driver
135 (0x87)
GPS General
200
GPS Rectangular Geofence
201
GPS Circular Geofence
202
GPS Polygon Geofence
203
User Defined
3567
7.2 Event Labels
Even though there are three components to every event (Event Type, Object ID, and
Event ID), they can be combined to create an Event Label. An event label simplifies the
command line for linking events together. The Event Label is always interpreted as
hexadecimal. The event label structure is described below:
Event Type
Object ID
Event ID
31
...
16
15
...
8
7
...
0
Event Label bits Figure 1.
If the Event Type, Object ID and/or Event ID is 0 then this means wildcard that means
“All”. An example of how to use this wildcard is, assume you wish to generate an event
label that will be used to listen for any GPIO event. In this case you would make the
Event Type equal to GPIO and the object ID and Event ID would be 0.
7.3 System Events
System Events apply to the whole system and are not tied to a specific subsystem.
System Event Type: 1
System Event
ID
System Event
Name
Description
1
Power On
The software has started.
2
Normal Start Up
All of the software subsystems have
initialized.
3
Start Up from Error
CPU exception, such as null pointer or
51
divide by 0.
4
Install Successful
A firmware tag file was installed and
activated.
5
Install Failed
A firmware tag file failed to install.
7.4 Event Label Command
This AT command is a utility command used to encode Event Labels in order to
configure the software subsystem to receive events or to decode Event Labels. This
command is not really intended for use during normal operation since it doesn’t control
any part of Courier M2M.
AT$EVENTLABEL 7.4.1
The $EVENTLABEL command is provided to allow for easy calculation of event labels
for use as action triggers. An event label represents three pieces of information: an
Event Type, and Object Identifier, and an Event ID.
The AT command is contextual. If you enter only one parameter it is assumed that the
parameter is an Event Label that needs to be decoded. The Event Label is always
interpreted as hexadecimal. If three parameters are entered then it is assumed that an
Event Label needs to be encoded based on the Event Type, Object ID and Event ID.
These parameters are always interpreted as decimal values.
Command:
AT$EVENTLABEL=<eventType>,<objectId>,<event>
Response:
$EVENTLABEL:“<deviceId>”,<status>,<eventLabel>
OK
Command:
AT$EVENTLABEL=<eventLabel>
Response:
$EVENTLABEL:
“<deviceId>”,<status>,<eventType>,<objectId>,<eventId>
OK
Please refer to section 2.3.1 for the definitions of the Event Types and 2.3.2 for the
definition of the Event Label.
A sample use for the $EVENTLABEL command is shown below. In this command, a
timer is created, and the $EVENTLABEL command us used to calculate a label for use
as a trigger in a GPIO command.
Ex 1: Sample $EVENTLABEL Usage
52
AT$TIMER=4,5,1
Create periodic timer with timer ID 4 and a
500ms duration to start immediately
OK
Success response from $timer command
AT$EVENTLABEL=2,4,3
Calculate an event label for a timer Event
Type 2 (timer object), object ID 4 (timer ID
4), and event ID 3 (timer expiration)
$EVENTLABEL:
"327004006981",0,"00402003"
OK
$eventlabel response with the muxed event
label 00402003
AT$GPIO=5,4,00402003,23,24
Create a GPIO action with an ID of 5, action
of 4 (toggle level), an event Id of 00402003,
to act on GPIOS 23 and 24
OK
Success creating action from $GPIO
command
!
7.5 Event Display Command
The $EVENTDISPLAY command turns on unsolicited responses for desired event
classes. Granularity and filtering is defined by the provided parameters. If only an
Event Type is provided, all events for the provided Event Type will be returned. If an
object Id is also provided, the results will be filtered by Event Type and object Id. If all
three parameters are provided, only events matching all three parameters will be
returned. A value of zero is used to denote all events. Only one event display setting
can be active at a time.
This command is for debugging purposes.
AT$EVENTDISPLAY 7.5.1
Action'command'
Enable or disable display of event.
AT$EVENTDISPLAY=<on/off>,<eventType>,<objectId>,<eventId>
$EVENTDISPLAY: ”<deviceId>”,<status>
(OK | ERROR)
53
Read'command'
AT$EVENTDISPLAY?
$EVENTDISPLAY: ”<deviceId>”,<status>,<eventLabel>
(OK | ERROR)
Unsolicited'response'
$EVT: “<deviceId>”,<status>,<eventType>,<objectId>,<eventId>
Parameter
Description
<on/off>
0 = Unsolicited event indications are disabled (default)
1 = Unsolicited event indications are enabled
<eventType>
See table in chapter 7.1
<objectId>
Specific object ID within the referenced EventType
<eventId>
Specific event ID within the referenced EventType
<eventLabel>
The current registered event label, in hex.
Examples:
AT$EVENTDISPLAY=1,0,0,0 //Display all eventsNOT ALLOWED!
$EVENTDISPLAY: "327004096909",1013
OK
AT$EVENTDISPLAY=1,2,0,0 //Display all Timer events
$EVENTDISPLAY: "327004096909",0
OK
AT$EVENTDISPLAY=1,2,1,0 //Display all events for Timer 1
$EVENTDISPLAY: "327004096909",0
OK
AT$EVENTDISPLAY=1,2,1,3 //Display all timer expiring events
$EVENTDISPLAY: "327004096909",0 //for Timer 1
OK
7.6 Event Filters
Event filters create lists of desired event labels to be passed to and used by other
commands. Their primary function is for use in event sequences, but they can also be
used in place of a list of events for some commands.
7.7 Events
The events below are generated by an EventFilter. They may be used to trigger any
action in the software that accepts events.
54
The Event Type is 3 for Events. The Event ObjectId is the EventFilter Id value.
Name
EventId
Description
EVENTFILTER_TRIGGERED
1
The EventFilter was triggered. This is
effectively an OR of all event labels in the
EventFilter.
AT$EVENTFILTER 7.7.1
The event filter command is used to create an event filter Id with associated events for
use by the $EVENTSEQUENCE command. Only events matching the event filter will
be passed to the event sequence. Zeros can be used as wildcards to match multiple
objects or event IDs for more or less granularity as needed.
Action Command
Delete an event filter
AT$EVENTFILTER=<objectId>
OK
Create and configure an event filter
AT$EVENTFILTER=<objectId>,<eventLabel>[,...<eventLabelN]
$EVENTFILTER: “<moduleId>”,<status>,<objectId>,”eventLabel>”{,...”<eventLabelN>”]
OK
objectId
ID for use when referencing the configured event filter in later
commands
eventLabel
Label of event or events that are listened for by this filter
Read'Command'
AT$EVENTFILTER?
$EVENTFILTER: “<moduleId>”,<status>,<objectId>,”eventLabel>”{,...”<eventLabelN>”]
[$EVENTFILTER:“<moduleId>”,<status>,<objectId>,”eventLabel>”{,...”<eventLabelN>”]]
OK
Example'
This example will create a filter with filter id 1 to include all DTMF tone events.
AT$EVENTFILTER=1,00080000
$EVENTFILTER: "327004006981",0,1,"00080000"
55
OK
Event filter 1 can now be used in an event sequence command. The event sequence
will monitor all DTMF tone events, but only trigger on the specific event defined in the
event sequence command.
7.8 Event Sequences
These commands allow users to create custom events based on two or more other
events. Event filter commands will restrict the list of received commands to those
specified in the corresponding event filter command. Event sequence commands can
be paired with configured event filters to create custom events. Event sequences, for
example, could be used to match a sequence of DTMF tones.
7.9 Events
The events below are generated by an EventSequence. They may be used to trigger
any action in the software that accepts events.
The Event Type is 11 (0x0B) for EventSequence. The Event ObjectId is the
SequenceId value.
Name
EventId
Description
SEQUENCE_MATCH
1
Complete sequence matched.
EVENT_MATCH
2
One event in the sequence matched (strict only).
SEQUENCE_FAIL
3
Sequence failed (strict only).
AT$EVENTSEQUENCE 7.9.1
The EventSequence command defines a sequence of events that must be matched to
trigger an EventSequence event. Events in a sequence can be configured to be loosely
interpreted (i.e. out of order, or with other events in between) or strictly interpreted (in
order, no interruptions) depending on the desired application. The $EVENTSEQUENCE
command is used in combination with the $EVENTFILTER command. The EventFilter
defines which events to listen for, then the sequence defines the subset which will
trigger the Sequence event.
For example, if a user wanted to trigger an event based on DTMF tones, an event filter
would be created that would listen to all DTMF tones. Then, a strict
$EVENTSEQUENCE could be created with the desired tone order.
56
Action'Command'
Delete an event sequence:
AT$EVENTSEQUENCE=<objectId>
OK
Create and configure an event sequence:
AT$EVENTSEQUENCE=<objectId>,<filterId>,<mode>,<eventLabel1>,<eventLabel2>
[,...<eventLabelN>]
$EVENTSEQUENCE:
“<deviceId>”,<status>,<objectId>,<filterId>,<mode>,”<eventLabel1>”, ”<eventLabel2>”[,...”<e
ventLabelN>”]
OK
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
1050 = Bad parameter or too many eventLabels
1065 = Invalid object
objectId
ID for use when referencing the configured event sequence
in later commands
filterId
ID for an event filter created in earlier $EVENTFILTER
commands. This restricts the events to consider in the
sequence.
mode
Match mode:
0 AND, non-strict. Match all the listed events in any
sequence.
1 – AND, strict. Match all the listed events exactly in the
defined sequence.
2 – OR. Match any one event in the defined sequence.
eventLabel1
First event in the sequence. Enter all eventLabels in hex.
eventLabel2
Second event in the sequence.
eventLableN
Nth event in the sequence. There may be up to 16 values.
Read'Command'
AT$EVENTSEQUENCE?
$EVENTSEQUENCE:
“<moduleId>”,<status>,<objectId>,<filterId>,<mode>,”<eventtLabel1>”, ”<eventLabel2>”[,...”
<eventLabelN>”]
…[more records]…
OK
57
Example'
This example uses the event filter id=1 created in the Event filter section (7), which
filters all DTMF tone events. To further fine tune event triggers, the event sequence
defines the exact events on which to trigger. This sequence will trigger if a DTMF tone 1
and DTMF tone 2 are detected, in that order.
AT$EVENTSEQUENCE=1,1,1,00080001,00080002
$EVENTSEQUENCE: "327004006981",0,1,1,1,"00080001","00080002"
OK
When DTMF tone 1 and 2 are detected, an event will be generated. This event can be
used as a trigger for a command to be executed. For example, GPIO20 can be
configured to go High if the sequence above happens.
AT$GPIOACTION=2,1,20,000B0101
GPIOACTION: "327004006981",0,2,1,20,"000B0101"
OK
To summarize, this configuration will cause GPIO 20 to go High when DTMF tone 1
followed by tone 2 is detected.
7.10 AT$EVENTGEN
The $EVENTGEN command allows users to trigger events manually. Triggered events
can be either defined system events or custom user defined events. This is especially
useful for testing the behavior of a sequence of event driven commands.
Parameter command
$EVENTGEN will accept either an event label or the corresponding separate event
values. Both forms of the command are shown below. Values should be in hexadecimal
format.
AT$EVENTGEN=<eventLabel>
$EVENTGEN: “<moduleId>”,<statusId>,<eventType>,<objectId>,<eventId>
OK
Or
AT$EVENTGEN=<eventType>,<objectId>,<eventId>
$EVENTGEN: “<moduleId>”,<statusId>,<eventType>,<objectId>,<eventId>
OK
58
8 Power Management
These commands allow the modem to be put into low power mode. In the low power
state, the modem is fully powered but the internal processor is in sleep state for a low
power consumption mode. The software is suspended, waiting for a timer expiration,
SMS message, or data connection to wake it up. To achieve the minimum power
consumption during low power mode, the following conditions must be met:
Serial port must not be connected
No pending AT command output can be queued
USB port must not be connected
Ethernet interface must be disabled (AT$ENABLEETHERNET=0)
The following commands are supported:
AT$LOWPOWERON – Configures and queries events and time duration for
enabling low power mode.
AT$LOWPOWEROFF – Configures and queries events for disabling low power
mode.
The Low Power Mode parameters are saved to NVM and restored after power cycles,
unless there are no events specified. If the command is entered to be executed
immediately, then nothing is saved to NVM.
8.1 Events
These system events are generated by the low power mode. The EventType is 1. The
ObjectId for the event is not used. See section 7 for more about events.
Name
EventId
Description
LOW POWER ENABLED
6
Low power mode was enabled.
LOW POWER
DISABLED
7
Low power mode was disabled.
8.2 String Tokens
This subsystem defines the follow dynamic string tokens:
Name
Description
Prefix #
Postfix #
lowpwr
Low power mode (0=disabled, 1=enabled)
59
8.3 AT$LOWPOWERON
This command configures or queries the events and time duration for low power mode.
Low power mode can be enabled immediately, or triggered to be enabled later by one or
more events. When low power mode is enabled, it generates a LOW POWER
ENABLED event. When the time duration expires, low power mode is disabled and it
generates a LOW POWER DISABLED event.
Action Command 8.3.1
The following shows the command (in bold) to enable low power mode.
AT$LOWPOWERON=<duration>[,<eventLabel>[…,<eventLabel>]]
$LOWPOWERON: ”<deviceId>”,<status>
(OK | ERROR)
Delete Configuration 8.3.2
If <duration> is the only parameter given and is equal to 0, all LOWPOWERON events
and the time duration will be deleted.
AT$LOWPOWERON=<0>
$LOWPOWERON: ”<deviceId>”,<status>
(OK | ERROR)
Read Command 8.3.3
The following shows the command (in bold) to query the parameters for enabling low
power mode.
AT$LOWPOWERON?
$LOWPOWERON: ”<deviceId>”,<status>,<duration>,<isEnabled>[,<eventLabel>[…,
<eventLabel>]]
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<duration>
The length of time low power mode is enabled (in 100ms
increments).
<isEnabled>
0 = Low power mode is disabled.
1 = Low power mode is enabled.
<eventLabel>
EventLabel. This defines the event(s) that trigger the
60
enabling of a low power mode. There may be from 0 to 10
values. A null or 0 value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
Example 8.3.4
The following example shows how to configure low power mode to be enabled upon
receiving a GPIO event. When triggered, low power mode will stay enabled for 5
minutes (300 seconds), then it will be disabled automatically.
The <eventLabel> for GPIO pin 29 going high is 00041D02 (see section 25.1).
Event Type = 4 for GPIO
Object Id = 29 for pin 29
Event Id = 2 for input high
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=4,29,2
$EVENTLABEL: "327004000672",0,"00041d02"
OK
AT$LOWPOWERON=3000,00041D02
8.4 AT$LOWPOWEROFF
This command configures or queries the events for disabling low power mode. Low
power mode can be disabled immediately, or triggered later by one or more events.
When low power mode is disabled, it generates a LOW POWER DISABLED event.
Action Command 8.4.1
The following shows the command (in bold) to disable low power mode.
AT$LOWPOWEROFF=<eventLabel>[…,<eventLabel>]
$LOWPOWEROFF: ”<deviceId>”,<status>
(OK | ERROR)
Delete Configuration 8.4.2
If a single <eventLabel> is the only parameter given and is equal to 0, all
LOWPOWEROFF events will be deleted.
61
AT$LOWPOWEROFF=0
$LOWPOWEROFF: ”<deviceId>”,<status>
(OK | ERROR)
Immediate Disable 8.4.3
To disable low power mode immediately, enter the command with 2 <eventLabel>
parameters = 0:
AT$LOWPOWEROFF=0,0
$LOWPOWEROFF: ”<deviceId>”,<status>
(OK | ERROR)
Read Command 8.4.4
The following shows the command (in bold) to query the parameters for disabling low
power mode.
AT$LOWPOWEROFF?
$LOWPOWEROFF: ”<deviceId>”,<status>,<isEnabled>[,<eventLabel>[…,
<eventLabel>]]
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<isEnabled>
0 = Low power mode is disabled.
1 = Low power mode is enabled.
<eventLabel>
EventLabel. This defines the event(s) that trigger the
disabling of a low power mode. There may be from 0 to 10
values. A null or 0 value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
Example 8.4.5
The following example shows how to configure low power mode to be disabled when
GPIO pin 28 goes high.
The <eventLabel> for GPIO pin 28 going high is 00041C02 (see section 25.1).
62
Event Type = 4 for GPIO
Object Id = 28 for pin 28
Event Id = 2 for input high
The AT$EVENTLABEL command can be used to assist with encoding the correct hex
value:
AT$EVENTLABEL=4,28,2
$EVENTLABEL: "327004000672",0,"00041c02"
OK
AT$LOWPOWEROFF=00041C02
63
9 Identification Commands
This set of commands may be used to query information that identifies the device and
the device’s capabilities. All of these commands are read only. There are a number of
different components and the version information is distinct for each component. Here is
an overview of the different components that have their own version numbers.
Application Version
The version of the hardware and application
that represents the wireless embedded
device.
Modem Version
The version of firmware loaded on the
cellular modem.
9.1 Events
The Identification subsystem generates events.
Identification Event Type: 10
Event ID
Event Name
Description
1
Device ID Change
This Event is triggered when the Device ID is
modified with AT$DEVICEID.
9.2 String Tokens
This subsystem defines the following dynamic string tokens:
Name
Description
Prefix #
Postfix #
subid
Subscriber Id
modemid
Modem id
deviceid
Device id
modulefirmve
r
Modem firmware version
appver
Software application version
platver
Software platform version
hwver
Modem hardware version
64
9.3 Get Application Version Command
This command set is used to get the application, firmware, and hardware versions of the
application.
The following command is supported:
AT$APPVERSION– Read command
AT$APPVERSION 9.3.1
AT command used to get the version of the Courier M2M Application software, library
software, and hardware. The version can only be read.
Read'Command'
The following shows the command to read the versions, followed by the expected
output.
Command:
AT$APPVERSION
Response:
$APPVERSION:
“<deviceId>”,<status>,”<applicationVersion>”,”<firmwareVersion>”,
”<build_time>”,”<hardwareVersion>”
OK
Parameters'9.3.1.1.1.1
9.4 Get Firmware Version Command
This command set describes the Commands available to get the cellular modem
firmware version of the device.
The following command is supported:
AT$FWVERSION– Read command
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 – Success
<applicationVersion
>
Version string set by the application.
<firmwareVersion>
<majorNumber>.<minorNumber>.<buildNumber>
<build_time>
Date and time when software was created
<hardwareVersion>
<majorNumber>.<minorNumber>
65
AT$FWVERSION 9.4.1
AT command used to get the version of the modem firmware. The version can only be
read.
Read!Command!9.4.1.1.1
The following shows the command to read the version, followed by the expected output.
Command:
AT$FWVERSION
Response:
$FWVERSION: “<deviceId>”,<status>,”<firmwareVersion>”
OK
Parameters'
9.5 Get Modem ID Command
This command set is available to get the ID of the cellular modem, usually the device
IMEI.
The following command is supported:
AT$MODEMID– Read command
AT$MODEMID 9.5.1
AT command used to get the modem ID. The modem ID can only be read.
Read'Command'
The following shows the command to read the version, followed by the expected output.
Command:
AT$MODEMID
Response:
$MODEMID: “<deviceId>”,<status>,”<modemId>
OK
''''Parameters'
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 – Success
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 – Success
<firmwareVersion>
The firmware version as returned by the modem
66
<modemId>
Modem ID
9.6 Get Subscriber ID Command
This command set is available to get the Subscriber ID attached to this device. For GSM
devices this value will be the IMSI. The subscriber ID should not be confused with the
modem ID. For GSM devices, if the SIM card isn’t inserted then no Subscriber ID will be
available.
The following command is supported:
AT$SUBSCRIBERID– Read command
AT$SUBSCRIBERID 9.6.1
AT command used to get the subscriber ID. The subscriber ID can only be read.
Read'Command'
The following shows the command to read the version, followed by the expected output.
Command:
AT$SUBSCRIBERID
Response:
$SUBSCRIBERID: “<deviceId>”,<status>,”<subscriberId>”
OK
''''Parameters'
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 – Success
<subscriberId>
Subscriber ID
9.7 Device Identification
This command set is available to query and modify the ID of the device. It is important
that you provision each device you send in the field to have a unique device ID.
By default, the device ID is the 12 digits of the IMEI that uniquely identify the modem.
You can select to automatically generate the device ID based off the modem ID (IMEI),
the subscriber ID (IMSI), or disable auto-generated and instead specify your own ID.
The following command is supported:
AT$DEVICEID – Action and Read commands
Refer to the following table for auto-generation types:
67
Auto-gen Type
Description
0
Generate device ID from modem ID (IMEI)
1
Generate device ID from subscriber ID (IMSI)
2
Disable autogen and specify a custom ID
AT$DEVICEID 9.7.1
AT command used to get and set the ID of the device, along with how the device ID is
auto-generated. The device ID can be set or read.
Action'Command/Response'
The following shows the command (in bold) to set the device ID, followed by the
expected output. If Autogen_Type = 2, then the “DeviceId” must be specified.
Command:
AT$DEVICEID=<Autogen_Type>[, “device Id”]
Response:
$DEVICEID: “<deviceId>”,<status>,<Autogen_Type>
OK|ERROR
Read'Command/Response'
The following shows the command (in bold) to read the device ID, followed by the
expected output.
Command:
AT$DEVICEID?
Response:
$DEVICEID: “<deviceId>”,<status>,<Autogen_Type>
OK|ERROR
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = OK
1012 = NV save error
1050 = Invalid parameter value
<Autogen_Type>
0 – Generate device ID from modem ID (IMEI)
1 – Generate device ID from subscriber ID (IMSI)
2 – Disable autogen and specify a custom ID
9.8 Get Build Features
This command set is available to get the application firmware build features.
68
The following command is supported:
AT$FEATURE – Read command
AT$FEATURE 9.8.1
AT command used to get the build features of the application software. The build
features can only be read.
Read'Command'
The following shows the command (in bold) to read the build features, followed by the
expected output.
Command:
AT$FEATURE?
Response:
$FEATURE: “<deviceId>”,<status>,”<projName>”,<featureBitmap>
OK
''''Parameters'
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 = Success
<projName>
Name of the build project
<featureBitmap>
A hex value of bits representing current features.
If bit is set, the feature is enabled.
Bit 0: Trial build
Bit 1: Debug build.
Bit 2: Model restricted
Bit 3: IMEI restricted
Bit 4: Ethernet interface
Bit 5: GPS tracking
69
10 Time
This section defines the commands used to control the device clock, timers and events
generated based on time.
10.1 Events
The Timer subsystem generates events.
Timer Event Type: 2
Event ID
Event Name
Description
1
Timer Start
This Event is triggered when a timer is started or
restarted.
2
Timer Stop
This Event is triggered when a timer is stopped
before it has a chance to expire.
3
Timer Expired
This Event is triggered when a timer expires.
4
Clock Changed
This Event is triggered when the system clock is
changed.
5
Clock Alarm
This Event is triggered when the Clock has
reached the time of an Alarm.
10.2 String Tokens
This subsystem defines the following dynamic string tokens:
Name
Description
Prefix #
Postfix #
year
Year (4 digits)
Min width
counter
month
Month
Min width
counter
monthname
Month name
counter
Day
Day of the month
Min width
counter
dow
Day of the week (1=Sun, 7=Sat)
Min width
counter
downame
Day of the week name
counter
hourint
Hour in 24 hour format
Min width
counter
hourus
Hour in 12 hour format
Min width
counter
ampm
AM or PM
counter
minute
Minutes (2 digits)
counter
second
Seconds (2 digits)
counter
Some of the tokens that return a numeric parameter accept a prefix, which specifies the
minimum width. If the number requires fewer characters than the minimum width, it will
be padded with zeros.
70
Using a Stored Timestamp 10.2.1
If the optional postfix is given, a UNIX timestamp stored in a counter is used instead of
the current system time. The postfix is formed from the lower 8 bits of the variable ID;
the volatile counters are accessed with postfixes 1-20, and the non-volatile counters
continue at 21.
When using this feature, operation 22 of the VARIABLESET command may be useful.
This can be used to store the current UNIX timestamp in a system variable, either
immediately or in response to an event.
Example'
The following example configures a timer that expires once every minute. The timer’s
expire event is used to store the current timestamp in counter1, and the counter’s
STATUS_CHANGED event is used to send a formatted time string to an endpoint.
Generate the event label for the timer1 expire event:
at$eventlabel=2,1,3
$EVENTLABEL: "327004106556",0,"00020103"
OK
Configure timer1 to restart automatically after it expires:
at$timerstart=1,600,20103
$TIMERSTART: "327004106556",0
OK
The timer must be manually started the first time:
at$timerstart=1,0
$TIMERSTART: "327004106556",0
OK
Now that the timer is configured, use $VARIABLESET operation 22 to listen for the
timer1 expire event and store the current timestamp in counter1:
at$variableset=1,1001,22,0,20103
$VARIABLESET: "327004106556",0
OK
Wait for the value in counter1 to be updated using the STATUS_CHANGED event, then
send a string containing the time to endpoint1:
at$stringsend=1,1,"Timer expire: %monthname1% %day1% %year1%
%hourus1%:%minute1%:%second1% %ampm1%%CRLF%",100180
$STRINGSEND: "327004106556",0
OK
71
The formatted time string will now be sent to the endpoint whenever the timer expires.
To watch this in real time, you can open up endpoint1 on your device’s serial port (use
“+++” to exit).
at$endpoint=1,3,1
$ENDPOINT: "327004106556",0
OK
10.3 Manually Set and Get Device Clock
This command set is available to get the clock on the device or manually configure the
time and date on the device. The following command is supported:
AT$TIME – Action and Read commands
AT$TIME 10.3.1
AT command used to get and set the current time and date on the device.
Action'Command/Response'
The following shows the command (in bold) to set the date and time, followed by the
expected output.
Command:
AT$TIME=<time>
Response:
$TIME: ”<deviceId>”,<status>
OK
Read'Command/Response'
The following shows the command (in bold) to read the date and time, followed by the
expected output.
Command:
AT$TIME?
Response:
$TIME: ”<deviceId>”,<status>,”<time>
OK
Parameters
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 – Success
1007 – Invalid format
<time>
12 digits: YYMMDDHHMMSS
72
Where:
YY year past 2000
MM month
DD day
HH hour
MM minute
SS – second
10.4 Automatically Set Device Clock
This command set is available to setup how the time and date on the device will
automatically be updated. The following command is supported:
AT$AUTOTIME – Set and Read commands
AT$AUTOTIME 10.4.1
AT command used to get and set the mode for how the device sets its time.
Action'Command/Response'
The following shows the command (in bold) to set the autotime mode, followed by the
expected output.
Command:
AT$AUTOTIME=<mode>[,<nitz_utc>]
Response:
$AUTOTIME: ”<deviceId>”,<status>
OK
Read'Command/Response'
The following shows the command (in bold) to read the autotime mode, followed by the
expected output.
Command:
AT$AUTOTIME?
Response:
$AUTOTIME: ”<deviceId>”,<status>,<mode>,<nitz_utc>
OK
Parameters!10.4.1.1.1
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 – Success
1050 – Invalid parameter
<mode>
Mode:
73
0 Off
1 – NITZ (default)
2 GPS
3 SNTP
<nitz_utc>
For NITZ only. Specifies whether to set the time as local or
UTC:
0 – Local time (default)
1 UTC
10.5 Timers
This command set allows you to configure, start and stop timers. These timers generate
events that can be tied into any other software subsystem.
The following commands are supported:
AT$TIMERSTART
AT$TIMERSTOP
Timer Events 10.5.1
These events are generated by timers. The EventType is 2 for timers. The ObjectId for
the event is the Timer Id. See section 7 for more about events.
Name
EventId
Description
TIMER_START
1
Timer started.
TIMER_STOP
2
Timer stopped.
TIMER_EXPIRE
3
Timer expired.
AT$TIMERSTART 10.5.2
This command defines a new timer, or restarts an existing timer. The timer can be
started immediately, or triggered to start later by one or more events. When a timer
starts, it generates a TIMER_START event. When a timer expires, it generates a
TIMER_EXPIRE event.
Timers are always defined as “one-shot” timers that stop when they expire. If a periodic
timer is desired, then the TIMER_EXPIRE <eventLabel> can be used as a trigger to
start the timer again.
Action'Command'
The following shows the command (in bold) to start a timer.
AT$TIMERSTART=<timerId>[,<duration>[,<eventLabel>[…,<eventLabel>]]]
74
$TIMERSTART: ”<deviceId>”,<status>
(OK | ERROR)
Restart'Timer'
If <timerId> and <duration=0> are the only parameters given, the timer is restarted with
its original duration value. If <timerId> does not exist, an error is returned.
AT$TIMERSTART=<timerId>,0
$TIMERSTART: ”<deviceId>”,<status>
(OK | ERROR)
Delete'Timer'
If <timerId> is the only parameter given, the timer is stopped and its START
<eventLabel> list is deleted. If <timerId> does not exist, an error is returned.
AT$TIMERSTART=<timerId>
$TIMERSTART: ”<deviceId>”,<status>
(OK | ERROR)
Read'Command'
The following shows the command (in bold) to query the parameters for starting timers.
AT$TIMERSTART?
$TIMERSTART:
”<deviceId>”,<status>,<timerId>,<duration>,<running>,<eventLabel>…,<eventLabel>
…(list of active timers)
(OK | ERROR)
Unsolicited'Response'
When a timer expires, the following unsolicited response is output.
$TMREVT: ”<deviceId>”,<status>,<timerId>
Parameters
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<timerId>
The Id of the timer (1-255).
<duration>
The length of the timer (in 100ms increments).
0 = Restart existing timer with original duration value.
<running>
0 = Timer is stopped.
1 = Timer is running.
75
<eventLabel>
EventLabel. This defines the event(s) that trigger the
starting of a timer. There may be from 0 to 10 values. A
null or 0 value specifies “immediate” (default).
Use the AT$EVENTLABEL command to aid with encoding
this parameter.
Example'
The following example shows how to create a timer that starts immediately, runs for 30
seconds, and then retriggers itself upon expiration.
AT$TIMERSTART=1,300,00020103
$TIMERSTART: "327004096909",0
OK
at$timerstart=1,0 //Timer has to be started manually the
$TIMERSTART: "327004096909",0 //the first time
OK
AT$TIMERSTOP 10.5.3
This command stops a timer. The timer can be stopped immediately, or triggered to be
stopped later by one or more events. When a timer stops, it generates a TIMER_STOP
event.
Action'Command'
The following shows the command (in bold) to create timer STOP events.
AT$TIMERSTOP=<timerId>[,<eventLabel>[…,<eventLabel>]]
$TIMERSTOP: ”<deviceId>”,<status>
(OK | ERROR)
To manually stop an existing timer, enter the timer id and one event label with a value of
0:
AT$TIMERSTOP=<timerId>,0
$TIMERSTOP: ”<deviceId>”,<status>
(OK | ERROR)
Delete'Timer'
If <timerId> is the only parameter given, the timer is stopped and its STOP
<eventLabel> list is deleted. If <timerId> does not exist, an error is returned.
AT$TIMERSTOP=<timerId>
$TIMERSTOP: ”<deviceId>”,<status>
76
(OK | ERROR)
Read'Command'
The following shows the command (in bold) to query timer STOP events.
AT$TIMERSTOP?
$TIMERSTOP:
”<deviceId>”,<status>,<timerId>,<running>,<eventLabel>…,<eventLabel>
…(list of active timers)
(OK | ERROR)
Parameters
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<timerId>
The Id of the timer (1-255).
<running>
0 = Timer is stopped.
1 = Timer is running.
<eventLabel>
EventLabel. This defines the event(s) that trigger the
stopping of a timer. There may be from 0 to 10 values. A 0
value specifies “immediate”.
Example'
The following example shows how to stop a timer immediately.
AT$TIMERSTOP=1,0
Watchdog Examples 10.5.4
Server'Connection'Watchdog'
The following example shows how the timer commands can be used to create a
watchdog on the remote server connection. The timer is started during power up
initialization and stopped when the server is connected. The timer is restarted when the
connection closes. If the timer expires, the modem will be reset.
// Configure a remote TCP server to receive reports.
AT$SERVER=1,"24.163.92.131",2400,1,1
// Create timer 1, with duration of 10 minutes (6000 x 0.1 sec).
// The first <eventLabel> is 0 to start immediately.
// The next <eventLabel> is to restart on the server close event:
// type=52 (sockets), obj=0 (don’t care), event=3 (close), entered in hex.
77
// The command AT$EVENTLABEL=52,0,3 can be used as an aid to encode
// the <eventLabel> parameters.
AT$TIMERSTART=1,6000,0,00340003
// Create stop conditions for timer 1 to stop on the server connect event:
// type=52 (sockets), obj=0 (don’t care), event=1 (connect).
AT$TIMERSTOP=1,00340001
// Define a reset condition for the timer expiration:
// type=2 (timer), obj=1 (timer id), event=3 (expire).
AT$RESET=00020103
TCP'Server'Data'Watchdog'
The following example shows how the timer commands can be used to create a
watchdog for incoming data to the local TCP server. The timer is started when a remote
client connects to the local TCP server. The timer is stopped when the connection
closes. The timer is restarted every time data is received from the remote client. If
more than 5 minutes pass since the last data was received, the timer expires and the
modem will be reset.
// Configure the local TCP server.
AT$TCPPORT=2010
// Create timer 2, with duration of 5 minutes (3000 x 0.1 sec).
// The first <eventLabel> is to start on the TCP connect event:
// type=52 (sockets), obj=0 (don’t care), event=4 (connect), entered in hex.
// The next <eventLabel> is to restart on the TCP read event:
// type=52 (sockets), obj=0 (don’t care), event=5 (read), entered in hex.
AT$TIMERSTART=2,3000,00340004,00340005
// Create stop conditions for timer 2 to stop on the TCP close event:
// type=52 (sockets), obj=0 (don’t care), event=6 (close).
AT$TIMERSTOP=2,00340006
// Define a reset condition for the timer expiration:
// type=2 (timer), obj=2 (timer id), event=3 (expire).
AT$RESET=00020203
Serial'Endpoint'Data'Watchdog'
The following example shows how the timer commands can be used to create a
watchdog for data going into a serial endpoint. The timer is started when the endpoint is
created. The timer is stopped when the endpoint is deleted. The timer is restarted
every time data is sent through the serial endpoint. If more than 5 minutes pass since
the last data was received, the timer expires and the modem will be reset.
// Assume the serial endpoint id is 1.
// Create timer 3, with duration of 5 minutes (3000 x 0.1 sec).
// The first <eventLabel> is to start on the endpoint create event:
// type=100 (endpoint), obj=1 (endpointId), event=1 (create), entered in hex.
78
// The next <eventLabel> is to restart on the serial endpoint data in event:
// type=103 (serial endpoint), obj=1 (endpointId), event=4 (data in).
AT$TIMERSTART=3,3000,00640101,00670104
// Create stop conditions for timer 3 to stop on the endpoint delete event:
// type=100 (endpoint), obj=1 (endpointId), event=2 (delete.
AT$TIMERSTOP=3,00340006
// Define a reset condition for the timer expiration:
// type=2 (timer), obj=3 (timer id), event=3 (expire).
AT$RESET=00020303
10.6 Alarm Clock
The alarm clock allows the user to generate events at a specified time. This event can
then be used to trigger other actions in the system.
Alarm Clock Events 10.6.1
These events are generated by alarm clocks. The EventType is 2 for timers. The
ObjectId for the event is the Alarm Id. See section 7 for more about events.
Name
EventId
Description
ALARMCLOCK_EXPIRE
5
Alarm clock expired.
AT$ALARMCLOCK 10.6.2
This command generates an event when the specified time is reached. This event can
be used to trigger other actions such as system reset.
Action'command'
Delete an already defined alarm
AT$ALARMCLOCK=<alarmId>
OK
Create an alarm, one shot
AT$ALARMCLOCK=<alarmId>,<type = 1>,”<defString>”
$ALARMCLOCK:”< deviceId >”,<status>,<alarmId>,<type = 1>,”<defString>”
OK
Create an alarm, repeat
AT$ALARMCLOCK=<alarmId>,<type =0>,”<defString>
$ALARMCLOCK:”< deviceId >”,<status>,<alarmId>,<type = 0>,”<defString>”
OK
79
Read'command'
AT$ALARMCLOCK?
$ALARMCLOCK:”< deviceId >”,<status>,<alarmId>,<type>,”<defString>”
OK
Parameter
Description
< deviceId >
The ID of the modem.
<status>
0 Success
1007 Invalid time format
1012 NV save error
<alarmId>
Identifier for the alarm to be created
<type>
0 - Repeat
1 – Once
<defString>
(a) (b) (c) (d) (e)
(a) minute (0 - 59)
(b) hour (0 - 23)
(c) day of month (1 - 31)
(d) month (1 - 12)
(e) day of week (1 - 7) (Monday=1)
Note: Use * as wildcard (Match any value). Minute value cannot be a
wildcard.
<defString examples>
Run once a year, midnight, Jan. 1
“0 0 1 1 *”
Run once a month, midnight, first of month
“0 0 1 * *”
Run once a week, midnight on Monday
“0 0 * * 1”
Run once a day, midnight
“0 0 * * *”
Run once an hour, beginning of hour
“0 * * * *”
80
11 Device Configuration
This section describes general commands used to configure the device.
11.1 System Variables
This subsystem defines the following system variables:
Identifier
(hex)
Name
Description
nonVolatile
autoUpdt
003201
sig
Signal strength
yes
11.2 String Tokens
This subsystem defines the following dynamic string tokens:
Name
Description
Prefix #
Postfix #
sig
Signal strength
11.3 Signal Quality
The signal quality commands return information about the current signal quality level
and bit error rate. It also allows users to configure signal quality ranges for use as
system events, which can be used to control various system behaviors like system
signal strength LEDs.
AT$CSQ 11.3.1
The $CSQ command can be used to set signal level intervals, read signal level intervals
or display the current signal level
Test'command'
AT$CSQ=?
OK
Action'command'
The following shows the command (in bold) to display the current signal level
81
AT$CSQ
$CSQ: :”<deviceId>”,<status>,<rssi>,<ber>
OK
Parameter'command'
The following shows the command (in bold) to set CSQ level intervals. At least two and
up to fifteen interval bounds must be provided.
AT$CSQ=<bound0>,<bound1>[,…boundN>]
$CSQ: :”<deviceId>”,<status>,<bound0>,<bound1>[,…<boundN>]
(OK|ERROR)
Read'command'
The following shows the command to read the current interval bounds.
AT$CSQ?
$ CSQ: :”<deviceId>”,<status>,<bound0>,<bound1>[,…<boundN>]
OK
11.4 SMS Forwarding Behavior
This command set controls whether incoming SMS messages are consumed by the
software or forwarded on for handling by the native AT command processor.
AT$SMSFORWARD – command to set and read the current SMS forwarding
behavior.
AT$SMSFORWARD 11.4.1
command to set and read the current SMS forwarding behavior. This setting is active
only when the software SMS functionality is enabled, such as SMS endpoints. If the
interface is turned off, all SMS messages will be forwarded for standard 3GPP handling,
regardless of the setting of this command.
Action'Command'
The following shows the command (in bold) to configure the SMS forwarding behavior.
82
AT$SMSFORWARD=<fwdMode>
$SMSFORWARD: ”<deviceId>”,<status>
(OK | ERROR)
Read'Command'
The following shows the command (in bold) to query the SMS forwarding behavior.
AT$SMSFORWARD?
$SMSFORWARD: ”<deviceId>”,<status>,<fwdMode>
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<fwdMode>
0 = Do not forward SMS messages. The software
consumes all SMS messages.
1 = Forward SMS messages that are not associated with
an SMS endpoint. The software consumes SMS messages
used by SMS endpoints (default).
2 = Forward all SMS messages.
<status>
Description
0
Success
1012
NV save error.
1035
Invalid mode parameter.
11.5 Device Reset
This command allows the user to reset the device immediately or reset the device
based on a system event. It is recommended the user turn on reporting so whenever the
device resets the server receives a report. See AT$RESET for an example of how to
configure an alarmclock to schedule an automatic reset.
The following command is supported:
AT$RESET – Action and Read commands
AT$RESET 11.5.1
AT command used to reset the device or configure the device to reset on a specified
event.
83
Action'Command'
The following shows the command (in bold) to reset the device, followed by the
expected output.
AT$RESET[=<eventLabel>,[...<eventLabelN>]]
$RESET: ”<deviceId>”,<status>
OK
Read'command'
The following shows the command (in bold) to query the reset configuration, followed by
the expected output.
AT$RESET?
$RESET: ”<deviceId>”,<status>[,<eventLabel>,[...<eventLabelN>]]
OK
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
0 – Success. Once the success parameter is returned the
device is reset.
<eventLabel>
Event that may be used to trigger the reset action.
Example'
This example schedules an automatic reset for a specific time of day. See
ALARMCLOCK commands for more information on configuring alarm clocks.
Command
Description
at$alarmclock=1,2,"2 30 * * 7”
$ALARMCLOCK: "327004019082",0,1,0,"2
30 * * 7"
OK
Alarmclock 1 expires every Sunday at 2:30
AM
at$reset=20105
$RESET: "327004019082",0
OK
Reset for alarmclock 1 expire
84
11.6 Device SHUTOFF
These commands allow the user to shutoff the device immediately or shutoff the device
based on a system event. It is recommended the user turn on reporting so whenever the
device resets the server receives a report.
The following command is supported:
AT$SHUTOFF – Shut down the device.
AT$SHUTOFF 11.6.1
This command provides a method to shut off the ME when a specified event occurs,
shutdown will be immediate.
Action command
AT$SHUTOFF[=<eventLabel>,[...<eventLabelN>]]
$SHUTOFF: ”<deviceId>”,<status>[,<eventLabel>,[...<eventLabelN>]]
OK
Read command
AT$SHUTOFF?
$SHUTOFF: ”<deviceId>”,<status>,<eventLabel>,[...<eventLabelN>]
Parameter
Description
< deviceId >
The ID of the modem.
<status>
0 – Success
1007 – Invalid time format
1012 – NV save error
<eventLabel>
Event to trigger ME shutoff
11.7 Device Event Reporting
The device originates unsolicited responses which are used to provide user status or to
notify of events occurring within the device.
The following command is supported:
AT$REPORT – Action commands.
NOTE: This command is currently separate from the central event system.
85
AT$REPORT 11.7.1
AT command used to configure which unsolicited reports are reported to the user.
Action'Command'
The following shows the command (in bold) to configure a report setting.
AT$REPORT=<ReportId>,<enabled>
$REPORT:”<deviceId>”,<status>
(OK | ERROR)
Read'Command'
The following shows the command (in bold) to query the report settings. All existing
report “on/off” settings are listed, starting at Report 1 and ending with the last report (in
this example, report N).
AT$REPORT?
$REPORT:”<deviceId>”,<status>,<Report 1 setting>,<Report 2 setting>,<Report 3
setting>,<Report 4 setting>, … <Report N setting>
(OK | ERROR)
Parameters
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the server command.
0 = Success
1012 = NV save error
1040 = Invalid report settings
<ReportId>
See the Report Id’s
0 = Special “wildcard” applies on/off setting to all Report
Id’s.
<enabled>
On/Off setting for an Report (0=off, 1=on)
Unsolicited $REPORT 11.7.2
AT command used to report various status changes that occur on the device. This
response is unsolicited.
Unsolicited'Response'
The following shows the format of the unsolicited $REPORT.
$REPORT: ”<deviceId>”,<status>,<date time>,<ReportId>,<detail>
86
Parameters
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 OK
<date time>
Date and Time of the report
<ReportId>
See the Report Id’s
<detail>
Details about the Report.
!
Report!Ids
Report
Description
1
Device Rebooted
2
Keep Alive
3
GPRS regained
4
FOTA download started
5
FOTA upgrade complete
6
FOTA Connection error
7
FOTA Login error
8
FOTA File not found
9
FOTA install error
10
TCP port or UDP port changed locally
11
IP address changed by the carrier
12
Reserved/Not used
13
SIM re-inserted
14
TELNET port changed
15
FOTA aborted
16-64
Reserved for future use
12 Cellular Communications
This section covers the commands required to setup the software so it may
communicate over a Wide Area Network (WAN). This includes setting up the
information required for the device to communicate with a server or for the server to
communicate with the device.
12.1 GPRS Events
These events are generated for GPRS. The EventType is 50 (0x32) for network. The
event ObjectId is not used (0). See section 7 for more about events.
87
Name
EventId
Description
IP_CHANGED
1
A new IP address was assigned.
GPRS_ATTACHED
2
GPRS attached
GPRS_DETTACHED
3
GPRS detached
GPRS_ACTIVATED
4
GPRS context was activated
GPRS_DEACTIVATED
5
GPRS context was deactivated
12.2 String Tokens
This subsystem defines the following dynamic string tokens:
Name
Description
Prefix #
Postfix #
apn
Access Point Name. postNumber = Context ID
(1-4)
wanip
IP address from the cellular network
12.3 GPRS settings
This command set allows you to modify and query the GPRS PDP Context data. Up to
four PDP Contexts can be configured.
The PDP Context data provides the device with the APN specific to wireless provider
and username and password needed to access the wireless network. Since most
carriers do not require username and password, these settings are optional.
The APN is provided by wireless network provider carrier. Once the device registers on
the network, it then connects to the first valid APN.
The following command is supported:
AT$CGDCONT – Action and Read commands
AT$CGDCONT 12.3.1
AT command used to configure PDP context settings. The PDP context settings can be
set or read.
Action'Command'
The following shows the command (in bold) to configure PDP context settings for a
specified context ID, followed by the expected output. The username and password are
optional parameters. When the APN is set to an empty string (“”), it in effect, clears or
invalidates the specified PDP context making it no longer valid.
AT$CGDCONT=<contextId>[,”<apn>”[,”<username>”[,”<password>”]]]
88
$CGDCONT: “<deviceId>”,<status>
(OK | ERROR)
Delete'Command'
The following shows the command (in bold) to delete an existing PDP context.
AT$CGDCONT=<contextId>
$CGDCONT: “<deviceId>”,<status>
OK
Read'Command'
The following shows the command (in bold) to list the PDP context settings for all PDP
Contexts.
AT$CGDCONT?
$CGDCONT: “<deviceId>”,<status>,<contextId>,”<apn>”,”<username>”,”<password>”
…(list of PDP contexts)
OK
Parameters(
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<contextId>
PDP context identifier. If just the context ID is entered
without other parameters, then the PDP context is deleted.
Range 1-4
<apn>
Access Point Name, max=32
<username>
Username, max=25
<password>
Password, max=15
<status>
Description
0
Success
21
Invalid context id
23
Memory failure
1004
Access point name too long.
1005
Username too long
1006
Password too long
1012
NV save error
Note: Most APN’s don’t use the username and password.
89
Note: This command is similar to the standard 27.007 command AT+CGDCONT,
except it takes the <username> and <password>, and the <deviceId> and <status> are
returned in the intermediate response.
12.4 Network IP
This section describes the commands available to query the IP address of the device
provided by the network.
The following command is supported:
AT$IP – Read commands
AT$IP 12.4.1
AT command used to query the IP address of the device provided by the network. The
device IP address can only be read.
Read'Command'
The following shows the command (in bold) to query the IP address of the device.
AT$IP?
$IP: “<deviceId>”,<status>,”<ipAddress>”
OK
'''Parameters'
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
<ipAddress>
The IP Address of the device.
12.5 Ping
This command set allows the user to Ping remote servers. This command is very useful
when debugging a new device or network provider to test the connectivity and latency of
the cellular connection.
The following command is supported:
AT$PING – PING command
90
AT$PING 12.5.1
Ping a remote server. This command is very similar to the Ping commands available on
Unix or Windows operating systems. Once this command is started it will return the
results via the “$PING:” unsolicited response.
Action'Command'
AT$PING=”<address>”[,<repeat>[,<interval>[,<timeout>[,<size>]]]]
$PING: “<deviceId>”,<status>
OK
Parameter
Description
<address>
The IP address or hostname for which to send the PING
packets.
<repeat>
The number of times to repeat the ping request. Default =
4.
<interval>
The amount of time in milliseconds to wait between ping
requests. Default = 4.
<timeout>
The amount of time in milliseconds to wait before a ping
packet is considered timed out. Default = 5000
milliseconds (5 seconds)
<size>
The size of the ping requests in bytes. Default = 20 Bytes.
Unsolicited'Response'
Each time a ping packet is returned to the device or if the packet times out, this
unsolicited response is returned.
$PINGRSP: “<deviceId>”,<status>,<index>[,<responseTime>]
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = Success
1070 = Timeout
<index>
The packet index received by the device or timed out.
<responseTime>
This value is not displayed if the packet times out. If the
response is received, this is the amount of time it took to
make a round trip from the device to the server and back.
91
13 Ethernet
This chapter covers commands relating to setting up an Ethernet interface. These
commands only apply when an Ethernet card is inserted and enabled. If the Ethernet
interface is not inserted, or the Ethernet interface is disabled by the
AT$ENABLEETHERNET command, then these commands will not be available.
13.1 Events
The ethernet interface generates events for the connection status and the link status.
The EventType is 53 (0x35). The object ID used is not used.
Name
Number
Description
CONNECTED
1
IP communication ready
DISCONNECTED
2
IP communication not ready
LINK_DOWN
3
Link down, cable unplugged
LINK_UP
4
Link up, cable plugged in
DRIVER_ERROR
5
Ethernet driver not installed
13.2 System Variables
This subsystem defines the following system variables:
Identifier
(hex)
Name
Description
nonVolatile
autoUpdt
003501
etherlink
Ethernet link status (cable
connected)
yes
13.3 String Tokens
This subsystem defines the following dynamic string tokens:
Name
Description
Prefix #
Postfix #
etheron
Ethernet on (0-1)
etherlink
Ethernet link status (cable connected)
gatewayip
Static IP address of the local ethernet interface
13.4 Ethernet Interface
This section describes the commands available to modify and query the Ethernet mode.
The Ethernet mode controls whether or not the local Ethernet interface is enabled.
92
The Ethernet mode is disabled by default.
The following command is supported:
AT$ENABLEETHERNET – Action and Read commands
AT$ENABLEETHERNET 13.4.1
command to set and read the current Ethernet mode.
Action'Command'
The following shows the command (in bold) to configure the Ethernet mode.
AT$ENABLEETHERNET=<ethernetMode>[,<localMac]
$ENABLEETHERNET: ”<deviceId>”,<status>
(OK | ERROR)
Read'Command'
The following shows the command (in bold) to query the Ethernet mode.
AT$ENABLEETHERNET?
$ENABLEETHERNET: ”<deviceId>”,<status>,<ethernetInitStatus>,<localMac>
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<ethernetMode>
0 = Ethernet is disabled (default).
1 = Ethernet is enabled.
<localMac>
Specifies whether to read the MAC address from an
EEPROM device, or to derive a local MAC address from
the modem serial number.
0 = Read MAC from EEPROM [default]
<ethernetInitStatus>
0 = Ethernet is disabled.
1 = Ethernet is operational.
2 = Ethernet is disabled because driver failed initialization.
<status>
Description
0
Success
1
Error
1012
NV save error.
1050
Invalid parameter value
93
13.5 Ethernet IP
This command set describes the commands available to query the IP address of the
local Ethernet interface on the device.
The following command is supported:
AT$ETHERNETIP – Read commands
GETETHERNETIP 13.5.1
This command gets the IP address, net mask, and link status of the Ethernet interface
on the device. The message body of the command from the server is empty.
The following shows the body of the response message from the device:
Message Body Byte
Description
0
IP Address byte 1
1
IP Address byte 2
2
IP Address byte 3
3
IP Address byte 4
4
Net Mask byte 1
5
Net Mask byte 2
6
Net Mask byte 3
7
Net Mask byte 4
8
Ethernet link status:
0 = Cable not connected
1 = Cable connected
AT$ETHERNETIP 13.5.2
AT command used to query the IP address, net mask, and link status of the local
Ethernet interface on the device. The IP address can only be read.
Read'Command'
The following shows the command (in bold) to query the IP address of the device.
AT$ETHERNETIP?
$ETHERNETIP: “<deviceId>”,<status>,”<cableConnected>,<ipAddress>”,<netmask>
OK
!!!Parameters!
94
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
0 = success
<cableConnected>
0 = Ethernet cable is not connected.
1 = Ethernet cable is connected.
<ipAddress>
The IP Address of the Ethernet interface.
<netmask>
The network mask of the Ethernet interface.
13.6 DHCP Server
This section describes the commands available to modify and query the DHCP server
settings.
The following commands are supported:
AT$DHCPS – Action and Read commands
AT$DHCPDNS – Action and Read commands
AT$DHCPS 13.6.1
AT command used to set DHCP host address, number of clients, first address, subnet
mask, lease time, and activation. The settings can be set or read.
Action'Command'
The following shows the command (in bold) to configure the DHCP settings.
AT$DHCPS=<active>[,”<listenIP>”,<numClientIPs>,”<1stClientIP>”,”<subnetMask
>”, <timeout>]
$DHCPS: ”<deviceId>”,<status>
(OK | ERROR)
Read'Command'
The following shows the command (in bold) to query the DHCP settings.
AT$DHCPS?
$DHCPS: ”<deviceId>”,<status>,<active>,”<listenIP>,<numClientIPs>,<1stClientIP>”,
<subnetMask>”,<timeout>
(OK | ERROR)
!!!Parameters!
95
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<active>
True/False.
<listenIP>
Listening server’s IP address (most likely the device IP.
See AT$STATICIP).
<numClientIPs>
Number of clients to provide addresses to.
<1stClientIP>
First IP address to provide to the first client request.
<subnetMask>
Subnet mask.
<leaseTime>
Lease time in seconds.
<status>
Description
0
Success
1
Error
AT$DHCPDNS 13.6.2
command AT command to set the DNS address that will be assigned to a DHCP client.
The behavior can be set or read.
Action'command'
The following shows the command (in bold) to configure the DHCP DNS settings.
AT$DHCPDNS=<setting>[,<DNSIpAddress>]
$DHCPDNS: ”<deviceId>”,<status>
Read'command'
The following shows the command (in bold) to query the DHCP settings.
AT$DHCPDNS?
$DHCPDNS: “<deviceId>”,<status>,<setting>,”<DNSIpAddress>”
Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<setting>
DNS behavior (0 – network, 1 – Initial with network
overwrite, 2 –user defined, no network overwrite)
<listenIP>
DNS server’s IP address
96
13.7 Static IP Address
This command set allows you to modify and query the static IP address of the local
Ethernet interface on the device. The static IP address can be disabled, thereby
enabling the DHCP client to automatically acquire an IP address.
The Static IP address should be chosen from one of the private address ranges, so it
does not conflict with the GPRS IP address. Most carrier VPN networks use the private
class A range (10.x.x.x). And many home routers use the class C range 192.168.x.x.
Therefore, a good choice for the Static IP should would be the class B addresses in the
range 172.16.x.x.
The following command is supported:
AT$STATICIP – Action and Read commands
AT$STATICIP 13.7.1
AT command used to set or read the static IP address of the local Ethernet interface on
the device. If the static IP address is set to 0, then it is disabled, and the DCHP client
will be enabled to automatically acquire an IP address from a DHCP server. A modem
restart is required for changes to take effect.
Action'Command'
The following shows the command (in bold) to configure the static IP address.
AT$STATICIP=”<staticIP>”
$STATICIP: ”<deviceId>”,<status>,”<staticIP>
(OK | ERROR)
Read'Command'
The following shows the command (in bold) to query the static IP address.
AT$STATICIP?
$ STATICIP: ”<deviceId>”,<status>,”<staticIP>
(OK | ERROR)
!!!Parameters!
Parameter
Description
<deviceId>
The ID of the modem.
<status>
The status of the command.
<staticIP>
Static IP address. If the static IP address is set to 0, then
97
it is disabled. A modem restart is required for changes to