OptConnect ema™ AT Command Manual Datasheet

MANAGED WIRELESS SOLUTIONS
OptConnect ema™
emaLink
AT Command Manual
V1.3 Updated May 2020
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
2
Table of Contents
Table of Contents 2
1. Introduction 4
1.1 Scope 4
1.2 Contact Information 4
1.1 Orderable Part Numbers 4
1.2 Additional Resources 5
1.3 Definitions 5
2. AT Command Formatting 5
2.1 Overview 5
2.2 ERROR Formatting 5
2.3 Response Formatting 6
2.4 Sending AT Commands 6
3. AT Commands 6
3.1 Starting A Command Line – AT 6
3.2 Command Echo - E 6
3.3 Available AT Commands - +CLAC 7
3.4 Serial Number - +GSN 7
3.5 Board ID - +OCBID 8
3.6 Firmware Version - +GMR 9
3.7 Extended Firmware Information - ATI 9
3.8 Glimpse - +OCGLIMPSE 11
4. Unsolicited Response Code (URC) Formatting 14
4.1 Overview 14
4.2 URC Formatting 14
5. Unsolicited Response Codes 14
5.1 ema AT Interface Ready 14
5.2 Cellular Module Powering ON 14
5.3 Cellular Module Ready for Use 15
5.4 Cellular Module Powering OFF 15
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
3
5.5 Cellular Module Powered OFF 15
5.6 ema Rebooting now 16
5.7 ema Rebooting in 60 seconds 16
5.8 Establishing Modem UART Interface 16
5.9 Establishing USB Interface 17
5.10 Removing Modem UART Interface 17
5.11 Removing USB Interface 18
5.12 Cellular Module Reset Requested 18
5.13 Cellular Module Resetting 18
5.14 Cellular Module Reset 19
5.15 Cellular Module Reset Not Observed 19
5.16 microFOTA Download Starting 19
5.17 microFOTA Download Complete 20
5.18 microFOTA Download Failed 20
5.19 Cellular Module FOTA Pending 20
5.20 Cellular Module FOTA Starting 21
5.21 Cellular Module FOTA Complete 21
5.22 Cellular Module FOTA Failed 21
5.23 Administrative Activity Pending 22
5.24 Administrative Activity Starting 22
5.25 Administrative Activity Complete 22
5.26 Board Notify 23
5.27 Sample URC Sequence Outputs 24
5.27.1 microFOTA 24
5.27.2 ema Powered ON 24
5.27.3 ema Cellular Module Turned ON 25
5.27.4 ema Cellular Module Turned OFF 25
5.27.5 ema Cellular Module Reset 25
5.27.6 ema Board Notify 26
6. Revision History 27
.0ptConnect FDD B2, B4, AT&T, FDD B2, B4, AT&T, FDD B2, B4, AT&T, FDD B2, B4, AT&T, emazPlay Evaluation Kit, OptConnect ema'“ evaluation emazPlay Evaluation Kit, OptConnect ema'“ evaluation emazPlay Evaluation Kit, OptConnect ema'“ evaluation
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
4
1. Introduction
1.1 Scope
This document serves as a guide for the usage of AT commands on the OptConnect emaLink interface.
The electrical specification for the emaLink interface is a standard Universal Asynchronous
Receiver/Transmitter (UART). This interface is available at pins 17 (ema_DOUT) and 18 (ema_DIN) of the
OptConnect ema™ modem.
1.2 Contact Information
For more information regarding OptConnect ema™ contact OptConnect Sales at 1.877.678.3343 ext. 2020
during normal business hours. For technical support contact OptConnect Customer Care Center at
1.877.678-3343 ext. 2021 from 8 am till 9 pm MST Monday through Saturday.
1.1 Orderable Part Numbers
Orderable Device
Primary
Module
Firmware
Revision
Operating
Temperature
LTE Bands
3G
UMTS
Network
EMA-L4-1-XX-A-A
20.00.505
-40 to +85˚C
FDD B2, B4,
B5, B12, B13
B2, B5
AT&T,
Verizon
EMA-L4-1-US-B-A
20.00.005
-40 to +85˚C
FDD B2, B4,
B5, B12, B13
B2, B5
AT&T,
Verizon
EMA-L4-1-XX-A-A-000
20.00.506
-40 to +85˚C
FDD B2, B4,
B5, B12, B13
B2, B5
AT&T,
Verizon
EMA-L4-1-US-B-A-000
20.00.006
-40 to +85˚C
FDD B2, B4,
B5, B12, B13
B2, B5
AT&T,
Verizon
Unless instructed otherwise EMA-L4-1-XX… will utilize AT&T as the primary carrier and Verizon as the
secondary carrier. Unless instructed otherwise, EMA-L4-1-US… will utilize Verizon as the primary carrier and
AT&T as the secondary carrier.
Orderable
Device
Description
Operating
Temperature
EMA-ZZ-1-XX-Z-B
ema:Play Evaluation Kit, OptConnect ema™ evaluation
platform
-40 to +85˚C
EMA-L4-1-XX-A-B
ema:Play Evaluation Kit, OptConnect ema™ evaluation
platform, EMA-L4-1-XX ema modem included
-40 to +85˚C
EMA-L4-1-US-B-B
ema:Play Evaluation Kit, OptConnect ema™ evaluation
platform, ema EMA-L4-1-US ema modem included
-40 to +85˚C
ERROR: 0, Unknown command .0piQonnect An invalid, unknown, or unsupported AT command ERROR: 1, Invalid format otherwise The AT command was recognized, but was
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
5
1.2 Additional Resources
OptConnect ema™ is supported by a full range of documentation in addition to this Manual; including
User Guides and Application Notes as well as an ema:Play Evaluation Kit User Guide and related code
samples. The latest versions of these resources can be found at http://optconnect.com/ema .
1.3 Definitions
For consistency, the AT Command interface outlined in this manual follows closely to the same definitions
as Telit's AT command definitions. Please reference Section 3.1 of the Telit LE910-V2 Series AT Commands
Reference Guide for more information.
2. AT Command Formatting
2.1 Overview
The OptConnect ema™ modem uses the emaLink interface for interacting with the Management
Microcontroller Unit (MCU). This allows the host to interact with ema using AT commands. This interface is
also reserved for future feature support.
This interface also allows ema to notify the host of various events that may be occurring and of any
actions that are in progress. The format for these notifications is an Unsolicited Result Code (URC).
2.2 ERROR Formatting
Any AT command that results in an Error response follows the following format:
ERROR: <n>, <str>
where <n> is a zero-index integer, and <str> is a verbose output message. This allows the host to
consider the verbose message when doing initial development, and parse the integer value for
processing.
Possible ERROR Messages
Message
Description
ERROR: 0, Unknown command
An invalid, unknown, or unsupported AT command
was entered.
ERROR: 1, Invalid format otherwise
The AT command was recognized, but was
improperly formatted or is missing required
arguments.
.thQonnect AT AT is the prefix for all commands. Used alone, it is a test Response OK if successful, okherwise Example AT ATE[] Set command enables/disables the command echo.
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
6
2.3 Response Formatting
If an AT command is successfully accepted and processed, the response will be in the following format:
<CR><LF>OK<CR><LF>
If an error occurs, the error response will be in the following format:
<CR><LF>ERROR: <n>, <str><CR><LF>
2.4 Sending AT Commands
All AT commands need to be terminated with:
<CR>
It is not necessary to send both:
<CR><LF>
The UART communication settings for the emaLink interface are 19200 8N1. This is not configurable at
the release of this document.
3. AT Commands
3.1 Starting A Command Line – AT
Starting A Command Line – Used to verify successful communication with ema.
AT
AT is the prefix for all commands. Used alone, it is a test
command to verify communications are established.
Response
OK if successful, otherwise
ERROR: 0, Unknown command
Example
AT
OK
3.2 Command Echo - E
Command Echo – Used to enable or disable echo.
ATE[<n>]
Set command enables/disables the command echo.
Parameter:
.thQonnect Response OK if successful, otherwise Examples ATE1 AT+CLAC Lists available AT commands in the format: Response OK if successful, otherwise Example AT+CLAC 7
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
7
<n>
0 - Disables command echo
1 - Enables command echo (default). Each byte of the AT
command will be echoed back in real time.
Response
OK if successful, otherwise
ERROR: 1, Invalid Format
Examples
ATE1
OK
ATE?
ERROR: 1, Invalid format
3.3 Available AT Commands - +CLAC
List Available AT Commands – Used to list all supported AT commands.
AT+CLAC
Lists available AT commands in the format:
<AT cmd1>
<AT cmd2>
<AT cmd3>
<AT cmdn>
OK
where <AT cmdn> is an available AT command.
Response
OK if successful, otherwise
ERROR: 1, Invalid Format
Example
AT+CLAC
AT+OCBID
ATE
AT+CLAC
AT+GSN
AT
OK
3.4 Serial Number - +GSN
Get Serial Number – Used to get the ema serial number.
.QPFQO'W‘??? AT+GSN Get command that returns the ema serial number in the Response OK if successful, otherwise Example AT+GSN AT+OCBID="" Set command to specify the Board ID. This is a custom ID that AT+0CBID? Get command returns the current Board ID that is stored in
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
8
AT+GSN
Get command that returns the ema serial number in the
format:
<SERIAL#>
ema-n19834e60001
OK
Max length of serial number = 16
Response
OK if successful, otherwise
ERROR: 1, Invalid Format
Example
AT+GSN
ema-n19834e60001
OK
3.5 Board ID - +OCBID
Get/Set Board ID – Used to set and get the Board ID.
AT+OCBID="<bid>"
Set command to specify the Board ID. This is a custom ID that
can be used by the host for identification purposes.
Parameter:
<bid> - Board ID string. Valid characters are alphanumeric
characters only (A-Z, a-z, 0-9).
Note: Any non-alphanumeric characters, including spaces, will
be replaced by a dash (-).
Note: Any <bid> entries longer than 64 bytes will be truncated
to 64 bytes.
Note: This value is saved to ema’s non-volatile memory (NVM).
Note: Subsequent uses of this command will overwrite the
current Board ID. To clear out the current Board ID, you can
issue AT+OCBID="" (empty string, no spaces between
quotation marks).
AT+OCBID?
Get command returns the current Board ID that is stored in
ema’s NVM in the format:
+OCBID: "<bid>"
.thQonnect AT+OCBID=? Test command retums the formatting information for this Response OK if successful, otherwise Example AT+0CBID="0ptConnect ema" AT+GMR Get command to get the ema MCU firmware version in the Response OK if successful, otherwise Example AT+GMR ATI[] Read command to get ema microcontroller firmware
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
9
OK
AT+OCBID=?
Test command returns the formatting information for this
command in the format:
+OCBID: (64, [a-z 0-9])
OK
Response
OK if successful, otherwise
ERROR: 1, Invalid Format
Example
AT+OCBID="OptConnect ema"
OK
AT+OCBID?
+OCBID: "OptConnect-ema"
OK
3.6 Firmware Version - +GMR
Get Firmware Version – Used to get the current ema firmware version.
AT+GMR
Get command to get the ema MCU firmware version in the
following format:
<FIRMWARE VERSION><CR><LF>
Response
OK if successful, otherwise
ERROR: 1, Invalid Format
Example
AT+GMR
V1.0.0-0-xxx BUILD=dev A
OK
3.7 Extended Firmware Information - ATI
Get Extended Firmware Information – Used to get extended firmware version
information.
ATI[<n>]
Read command to get ema microcontroller firmware
information in the format:
Response OK if successful, otherwise Examples ATI 1O
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
10
<FIRMWARE INFORMATION><CR><LF>
Parameter:
<n>
0 - Full firmware information
1 - Firmware revision
2 - Firmware sub-revision
3 - Firmware hash
4 - Build information
5 - A/B Version used for firmware over the air (FOTA) update
testing
Note: If parameter is omitted, the command has the same
behavior as ATI0.
Response
OK if successful, otherwise
ERROR: 1, Invalid Format
Examples
ATI
V1.0.0-0-xxx BUILD=dev A
OK
ATI1
V1.0.0
OK
ATI2
0
OK
ATI3
xxx
OK
ATI4
BUILD=dev
OK
ATI5
A
AT+0CGLIMPSE[] Read command to get Glimpse information. 11
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
11
OK
3.8 Glimpse - +OCGLIMPSE
OptConnect Glimpse is a powerful feature that allows the local host system to inquire over the emaLink
interface about ema’s management and monitoring activities. Valuable information including, but not
limited to; signal analytics, failover time, primary carrier, active carrier, cellular tower location, etc., can be
queried, without the need to pause or bring down an active cellular data session.
Glimpse query – Used to gather information regarding ema’s management and
monitoring activities.
AT+OCGLIMPSE[<group>]
Read command to get Glimpse information.
Parameter:
<group> - Glimpse group to read. This value is optional. Omit this
parameter to read all groups. Valid values are 1 – 5.
<group> description:
+OCGLIMPSE1: <ema Uptime>, “<ema FW>”, “<Serial Number>”,
“<Model>”
+OCGLIMPSE2: “<Primary Carrier>”, “<Active Carrier>”,
“<Active Firmware>”, “<Reg. status>”, “<Failover Enabled>”,
“<Last Failover Event>”, “<Access Tech.>”
+OCGLIMPSE3: <Cell ID>, <MCC>, <MNC>, <TAC>
+OCGLIMPSE4: <Signal quality>, <Curr. RSSI>, <Curr. RSRQ>,
<Curr. RSRP>, <RSSI Min.>, <RSSI Max.>, <RSSI Avg.>, <RSRQ
Min.>, <RSRQ Max.>, <RSRQ Avg.>, <RSRP Min.>, <RSRP Max.>,
<RSRP Avg.>
+OCGLIMPSE5: “<ema Services State>”
where:
<ema Uptime> - ema uptime(since boot) in seconds
“<ema FW>” - ema firmware version
“<Serial Number>” - ema serial number
“<Model>” - ema model number
"" 7 primary cellular carrier ("AT&T" or "Verizun 12
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
12
“<Primary Carrier>” - primary cellular carrier (“AT&T” or “Verizon
Wireless”), as dictated by the ema Model
“<Active Carrier>” – currently active cellular carrier (“AT&T” or “Verizon
Wireless”)
“<Active Firmware>” – currently active cellular firmware version
“<Reg. Status>” – current cellular registration status:
“Not Registered, Not Searching”
“Registered, Home Network”
“Not Registered, Searching”
“Registration Denied”
“Registration, Roaming”
“Registration Status Unknown”
“<Failover Enabled>” - failover enabled state (“Enabled” or “Disabled”)
<Last Failover Event> - failover timestamp in seconds, relative to <ema
Uptime>
“<Access Tech.>” - currently active cellular access technology:
“GSM”
“UTRAN”
“E-UTRAN”
<Cell ID> - Cellular ID. A value of 0 is unknown.
<MCC> - Mobile country code. A value of 999 is unknown.
<MNC> - Mobile network code. A value of 999 is unknown.
<TAC> - Tracking area code. A value of 0 is unknown.
<Signal Quality> - Signal quality
0 - Unknown
1 - Poor
2 - OK
3 - Good
4 - Excellent
<Curr. RSSI> - Current Received Signal Strength Indicator (RSSI)
<Curr. RSRQ> - Current Reference Signal Received Quality (RSRQ)
<Curr. RSRP> - Current Reference Signal Received Power (RSRP)
<RSSI Min.> - Minimum RSSI since module power on
<RSSI Max.> - Maximum RSSI since module power on
<RSSI Avg.> - Average RSSI since module power on
<RSRQ Min.> - Minimum RSRQ since module power on
<RSRQ Max.> - Maximum RSRQ since module power on
<RSRQ Avg.> - Average RSRQ since module power on
<RSRP Min.> - Minimum RSRP since module power on
<RSRP Max.> - Maximum RSRP since module power on
<RSRP Avg.> - Average RSRP since module power on
<ema Services State> - current connection status to OptConnect
services (“Connected” or “Not Connected”)
Note: When ema is unable to connect to OptConnect services, it will no
longer collect signal information. <Curr. RSSI>, <Curr. RSRQ>, and
awcomect will be 0. Any collected minimum, maximum, and average AT+OCGLIMPSE=? Test command returns the formatting information for this command in Response OK if successful, othenNise Examples AT+OCGLIMPSE 13
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
13
<Curr. RSRP> will be 0. Any collected minimum, maximum, and average
information will remain.
Note: This command may take up to 30 seconds to get a response.
AT+OCGLIMPSE=?
Test command returns the formatting information for this command in
the format:
AT+OCGLIMPSE[1-5]
+OCGLIMPSE1: Ema Uptime, "Ema FW", "Serial Number", "Model"
+OCGLIMPSE2: "Primary Carrier", "Active Carrier", "Active
Firmware", "Reg. Status", "Failover Enabled", Last Failover Event,
"Access Tech."
+OCGLIMPSE3: Cell ID, MCC, MNC, TAC
+OCGLIMPSE4: Signal Quality, Curr. RSSI, Curr. RSRQ, Curr. RSRP,
RSSI Min., RSSI Max., RSSI Avg., RSRQ Min., RSRQ Max., RSRQ Avg.,
RSRP Min., RSRP Max., RSRP Avg.
+OCGLIMPSE5: "Ema Services State"
OK
Response
OK if successful, otherwise
ERROR: 1, Invalid Format
Examples
AT+OCGLIMPSE
+OCGLIMPSE1: 10400, "v1.0.0-0-01234567 BUILD=dev A", "ema-
k1abcdef9999", "EMA-L4-1-XX-A-A"
+OCGLIMPSE2: "AT&T", "AT&T", "20.00.505", "Registered, Home
Network", "Enabled", 8032, "E-UTRAN"
+OCGLIMPSE3: 4E6300A, 310, 410, 17937
+OCGLIMPSE4: 3, -51.00, -6.00, -81.00, -51.00, -51.00, -51.00, -9.50,
-6.00, -7.75, -81.00, -81.00, -81.00
+OCGLIMPSE5: "Connected"
OK
AT+OCGLIMPSE3
+OCGLIMPSE3: 4E6300A, 310, 410, 17937
OK
AT+OCGLIMPSE5
+OCGLIMPSE5: “Connected”
OK
.0thonnect Value Message Description Displays when the ema AT interface is ready for use. This Action Needed Value Message
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
14
4. Unsolicited Response Code (URC) Formatting
4.1 Overview
OptConnect ema™ outputs unsolicited response codes (URCs) on the emaLink interface to notify the user
of various events, or to instruct the user. Failure to observe these URCs may damage the ema MCU or
cellular module.
4.2 URC Formatting
URCs asynchronously appear as an event occurs. URCs have the following format:
<CR><LF>OCURC: <n>, "<str>"<CR><LF>
where <n> is a zero-index integer signified by a value shown in section 5, and <str> is a corresponding
verbose output message signified by a message. This allows the user to view the verbose message when
doing initial development, and parse the integer value when developing on the host system.
5. Unsolicited Response Codes
5.1 ema AT Interface Ready
ema AT Interface Ready – Occurs shortly after power has been applied to pin 1
(VCC). The on-board cellular module may or may not be ON, depending on the
state of pin 20 (ON_OFF). AT commands can now be sent to ema.
Value
0
Message
“ema AT interface ready.”
Description
Displays when the ema AT interface is ready for use. This
occurs once power is applied to ema.
Action Needed
None
5.2 Cellular Module Powering ON
Cellular Module Powering ON – Occurs once ema has started the power on
sequence of the on-board cellular module.
Value
1
Message
“Cellular module powering on.”
.thQonnect Description Displays when the ema ONioFF pin is pulled LOW or during a Action Needed Value Message Description Displays when the cellular module has properly booted and is Action Needed Cellular Module Powering OFF - Occurs once ema has started the powering off Value Message Description Displays when the cellular module is in the process of Action Needed Wait for this URC before removing power. Value Message 15
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
15
Description
Displays when the ema ON_OFF pin is pulled LOW or during a
reboot cycle.
Action Needed
None
5.3 Cellular Module Ready for Use
Cellular Module Ready for Use – Occurs once ema has successfully completed the
power on sequence of the on-board cellular module and the cellular module is
ready for use with the host system.
Value
2
Message
“Cellular module ready for use.”
Description
Displays when the cellular module has properly booted and is
ready for use by the host system.
Action Needed
None
5.4 Cellular Module Powering OFF
Cellular Module Powering OFF – Occurs once ema has started the powering off
sequence of the on-board cellular module.
Value
3
Message
“Cellular module powering off.”
Description
Displays when the cellular module is in the process of
powering off. Note: This could be caused by releasing the
ON_OFF pin, a local reset request, a remote reset request, etc.
Action Needed
Wait for this URC before removing power.
5.5 Cellular Module Powered OFF
Cellular Module Powered OFF – Occurs once ema has successfully completed the
powering off sequence of the on-board cellular module.
Value
4
Message
“Cellular module powered off.”
.thQonnect Description Action Needed Value Message Description Displays immediately before ema and the cellular module Action Needed Value Message Description Warning message displayed 60 seconds before ema and the Action Needed Complete short term (<30 seconds)="" operations="" that="" are="" using="" value="">
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
16
Description
Displays when the cellular module is powered off.
Action Needed
None
5.6 ema Rebooting now
ema Rebooting Now – Occurs immediately before both ema and the on-board
cellular module will reboot.
Value
5
Message
“ema rebooting now.”
Description
Displays immediately before ema and the cellular module
reboots.
Note: Another message(“ema rebooting in 60 seconds.”)
with a time remaining before a reboot occurs will precede this
URC.
Action Needed
Immediately stop all operations that are using ema.
5.7 ema Rebooting in 60 seconds
ema Rebooting in 60 Seconds – Occurs as a warning for the host system,
indicating that both ema and the on-board cellular module will be rebooting
shortly.
Value
6
Message
“ema rebooting in 60 seconds.”
Description
Warning message displayed 60 seconds before ema and the
cellular module reboots.
Action Needed
Complete short term (<30 seconds) operations that are using
ema, and gracefully close any connections.
5.8 Establishing Modem UART Interface
Establishing Cellular UART Interface – Occurs once ema has made the Modem
UART Interface available for use.
Value
7
.thQonnect Message Description Displays when the modem (cellular module) UART interface is Action Needed None Value Message Description Displays when the cellular module USB interface is ready after Action Needed Value Message Description Displays when the modem (cellular module) UART interface is Action Needed Immediately stop all operations that are using this interface
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
17
Message
“Establishing cellular UART interface.”
Description
Displays when the modem (cellular module) UART interface is
ready after being taken down.
Note: Displays after URC (“Removing cellular UART
interface.”).
Action Needed
None
5.9 Establishing USB Interface
Establishing Cellular USB Interface – Occurs once ema has made the USB
interface available for use.
Value
8
Message
“Establishing cellular USB interface.”
Description
Displays when the cellular module USB interface is ready after
being taken down.
Note: Displays after URC (“Removing cellular USB
interface.”).
Action Needed
None
5.10 Removing Modem UART Interface
Removing Cellular UART Interface - Occurs once ema has removed the Modem
UART Interface and it is periodically unavailable for use.
Value
9
Message
“Removing cellular UART interface.”
Description
Displays when the modem (cellular module) UART interface is
periodically not available for use.
Note: The modem UART interface will not be usable until URC
(“Establishing cellular UART interface.”) appears, or pin 13
(STATUS) drives HIGH.
Action Needed
Immediately stop all operations that are using this interface
until it becomes available again.
.thQonnect Value Message Description Displays when the cellular module USB interface is periodically Action Needed Value Message Description Displays when the cellular module pin 5 (nRESETiREQUEST) is Action Needed Value Message Description Displays when the cellular module reset is in progress.
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
18
5.11 Removing USB Interface
Removing Cellular USB Interface – Occurs once ema has removed the USB
Interface and it is periodically unavailable for use.
Value
10
Message
“Removing cellular USB interface.”
Description
Displays when the cellular module USB interface is periodically
not available for use.
Note: The cellular module USB interface will not be usable until
URC (“Establishing cellular USB interface.”) appears, or pin
13 (STATUS) drives HIGH.
Action Needed
None
5.12 Cellular Module Reset Requested
Cellular Module Reset Requested – Occurs once ema has detected a successful
toggle of pin 5 (nRESET_REQUEST) and a reset is pending.
Value
11
Message
“Cellular module reset requested.”
Description
Displays when the cellular module pin 5 (nRESET_REQUEST) is
toggled successfully.
Action Needed
Prepare for a cellular module reboot.
5.13 Cellular Module Resetting
Cellular Module Resetting – Occurs once ema has begun the reset sequence of
the on-board cellular module.
Value
12
Message
“Cellular module resetting.”
Description
Displays when the cellular module reset is in progress.
Note: This URC will follow (“Cellular module reset
requested.”).
.thQonnect Action Needed Value Message Description Displays after the cellular module has reset. Action Needed Value Message Description Displays if ema pin 5 (nRESETiREQUEST) was not held LOW Action Needed Hold pin 5 (nRESETiREQUEST) LOW for at least one (1) second Value Message Description Displays when the microcontroller firmware update over the air
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
19
Action Needed
None
5.14 Cellular Module Reset
Cellular Module Reset – Occurs once ema has completed the reset sequence of
the on-board cellular module.
Value
13
Message
“Cellular module reset.”
Description
Displays after the cellular module has reset.
Note: This URC will follow (“Cellular module resetting.”).
Action Needed
None
5.15 Cellular Module Reset Not Observed
Cellular Reset Pin Time Not observed – Occurs if ema detected that pin 5
(nRESET_REQUEST) was not held LOW long enough and the reset sequence
cannot begin yet.
Value
14
Message
“Cellular reset pin time not observed.”
Description
Displays if ema pin 5 (nRESET_REQUEST) was not held LOW
long enough (>= one (1) second).
Action Needed
Hold pin 5 (nRESET_REQUEST) LOW for at least one (1) second
if a reset is desired.
5.16 microFOTA Download Starting
Microcontroller FOTA Download Starting – Occurs once ema has begun the
process of downloading a new firmware image in the background.
Value
30
Message
“Microcontroller FOTA download starting.”
Description
Displays when the microcontroller firmware update over the air
(microFOTA) download is starting.
.thQonnect Action Needed None Value Message Description Displays when the microcontroller firmware update over the air Action Needed Preparations should be made for a pending ema and cellular Value Message Description Displays when the microcontroller firmware update over the air Action Needed Value Message “Cellular FOTA will begin in 60 seconds. Please close all 20
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
20
Action Needed
None
5.17 microFOTA Download Complete
Microcontroller FOTA Download Complete – Occurs once ema has completed
downloading a new firmware image in the background.
Value
31
Message
“Microcontroller FOTA download complete.”
Description
Displays when the microcontroller firmware update over the air
(microFOTA) download has completed.
Action Needed
Preparations should be made for a pending ema and cellular
module reboot.
5.18 microFOTA Download Failed
Microcontroller FOTA Download Failed. Resuming later. – Occurs if ema has
detected that the downloading of a new firmware image could not complete
successfully, and will retry shortly.
Value
32
Message
“Microcontroller FOTA download failed. Resuming later.”
Description
Displays when the microcontroller firmware update over the air
(microFOTA) download has failed and will retry later.
Action Needed
None
5.19 Cellular Module FOTA Pending
Cellular FOTA Will Begin in 60 Seconds. Please Close All Connections. – Occurs as
a warning that ema will begin to download and update the on-board cellular
module’s firmware image.
Value
40
Message
“Cellular FOTA will begin in 60 seconds. Please close all
connections.”
.thQonnect Description Displays when a firmware update over the air (FOTA) for the Action Needed Value Message Description Displays when a firmware update over the air (FOTA) for the Action Needed Value Message Description Displays when a firmware update over the air (FOTA) for the Action Needed Value Message Description Displays when the firmware update over the air (FOTA) for the 21
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
21
Description
Displays when a firmware update over the air (FOTA) for the
cellular module is available, and will begin in 60 seconds.
Action Needed
Begin to close all active connections.
5.20 Cellular Module FOTA Starting
Cellular FOTA Update Starting – Occurs once ema has begun the process of
updating the new cellular module’s firmware image.
Value
41
Message
“Cellular FOTA update starting.”
Description
Displays when a firmware update over the air (FOTA) for the
cellular module is starting.
Action Needed
None
5.21 Cellular Module FOTA Complete
Cellular FOTA Update Complete – Occurs once ema has completed updating the
new cellular module’s firmware image.
Value
42
Message
“Cellular FOTA update complete.”
Description
Displays when a firmware update over the air (FOTA) for the
cellular module has completed.
Action Needed
None
5.22 Cellular Module FOTA Failed
Cellular FOTA Update Failed. Resuming Later. – Occurs if ema has detected that
the updating of the new cellular module’s firmware image could not complete
successfully, and will retry shortly.
Value
43
Message
“Cellular FOTA update failed. Resuming later.”
Description
Displays when the firmware update over the air (FOTA) for the
cellular module has failed and will retry later.
.thQonnect Action Needed Value Message “Administrative activity will begin in 60 seconds. Please Description Displays when administrative activity is pending and will begin Action Needed Begin to close all active connections, until instructed otherwise Value Message Description Action Needed Value Message Description Action Needed 22
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
22
Action Needed
None
5.23 Administrative Activity Pending
Administrative Activity Will Begin in 60 Seconds. Please Close All Connections. –
Occurs as a warning that ema has detected that administrative activity is
required and will begin shortly.
Value
90
Message
“Administrative activity will begin in 60 seconds. Please
close all connections.”
Description
Displays when administrative activity is pending and will begin
in 60 seconds.
Action Needed
Begin to close all active connections, until instructed otherwise
by a different URC.
5.24 Administrative Activity Starting
Administrative Activity Starting – Occurs once ema has started an administrative
activity.
Value
91
Message
“Administrative activity starting.”
Description
Displays when administrative activity is starting.
Action Needed
None, unless instructed otherwise by a different URC.
5.25 Administrative Activity Complete
Administrative Activity Complete – Occurs once ema has completed an
administrative activity.
Value
92
Message
“Administrative activity complete.”
Description
Displays when administrative activity has completed.
Action Needed
None, unless instructed otherwise by a different URC.
.0thonnect Value Message Description Displays after the Board Notify Summit API has been invoked. Action Needed 23
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
23
5.26 Board Notify
Board Notify – Occurs with cmd data that has been sent or pushed from
OptConnect Summit cloud services. The Summit API
/devices/ema/boardnotify/serial/{serial} must be invoked with cmd data.
Reference Summit API here: https://docs.optconnect.com/documentation
Value
99
Message
“cmd data”
Description
Displays after the Board Notify Summit API has been invoked.
Valid characters for cmd data are alphanumeric characters (A-
Z, a-z, 0-9) and $-_.+!*'(),;/?:@=&,Space(0x20h)
Note: Any non-valid characters, will be replaced by a dash (-).
Note: cmd data length longer than 160 bytes will be truncated
to 160 bytes.
Action Needed
None, host application must process cmd data
\ .0ptConnect 24
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
24
5.27 Sample URC Sequence Outputs
5.27.1 microFOTA
microFOTA Sample URC Output. microFOTA initiated (server side).
OCURC: 30, "Microcontroller FOTA download starting." // ema has started the download.
OCURC: 31, "Microcontroller FOTA download complete." // ema has completed the download.
OCURC: 06, "ema rebooting in 60 seconds." // warning of a pending reboot.
OCURC: 03, "Cellular module powering off." // ema powering off on-board cellular module.
OCURC: 09, "Removing cellular UART interface." // ema removing use of Modem UART/USB
// interfaces due to the cellular module being
// powered off.
OCURC: 10, "Removing cellular USB interface."
OCURC: 04, "Cellular module powered off." // ema has powered off the on-board cellular
// module.
OCURC: 05, "ema rebooting now." // ema is now rebooting.
OCURC: 00, "ema AT interface ready." // ema has rebooted and emaLink is ready for
// use.
OCURC: 01, "Cellular module powering on." // ema powering on the on-board cellular
// module.
OCURC: 09, "Removing cellular UART interface." // ema taking steps to make the Modem UART
OCURC: 10, "Removing cellular USB interface." // and USB interfaces available, but not ready
OCURC: 09, "Removing cellular UART interface." // yet.
OCURC: 10, "Removing cellular USB interface." //
OCURC: 07, "Establishing cellular UART interface." // ema has made the Modem UART/USB
OCURC: 08, "Establishing cellular USB interface." // interfaces available for use.
OCURC: 02, “Cellular module ready for use.” // the on-board cellular module is now ready for
// use by the host system.
5.27.2 ema Powered ON
Power has been applied to pin 1 (VCC):
OCURC: 00, "ema AT interface ready." // Power has been applied to ema, ON_OFF pin
// has not been pulled LOW yet
\ @OptCOIwrwect 25
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
25
5.27.3 ema Cellular Module Turned ON
Pin 20 (ON_OFF) has been driven and held LOW, power has been applied to pin 1 (VCC) for some time:
OCURC: 01, "Cellular module powering on." // ema powering on the on-board cellular
// module.
OCURC: 09, "Removing cellular UART interface." // ema taking steps to make the Modem UART
OCURC: 10, "Removing cellular USB interface." // and USB interfaces available, but not ready
OCURC: 09, "Removing cellular UART interface." // yet.
OCURC: 10, "Removing cellular USB interface." //
OCURC: 07, "Establishing cellular UART interface." // ema has made the Modem UART/USB
OCURC: 08, "Establishing cellular USB interface." // interfaces available for use.
OCURC: 02, "Cellular module ready for use." // the on-board cellular module is now ready for
// use by the host system.
5.27.4 ema Cellular Module Turned OFF
Pin 20 (ON_OFF) has been released, power still applied to pin 1 (VCC):
OCURC: 03, "Cellular module powering off." // ema powering off on-board cellular module.
OCURC: 09, "Removing cellular UART interface." // ema shutting down Modem UART/USB
OCURC: 10, "Removing cellular USB interface." // interfaces.
OCURC: 04, "Cellular module powered off." // ema has powered off the on-board cellular
// module.
5.27.5 ema Cellular Module Reset
Pin 5 (nRESET_REQUEST) has been driven and held low for at least one (1) seconds and released, power
still applied to pin 1 (VCC) and pin 20 (ON_OFF) is still being held LOW.
OCURC: 11, "Cellular module reset requested." // ema has detected a reset request for the
// on-board cellular module
OCURC: 12, "Cellular module resetting." // ema has started the reset sequence of the
// on-board cellular module
OCURC: 03, "Cellular module powering off." // ema powering off on-board cellular module.
OCURC: 09, "Removing cellular UART interface." // ema shutting down Modem UART/USB
OCURC: 10, "Removing cellular USB interface." // interfaces.
OCURC: 04, "Cellular module powered off." // ema has powered off the on-board cellular
\ .0ptConnect 26
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
26
// module.
OCURC: 13, "Cellular module reset." // ema has completed the reset sequence of the
// on-board cellular module
OCURC: 07, "Establishing cellular UART interface." // ema has made the Modem UART/USB
OCURC: 08, "Establishing cellular USB interface." // interfaces available for use after the reset.
OCURC: 02, "Cellular module ready for use." // the on-board cellular module is now ready for
// use by the host system.
5.27.6 ema Board Notify
The OptConnect ema™ Board Notify feature is a very powerful and useful method to send one-way
notification messages from cloud to host system via ema. The Summit API must be used to start the
process
Summit API /devices/ema/boardnotify/serial/{serial} invoked with cmd data “do something”
OCURC: 99, "do something" // ema sends out the board notify URC
// for the host to process
\ .thQonngct 27
© OptConnect Management, LLC 2020. All rights reserved. Revision 1.3
27
6. Revision History
Revision
Date
Description
Author
1.0
6/4/2019
Initial Release
MSV
1.1
9/10/2019
Updated sections 3 & 4. Added section 5.27. General cleanup of the
document.
MSV
1.2
11/26/2019
Added sections 3.7, 3.8, 5.26 and 5.27.6. ema Management UART is
now referred to as emaLink
MSV
1.3
5/18/2020
Updated ema p/n’s
MSV