7 ExpressLink module OTA updates

ExpressLink modules natively support over the air (OTA) firmware updates utilizing the AWS IoT OTA service (as currently implemented in the AWS Embedded C-SDK v.202103.00). To support the OTA feature, ExpressLink modules provide additional bulk storage space (non-volatile memory). The amount of non-volatile memory available is sufficient to store at least two full copies of the ExpressLink module's own firmware image -- a current known-good copy and a new copy. Consult the manufacturer's datasheet to verify the amount of memory available on a specific model.

When an ExpressLink firmware update job is triggered (using the AWS IoT OTA console), the update process begins and takes place in five steps:

This process provides two types of security/safety assurance to the user:

The host processor is notified of the module's OTA ready/pending status by means of an event. (See the EVENT? command.)

The host processor can poll the OTA process state at any time using the OTA? Command. (See 7.2 OTA commands.)

7.1 ExpressLink module support of Host Processor OTA

ExpressLink modules are designed to support Host processor updates Over the Air (HOTA). This is done in a shared responsibility model in collaboration with the host processor. The Bulk Storage memory capacity of the module might be shared between the module and host OTA images, so that only one of the two is guaranteed to be supported at any time, although manufacturers can choose to differentiate their products by offering a larger amount of non-volatile memory. Consult the manufacturer's datasheet to verify the amount of memory available on a specific model.

The HOTA feature is not limited to supporting only host processor firmware images but can also be used to transport, stage, and verify the delivery of any large payload including pictures, audio files, or any binary blobs that may potentially contain multiple files of different natures.

The mechanism utilized to trigger and perform the transfer of host processor images makes use of the same underlying services as the module OTA (namely, AWS IoT Jobs and AWS IoT OTA). It utilizes a collaborative model based on the paradigm of a mailbox. ExpressLink devices act as the recipient of envelopes meant for the host. They can verify the envelope's integrity (checksum) and authenticity (signature) before notifying the host by raising a flag (event). It is up to the host to periodically check for flags, and when ready, to retrieve the contents of the mailbox. ExpressLink devices, much like actual mailboxes, are not concerned with the nature of the contents of the envelopes. Once the envelope is retrieved, and the flag lowered, they are ready (empty) to receive more mail. Successive attempts to deliver more updates to a host processor will be NACKed until the host either retrieves the update or rejects it and clears the flag without retrieving the contents.

The communication between the host processor and the ExpressLink module required to deliver an OTA payload can be represented in the following diagram:

The Host processor is not required to retrieve the entire payload at once, nor to follow a strictly sequential process, the fetching pointer can be moved (seek) to allow random access to the payload contents. Also, the size of the chunks retrieved by the Host processor is independent from the chunking performed during the image download by the module. Instead, this is intended to be the most convenient value depending on the host processor's serial interface buffer size, the Host processor's own (flash) memory page size, and/or binary format decoding needs (for example, INTEL HEX...). Consequently, the host processor can choose the reboot directly from the ExpressLink module host OTA memory or can choose to transfer only parts of the payload to be consumed by other subsystems as necessary.

The serial interface commands involved in the implementation of the OTA and Host OTA features are summarized here:

7.2 OTA commands

7.2.1 OTA?: Fetches the current state of the OTA process

7.2.2 OTA codes:

Example 1:

AT+OTA?    # check the OTA status
OK 3       # an OTA operation is in progress, the module OTA buffer is in use

Example 2:

AT+OTA?        # check the OTA status
OK 1 v2.5.7    # a module OTA firmware update is proposed

7.2.3 OTA ACCEPT: Allow the OTA operation to proceed

The host allows the module to download a new image for the module or the host OTA.

Example:

AT+OTA ACCEPT    # accept the OTA download 
OK 1 

7.2.4 OTA READ #bytes: Requests the next # bytes from the OTA buffer

The read operation is designed to allow the host processor to retrieve the contents of the OTA buffer starting from the current position (0 initially). The # bytes must be provided as a decimal value.

Example 1:

AT+OTA READ 2       # request 2 bytes of data from the OTA buffer
OK 02 ABAB CK 

Example 2:

