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:
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¶
include/net/aws_fota.h
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
-
enumerator
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.
- Returns 0
If successfully initialized.
- Returns -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.
- Returns 0
If successful and the application can skip handling this event.
- Returns 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>
-