8 Over the Air Updates

Note

The OTA service is supported only when the device is in the onboarded state (see 11.3.2 ExpressLink onboarding states and transitions), that is, only when the module is connected to the customer's AWS account.

ExpressLink modules natively support Over The Air (OTA) firmware updates utilizing the AWS IoT OTA service and, locally, using Over the Wire (OTW) updates. 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. This is intended to provide a backup in case of a fatal failure during the update process.

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

1. Without disrupting the Host processor communication, the module starts receiving chunks of the new firmware image.

2. Each chunk is checked for integrity and acknowledged, retried as necessary, and stored in bulk memory.

3. When all chunks are reassembled in bulk memory, the module performs a final signature check.

4. Only if successfully verified, the module notifies the Host processor.

5. Upon receiving an explicit request, the ExpressLink module initiates a reboot.

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

• It makes sure that only valid memory images are accepted.

• The potentially disruptive process of rebooting is performed in agreement with the host processor to avoid impacting the overall product functionality and potential safety hazards.

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 8.2 OTA commands.)

8.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:

8.1.1.1   ExpressLink OTA/HOTA process
ExpressLink module	Host Processor
Receives an event indicating an OTA request and generates an event (also raising the EVENT Pin).
	EVENT? polls the event queue.
Returns OK OTA indicating an OTA event.
	OTA? checks the OTA state.
Returns an OTA or HOTA ready state.
if OTA ready
	When safe, issue an OTA APPLY command to allow the ExpressLink module to update its firmware and reboot (or OTA FLUSH to abort).
If HOTA ready	Retrieve the payload in chunks of appropriate size.
	READ 1024 – Requests the first chunk of payload data.
Delivers first chunk of payload data and advances pointer.
The process repeats until the entire payload is transferred to the host processor. At any point, the Host processor can request a pointer reset or terminate the process altogether.
The module returns a 0 sized chunk, indicating transfer complete.
	CLOSE – indicate to the ExpressLink module that the buffer can now be freed and the process was completed successfully.
The ExpressLink module returns a Job complete notification to the AWS IoT OTA service.

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.

Figure 3 - ExpressLink module OTA state diagram

 

Figure 4 - ExpressLink Host OTA state diagram

 

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

8.2 OTA commands

8.2.1 OTA?   »Fetches the current state of the OTA process«

Returns:

OK {code} {detail}

8.2.2 OTA codes

0	No OTA in progress.
1	A new module OTA update is being proposed. The host can inspect the version number and decide to accept or reject it. The {detail} field provides the version information (string).
2	A new Host OTA update is being proposed. The host can inspect the version details and decide to accept or reject it. The {detail} field provides the metadata that is entered by the operator (string).
3	OTA in progress. The download and signature verification steps have not been completed yet.
4	A new module firmware image has arrived. The signature has been verified and the ExpressLink module is ready to reboot. (Also, an event was generated.)
5	A new host image has arrived. The signature has been verified and the ExpressLink module is ready to read its contents to the host. The size of the file is indicated in the response detail. (Also, an event was generated.)

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

Note

The host has the ultimate say to allow this update to proceed (downloading) by sending the OTA ACCEPT command, or to reject it immediately (if it is deemed incompatible with the host version) by sending the OTA FLUSH command.

8.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.

Returns:

8.2.3.1   OK{EOL}

If a valid request was pending and the host is allowing the OTA operation to commence, the host returns 'OK'.

8.2.3.2   ERR21 INVALID OTA UPDATE

If no OTA update is pending, the host returns 'INVALID OTA UPDATE'.

Example:

AT+OTA?                   # Check the OTA state
OK 0                      # No pending OTA request (host or module)
AT+OTA ACCEPT             # accept the OTA download 
ERR21 INVALID OTA UPDATE  # No OTA pending, nothing there for the host to accept

8.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.

Returns:

8.2.4.1   OK {count} ABABABAB... {checksum}