AT+OTA READ 256           # request 256 bytes of data from the OTA buffer
OK 100 ABABAB....AB CK

Example 3:

AT+OTA READ 16      # request 16 bytes of data from the OTA buffer
OK 0C ABABAB.. CK   # reached the end of the OTA buffer, only 12 bytes were available

7.2.5 OTA SEEK {address}: Moves the read pointer to an absolute address

This command moves the read pointer to the specified address in the OTA buffer. If no address is specified, the read pointer is moved back to the beginning (0). The # bytes must be provided as a decimal value.

Example 1:

AT+OTA SEEK 1024    # move the read pointer to location 1024
OK 400

Example 2:

AT+OTA SEEK         # move the read pointer back to location 0
OK 0

7.2.6 OTA APPLY: Authorize the ExpressLink module to apply the new image.

When an ExpressLink module OTA image has been downloaded and is ready to be applied, the host processor is notified by an event. When it is appropriate (safe for the application), the host processor should activate the boot command to update its own firmware version. Upon completion, the OTA buffer is emptied, making it available for additional OTA operations. The OTA status is cleared.

Upon successful completion of the boot sequence, the ExpressLink module communicates the new status and firmware revision number to the AWS IoT OTA service. An event is generated to inform the host processor of the process completion result. The host processor must assume that all state and configuration parameters of the module are reset in a way similar to a factory reset command.

7.2.7 OTA CLOSE: The host OTA operation is completed

The host's use of the OTA buffer is terminated and the buffer can be released. The OTA flag is cleared and the operation is reported to the AWS IoT Core as successfully completed.

7.2.8 OTA FLUSH: The contents of the OTA buffer are emptied

The OTA buffer is immediately released. The OTA flag is cleared. Any pending OTA operation is stopped. The OTA operation is reported as failed.

7.3 OTA update jobs

OTA updates are meant to be issued by the customers' fleet managers through the AWS cloud console using the AWS IoT OTA Update Manager service. This is built upon the AWS IoT Jobs service and is designed to allow customers to send updates to selected groups of devices in a fleet. (For more information, see Prerequisites for OTA updates using MQTT in the AWS FreeRTOS User Guide.) The OTA Job creation can be instantiated from the AWS CLI or from the AWS IoT Console.

The OTA Jobs service is generic and can transfer (stream) any type of file to a selected group of devices. Meta-data that communicates the nature of the incoming OTA payload, the file signing method (if used), and a number of additional options are provided by the user and transferred to the ExpressLink module in the form a JSON string. ExpressLink devices require the fileType attribute to be set to values according to Table 5 - Reserved OTA file type codes (0-255) .

[1] Certificates are already hashed and signed, no additional signing is required.

These codes allow the ExpressLink modules that receive them to determine and initiate the corresponding module or host update processes described in this chapter. Different signing rules apply to each type of update/file and the certificates used for the validation of the signatures can themselves be updated.

7.4 Module OTA signature verification

ExpressLink modules are pre-provisioned with a manufacturer's module certificate that is used to validate the signature of firmware update image.

Module OTA jobs include additional meta-data to clearly identify the module's manufacturer, model, and major and minor versions. This allows the ExpressLink executive to discard incorrect OTA images ahead of time to prevent unnecessary downloads.

7.5 Module OTA certificate updates

The certificates used for the module OTA signature validation (not to be confused with the module birth certificate used to authenticate with the AWS cloud) may be accessed (read) by means of the serial API (see the CONF? command). Module OTA certificates may also be updated using the OTA mechanism or using the the serial API:

Example:

AT+CONF OTAcertificate=<x509.pem>2

[2] Some escaping required to accommodate newlines may be present in the certificate (.pem) file.

The new certificate must be signed with the private key corresponding to the previous valid module OTA certificate.

Module OTA certificate updates performed using the OTA mechanism do not require the host to accept the update nor to control its run timing.

Module OTA certificates are NOT deleted upon a factory reset.

7.6 Module OTA override

