AWS FOTA

The Amazon Web Services firmware over-the-air (AWS FOTA) library combines the AWS jobs and FOTA download libraries into a library that can perform an over-the-air firmware update using HTTP and HTTPS.

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.

When an update is available, the library receives a notification that contains metadata about the update. This metadata contains the location of the uploaded firmware image. The library then uses HTTP or HTTPS to download the firmware image, replacing the current firmware with the downloaded firmware. After the new firmware image is downloaded, the application must perform a reboot to run the new image and complete the FOTA process. The library supports the updating of delta images for both the application and modem firmware.

See AWS FOTA implementation for information about the download procedure, and AWS IoT Developer Guide for general information about the Amazon Web Services IoT service.

Requirements

The library requires an AWS account with access to Simple Storage Service (S3) and the IoT Core service.

Creating a FOTA job

1. Go to AWS S3 console and sign in.

2. Click Create bucket and select a name.

3. Uncheck Block all public access under the Block Public Access settings for this bucket label.

4. Scroll down and click Create bucket.

5. Click the newly created bucket, select Permissions and insert the following permissive policy under Bucket Policy:

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

   Replace the bucket_name with the name of your bucket.

Note

The policy example is only intended for development environments. AWS Best Practices recommends that the principal is specified in the Bucket Policy to prevent anonymous users access to S3. For more information, refer to the example policies listed in AWS IoT Core policy examples and Security best practices in AWS IoT Core.

1. Click Objects to go back to the bucket.

2. Click Upload and Add files.

3. Select the file app_update.bin (located in the zephyr subfolder of your build directory).

   If you want to update the modem firmware, extract the content of a downloaded modem firmware zip and select the desired delta update, for example mfw_nrf9160_update_from_1.3.1_to_1.3.2. The various modem firmware versions can be found in nRF9160 DK Downloads.

4. Click Upload and then Close.

5. Click the uploaded image file app_update.bin and copy the Object URL without the https:// prefix and folder path.

6. Create a text file (job document) with content as in the snippet, replacing the following data:

   • protocol with either http or https.

   • host_url with the Object URL copied in the previous step (for example, examplebucket.s3.eu-central-1.amazonaws.com).

   • file_path with the path and file name (for example, app_update.bin).

   {
     "operation": "app_fw_update",
     "fwversion": "v1.0.2",
     "size": 181124,
     "location": {
       "protocol": "protocol",
       "host": "host_url",
       "path": "file_path"
      }
   }

   To use a single URL, such as when using presigned AWS S3 URLs, see AWS IoT jobs. See AWS IoT Developer Guide: Jobs for more information about AWS jobs.

7. In the AWS S3 console Select the bucket, click Upload, and upload your job document. You must now have two files in your bucket, the uploaded image and the job document.

8. Log in to the AWS IoT console.

9. Go to Manage -> Remote actions-> Jobs, and select Create job.

10. Click Create custom job, enter a unique job name and select your Thing.

11. Click Browse S3 and locate the job document.

12. Click Next.

13. Select Snapshot under Job run type

14. Click the Submit button.

After the job has been submitted, the device picks up the job automatically. This can take several minutes. In the AWS S3 console you can check the status of the job to confirm that it is in progress.

Troubleshooting

ERROR: -NRF_ECONNREFUSED:

Error -NRF_ECONNREFUSED (“Connection refused”) indicates an error with the configured certificates.

ERROR: -NRF_EHOSTUNREACH:

Error -NRF_EHOSTUNREACH (“Host is unreachable”) indicates that the download URL provided in the job document is wrong.

Content range is not defined:

If you host the firmware image on a different server than in an S3 bucket, this error indicates that the Content-Range field is missing in the HTTP GET header. To fix this problem, configure the host server to provide this field. Also, confirm that your file is available from the browser without being logged into your AWS account.

Configuration

Configure the following parameters when using this library:

• CONFIG_AWS_FOTA_PAYLOAD_SIZE - Sets the maximum payload size for AWS IoT job messages.

• CONFIG_AWS_FOTA_DOWNLOAD_SECURITY_TAG - Sets the security tag to be used in case of HTTPS downloads.

Additionally, configure the Download client library:

• CONFIG_DOWNLOAD_CLIENT_MAX_HOSTNAME_SIZE - Sets the maximum length of the host name for the download client.

• CONFIG_DOWNLOAD_CLIENT_MAX_FILENAME_SIZE - Sets the maximum length of the file name for the download client.

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 Firmware Over-the-Air

Important

Other devices that are connected to the same AWS MQTT broker receive the same messages if the following conditions are met:

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

AWS IoT jobs

The implementation uses a job document like the following (where protocol is either http or https, 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": "protocol",
    "host": "bucket_name.amazonaws.com",
    "path": "file_name.bin"
   }
}

Alternatively, to use a single URL, a document like the following can be used:

{
  "operation": "app_fw_update",
  "fwversion": "v1.0.2",
  "size": 181124,
  "location": {
    "url": "url"
   }
}

For information on how to use presigned AWS S3 URLs, refer to AWS IoT Developer Guide: Managing Jobs.

Limitations

• If the CONFIG_AWS_FOTA_DOWNLOAD_SECURITY_TAG Kconfig option is not configured but HTTPS is selected as the protocol, the update job fails. For further information about HTTPS support, refer to the HTTPS section of the download client documentation.

• 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. Payload of type dfu_target_image_type (image).

If the image parameter type is of type DFU_TARGET_IMAGE_TYPE_MCUBOOT the device needs to reboot to apply the new application image.

If the image parameter type is of type DFU_TARGET_IMAGE_TYPE_MODEM_DELTA the modem needs to be reinitialized to apply the new modem image.

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 received 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>