The byte count is expressed in hex (from 1 to 6 digits), each byte is then presented as a pair of hex digits (no spaces) for a total of count*2 characters followed by a checksum (4 hex digits).

The reading pointer is advanced by count bytes. Count can be less than requested or 0 if the end of the payload was reached. If the count is zero, the data and checksum portion are omitted.

The maximum #bytes a module can read is implementation specific and will be declared by the manufacturer in the device datasheet. If the requested value is greater than the maximum supported by the module, the module will return the maximum value possible.

The checksum is provided as a 16-bit (4 digit hex value) computed as the sum of all data (byte) values returned (modulo 2^16).

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

8.2.4.2   ERR19 HOST OTA IMAGE NOT AVAILABLE

The module returns an error if the OTA buffer is empty, or if it is in use and the download or signature verification processes have not been completed. The host processor should first check the OTA status using the OTA? command.

8.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.

Returns:

OK {address}

If the pointer was successfully moved the module returns 'OK'. The address is returned in hex (from 1 to 6 digits).

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

8.2.5.1   ERR20 INVALID ADDRESS

If the address provided was out of bounds (> OTA buffer content size), then the module returns 'INVALID ADDRESS'.

8.2.5.2   ERR19 HOST OTA IMAGE NOT AVAILABLE

An error is issued if the OTA buffer is empty or in use and the download or signature verification processes have not been completed. The host processor should first check the OTA status using the OTA? command.

8.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.

Returns:

8.2.6.1   OK{EOL}

The module has initiated a boot sequence.

8.2.6.2   ERR19 HOST OTA IMAGE NOT AVAILABLE

An error is returned if the OTA buffer is empty or it is in use and the download or signature verification processes have not been completed. The host processor should first check the OTA status using the OTA? command.

8.2.6.3   ERR21 INVALID OTA UPDATE

The module is unable to apply the new module images (integrity issue or version incompatibility).

8.2.6.4   ERR23 INVALID SIGNATURE

The new image signature check failed.

8.2.6.5   Upon successful completion of the boot sequence, the ExpressLink module communicates the new status and firmware revision number to the AWS IoT OTA service.

8.2.6.6   The event queue is emptied and a STARTUP event is generated to inform the host processor that the process has completed.

8.2.6.7   The host processor should expect all state and configuration parameters of the module to be reset in a way similar to a Reset command (although additional changes may apply and are implementation and firmware version dependent).

8.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.

Returns:

8.2.7.1   OK{EOL}

When the ExpressLink module returns 'OK', it indicates that the command was received correctly, but the actual run sequence (that requires a handshake with the AWS IoT OTA service) can still fail later. In that case, an event is generated to inform the host and help diagnose the problem.

8.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.

Returns:

8.2.8.1   OK{EOL}

When the ExpressLink module returns 'OK', it indicates the command was received correctly, but the actual run sequence (that requires a handshake with the AWS IoT OTA service) can still fail at a later time. In that case, an event will be generated to inform the host and help diagnose the problem.

8.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 service has the following basic requirements:

• Each device must be associated with a policy allowing it to publish and subscribe to the AWS reserved topics for streams/* and jobs/*. This policy will be automatically added to the thing created in the staging account (see the JITP template) and later moved to the customer's account using the AWS IoT API.

• Firmware updates and certificates for ExpressLink modules will only be provided and signed by the module manufacturer. Firmware updates and certificates for the host can be provided and signed by the customer/developer. They will be uploaded to an Amazon S3 bucket before the process is initiated.

• The customer will create an OTA update role to allow the service to operate in the account

• The operator initiating the update process must have an OTA User policy that authorizes them to operate the service.

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. Metadata 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:

Table 5 - Reserved OTA file type codes (0-255)
fileType	Reserved for	Signature	Certificate	Request Host Permission
101	Module firmware update	Signed	Module OTA	Y
103	Module OTA certificate update	Signed1	Module OTA	N
107	Server Root certificate update	Signed1	Server Root	N
202	Host firmware update	Optional	Host OTA	N
204	Host OTA certificate update	Certificates are already hashed and signed, no additional signing is required.	Host OTA	N

[1] Not required if the HostCertificate parameter is empty (factory default).

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.

8.4 Module OTA image signing

ExpressLink module manufacturers may create a new profile with the AWS Code Signing service for each ExpressLink module model they qualify and introduce to production. This profile will then be used exclusively to sign images before distributing them to their customer base (publishing them on a dedicated manufacturer support web page).

For a complete workflow detailing all steps required for the generation of signed image, see Creating an OTA update with the AWS CLI in the FreeRTOS User Guide.

ExpressLink manufacturers are free to choose any signature and hashing algorithms compatible with AWS IoT Core specifications to best match the cryptographic capabilities of their modules. Contact the module manufacturer or check the module manufacturer's datasheet for the algorithms used.

8.5 Module OTA signature verification

In order for ExpressLink modules to validate module OTA updates, they are pre-provisioned by the manufacturer with an OTA certificate that will be used automatically after download to ensure the payload integrity and authenticity.

8.6 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 updated using the OTA mechanism or using the serial API:

• Module OTA certificate updates performed using OTA use the fileType code indicated in Table 5 - Reserved OTA file type codes (0-255) (Module OTA certificate update).

• Module OTA certificate updates performed using the AT+CONF command use the key OTAcertificate.

Example:

AT+CONF OTAcertificate=<x509.pem>2

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

Returns:

8.6.1.1   OK{EOL}

The module returns 'OK' if the new certificate was valid.

8.6.1.2   ERR23 INVALID SIGNATURE

The module returns 'INVALID SIGNATURE' if the new certificate could not be verified.

8.6.1.6   ERR26 INVALID CERTIFICATE

The module returns 'INVALID CERTIFICATE' if the new certificate provided was invalid or corrupted.

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

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

8.6.1.5   Module OTA certificates are NOT affected by a factory reset.

8.7 Module OTA override

As described in 8.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 metadata that uses the attribute <force:YES> will be provided to bypass the host control and to activate an immediate module firmware update.

Note

A forced module OTA update cleans the module OTA buffer (bulk memory), and erases all its contents, potentially including a host payload previously occupying this memory. This is an extremely invasive operation and, as such, should be used only when strictly necessary and with the customer's full understanding of its implications for the host application.

8.8 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:

1. The manufacturer publishes the new module image and documents the incompatibilities.

2. The customer evaluates the opportunity to apply the update to their fleet and its impact on the host application.

3. The customer develops a new host application with old and new ExpressLink module support.

4. A host firmware OTA update is sent to (and accepted by) the host.

5. After rebooting, the host can verify the module current version.

6. An OTA module update must then be offered to the (new) host.

7. The new host can validate the proposed new module version and "allow" the module update.

8. The new host can then switch to the new module API or start using the new feature.

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.

8.9 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:

• The ability to transport and reconstruct a potentially large payload into the OTA buffer (bulk memory space inside the module) making it available for retrieval by the host in small increments to optimize the host memory resources. The payload can be of any nature (for example, pictures, sounds, and video) and could in fact be a bundle itself, composed of multiple files concatenated together.

• The ability to perform an authenticity check, relieving the host of the heavy cryptographical effort required to hash and verify a cryptographical signature. This second feature is optional in this case, because a host application might perform integrity and authenticity checks on its own, using secrets not accessible to the ExpressLink module or using another custom defined protocol.

8.10 Host OTA Signature Verification

Host firmware updates can also optionally have a crypt signature verified by the ExpressLink module after download. Metadata provided during the OTA Job creation (using the AWS IoT Console or the AWS IoT API) informs the module whether the optional signature verification step is required. The developer must then ensure that the host (or other Automated Test Equipment at the end of the production line) sets the HostOTACertificate which provides the required decryption (public) key, otherwise undefined/empty by default.

8.11 Host OTA certificate update

The host OTA certificate can be updated by the customer (OEM) using the AT+CONF command at the end of the product assembly line or later using the OTA mechanism using the code indicated in Table 5 - Reserved OTA file type codes (0-255) . (See the "Host OTA certificate update" entry.)

8.11.1.1   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.

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

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

8.11.2 CONF? {certificate} pem   »Special certificate output formatting option«

The special qualifier pem (case insensitive) can be appended to read a certificate configuration dictionary key (Certificate, HOTAcertificate, RootCA) 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.

Note

The response to this command is an exception to the general format described in 4.6.1 General response formats: because it produces more than one output line.

Example:

AT+CONF? HOTAcertificate pem{EOL}

Returns:

8.11.2.1   OK# pem{EOL}

The command returns 'OK' with the number (#) of additional lines, followed by those additional lines composing the certificate, for example:

OK9 pem
-----BEGIN CERTIFICATE-----
MIIDWTCCAkGgAwIBAgIUeKvfYpklvnnattQF09ug9UULjZwwDQYJKoZIhvcNAQEL
BQAwTTFLMEkGA1UECwxCQW1hem9uIFdlYiBTZXJ2aWNlcyBPPUFtYXpvbi5jb20g
...
KHiN1yooauYJKaKr5eJilRAhdYsV2t9X3EFD60/eKmZyD+NE68jAwK/OvokhIGms
cZAj8m0QwqvPkZ0Y2Yc+hPSipQl/hLsg4W/GtbA2MPkTGcvkCBHLYgLBBGpe
-----END CERTIFICATE----- 

8.11.3 CONF {certificate}=pem   »Special certificate input formatting option«

The special value pem (case insensitive) can be used to input a certificate (OTAcertificate, HOTAcertificate, RootCA) as a multi-line string to allow the developer to directly cut and paste 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-----

Returns:

8.11.3.1   OK{EOL}

The module returns 'OK' if the new certificate was valid.

8.11.3.2   ERR23 INVALID SIGNATURE

The module returns 'INVALID SIGNATURE' if the new certificate could not be verified.

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.

8.12 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).

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

8.12.1.2   Server Root certificates are NOT deleted upon a factory reset

8.13 Over the Wire (OTW) module firmware update command

A direct module firmware update mechanism is offered as a convenient alternative for customers that intend to update module firmware during, or immediately after, the assembly/testing line.

The OTW command allows the host to act as the conduit for a new firmware image to the module through the same interface used for the AT commands. Alternatively, a customer's Automated Testing Equipment can seize control of the interface and take over communication with the module (holding the host processor in RESET).

8.13.1 OTW   »Enter firmware update mode«

When it receives this command, the module enters a custom bootloader interface that allows you to transfer a complete image to the reserved bulk storage memory.

Returns:

8.13.1.1   OK{EOL}

The module is in OTW mode and ready to receive the new firmware image.

8.13.1.2   The actual protocol used to negotiate the transfer of the file is implementation dependent (XMODEM) and must be documented by each vendor in the module datasheet.

8.13.1.3   The OTW process can be terminated at any point by issuing a hardware reset (pulling the RST pin low).

When the transfer is completed, the same firmware integrity, version compatibility and signature verification process described for the module OTA will be applied. At this point, the module returns one of the values shown here:

Returns:

8.13.1.4   OK{EOL}

The image was downloaded successfully. The module will now reboot from the new image in bulk storage.

8.13.1.5   The process will erase all volatile configuration parameters (Topics, PATHs) and re-initialize some of the non-volatile ones in the same way as a Reset command (actual details can be implementation and firmware version dependent).

8.13.1.6   When the boot process completes successfully, the event queue is emptied and a new STARTUP event is generated.

8.13.1.7   ERR21 INVALID OTA UPDATE

If the module is unable to apply the new module images (because of version incompatibility or an integrity check failure), the module returns 'INVALID OTA UPDATE'. The update process is stopped and any OTA memory used is freed.

8.13.1.8   ERR23 INVALID SIGNATURE

If the image signature check fails, the module returns 'INVALID SIGNATURE'. The update process is stopped and any OTA memory used is freed.