As described in 7.1.1.1 ExpressLink OTA/HOTA process, the host processor is given ultimate control over the ExpressLink module firmware update process, including whether to accept or reject an incoming image, and control over when the process starts. While this mechanism is meant to prevent scenarios where host and module firmware versions could become incompatible or the module reboot could happen at an inconvenient time (possibly affecting the device functional safety), we must consider cases where a poorly behaved (or too basic) host application might indefinitely prevent an ExpressLink module from being updated to fix a critical bug or an identified security threat. To this end, an additional piece of meta-data that uses the attribute <force:YES> will be provided to bypass the host control and to activate an immediate module firmware update.

7.7 Synchronized Module and Host update sequence

When new capabilities or API changes are introduced by a new ExpressLink module firmware version that potentially has backward compatibility issues (side-effects) affecting the host application, the following recommended update sequence should be applied:

If the host and module fail to stay in step with this sequence, it can be terminated at any point without irreversible consequences and restarted.

7.8 Host OTA updates

Host application updates can be sent to an ExpressLink module using the same OTA mechanisms used for the module's own OTA updates. Thanks to the host OTA feature, ExpressLink modules provide two important services:

7.9 Host OTA Signature Verification

Meta-data provided during OTA Job creation indicates to the module whether the optional signature verification is required.

A host OTA certificate that contains the public key that corresponds to the customer's private host OTA signing key, must be provided by the customer.

The certificates used for the host OTA signature validation are accessible for reading by means of the serial API (see the CONF? command).

7.10 Host OTA certificate update

Host OTA certificates can also be updated using the same OTA mechanism or using the AT command interface. In both cases, the new certificate must be signed with the private key corresponding to the previous valid host OTA certificate. The host OTA certificate can be updated by the module manufacturer (OEM) at the end of the product assembly line using the AT+CONF command, or later using the OTA mechanism by making use of the code indicated in Table 5 - Reserved OTA file type codes (0-255) (Host OTA certificate update).

Host OTA certificate updates performed using the OTA mechanism do not require the host to accept the update nor to control when it is run.

The host OTA certificate is a configuration parameter initially undefined (empty) and cleared at factory reset.

When the host OTA certificate is undefined, the signature verification of an incoming (first) host OTA certificate payload cannot and will NOT be verified.

7.10.1 CONF? {certificate} pem: Special certificate output formatting option

The special qualifier pem can be appended to read a certificate configuration dictionary key (Certificate, OTAcertificate, HOTAcertificate) and produce output in a format that allows the developer to cut and paste the output directly into a standard .pem file for later upload to the AWS IoT dashboard.

Example:

AT+CONF? HOTAcertificate pem

7.10.2 CONF {certificate key}=pem: Special certificate input formatting option

The special value pem can be used to input a certificate (Certificate, OTAcertificate, HOTAcertificate) as a multi-line string to allow the developer to cut and paste directly the content of a standard .pem file.

Example:

AT+CONF HOTAcertificate=pem
-----BEGIN CERTIFICATE-----
MIIDWTCCAkGgAwIBAgIUeKvfYpklvnnattQF09ug9UULjZwwDQYJKoZIhvcNAQEL
BQAwTTFLMEkGA1UECwxCQW1hem9uIFdlYiBTZXJ2aWNlcyBPPUFtYXpvbi5jb20g
...
KHiN1yooauYJKaKr5eJilRAhdYsV2t9X3EFD60/eKmZyD+NE68jAwK/OvokhIGms
cZAj8m0QwqvPkZ0Y2Yc+hPSipQl/hLsg4W/GtbA2MPkTGcvkCBHLYgLBBGpe
-----END CERTIFICATE-----

These command extensions are meant for the developer to use to manually input/output certificates from a terminal application without worrying about escaping the many newline characters contained in a typical .pem file. When a host processor reads or writes to the same certificates, the developer can easily implement the necessary escaping programmatically, resulting in single line (long) strings.

7.11 Server Root Certificate Update

All ExpressLink modules are pre-provisioned with a long-lived AWS server root certificate that is used to validate the endpoint (server) during the TLS connection setup. A new certificate can be provided by means of the AT command interface or the OTA mechanism, using the code indicated in Table 5 - Reserved OTA file type codes (0-255) (Server Root certificate update).

Server root certificate updates performed using the OTA mechanism do not require the host to accept the update nor to control its run timing.

Server Root certificates are NOT deleted upon a factory reset