AWS FOTA

The Amazon Web Services firmware over-the-air (AWS FOTA) library combines the AWS jobs and FOTA download libraries to create a user-friendly library that can perform an over-the-air firmware update using HTTP and MQTT TLS.

It connects to the specified broker using the existing or given certificates and uses TLS for the MQTT connection. This means that the data sent in each MQTT message is encrypted.

Note that other devices that are connected to the same AWS MQTT broker receive the same messages if:

• The other device has valid (but different) certificates that use the same AWS IoT policy as the original device.

• The other device is subscribed to the same MQTT topic as the original device.

The library uses MQTT to receive notification that an update is available, and to retrieve metadata about the update. It uses HTTP to download the update payload.

It is up to the application that uses the library to restart the device when the FOTA is complete.

The AWS FOTA library is used in the nRF9160: AWS FOTA sample.

Configuration

Configure the following parameters when using this library:

• CONFIG_AWS_FOTA_PAYLOAD_SIZE

• CONFIG_AWS_FOTA_HOSTNAME_MAX_LEN

• CONFIG_AWS_FOTA_FILE_PATH_MAX_LEN

Implementation

The following sequence diagram shows how a firmware over-the-air update is implemented through the use of AWS IoT MQTT, AWS IoT jobs, and AWS Simple Storage Service (S3).

Setting up an AWS S3 bucket

The firmware files for download must be stored in a bucket on an AWS S3 server. To do this, set up your own bucket.

When setting up your own bucket, make sure to configure the permissions as shown in the following screenshot:

To update the permissions for an existing bucket, select your bucket and navigate to Permissions > Block public access.

In addition to the permissions, you must configure a bucket policy. To determine a suitable security scheme for your application, see AWS S3 Developer Guide: Using Bucket Policies and User Policies and AWS S3 Developer Guide: Bucket Policy Examples. To configure the policy, select your bucket and navigate to Permissions > Bucket Policy.

For testing purposes, you can use the following, very permissive, bucket policy (replace bucket_name with the name of your bucket):

{    "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Principal": "*",
             "Action": "s3:GetObject",
             "Resource": "arn:aws:s3:::bucket_name/*"
         }
      ]
 }

AWS IoT jobs

The implementation uses a job document similar to the following (where bucket_name is the name of your bucket and file_name is the name of your file) for passing information from AWS IoT jobs to the device:

{
  "operation": "app_fw_update",
  "fwversion": "v1.0.2",
  "size": 181124,
  "location": {
    "protocol": "http:",
    "host": "bucket_name.amazonaws.com",
    "path": "file_name.bin"
   }
}

The current implementation uses information from the host and path fields only.

Limitations

• Currently, the library uses HTTP for downloading the firmware. To use HTTPS instead, apply the changes described in the HTTPS section of the download client documentation to the FOTA download library.

• The library requires a Content-Range header to be present in the HTTP response from the server. This limitation is inherited from the Download client library.

API documentation

Header file: include/net/aws_fota.h

Source files: subsys/net/lib/aws_fota/

group aws_fota

Library for performing FOTA with MQTT and HTTP.

Defines

AWS_FOTA_EVT_DL_COMPLETE_VAL

Typedefs

typedef void (*aws_fota_callback_t)(struct aws_fota_event *fota_evt)

Enums

enum aws_fota_evt_id

Values:

enumerator AWS_FOTA_EVT_START

AWS FOTA has started

enumerator AWS_FOTA_EVT_DONE

AWS FOTA complete and status reported to job document

enumerator AWS_FOTA_EVT_ERROR

AWS FOTA error

enumerator AWS_FOTA_EVT_ERASE_PENDING

AWS FOTA Erase pending

enumerator AWS_FOTA_EVT_ERASE_DONE

AWS FOTA Erase done

enumerator AWS_FOTA_EVT_DL_PROGRESS

AWS FOTA download progress

Functions

int aws_fota_init(struct mqtt_client *const client, aws_fota_callback_t evt_handler)

Initialize the AWS Firmware Over the Air library.

Parameters

• client – Pointer to an initialized MQTT instance.

• evt_handler – Callback function for events emitted by the aws_fota library.

Return values

• 0 – If successfully initialized.

• -EINVAL – If any of the input values are invalid.

Returns

Negative value on error.

int aws_fota_mqtt_evt_handler(struct mqtt_client *const client, const struct mqtt_evt *evt)

AWS Firmware over the air mqtt event handler.

Parameters

• client – Pointer to the mqtt_client instance.

• evt – Pointer to the recived mqtt_evt.

Return values

• 0 – If successful and the application can skip handling this event.

• 1 – If successful but wants the application to handle the event.

Returns

A negative value on error.

int aws_fota_get_job_id(uint8_t *const job_id_buf, size_t buf_size)

Get the null-terminated job id string.

Parameters

• job_id_buf – Buffer to which the job id will be copied.

• buf_size – Size of the buffer.

Returns

Length of the job id string (not counting the terminating null character) or a negative value on error.

struct aws_fota_event_dl

#include <aws_fota.h>

struct aws_fota_event

#include <aws_fota.h>