# 4 ExpressLink commands ## 4.1 Introduction **4.1.1.1**   These commands are sent to and from the UART. The default UART configuration shall be 115200, 8, N, 1 (baud rate: 115200; data bits: 8; parity: none; stop bits: 1). There is no hardware or software flow control for UART communications. **4.1.1.2**   The baud rate is NOT configurable. **4.1.1.3**   No Local Echo is provided. **Note** Communication between the ExpressLink modules and the AWS Cloud are encrypted both during transmission (using the TLS 1.2 protocol) and while at rest. However, the serial interface (UART) between the host processor and the module isn't encrypted. If sensitive data needs to be transmitted to and from the ExpressLink module, and unauthorized persons can potentially gain physical control of the device, we recommend that the host processor and the corresponding cloud application implement a suitable, additional end-to-end message encryption scheme. ## 4.2 ExpressLink commands format All ExpressLink commands assume the following general format: `AT+{command}[#]{separator}[parameter]{EOL}` Where: **4.2.1**   `{command}` A short, alphabetical character string (including "\$1", "\$1", and "?") that matches one of the commands listed in the following sections (CONNECT, TIME?, FACTORY\$1RESET). 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 *\$1EOL\$1*, not including either the separator or the *\$1EOL\$1*. 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](#elpg-delimiters). ## 4.3 Delimiters and escaping The format described in the previous section, and the specific choice of delimiters, removes the need for quotes surrounding parameters, and for other delimiters between successive parameters. As a further benefit, this removes the need for most escaping sequences with the exclusion of the ASCII characters *\$1EOL\$1* (0x0a or 0x0d) and backslash ('\$1'). **4.3.1**   *\$1EOL\$1* 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 '\$1A'. **4.3.1.2**   Carriage return is escaped as: 0x5C 0x44 or '\$1D'. **4.3.2**   Backslash ('\$1') in the parameter string Backslash (0x5C) in the parameter string is replaced by the escape sequence: 0x5C 0x5C ('\$1\$1'). **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](#elpg-responses). **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 '\$1A'. **4.3.4.2**   Carriage return is escaped as: 0x5C 0x44 or '\$1D'. **4.3.5**   Backslash ('\$1') in the command response Backslash (0x5C, '\$1') in a command response is replaced by the escape sequence: 0x5C, 0x5C or '\$1\$1'. ## 4.4 Maximum values **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 Data processing **4.5.1**   Data entry The data entry for a command begins with the 'AT\$1' and ends with the *\$1EOL\$1*. The module will not begin running a command before it receives the *\$1EOL\$1*. **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 *\$1EOL\$1* arrives. **4.5.2.1**   The module returns 'ERR1 OVERFLOW' and the entire message is discarded. **4.5.3**   Data arriving after *\$1EOL\$1* Any data that arrives after *\$1EOL\$1* and before 'AT\$1' will be ignored and discarded. Note that this includes multiple *\$1EOL\$1* characters–they will be ignored and discarded. **Example** ``` abcdefAT{EOL} spurious characters preceding a command are ignored OK AT{0x0a}{0x0d} line feed followed by carriage return OK AT{0x0d}{0x0a} carriage return followed by line feed OK AT{0x0d}{0x0d} multiple carriage returns OK ``` ## 4.6 Command responses and error codes All commands respond according to the response format described in section [4.6.1 General response formats:](#elpg-responses-formats) when the command has been completed. In some cases, this can take a significant amount of time, but under no circumstances longer than the *response timeout* defined in section [4.6.2 Response timeout](#elpg-response-timeout). ### 4.6.1 General response formats: `OK[#]|ERR{#}{separator}[detail]{EOL}` Where: **OK*[\$1]*** 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*\$1\$1\$1*** 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](#elpg-table1). *\$1separator\$1* Is a *single* ASCII space character (ASCII 0x20). *[detail]* Is an optional ASCII string that contains the command response or error description. *\$1EOL\$1* Is composed of a *carriage return* (ASCII 0x0d) followed by a *newline* character (ASCII 0x0a). **Table 1 - Error codes** | Code | ExpressLink text | Description | | --- | --- | --- | | 1 | OVERFLOW | More bytes have been received than fit in the receive buffer. | | 2 | PARSE ERROR | Message not formatted correctly. | | 3 | COMMAND NOT FOUND | Invalid command. | | 4 | PARAMETER ERROR | Command does not recognize the parameters. | | 5 | INVALID ESCAPE | An incorrect escape sequence was detected. | | 6 | NO CONNECTION | Command requires an active connection to AWS IoT. | | 7 | OUT OF RANGE | The index provided is out of range (0 or greater than MaxTopic). | | 8 | PARAMETER UNDEFINED | The key provided references an empty configuration parameter. | | 9 | INVALID KEY LENGTH | Key is longer than 16 characters. | | 10 | INVALID KEY NAME | A non-alphanumeric character was used in the key name. | | 11 | UNKNOWN KEY | The supplied key cannot be found in the system. | | 12 | KEY READONLY | The key cannot be written. | | 13 | KEY WRITEONLY | The key cannot be read. | | 14 | UNABLE TO CONNECT | The module is unable to connect. | | 15 | TIME NOT AVAILABLE | A time fix could not be obtained. | | 16 | LOCATION NOT AVAILABLE | A location fix could not be obtained. | | 17 | MODE NOT AVAILABLE | The requested mode is not available. | | 18 | ACTIVE CONNECTION | An active connection prevents the command from running. | | 19 | HOST IMAGE NOT AVAILABLE | A host OTA command was issued but no valid HOTA image is present in the OTA buffer. | | 20 | INVALID ADDRESS | The OTA buffer pointer is out of bounds (> image size). | | 21 | INVALID OTA UPDATE | The OTA update failed. | | 22 | [reserved] | | | 23 | INVALID SIGNATURE | A signature verification failed. | | 24 | SHADOW ERROR | Shadow support disabled, not initialized, or request rejected. | | 25 | NOT ALLOWED | The module cannot accept the command at this time (it is busy or operating in a mode that conflicts with the request). | | 26 | INVALID CERTIFICATE | The certificate was invalid or corrupted. | **Note** Refer to section [4.3 Delimiters and escaping](#elpg-delimiters) for how special characters are escaped in the command response string. ### 4.6.2 Response timeout The maximum runtime for every command must be listed in the module manufacturer's datasheet. No command can take more than 120 seconds to complete (the maximum time for a TCP connection timeout). ### 4.6.3 AT   »Communication test« By sending only the 'AT' (attention) command, the host can verify the presence and readiness of the module command parser. Example: ``` AT{EOL} # request the module's attention ```Returns: `OK{EOL}` If the module is connected and the command parser active, then the module returns 'OK'. ## 4.7 Power and connection control ### 4.7.1 CONNECT?   »Request the connection status« Requests the current status of the connection to the AWS cloud and the device onboarding state (see [11.3.2 ExpressLink onboarding states and transitions](elpg-provisioning.md#elpg-provisioning-onboarding-states)). The connection status indicates the completion of the entire sequence of actions required for the module to connect and authenticate with the AWS cloud. The onboarding state is determined by comparing the current Endpoint configuration parameter (string) against the module default Endpoint (staging account) string that is hardcoded as the factory reset value for the parameter (see the Endpoint entry in [Table 2 - Configuration Dictionary Persistent Keys](elpg-configuration-dictionary.md#elpg-table2)).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'. ### 4.7.2 CONNECT   »Establish a connection to an AWS IoT Core Endpoint« Request a connection to the AWS Cloud, bringing an active device into a higher power consumption mode where it is able to communicate with the AWS IoT Core endpoint. **Note** This command is blocking. The connection process can require a long time during which no further communication is possible with the module until one of the following responses is returned to the host. (For a non-blocking option, see the asynchronous command [4.7.8 CONNECT\$1   »Non-blocking request to connect to IoT Core«](#elpg-connect-nonblocking-command).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 *\$1\$1hint\$1* 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: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-expresslink/archive/v1.1.2/programmersguide/elpg-commands.html) 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 ``` ### 4.7.3 DISCONNECT   »Leave the connected state and enter the active state« This command allows the host to prepare for a transition to low power (using the SLEEP command), or to update the connection parameters before it attempts to reconnect again with the changed parameters (using a new CONNECT command).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 SLEEP*[\$1] [duration]*   »Request to enter a low power mode« This command forces the module to enter a low power mode. ExpressLink module manufacturers can implement specific low power modes with increasing values (*[\$1]*) that correspond to deeper sleep states (as capable) to provide the lowest power consumption and longest possible battery life. The manufacturer documents the power consumption figures achievable in such modes in the module datasheet. **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**. 1. a wakeup event is generated by the host lowering the **WAKE pin**. 1. 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). \$1mode\$1 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](elpg-event-handling.md).) Example 1: ``` AT+SLEEP 100 # Disconnect and suspend all activities for 100 seconds OK 0 # Enters sleep mode 0 (default) AT+CONNECT # Resume connection ``` Example 2: ``` AT+SLEEP9 # Request a deep sleep (proprietary mode) indefinitely OK 3 # Enters nearest/deepest sleep mode available on this model ``` Note that the device might require a hardware reset/wake event to be re-awakened, and all status (non-volatile) information might be lost requiring a new initialization and configuration. Example 3: ``` AT+SLEEP SOME TEXT ERR4 PARAMETER ERROR # a numerical value is expected for {duration} ``` Example 4: ``` AT+SLEEP9A ERR4 PARAMETER ERROR # a numerical value is expected for {mode} ``` ### 4.7.5 CONFMODE *[parameter]*   »Activate modal credential entry« ExpressLink modules that require additional user credentials can be set by the host to enter CONFMODE (see [Figure 2](elpg-run-states.md#elpg-figure2)) to enable or repurpose an interface to receive additional connection credentials from user input. Consult the module manufacturer's datasheet for details specific to your model. **Example 1:** An ExpressLink Wi-Fi module could use this command to enter a SoftAP mode, temporarily assume the role of an Access Point, and serve an HTML form. This would allow the user to enter the local Wi-Fi router credentials using a mobile device web browser. The optional parameter could be used to provide a customized, unique SSID based on the device UID. **Example 2:** If a Bluetooth interface is available, the ExpressLink module could receive the credentials using a serial interface (SPP profile). For Bluetooth LE modules, this could be performed using a dedicated (GATT) service using a custom mobile application.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. **4.7.5.4**   While in CONFMODE, an ExpressLink module can still process all commands that do not require an active connection (for example, 'AT\$1CONF? Version'). **4.7.5.5**   Commands that require an active connection return 'ERR6 NO CONNECTION'. Attempting to issue a CONNECT command while in CONFMODE results in an 'ERR14 UNABLE TO CONNECT'. **4.7.5.6**   The host may issue a RESET command at any time to exit CONFMODE (see [ Figure 2](elpg-run-states.md#elpg-figure2)). **4.7.5.7**   A CONFMODE notification event (see [Table 4 - ExpressLink event codes](elpg-event-handling.md#elpg-table4) is provided to the host when the entry of new credentials has been completed. Only after that can the host issue a new CONNECT command to attempt to establish a connection using the newly entered credentials. ### 4.7.6 RESET   »Request a full reset of the ExpressLink internal state« This command disconnects the device (if connected) and resets its internal state. Non-persistent configuration parameters (see [Table 3 - Configuration dictionary non-persistent keys](elpg-configuration-dictionary.md#elpg-table3)) are reinitialized, all subscriptions are terminated, and the message queue is emptied. Returns: **4.7.6.1**   `OK{EOL}` If the command was successful, the module returns 'OK'. **4.7.6.2**   A **STARTUP** event is added to the event queue when the process is completed. ### 4.7.7 FACTORY\$1RESET   »Request a factory reset of the ExpressLink module« This command performs a full factory reset of the ExpressLink module, including re-initializing all non-persistent configuration parameters (see [Table 3 - Configuration dictionary non-persistent keys](elpg-configuration-dictionary.md#elpg-table3)) and selected persistent parameters (as indicated in [Table 2 - Configuration Dictionary Persistent Keys](elpg-configuration-dictionary.md#elpg-table2) in the Factory Reset column), and the message queue is emptied.Returns: **4.7.7.1**   `OK{EOL}` If the command was successful, the module returns 'OK'. **4.7.7.2**   A **STARTUP** event is added to the event queue when the process is completed. ### 4.7.8 CONNECT\$1   »Non-blocking request to connect to IoT Core« Request a connection to the AWS cloud, bringing an active device into a higher power consumption mode where it is able to communicate with the AWS IoT Core endpoint. **Note** This command is non-blocking and immediately returns OK or an error as documented below. However, it can take a long time for the connection process to complete, and until it is complete, other power and connection control commands are rejected. Once the connection is established, a CONNECT event is issued. (For a blocking option, see the synchronous command [4.7.2 CONNECT   »Establish a connection to an AWS IoT Core Endpoint«](#elpg-connect-command).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\$1 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\$1 command is already in progress.