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.

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

AWS FOTA sequence diagram for doing FOTA through AWS jobs

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:

Bucket permissions in AWS S3

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

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.

Typedefs

typedef void (*aws_fota_callback_t)(enum aws_fota_evt_id evt_id)

Enums

enum aws_fota_evt_id

Values:

AWS_FOTA_EVT_DONE

AWS FOTA complete and status reported to job document

AWS_FOTA_EVT_ERROR

AWS FOTA error

Functions

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

Initialize the AWS Firmware Over the Air library.

Return

Negative value on error.

Parameters
  • client: Pointer to an initialized MQTT instance.

  • app_version: Current version number of the application as a \0 terminated ASCII string.

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

Return Value
  • 0: If successfully initialized.

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

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

AWS Firmware over the air mqtt event handler.

Return

A negative value on error.

Parameters
Return Value
  • 0: If successful but wants the application to handle the event.

  • 1: If successful and the application can skip handling this event.