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 
.
Page Count: 224
| Download | |
| Open PDF In Browser | View PDF |
Courier M2M 3G Cellular Modem USR3500 Application Guide R24.0794.00 Revision History Date Reason For Changes Version 1/28/14 Initial Release 1.0 2/25/14 Cosmetic updates 1.1 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 ii 1 OVERVIEW ............................................................................................................................................................ 13 1.1 1.2 2 DEFINITIONS ..................................................................................................................................................... 13 DESIGN PRINCIPLES .......................................................................................................................................... 13 NETWORK CONFIGURATIONS ........................................................................................................................... 14 2.1 PRIVATE IP WITH VPN ....................................................................................................................................... 14 2.2 PRIVATE IP ....................................................................................................................................................... 15 2.2.1 Mobile Originated.................................................................................................................................... 15 2.2.2 Mobile Originated with SMS wake up (Server initiated) ......................................................................... 15 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 4.2 4.3 5 PROTOCOL ....................................................................................................................................................... 19 ASCII FORMAT ................................................................................................................................................. 19 ASCII COMMAND/RESPONSE TYPES ................................................................................................................... 21 STRING TOKENS .................................................................................................................................................. 24 5.1 STRINGSEND EVENTS .................................................................................................................................... 26 5.2 AT$STRINGTOKENS ..................................................................................................................................... 27 5.2.1 Action Command .................................................................................................................................... 27 5.2.2 Read Command...................................................................................................................................... 27 5.3 AT$STRINGTEST .......................................................................................................................................... 27 5.3.1 Action Command .................................................................................................................................... 28 5.3.2 Example .................................................................................................................................................. 28 5.4 AT$STRINGSENDEMAIL ............................................................................................................................... 28 5.4.1 Action Command .................................................................................................................................... 28 5.4.2 Read Command...................................................................................................................................... 29 5.4.3 Example .................................................................................................................................................. 30 5.5 AT$STRINGSENDSMS .................................................................................................................................. 31 5.5.1 Action Command .................................................................................................................................... 31 5.5.2 Read Command...................................................................................................................................... 32 5.5.3 Example .................................................................................................................................................. 33 5.6 AT$STRINGSEND.......................................................................................................................................... 33 5.6.1 Action Command .................................................................................................................................... 33 5.6.2 Read Command...................................................................................................................................... 34 5.6.3 Example 1: Send Email ......................................................................................................................... 35 5.6.4 Example 2: Serial to TCP Endpoint Connection .................................................................................... 35 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 6.5.1 Read Command...................................................................................................................................... 39 6.6 AT$VARIABLETHRESHOLD ......................................................................................................................... 40 6.6.1 Set Command ......................................................................................................................................... 40 6.6.2 Delete Command .................................................................................................................................... 40 6.6.3 Read Command...................................................................................................................................... 40 6.6.4 Example .................................................................................................................................................. 41 6.7 AT$VARIABLECOMPARE ............................................................................................................................. 41 6.7.1 Set Command ......................................................................................................................................... 42 6.7.2 Delete Command .................................................................................................................................... 42 iii 6.7.3 Read Command...................................................................................................................................... 42 6.7.4 Example .................................................................................................................................................. 43 6.8 AT$VARIABLESET ........................................................................................................................................ 43 6.8.1 Set Command ......................................................................................................................................... 43 6.8.2 Delete Command .................................................................................................................................... 43 6.8.3 Read Command...................................................................................................................................... 44 6.8.4 Example .................................................................................................................................................. 45 6.9 AT$VARIABLESEND ..................................................................................................................................... 45 6.9.1 Set Command ......................................................................................................................................... 45 6.9.2 Delete Command .................................................................................................................................... 46 6.9.3 Read Command...................................................................................................................................... 46 6.9.4 Example .................................................................................................................................................. 47 7 EVENTS ................................................................................................................................................................. 47 7.1 EVENT TYPES ................................................................................................................................................... 48 7.2 EVENT LABELS .................................................................................................................................................. 50 7.3 SYSTEM EVENTS ............................................................................................................................................... 50 7.4 EVENT LABEL COMMAND .................................................................................................................................... 51 7.4.1 AT$EVENTLABEL .................................................................................................................................. 51 7.5 EVENT DISPLAY COMMAND ................................................................................................................................ 52 7.5.1 AT$EVENTDISPLAY .............................................................................................................................. 52 Action command ............................................................................................................................................. 52 Read command .............................................................................................................................................. 53 Unsolicited response ...................................................................................................................................... 53 7.6 EVENT FILTERS ................................................................................................................................................. 53 7.7 EVENTS ............................................................................................................................................................ 53 7.7.1 AT$EVENTFILTER ................................................................................................................................. 54 Action Command ............................................................................................................................................ 54 Read Command .............................................................................................................................................. 54 Example .......................................................................................................................................................... 54 7.8 EVENT SEQUENCES ........................................................................................................................................... 55 7.9 EVENTS ............................................................................................................................................................ 55 7.9.1 AT$EVENTSEQUENCE ......................................................................................................................... 55 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 8.3.1 Action Command .................................................................................................................................... 59 8.3.2 Delete Configuration ............................................................................................................................... 59 8.3.3 Read Command...................................................................................................................................... 59 8.3.4 Example .................................................................................................................................................. 60 8.4 AT$LOWPOWEROFF .................................................................................................................................... 60 8.4.1 Action Command .................................................................................................................................... 60 8.4.2 Delete Configuration ............................................................................................................................... 60 8.4.3 Immediate Disable .................................................................................................................................. 61 8.4.4 Read Command...................................................................................................................................... 61 8.4.5 Example .................................................................................................................................................. 61 9 IDENTIFICATION COMMANDS ............................................................................................................................ 63 9.1 EVENTS ............................................................................................................................................................ 63 9.2 STRING TOKENS ................................................................................................................................................ 63 9.3 GET APPLICATION VERSION COMMAND ............................................................................................................... 64 9.3.1 AT$APPVERSION .................................................................................................................................. 64 Read Command .............................................................................................................................................. 64 iv 9.4 GET FIRMWARE VERSION COMMAND ................................................................................................................... 64 9.4.1 AT$FWVERSION ................................................................................................................................... 65 9.5 GET MODEM ID COMMAND................................................................................................................................. 65 9.5.1 AT$MODEMID ........................................................................................................................................ 65 Read Command .............................................................................................................................................. 65 9.6 GET SUBSCRIBER ID COMMAND ......................................................................................................................... 66 9.6.1 AT$SUBSCRIBERID .............................................................................................................................. 66 Read Command .............................................................................................................................................. 66 9.7 DEVICE IDENTIFICATION ..................................................................................................................................... 66 9.7.1 AT$DEVICEID ........................................................................................................................................ 67 Action Command/Response ........................................................................................................................... 67 Read Command/Response ............................................................................................................................ 67 9.8 GET BUILD FEATURES........................................................................................................................................ 67 9.8.1 AT$FEATURE ........................................................................................................................................ 68 Read Command .............................................................................................................................................. 68 10 TIME ..................................................................................................................................................................... 69 10.1 EVENTS .......................................................................................................................................................... 69 10.2 STRING TOKENS .............................................................................................................................................. 69 10.2.1 Using a Stored Timestamp ................................................................................................................... 70 Example .......................................................................................................................................................... 70 10.3 MANUALLY SET AND GET DEVICE CLOCK ........................................................................................................... 71 10.3.1 AT$TIME............................................................................................................................................... 71 Action Command/Response ........................................................................................................................... 71 Read Command/Response ............................................................................................................................ 71 10.4 AUTOMATICALLY SET DEVICE CLOCK ................................................................................................................ 72 10.4.1 AT$AUTOTIME..................................................................................................................................... 72 Action Command/Response ........................................................................................................................... 72 Read Command/Response ............................................................................................................................ 72 10.5 TIMERS........................................................................................................................................................... 73 10.5.1 Timer Events......................................................................................................................................... 73 10.5.2 AT$TIMERSTART ................................................................................................................................ 73 Action Command ............................................................................................................................................ 73 Restart Timer .................................................................................................................................................. 74 Delete Timer ................................................................................................................................................... 74 Read Command .............................................................................................................................................. 74 Unsolicited Response ..................................................................................................................................... 74 Example .......................................................................................................................................................... 75 10.5.3 AT$TIMERSTOP .................................................................................................................................. 75 Action Command ............................................................................................................................................ 75 Delete Timer ................................................................................................................................................... 75 Read Command .............................................................................................................................................. 76 Example .......................................................................................................................................................... 76 10.5.4 Watchdog Examples ............................................................................................................................. 76 Server Connection Watchdog ......................................................................................................................... 76 TCP Server Data Watchdog ........................................................................................................................... 77 Serial Endpoint Data Watchdog ...................................................................................................................... 77 10.6 ALARM CLOCK ................................................................................................................................................ 78 10.6.1 Alarm Clock Events .............................................................................................................................. 78 10.6.2 AT$ALARMCLOCK .............................................................................................................................. 78 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 11.3.1 AT$CSQ ............................................................................................................................................... 80 Test command ................................................................................................................................................ 80 v Action command ............................................................................................................................................. 80 Parameter command ...................................................................................................................................... 81 Read command .............................................................................................................................................. 81 11.4 SMS FORWARDING BEHAVIOR ......................................................................................................................... 81 11.4.1 AT$SMSFORWARD ............................................................................................................................. 81 Action Command ............................................................................................................................................ 81 Read Command .............................................................................................................................................. 82 11.5 DEVICE RESET ................................................................................................................................................ 82 11.5.1 AT$RESET ........................................................................................................................................... 82 Action Command ............................................................................................................................................ 83 Read command .............................................................................................................................................. 83 Example .......................................................................................................................................................... 83 11.6 DEVICE SHUTOFF ......................................................................................................................................... 84 11.6.1 AT$SHUTOFF ...................................................................................................................................... 84 11.7 DEVICE EVENT REPORTING .............................................................................................................................. 84 11.7.1 AT$REPORT ........................................................................................................................................ 85 Action Command ............................................................................................................................................ 85 Read Command .............................................................................................................................................. 85 11.7.2 Unsolicited $REPORT .......................................................................................................................... 85 Unsolicited Response ..................................................................................................................................... 85 12 CELLULAR COMMUNICATIONS ....................................................................................................................... 86 12.1 GPRS EVENTS ............................................................................................................................................... 86 12.2 STRING TOKENS .............................................................................................................................................. 87 12.3 GPRS SETTINGS ............................................................................................................................................. 87 12.3.1 AT$CGDCONT ..................................................................................................................................... 87 Action Command ............................................................................................................................................ 87 Delete Command ............................................................................................................................................ 88 Read Command .............................................................................................................................................. 88 12.4 NETWORK IP .................................................................................................................................................. 89 12.4.1 AT$IP .................................................................................................................................................... 89 Read Command .............................................................................................................................................. 89 Parameters ..................................................................................................................................................... 89 12.5 PING .............................................................................................................................................................. 89 12.5.1 AT$PING .............................................................................................................................................. 90 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 13.4.1 AT$ENABLEETHERNET...................................................................................................................... 92 Action Command ............................................................................................................................................ 92 Read Command .............................................................................................................................................. 92 13.5 ETHERNET IP .................................................................................................................................................. 93 13.5.1 GETETHERNETIP................................................................................................................................ 93 13.5.2 AT$ETHERNETIP ................................................................................................................................ 93 Read Command .............................................................................................................................................. 93 13.6 DHCP SERVER ............................................................................................................................................... 94 13.6.1 AT$DHCPS........................................................................................................................................... 94 Action Command ............................................................................................................................................ 94 Read Command .............................................................................................................................................. 94 13.6.2 AT$DHCPDNS ..................................................................................................................................... 95 Action command ............................................................................................................................................. 95 Read command .............................................................................................................................................. 95 13.7 STATIC IP ADDRESS ........................................................................................................................................ 96 13.7.1 AT$STATICIP ....................................................................................................................................... 96 vi Action Command ............................................................................................................................................ 96 Read Command .............................................................................................................................................. 96 13.8 NETWORK ADDRESS TRANSLATION (NAT) ......................................................................................................... 97 13.8.1 AT$NAT ................................................................................................................................................ 97 Action Command ............................................................................................................................................ 97 Read Command .............................................................................................................................................. 97 13.9 PORT FORWARDING ......................................................................................................................................... 98 13.9.1 AT$PORTFORWARD........................................................................................................................... 98 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 14.1.1 System Variables ................................................................................................................................ 101 14.1.2 String Tokens...................................................................................................................................... 101 14.1.3 Telnet Port Events .............................................................................................................................. 102 14.1.4 AT$TELNETPORT ............................................................................................................................. 102 Action Command .......................................................................................................................................... 102 Read Command ............................................................................................................................................ 102 Example ........................................................................................................................................................ 103 14.2 SMS COMMAND INTERFACE ........................................................................................................................... 104 14.2.1 AT$SMS ............................................................................................................................................. 104 Action Command .......................................................................................................................................... 104 Read Command ............................................................................................................................................ 105 Example ........................................................................................................................................................ 106 15 ENDPOINT / BRIDGE: “PASS THROUGH” ROUTING SUPPORT ................................................................. 106 15.1 EVENTS ........................................................................................................................................................ 107 15.1.1 Serial Endpoint Events ....................................................................................................................... 107 15.1.2 TCP/UDP Endpoint Events ................................................................................................................. 108 15.2 SYSTEM VARIABLES ....................................................................................................................................... 108 15.3 STRING TOKENS ............................................................................................................................................ 109 15.4 ENDPOINT SETTINGS ...................................................................................................................................... 109 15.4.1 AT$ENDPOINT................................................................................................................................... 110 Action Command .......................................................................................................................................... 110 Read Command ............................................................................................................................................ 111 15.4.2 Examples ............................................................................................................................................ 114 15.5 BRIDGE (ROUTE) SETTINGS ............................................................................................................................. 115 15.5.1 Bridge Events ..................................................................................................................................... 115 15.5.2 AT$BRIDGECREATE ......................................................................................................................... 116 Action Command .......................................................................................................................................... 116 Immediate Command ................................................................................................................................... 116 Delete Command .......................................................................................................................................... 116 Read Command ............................................................................................................................................ 117 15.5.3 AT$BRIDGEDELETE ......................................................................................................................... 118 Action Command .......................................................................................................................................... 118 Delete Command .......................................................................................................................................... 118 Read Command ............................................................................................................................................ 118 15.6 ENDPOINT SERVER ........................................................................................................................................ 119 15.6.1 AT$ESERVER .................................................................................................................................... 119 Action Command .......................................................................................................................................... 119 Read Command ............................................................................................................................................ 119 15.7 ONLINE DATA MODE ...................................................................................................................................... 120 15.7.1 AT$ONLINE ........................................................................................................................................ 121 15.8 FILTERING ENDPOINTS ................................................................................................................................... 121 15.8.1 Strip ETX/DLE .................................................................................................................................... 122 Example ........................................................................................................................................................ 122 15.8.2 Compress/Decompress ...................................................................................................................... 123 vii Example 1 ..................................................................................................................................................... 123 Example 2 ..................................................................................................................................................... 124 16 AT PARSER ENDPOINTS ................................................................................................................................. 125 16.1 EVENTS ........................................................................................................................................................ 125 16.2 ASCII COMMANDS ........................................................................................................................................ 125 16.2.1 Action Command ................................................................................................................................ 125 16.2.2 Read Command.................................................................................................................................. 126 16.2.3 Example .............................................................................................................................................. 127 17 SMS ENDPOINTS ............................................................................................................................................. 127 17.1 ENDPOINT CONFIGURATION ............................................................................................................................ 128 17.2 EVENTS ........................................................................................................................................................ 128 17.3 ASCII COMMANDS ........................................................................................................................................ 128 17.3.1 Action Command ................................................................................................................................ 128 17.3.2 Read Command.................................................................................................................................. 129 18 FTP ENDPOINTS............................................................................................................................................... 131 18.1 CONFIGURATIONS .......................................................................................................................................... 131 18.2 EVENTS ........................................................................................................................................................ 131 18.2.1 FTP GET............................................................................................................................................. 131 18.2.2 FTP PUT ............................................................................................................................................. 132 18.3 ASCII COMMANDS ........................................................................................................................................ 132 18.3.1 Action Command ................................................................................................................................ 132 18.3.2 Read Command.................................................................................................................................. 133 18.4 GET EXAMPLE .............................................................................................................................................. 134 18.5 PUT EXAMPLE .............................................................................................................................................. 134 19 HTTP ENDPOINTS ............................................................................................................................................ 135 19.1 CONFIGURATIONS .......................................................................................................................................... 135 19.2 EVENTS ........................................................................................................................................................ 135 19.2.1 HTTP GET .......................................................................................................................................... 135 19.2.2 HTTP PUT .......................................................................................................................................... 136 19.2.3 HTTP POST........................................................................................................................................ 136 19.3 ASCII COMMANDS ........................................................................................................................................ 136 19.3.1 Action Command ................................................................................................................................ 136 19.3.2 Read Command.................................................................................................................................. 137 19.4 GET EXAMPLE ............................................................................................................................................... 139 19.5 PUT EXAMPLE ............................................................................................................................................... 140 20 EMAIL ENDPOINTS .......................................................................................................................................... 140 20.1 CONFIGURATIONS .......................................................................................................................................... 140 20.2 EVENTS ........................................................................................................................................................ 141 20.2.1 POP Endpoint ..................................................................................................................................... 141 20.2.2 SMTP Endpoint................................................................................................................................... 141 20.3 AT$ENDPOINT .......................................................................................................................................... 141 20.3.1 Action Command ................................................................................................................................ 141 20.3.2 Read Command.................................................................................................................................. 142 20.4 EMAIL HEADER .............................................................................................................................................. 143 20.4.1 AT$EMAILHDR................................................................................................................................... 143 Action Command .......................................................................................................................................... 143 Read Command ............................................................................................................................................ 144 20.5 EXAMPLE ...................................................................................................................................................... 144 21 OFFLINE DATA MODE ..................................................................................................................................... 146 21.1 EVENTS ........................................................................................................................................................ 146 21.2 AT$ENDPOINT .......................................................................................................................................... 146 21.2.1 Action Command ................................................................................................................................ 146 21.2.2 Read Command.................................................................................................................................. 147 viii 21.3 AT$EPWRITE............................................................................................................................................. 147 21.3.1 Action Command ................................................................................................................................ 148 21.4 AT$EPREAD .............................................................................................................................................. 149 21.4.1 Action Command ................................................................................................................................ 149 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 22.3.1 Action Command ................................................................................................................................ 153 22.3.2 Immediate Command ......................................................................................................................... 153 22.3.3 Delete OPEN parameters ................................................................................................................... 153 22.3.4 Read Command.................................................................................................................................. 154 22.3.5 Examples ............................................................................................................................................ 154 22.4 AT$FTPCLOSE .......................................................................................................................................... 155 22.5 AT$FTPMKDIR........................................................................................................................................... 155 22.5.1 Action Command ................................................................................................................................ 155 22.5.2 Immediate Command ......................................................................................................................... 155 22.5.3 Delete MKDIR parameters.................................................................................................................. 155 22.5.4 Read Command.................................................................................................................................. 156 22.5.5 Examples ............................................................................................................................................ 156 22.6 AT$FTPCWD.............................................................................................................................................. 157 22.7 AT$FTPDELDIR ......................................................................................................................................... 157 22.8 AT$FTPDEL ............................................................................................................................................... 157 22.8.1 Action Command ................................................................................................................................ 157 22.8.2 Immediate Command ......................................................................................................................... 158 22.8.3 Delete DEL parameters ...................................................................................................................... 158 22.8.4 Read Command.................................................................................................................................. 158 22.8.5 Examples ............................................................................................................................................ 159 22.9 AT$FTPREN............................................................................................................................................... 159 22.9.1 Action Command ................................................................................................................................ 159 22.9.2 Immediate Command ......................................................................................................................... 160 22.9.3 Delete REN parameters...................................................................................................................... 160 22.9.4 Read Command.................................................................................................................................. 160 22.9.5 Examples ............................................................................................................................................ 161 23 SMS ALERTING ................................................................................................................................................ 161 23.1 SMS ALERTING EVENTS ................................................................................................................................ 162 23.2 COMMANDS .................................................................................................................................................. 162 23.3 AT$STRINGLIST ........................................................................................................................................ 162 23.3.1 Action Command ................................................................................................................................ 162 23.3.2 Delete ................................................................................................................................................. 162 23.3.3 Read Command.................................................................................................................................. 162 23.3.4 Examples ............................................................................................................................................ 163 23.4 AT$SENDSMSLIST .................................................................................................................................... 163 23.4.1 Action Command ................................................................................................................................ 164 23.4.2 Immediate Command ......................................................................................................................... 164 23.4.3 Delete ................................................................................................................................................. 164 23.4.4 Read Command.................................................................................................................................. 164 23.4.5 Examples ............................................................................................................................................ 165 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 24.4.1 Tag Endpoint Events .......................................................................................................................... 168 24.4.2 AT$ENDPOINT................................................................................................................................... 169 ix Action Command .......................................................................................................................................... 169 Read Command ............................................................................................................................................ 169 24.5 TAG COMMANDS ........................................................................................................................................... 171 24.6 TAG FORMAT ................................................................................................................................................ 171 24.6.1 AT$TAGFORMAT............................................................................................................................... 171 Action Command .......................................................................................................................................... 171 24.7 TAG RECOMPACT .......................................................................................................................................... 172 24.7.1 AT$TAGRECOMPACT ....................................................................................................................... 172 Action Command .......................................................................................................................................... 172 24.8 TAG INSTALL ................................................................................................................................................. 173 24.8.1 AT$TAGINSTALL ............................................................................................................................... 173 Action Command .......................................................................................................................................... 173 Read Command ............................................................................................................................................ 174 Examples ...................................................................................................................................................... 174 24.9 TAG WRITE ................................................................................................................................................... 175 24.9.1 AT$TAGWRITE .................................................................................................................................. 175 Action Command .......................................................................................................................................... 175 Example ........................................................................................................................................................ 176 24.10 TAG CLOSE................................................................................................................................................. 176 24.10.1 AT$TAGCLOSE ............................................................................................................................... 176 Action Command .......................................................................................................................................... 176 Read Command ............................................................................................................................................ 177 Examples ...................................................................................................................................................... 178 24.11 TAG DELETE ............................................................................................................................................... 178 24.11.1 AT$TAGDELETE .............................................................................................................................. 178 Action Command .......................................................................................................................................... 178 Read Command ............................................................................................................................................ 179 Examples ...................................................................................................................................................... 179 24.12 TAG READ .................................................................................................................................................. 180 24.12.1 AT$TAGREAD .................................................................................................................................. 180 Action Command .......................................................................................................................................... 180 24.13 TAG SYSTEM INFORMATION .......................................................................................................................... 181 24.13.1 AT$TAGSYSINFO ............................................................................................................................ 181 Action Command .......................................................................................................................................... 181 24.14 TAG LIST ALL .............................................................................................................................................. 182 24.14.1 AT$TAGLISTALL .............................................................................................................................. 182 Action Command .......................................................................................................................................... 182 24.15 TAG CREATE ............................................................................................................................................... 182 24.15.1 AT$TAGCREATE ............................................................................................................................. 183 Action Command .......................................................................................................................................... 183 Read Command ............................................................................................................................................ 183 Examples ...................................................................................................................................................... 184 24.16 TAG DOWNLOAD.......................................................................................................................................... 184 24.16.1 AT$TAGDOWNLOADFTP and AT$TAGDOWNLOADHTTP ........................................................... 185 Action Command .......................................................................................................................................... 185 Read Command ............................................................................................................................................ 186 Examples ...................................................................................................................................................... 187 24.16.2 Firmware Upgrade (FOTA) ............................................................................................................... 188 Example ........................................................................................................................................................ 188 24.17 TAG UPLOAD .............................................................................................................................................. 188 24.17.1 AT$TAGUPLOADFTP and AT$TAGUPLOADHTTP ........................................................................ 189 Action Command .......................................................................................................................................... 189 Read Command ............................................................................................................................................ 189 Examples ...................................................................................................................................................... 191 25 GPIO .................................................................................................................................................................. 191 25.1 25.2 25.3 EVENTS ........................................................................................................................................................ 192 STRING TOKENS ............................................................................................................................................ 192 AT$GPIOCONFIG ...................................................................................................................................... 192 x 25.3.1 Action Command ................................................................................................................................ 192 25.3.2 Read Command.................................................................................................................................. 193 25.4 AT$GPIOREAD .......................................................................................................................................... 194 25.4.1 Action Command ................................................................................................................................ 194 25.4.2 Read Command.................................................................................................................................. 194 25.5 AT$GPIOWRITE ........................................................................................................................................ 194 25.5.1 Action Command ................................................................................................................................ 194 25.5.2 Read Command.................................................................................................................................. 195 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 26.3.1 Action Command/Response ............................................................................................................... 198 26.3.2 Read Command/Response ................................................................................................................ 198 26.3.3 Test Command/Response .................................................................................................................. 198 26.3.4 Unsolicited response .......................................................................................................................... 198 26.4 AT$CALLSTART ........................................................................................................................................ 199 26.4.1 Action Command/Response ............................................................................................................... 199 26.4.2 Read Command/Response ................................................................................................................ 199 26.4.3................................................................................................................................................................. 200 26.5 AT$CALLANSWER .................................................................................................................................... 200 26.5.1 Action Command/Response ............................................................................................................... 201 26.5.2 Read Command/Response ................................................................................................................ 201 26.5.3................................................................................................................................................................. 201 26.6 AT$CALLHANGUP ..................................................................................................................................... 202 26.6.1 Action Command/Response ............................................................................................................... 202 26.6.2 Read Command/Response ................................................................................................................ 202 26.6.3................................................................................................................................................................. 202 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 27.3.1 Action Command/Response ............................................................................................................... 206 27.3.2 Read Command/Response ................................................................................................................ 206 27.4 AT$DTMFDETECT ..................................................................................................................................... 207 27.4.1 Action Command/Response ............................................................................................................... 208 27.4.2 Read Command/Response ................................................................................................................ 208 27.4.3 Unsolicited Response ......................................................................................................................... 208 27.5 DTMF TONE EXAMPLES ................................................................................................................................. 209 28 GPS TRACKING ................................................................................................................................................ 210 28.1 OVERVIEW .................................................................................................................................................... 210 28.2 GPS EVENTS................................................................................................................................................ 210 28.3 SYSTEM VARIABLES ....................................................................................................................................... 210 28.3.1 Example .............................................................................................................................................. 211 28.4 STRING TOKENS ............................................................................................................................................ 211 28.5 GPS CONFIGURATION ................................................................................................................................... 212 28.5.1 AT$GPS.............................................................................................................................................. 212 Action Command .......................................................................................................................................... 212 Read Command ............................................................................................................................................ 212 28.6 LOCATION MONITORING ................................................................................................................................. 213 28.6.1 AT$LOCATE ....................................................................................................................................... 213 Action Command .......................................................................................................................................... 213 xi Read Command ............................................................................................................................................ 214 Unsolicited Response ................................................................................................................................... 214 28.7 EXTENDED LOCATION MONITORING ................................................................................................................. 215 28.7.1 AT$LOCATEEXT ................................................................................................................................ 215 Action Command .......................................................................................................................................... 215 Read Command ............................................................................................................................................ 215 28.8 NMEA OUTPUT ............................................................................................................................................ 216 28.8.1 AT$NMEA ........................................................................................................................................... 216 Action Command .......................................................................................................................................... 216 Read Command ............................................................................................................................................ 216 28.9 GEOFENCE CONTROL ................................................................................................................................ 217 28.9.1 AT$GEOFENCE ................................................................................................................................. 217 Action Command .......................................................................................................................................... 217 Read Command ............................................................................................................................................ 218 Unsolicited Response ................................................................................................................................... 218 28.10 SPEED MONITORING .................................................................................................................................. 218 28.10.1 AT$SPEED ....................................................................................................................................... 219 Action Command .......................................................................................................................................... 219 Read Command ............................................................................................................................................ 219 29 CONFIGURATION SYSTEM ............................................................................................................................. 220 29.1 29.2 30 FIRMWARE AND SOFTWARE UPDATES ....................................................................................................... 221 30.1 30.2 31 OVERVIEW .................................................................................................................................................... 220 AT$CONFIG ............................................................................................................................................... 220 DOWNLOADING MODEM FIRMWARE .................................................................................................................. 221 DOWNLOADING APPLICATION SOFTWARE .......................................................................................................... 221 APPENDIX A – STATUS CODES ..................................................................................................................... 222 31.1 31.2PARAMETER .................................................................................................................................. 222 STANDARD CME ERRORS .............................................................................................................................. 224 xii 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 ADC APN ASCII DHCP DNS FOTA GPRS IP NAT NVM PDP SMS TCP UDP USB WD Description A to D Converter Access Point Name American Standard Code for Information Interchange Dynamic Host Configuration Protocol Domain Name System Firmware Upgrade Over The Air General Packet Radio Service Internet Protocol Network Address Translator Non-Volatile Memory (Flash) Packet Data Protocol Short Message Service Transmission Control Protocol User Datagram Protocol Universal Serial Bus 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. 13 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. 14 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). 2.2.1 Mobile Originated 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. 2.2.2 Mobile Originated with SMS wake up (Server initiated) 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. 15 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. 16 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. 17 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,” ” 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: " ",0,"203.0.113.1" OK 18 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”. 19 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. 20 4.3 ASCII Command/Response Types The following table defines the AT command based messages. Type Events AT$EVENTLABEL AT$EVENTDISPLAY AT$EVENTFILTER Description AT$EVENTSEQUENCE AT$EVENTGEN Encode and decode Event Labels Display events when they are generated Configure a list of events to subscribe to for use in other event capable commands Define a list of events to match to trigger a sequence event. Used to generate system or user defined events manually Identification AT$APPVERSION AT$FWVERSION AT$MODEMID AT$SUBSCRIBERID AT$DEVICEID AT$FEATURE Get the application and hardware version Get the modem firmware version Return the modem ID, usually the IMEI Return the subscriber ID, usually the IMSI Set and Get the Device Id Gets the build features Time AT$TIME AT$AUTOTIME AT$TIMERSTART AT$TIMERSTOP AT$ALARMCLOCK Set and Get the current time Set and Get the Autotime Mode Start a timer Stop a timer Configure or delete an alarm Device Control AT$SMSFORWARD AT$RESET AT$REPORT AT$LOWPOWERON AT$LOWPOWEROFF Set and Get SMS Forward Mode Reset the device Configures which unsolicited reports are generated by the device and report various device statuses Enable low power mode Disable low power mode Communications AT$CGDCONT AT$IP AT$PING Set and Get PDP context Returns the network IP address of the device Allows a device to ping a remote server Ethernet AT$ENABLEETHERNET AT$ETHERNETIP AT$DHCPS AT$STATICIP Enable/Disable the Ethernet interface Returns the Ethernet IP address of the device Set and Get DHCP settings for Ethernet Interface Set and Get static IP for Ethernet Interface 21 Type AT$DHCPDNS Description Set and get DNS settings for the DHCP server Endpoint / Bridge AT$ENDPOINT AT$BRIDGECREATE AT$BRIDGEDELETE AT$ONLINE AT$EPWRITE AT$EPREAD Set and Get Endpoint used for “Pass through” routing Query or Connect 2 endpoints completing a “Pass through” route Define or query bridge DELETE parameters. Return serial endpoint to online data mode. Write data to an Offline Data Mode Endpoint Read data from an Offline Data Mode Endpoint Email AT$ESERVER AT$EMAILHDR Define and query Endpoint Server settings Define and query Email Header settings Remote AT Commands AT$TELNETPORT AT$SMS Set and Get telnet port used for AT Set and Get SMS AT command configuration FTP Commands AT$FTPOPEN AT$FTPCLOSE AT$FTPMKDIR AT$FTPCWD AT$FTPDELDIR AT$FTPDEL AT$FTPREN Open an FTP session. Close an FTP session. Make a directory. Change working directory. Delete a directory. Delete a file. Rename a file. Tag File System AT$TAGFORMAT AT$TAGRECOMPACT AT$TAGINSTALL AT$TAGDELETE AT$TAGCREATE AT$TAGWRITE AT$TAGCLOSE AT$TAGREAD AT$TAGSYSINFO AT$TAGLISTALL AT$TAGDOWNLOADFTP AT$TAGDOWNLOADHTTP AT$TAGUPLOADFTP AT$TAGUPLOADHTTP Format the Tag file system. Recompact the FLASH containing the Tag file system. Install a Tag file as either new cellular modem firmware or software application. Delete a Tag. Create an empty tag file. Write data to a Tag. Close a Tag file. Read data from a Tag. Display system information on Tag file system. List all Tag files in the file system. Download from FTP server to tag file. Download from HTTP server to tag file. Upload from tag file to FTP server. Upload from tag file to HTTP server. GPIO AT$GPIOCONFIG Allocate, deallocate, save and delete from flash and view the 22 Type AT$GPIOREAD AT$GPIOWRITE AT$GPIOACTION AT$GPIOACTIONMULTI Description status and capabilities of GPIOs Read one or more GPIOs Write to one or more GPIOs Allow multiple events to operate on one GPIO Allow multiple GPIOs to be manipulated by one event. GPS Tracking AT$LOCATE AT$GEOFENCE AT$SPEED AT$LOCATEEXT Set unsolicited locate time and get current location Set and get parameters for Geofence tracking Set and get speed settings and status Set and get extended location filter assignments SENSOR AT$SENSORCONFIG AT$SENSORCALIBRATE AT$SENSORTRIGGER AT$SENSORREAD Define a sensor driver. Define a calibration table for a sensor channel. Define trigger events for reading a sensor channel. Read a sensor channel. Config System AT$CONFIG Set and get configuration settings System Variables AT$VARIABLETHRESHOLD AT$VARIABLECOMPARE AT$VARIABLESET AT$VARIABLESEND Configure a variable threshold. Configure a variable comparison. Configure a variable to be modified. Send a variable to an endpoint. 23 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 system %% CR CRLF HT LF FILL lowpwr time year month monthname day dow downame hourint hourus ampm Description Insert a single percent sign Carriage return (default count=1) Carriage return, line feed (default count=1) Horizontal tab (default count=1) Line feed (default count=1) Fill string with characters (default count=1) Low power mode (0=disabled, 1=enabled) Year (4 digits) Month Month name Day of the month Day of the week (1=Sun, 7=Sat) Day of the week name Hour in 24 hour format Hour in 12 hour format AM or PM Prefix # Postfix # – count count count count count – – – – – – character – Min width Min width – Min width Min width – Min width Min width – counter counter counter counter counter counter counter counter counter 24 Name minute second Description Minutes (2 digits) Seconds (2 digits) Prefix # – – Postfix # counter counter identification mfg model subid modemid deviceid modulefirmver appver platver hwver projname features Modem manufacturer Modem model Subscriber Id Modem id Device id Modem firmware version Software application version Software platform version Modem hardware version Name of the project build. Feature bitmap in hex. – – – – – – – – – – – – – – – – – – – – – – counter counter nvcounter General purpose counter. N=1-20 General purpose NVM counter. N=1-20 – – N N gpio gpio Status of GPIO pin – pin endpoint epbyteswritten eptransactions epbytesread Bytes written to endpoint X buffer Transactions written to endpoint X buffer Bytes written to endpoint X buffer – – – X X X telnet Telnet server status. 0=off, 1=on, 2=client connected tcpserver – – – – udpserver TCP server status. 0=off, 1=on, 2=client connected UDP server status. 0=off, 1=on – – ethernet etheron etherlink gatewayip Ethernet on (0-1) Ethernet link status (cable connected) Static IP address of the local ethernet interface – – – – – – network apn sig wanip Access Point Name for Context ID (1-4) Signal strength IP address from the cellular network – – – ID – – ip tag 25 Name Description tagmemtotal tagmemdel tagmemfree tagrecompact Tag memory total bytes Tag memory deleted bytes Tag memory free bytes Tag recompact flag. 1=Recompact on next reset. Prefix # – – – – Postfix # – – – – Decimal places Decimal places Decimal places Decimal places Decimal places Decimal places Decimal places – – – – – – – – – – gps longitudeF GPS longitude, Float format Min width latitudeF GPS latitude, Float format Min width speedF GPS speed, Float format Min width headingF GPS heading, Float format Min width altitudeF GPS altitude, Float format Min width accuracyF GPS accuracy, Float format Min width mileageF GPS miles between updates, Float format Min width latitude longitude heading speed altitude numsat accuracy mileage odometer fixtime Latitude (deg*1000000) Longitude (deg*1000000) Heading (deg*10) Current speed (mph*10) Altitude (feet*10) Number of GPS satellites Accuracy (miles*1000000) Miles between updates (*1000) Accumulated miles *1000 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 Started Done EventId Description 1 A STRINGSEND transfer has started. 2 A STRINGSEND transfer has completed. 26 Error Aborted 3 4 A STRINGSEND transfer encountered an error. A STRINGSEND transfer was aborted. 5.2 AT$STRINGTOKENS This Command enables or disables the string token processing, and lists all string tokens. 5.2.1 Action Command The following shows the command (in bold) to enable or disable string token processing. AT$STRINGTOKENS= $STRINGTOKENS: ” ”, (OK | ERROR) 5.2.2 Read Command The following shows the command (in bold) to list all string tokens with a brief description. AT$STRINGTOKENS? $STRINGTOKENS: ” ”, , $STRINGTOKENS: ” ”, ,%name%,”Description” …...(list of all string tokens) (OK | ERROR) Parameters Parameter Description The ID of the modem. The status of the command. 0 – Disable processing 1 – Enable processing 0 1050 Description Success Invalid . 5.3 AT$STRINGTEST 27 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. 5.3.1 Action Command The following shows the command (in bold) to test a string. AT$STRINGTEST=" " $STRINGTOKENS: ” ”, ,” ” (OK | ERROR) Parameters Parameter Description The ID of the modem. The status of the command. 0 1050 Description Success Invalid string 5.3.2 Example AT$STRINGTEST="Current date and time: %hourus%:%minute%:%second% %ampm%" %downame% %month%/%day%/%year% $STRINGTEST: "327004000672",0,"Current date and time: 5:38:36 PM" Wednesday 6/20/2012 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. 5.4.1 Action Command The following shows the command (in bold) to send a string. 28 AT$STRINGSENDEMAIL= , , ," " [, [, [, [..., ]]]] $STRINGSENDEMAIL: ” ”, (OK | ERROR) The above command response indicates the status of the command and its parameters. If successful, then when triggered by an , a connection will be established with the SMTP email server, and the will be sent. Unsolicited messages will be output to indicate the progress: $STRINGSENDEMAIL: ” ”, ,< strSendId >, To delete a STRINGSENDEMAIL Id, enter the command with the StringSend Id as the only parameter: AT$STRINGSENDEMAIL=< strSendId > 5.4.2 Read Command The following shows the command (in bold) to query the STRINGSENDEMAIL settings. AT$STRINGSENDEMAIL? $STRINGSENDEMAIL: ” ”, , , , , " ", , , ..., …...(list of all valid records) (OK | ERROR) Parameters Parameter emailHdrId Description The ID of the modem. The status of the command. StringSendEmail identifier (1-20). Endpoint Server Id. The Eserver contains the SMTP server’s IP address, and optional port, username, and password. Email Header Id. The Email header contains the sender and recipient information. The body of the email, which may contain string tokens. The tokens will be evaluated when the email transfer is triggered to begin. 29 0 1050 1052 1055 1056 1100 Not currently supported. Tag file to be attached to the email. Not currently supported. Type of compression performed on the tag file before attaching to the email: 0 = None (default) 1 = zlib 2 = bzip 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. Status of the transfer process: 1 = Transfer has started. 2 = Email was sent successfully. 3 = An error was encountered. 4 = Transfer was aborted. Description Success Invalid StringSend Id Already in use Invalid Eserver Id Invalid EmailHdr Id Invalid Tag Id 5.4.3 Example The following example sets up StringSendEmail Id 3 to send an email when timer 1 expires. The 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" 30 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. 5.5.1 Action Command The following shows the command (in bold) to send a string. AT$STRINGSENDSMS= ," "," "[, [..., ]] $STRINGSENDSMS: ” ”, (OK | ERROR) The above command response indicates the status of the command and its parameters. If successful, then when triggered by an , the will be sent. Unsolicited messages will be output to indicate the progress: 31 $STRINGSENDSMS: ” ”, , , To delete a STRINGSENDSMS Id, enter the command with the StringSend Id as the only parameter: AT$STRINGSENDSMS= 5.5.2 Read Command The following shows the command (in bold) to query the STRINGSENDSMS settings. AT$STRINGSENDSMS? $STRINGSENDSMS: ” ”, , , ," ", ..., …...(list of all valid records) (OK | ERROR) Parameters Parameter Description The ID of the modem. The status of the command. StringSendSms identifier (1-20). SMS Phone Number. This number must be a valid destination phone number. The content of the SMS message, which may contain string tokens. The tokens will be evaluated when the message is sent. 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. Status of the transfer process: 1 = Transfer has started. 2 = SMS was sent successfully. 3 = An error was encountered. 4 = Transfer was aborted. Description 32 0 1050 1052 Success Invalid StringSend Id Already in use 5.5.3 Example The following example sets up StringSendSms Id 2 to send an SMS when timer 1 expires. The 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. 5.6.1 Action Command The following shows the command (in bold) to send a string. AT$STRINGSEND= , ," "[, [..., ]] $STRINGSEND: ” ”, (OK | ERROR) 33 The above command response indicates the status of the command and its parameters. If successful, then when triggered by an , the will be sent to the specified endpoint. Unsolicited messages will be output to indicate the progress: $STRINGSEND: ” ”, ,< strSendId >, To delete a STRINGSEND Id, enter the command with the StringSend Id as the only parameter: AT$STRINGSEND=< strSendId > 5.6.2 Read Command The following shows the command (in bold) to query the STRINGSEND settings. AT$STRINGSEND? $STRINGSEND: ” ”, , , ," ", ..., …...(list of all valid records) (OK | ERROR) Parameters Parameter Description The ID of the modem. The status of the command. StringSend identifier (1-20). Endpoint Id. This endpoint must already exist. The string to be sent, which may contain string tokens. The tokens will be evaluated when the message is sent. 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. Status of the transfer process: 1 = Transfer has started. 2 = String was sent successfully. 3 = An error was encountered. 4 = Transfer was aborted. Description 34 0 1050 1052 1090 1091 Success Invalid StringSend Id Already in use Invalid Endpoint Id Endpoint Id out of range 5.6.3 Example 1: Send Email 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 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 5.6.4 Example 2: Serial to TCP Endpoint Connection 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 for endpoint 6 Open is 00650101 (see section 15.1.2). 35 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 36 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 varthreshold varcompare Description Current state of the requested variable threshold Current state of the requested variable comparison Prefix # – Postfix # thresholdId– – 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 SENT EventType System ObjectId sendId EventId Description 1 Variables were sent. 37 SEND ERROR THRESHOLD_FALSE THRESHOLD_TRUE COMPARE_FALSE COMPARE_TRUE Variable System Variable System Variable System Variable System Variable System Variable sendId 2 thresholdId 3 An error occurred during send. Threshold became false. thresholdId 4 Threshold became true. compareId 5 Compare became false. compareId 6 Compare became true. STATUS_CHANGED variableId 128 CONFIG_CHANGED variableId 129 Status variable was modified. 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 Name Description (hex) endpoint 005A00+X epbyteswrittenX Bytes written to endpoint X 005B00+X eptransactionsX Transactions written to endpoint X 005C00+X epbytesreadX Bytes read from endpoint X gpio gpio Status of GPIO pin ip 003401 telnet Telnet server status. 0=off, 1=on, 2=client connected 003402 tcpserver TCP server status. 0=off, 1=on, 2=client connected 003403 udpserver UDP server status. 0=off, 1=on ethernet 003501 etherlink Ethernet link status (cable connected) network 003201 sig Signal strength counter 001000 + counterN General purpose counter. N=1N 20 nonVolatile autoUpdt – – yes yes – yes yes yes yes yes yes 38 Identifier (hex) 001014 + N tag 000C01 000C02 000C03 000C04 Name Description nvcounterN Non-volatile counter. N=1-15 tagmemtotal tagmemdel tagmemfree tagrecompact Tag memory total bytes Tag memory deleted bytes Tag memory free bytes Tag recompact flag. 1=Recompact on next reset. gps 00C801 00C802 00C803 00C804 00C805 00C806 00C807 00C808 00C809 00C80A longitude latitude heading speed altitude numsat accuracy mileage odometer fixtime Longitude (deg*1000000) Latitude (deg*1000000) Heading (deg*10) Current speed (mph*10) Altitude (feet*10) Number of GPS satellites Accuracy (miles*1000000) Miles between updates (*1000) Accumulated miles * 1000 Fix time, secs since 1/1/1970 (unsigned) sensor 0087MN sensorX The current sensor channel reading for sensor M, channel N. X=(M*16)+N nonVolatile autoUpdt yes Yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes 6.5 AT$VARIABLESTATUS This AT command displays a listing of all status variables in the system. 6.5.1 Read Command The following shows the command (in bold) to query all status variables. AT$VARIABLESTATUS? $VARIABLESTATUS: ” ”, , ,” ”, ” ”, , , , …...(list of all valid records) (OK | ERROR) Parameters Parameter Description 39 The ID of the modem. The status of the command. 0 = Success Variable identifier Short ASCII name for the variable. Brief description of the variable. 1 = Saved in NVM. 0 = Not saved in NVM 1 = Updated automatically. 0 = Not updated automatically. Number of readings in rolling average. 0 – No averaging. 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. 6.6.1 Set Command The following shows the command (in bold) to configure a variable threshold. AT$VARIABLETHRESHOLD= , , , [, ] $VARIABLETHRESHOLD: ” ”, (OK | ERROR) 6.6.2 Delete Command If is the only parameter given, the threshold is deleted. AT$VARIABLETHRESHOLD= $VARIABLETHRESHOLD: ” ”, (OK | ERROR) 6.6.3 Read Command The following shows the command (in bold) to query all variable thresholds. AT$VARIABLETHRESHOLD? 40 $VARIABLETHRESHOLD: ” ”, , , , , , , …...(list of all valid records) (OK | ERROR) Parameters Parameter Description The ID of the modem. The status of the command. 0 = Success Threshold identifier Variable identifier Threshold value to be compared with the variable Type of comparison: 1 – Variable < Threshold 2 – Variable <= Threshold 3 – Variable = Threshold 4 – Variable >= Threshold 5 – Variable > Threshold 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. 1 = The comparison is true. 0 = false 6.6.4 Example 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. 41 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. 6.7.1 Set Command The following shows the command (in bold) to configure a variable comparison. AT$VARIABLECOMPARE= , , , [, ] $VARIABLECOMPARE: ” ”, (OK | ERROR) 6.7.2 Delete Command If is the only parameter given, the comparison is deleted. AT$VARIABLECOMPARE= $VARIABLECOMPARE: ” ”, (OK | ERROR) 6.7.3 Read Command The following shows the command (in bold) to query all variable comparisons. AT$VARIABLECOMPARE? $VARIABLECOMPARE: ” ”, , , , , , , …...(list of all valid records) (OK | ERROR) Parameters Parameter Description The ID of the modem. The status of the command. 0 = Success Comparison identifier First variable identifier Second variable identifier Type of comparison: 1 – Variable1 < Variable2 2 – Variable1 <= Variable2 3 – Variable1 = Variable2 42 4 – Variable1 >= Variable2 5 – Variable1 > Variable2 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. 1 = The comparison is true. 0 = false 6.7.4 Example 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. 6.8.1 Set Command The following shows the command (in bold) to configure a variable update. AT$VARIABLESET= , , , [, […, ]] $VARIABLESET: ” ”, (OK | ERROR) 6.8.2 Delete Command If is the only parameter given, the update object is deleted. AT$VARIABLESET= $VARIABLESET: ” ”, (OK | ERROR) 43 6.8.3 Read Command The following shows the command (in bold) to query all update objects. AT$VARIABLESET? $VARIABLESET: ” ”, , , , , , …, …...(list of all valid records) (OK | ERROR) Parameters Parameter Description The ID of the modem. The status of the command. 0 = Success Set identifier Variable identifier in hex. Operation to perform on the variable: 1 = Set to the 2 = Add 3 = Subtract 4 = Multiply by 5 = Divide by 6 = Mod by 7 = AND with 8 = OR with 9 = XOR with 10 = NOT ( is ignored) Values 11-20 are the same as above, except the 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 ( is ignored) 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 in hex. This defines the event(s) that trigger the 44 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. 6.8.4 Example 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 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. 6.9.1 Set Command The following shows the command (in bold) to configure a variable send object. AT$VARIABLESEND= , , , , […, ] 45 $VARIABLESEND: ” ”, (OK | ERROR) The above command response indicates the status of the command and its parameters. If successful, then when triggered by the , the list will be sent to the specified endpoint. An unsolicited message will be output to indicate the status: $VARIABLESEND: ” ”, , , 6.9.2 Delete Command If is the only parameter given, the send object is deleted. AT$VARIABLESEND= $VARIABLESEND: ” ”, (OK | ERROR) 6.9.3 Read Command The following shows the command (in bold) to query all variable send objects. AT$VARIABLESEND? $VARIABLESEND: ” ”, ,