4 ExpressLink commands

4.2.1   {command}

A short, alphabetical character string (including "_", "!", and "?") that matches one of the commands listed in the following sections (CONNECT, TIME?, FACTORY_RESET).

Note

Commands are not case sensitive, although in this document, uppercase is always used for consistency.

Returns:

4.2.1.1   ERR3 COMMAND NOT FOUND

If the command is unknown, then the module returns 'COMMAND NOT FOUND'.

4.2.2   [#]

An optional decimal (0..N) suffix qualifier (multiple digits allowed) is used by selected commands as a first numerical parameter.

Returns:

4.2.2.1   ERR4 PARAMETER ERROR

If a numerical suffix was provided but the command did not expect it, or if a numerical suffix is missing but required, the module returns 'ERR4 PARAMETER ERROR'.

4.2.2.2   ERR7 OUT OF RANGE

If the numeric suffix is out of the valid range for the command, the module returns 'ERR7 OUT OF RANGE'.

4.2.3   {separator}

A single ASCII space character (0x20).

Returns:

4.2.3.1   ERR2 PARSE ERROR

If ANY character other than 0x20 is present after the numerical suffix or '?' in the command string, then the module returns 'ERR2 PARSE ERROR'.

4.2.4   [parameter]

An (escaped) ASCII string with the data required for the command.

Returns:

4.2.4.1   ERR4 PARAMETER ERROR

If the command is unable to process the parameter supplied, then the module returns 'ERR4 PARAMETER ERROR'.

4.2.5   {EOL}

The ASCII line feed character (0x0a) or the ASCII carriage return character (0x0d).

4.2.6   Parameter string note

The parameter string includes all bytes from the separator to the {EOL}, not including either the separator or the {EOL}. ALL ASCII values from 0 - 0xFF are valid in the parameter string which allows for binary payloads if proper escaping is performed as detailed in 4.3 Delimiters and escaping.

4.3.1   {EOL} in the parameter string (input escaping)

if a line feed character (0x0a) or carriage return character (0x0d) is required in the parameter string, it must be replaced by the backslash escaped sequence as follows:

4.3.1.1   Line feed is escaped as: 0x5C 0x41 or '\A'.

4.3.1.2   Carriage return is escaped as: 0x5C 0x44 or '\D'.

4.3.2   Backslash ('\') in the parameter string

Backslash (0x5C) in the parameter string is replaced by the escape sequence: 0x5C 0x5C ('\\').

4.3.2.1   All other combinations of the escape sequence are illegal and the module returns 'ERR5 INVALID ESCAPE'.

4.3.3   Formatting and Parsing Errors

Parsing of a command is immediately terminated when the first formatting error condition is detected. The module then discards the remainder of the command input up to the closing EOL character and reports the appropriate error code as indicated in 4.6 Command responses and error codes.

4.3.4   EOL in the command response (output escaping)

If a line feed character (0x0a) or a carriage return character (0x0d) is present in a command response string, it is replaced by the backslash escaped sequence as follows:

4.3.4.1   Line feed is escaped as: 0x5C 0x41 or '\A'.

4.3.4.2   Carriage return is escaped as: 0x5C 0x44 or '\D'.

4.3.5   Backslash ('\') in the command response

Backslash (0x5C, '\') in a command response is replaced by the escape sequence: 0x5C, 0x5C or '\\'.

4.4.1   Maximum bytes in the formatted command string

The formatted command string as received by ExpressLink can be up to 9K bytes in length.

AT+[ up to 9K bytes ]{EOL}

4.4.2   Maximum command word size

The command word portion of the command string can be up to 32 bytes long.

4.5.1   Data entry

The data entry for a command begins with the 'AT+' and ends with the {EOL}. The module will not begin running a command before it receives the {EOL}.

4.5.2   Data overflow

If the data buffer overflows during the data entry phase of a command, the ExpressLink module continues to accept, but discards, the incoming data until the next {EOL} arrives.

4.5.2.1   The module returns 'ERR1 OVERFLOW' and the entire message is discarded.

4.5.3   Data arriving after {EOL}

Any data that arrives after {EOL} and before 'AT+' will be ignored and discarded. Note that this includes multiple {EOL} characters–they will be ignored and discarded.

abcdefAT{EOL}         spurious characters preceding a command are ignored
OK{EOL}

AT{0x0a}{0x0d}{EOL}   line feed followed by carriage return
OK{EOL}

AT{0x0d}{0x0a}{EOL}   carriage return followed by line feed
OK{EOL}

AT{0x0d}{0x0d}{EOL}   multiple carriage returns
OK{EOL}
                            

OK[#]

Indicates that the command was valid and ran correctly. The optional numerical suffix [#] indicates the number of additional output lines, with no additional lines expected if this suffix is omitted.

ERR{#}

Indicates the command was invalid or an error occurred while running it. The required numerical suffix is an error code as defined in Table 1 - Error codes .

{separator}

Is a single ASCII space character (ASCII 0x20).

[detail]

Is an optional ASCII string that contains the command response or error description.

{EOL}

Is composed of a carriage return (ASCII 0x0d) followed by a newline character (ASCII 0x0a).

Returns:

OK{EOL}

If the module is connected and the command parser active, then the module returns 'OK'.

Returns:

OK {status}{onboarded}[CONNECTED/DISCONNECTED][STAGING/CUSTOMER]

4.7.1.1   OK 1 0 CONNECTED STAGING

If the device is connected to the staging account, then the module returns 'OK 1 0 CONNECTED STAGING'.

4.7.1.2   OK 0 0 DISCONNECTED STAGING

If the device is not connected to the staging account, then the module returns 'OK 0 0 DISCONNECTED STAGING'.

4.7.1.3   OK 1 1 CONNECTED CUSTOMER

If the device is connected and onboarded (customer account), then the module returns 'OK 1 1 CONNECTED CUSTOMER'.

4.7.1.4   OK 0 1 DISCONNECTED CUSTOMER

If the device is not connected (customer account), then the module returns 'OK 0 1 DISCONNECTED CUSTOMER'.

Returns:

4.7.2.1   OK 1 CONNECTED

The module has successfully connected to AWS IoT Core.

4.7.2.2   ERR14 {#hint} UNABLE TO CONNECT [detail]

The module is unable to connect. Additional clues can be provided by the mandatory {#hint} numerical code and the optional [detail] field. The hint numerical codes indicate the state of advancement of the connection process when the failure occurred so that meaningful debugging tips can be provided in the module documentation (including datasheets and FAQs). They are numbered according to the following sequence of steps:

1.	Backoff algorithm imposed delay (see 4.7.2.4)
2.	Failed to access network – reported by a Wi-Fi module when it fails to connect to a local access point/router or by a cellular module if it fails to connect to the nearest cell tower. Tip Check SSID/passphrase or local router state. After this step the device is assumed to be able to communicate over the network (it has obtained an IP address).
3.	Failed to reach AWS endpoint – reported when the device fails to connect to an AWS endpoint. Tip Check the endpoint configuration parameter (URL) After this step, the device is assumed to have reached an AWS server.
4.	Failed to securely authenticate with AWS – reported when the device fails to upgrade the socket to a secure socket (TLS). Tip Check if the AWS root certificate might have expired. After this step, a secure socket is established with AWS.
5.	Failed to login AWS (MQTT) broker – reported when the MQTT login is unsuccessful Tip Check if the device certificate is present in the customer account registry. After this step, the device should be able to issue MQTT commands.
6.	Failed to register for Jobs – reported when the device fails to publish or subscribe to standard AWS topics used for JOBS/OTA (connection dropped by AWS server) Tip Check policies attached to device certificate. After this step, the device is connected and fully functional.

Different modules will interpret the hint codes according to the specific wireless/networking stack that is applicable for the given technology and will provide meaningful tips in the module documentation. Some of the steps might not be applicable to all technologies (for example, the hint code for step 2 might not apply for a LoRA or Bluetooth module that transitions directly from step 1 to 3). Similarly, additional intermediate hint codes can be provided using dot notation, as applicable, to provide finer granularity (for example, a hint code 5.1 can be added between step 5 and step 6).

4.7.2.3   OK 1 CONNECTED

If the ExpressLink module is already connected, issuing a CONNECT command returns immediately with a success response ('OK 1 CONNECTED').

4.7.2.4   ERR14 {#hint} UNABLE TO CONNECT [detail]

In case of a connection failure, the ExpressLink module keeps a timestamp of the event. This is used to ensure that a subsequent (repeated) connection request complies with the correct backoff timing limits. If the request from the host is repeated too soon after the previous attempt (the interval between requests is shorter than the prescribed minimum backoff time), the ExpressLink module will return ERR14 with an appropriate hint code. The necessary delay will increase according to the backoff algorithm until a successful connection is established.

4.7.2.5   ERR25 NOT ALLOWED{EOL}

The CONNECT command cannot be issued when the device is in CONFMODE or otherwise busy with activities that require conflicting resources.

Examples:

AT+CONNECT        # request to connect
OK 1 CONNECTED    # connection established successfully

Or

ERR14 3 UNABLE TO CONNECT Invalid Endpoint?    # Error detail and hint detail/tip provided
ERR14 5 UNABLE TO CONNECT                      # Hint code but no hint detail provided 

Or

ERR25 NOT ALLOWED  # The command cannot be accepted until the asynchronous connection 
                   #   attempt is completed successfully or otherwise

Returns:

4.7.3.1   OK 0 DISCONNECTED

Note that if already disconnected, the command will return immediately with a success value ('OK 0 DISCONNECTED').

4.7.4.1   The [duration] parameter

If present, this indicates the number of seconds before the module awakes automatically.

4.7.4.2   If the duration parameter is absent, the module remains in low power mode until:

1. a hardware Reset is generated by the host lowering the RST pin.

2. a wakeup event is generated by the host lowering the WAKE pin.

3. a new AT command is sent by the host using the serial interface (this might not be possible in case of advanced (deep) sleep modes, see 4.7.4.4)

4.7.4.3   A SLEEP command without a numerical suffix defaults to mode 0.

Mode 0 is the default low power mode where the ExpressLink module reduces its power consumption as much as possible while it still maintains the serial interface active and preserves the contents of all configuration parameters.

4.7.4.4   Before entering SLEEP mode, the device will empty the event queue.

Advanced low power modes can disable the serial command interface. In these cases, in absence of the sleep duration parameter, the only way to awaken the device is to apply an external reset or wake signal. Deep sleep states might cause loss of part or all volatile (RAM) information, including all module state information including configuration parameters that are not maintained in non-volatile memory (for example, Topics). The host processor must reconfigure such parameters as required by the application.

Returns:

4.7.4.5   OK {mode}[{detail}]

The device is ready and will proceed to the lower power mode selected immediately after sending the reply (and flushing the serial port output). {mode} indicates the sleep mode activated.

4.7.4.6   ERR18 ACTIVE CONNECTION

The device cannot transition to a low power mode because there is an active cloud connection. Use the DISCONNECT command first to shut down the connection.

4.7.4.7   Sleep mode fall back

When the host requests a SLEEP mode higher than any implemented on the specific ExpressLink model, the module will fall back to the nearest/highest mode available. (For example, SLEEP9, might fall back to SLEEP3 if mode 3 is the highest available or simply SLEEP if no advanced modes are available.) The actual sleep mode activated is reported in the response.

4.7.4.8   Upon returning to the active state, a STARTUP event is generated and added to the event queue.

(See 7 Event handling.)

4.7.4.9   Sleep modes for devices supporting Bluetooth Low Energy (BLE)

Modules implementing the BLE API are expected to continue to offer support for the BLE feature while in default low power mode (SLEEP, SLEEP0)- BLE events are able to awaken the module. Advanced low power modes (SLEEP1 and greater) can disable the BLE radio to further reduce the power consumption of the device. Refer to the specific manufacturer’s module datasheet to determine which modes are available and how they affect the BLE functionality.

Returns:

4.7.5.1   OK CONFMODE ENABLED

The device has entered CONFMODE and is ready to receive user input.

4.7.5.2   ERR17 MODE NOT AVAILABLE

This ExpressLink model/version does not support CONFMODE.

4.7.5.3   ERR18 ACTIVE CONNECTION

The device cannot enter CONFMODE because it is currently connected. The host must disconnect first.

Returns:

4.7.6.1   OK{EOL}

If the command was successful, the module returns 'OK'.

Returns:

4.7.7.1   OK{EOL}

If the command was successful, the module returns 'OK'.

Returns:

4.7.8.1   OK{EOL}

The module has accepted the request and initiated the process to connect to AWS IoT Core. Note that the connection process can require a significantly long time.

4.7.8.2   A CONNECT event is generated when the process is completed or terminated with an error. A hint code is provided as the event parameter (with the same interpretation provided in 4.7.2.2 for the CONNECT ERR14 response). In case of success, the hint-code will be 0.

4.7.8.3   If the ExpressLink module is already connected, issuing a CONNECT! command will immediately produce a CONNECT event with a success hint code (0).

4.7.8.4   In case of a connection failure, the ExpressLink module will keep a timestamp of the event. This will be used to ensure that a subsequent (repeated) connection request will comply with the correct backoff timing limits. If the request from the host is repeated too soon after the previous attempt (a shorter interval than the prescribed minimum backoff time) the ExpressLink module will produce a CONNECT event with the Backoff hint code. Delays will increase according to the backoff algorithm until a successful connection is established.

4.7.8.5   ERR25 NOT ALLOWED{EOL}

The device is in CONFMODE or a CONNECT! command is already in progress.