nRF9160: HTTP application update

The HTTP application update sample demonstrates how to do a basic FOTA (firmware over-the-air) update. It uses the FOTA download library to download a file from a remote server and write it to flash.

Overview

The sample connects to an HTTP server to download a signed firmware image. The image is generated when building the sample, but you must upload it to a server and configure where it can be downloaded. See Specifying the image file for more information.

By default, the image is saved to MCUboot bootloader secondary slot. The downloaded image must be signed for use by MCUboot with imgtool.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Build target

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160ns

The sample also requires a signed firmware image that is available for download from an HTTP server. This image is automatically generated when building the application.

The sample is configured to compile and run as a non-secure application on nRF91’s Cortex-M33. Therefore, it automatically includes the Secure Partition Manager that prepares the required peripherals to be available for the application.

Building and running

This sample can be found under samples/nrf9160/http_application_update in the nRF Connect SDK folder structure.

See Building and programming a sample application for information about how to build and program the application.

The sample is built as a non-secure firmware image for the nrf9160dk_nrf9160ns build target. Because of this, it automatically includes the Secure Partition Manager. The sample also uses MCUboot, which is automatically built and merged into the final HEX file when building the sample.

Specifying the image file

Before building the sample, you must specify where the image file will be located. If you do not want to host it yourself, you can upload it to a public S3 bucket on Amazon Web Services (AWS). See Setting up an AWS S3 bucket for instructions.

To specify the location in SEGGER Embedded Studio:

  1. Select Project -> Configure nRF Connect SDK Project.

  2. Navigate to HTTP application update sample and specify the download host name (CONFIG_DOWNLOAD_HOST) and the file to download (CONFIG_DOWNLOAD_FILE).

  3. Click Configure to save the configuration.

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/*"
         }
      ]
 }

Hosting your image on an AWS S3 Server

  1. Go to AWS S3 console and sign in.

  2. Go to the bucket you have created.

  3. Click Upload and select the file app_update.bin (located in the zephyr subfolder of your build directory).

  4. Click the file you uploaded in the bucket and check the Object URL field to find the download URL for the file.

When specifying the image file, use the <bucket-name>.s3.<region>.amazonaws.com part of the URL for the download hostname. Make sure to not include the https. Specify the rest of the URL as file name.

Testing

After programming the sample to the board, test it by performing the following steps:

  1. Configure the application version to be 2. To do so, either change CONFIG_APPLICATION_VERSION to 2 in the prj.conf file, or select Project -> Configure nRF Connect SDK Project -> HTTP application update sample in SEGGER Embedded Studio and change the value for Application version. Then rebuild the application.

  2. Upload the file update.bin to the server you have chosen. To upload the file on nRF Cloud, click Upload for the firmware URL that you generated earlier. Then select the file update.bin and upload it.

  3. Reset your nRF9160 DK to start the application.

  4. Open a terminal emulator and observe that an output similar to this is printed:

    SPM: prepare to jump to Non-Secure image
***** Booting Zephyr OS v1.13.99 *****

  5. Observe that LED 1 is lit. This indicates that version 1 of the application is running.

  6. Press Button 1 on the nRF9160 DK to start the download process and wait until “Download complete” is printed in the terminal.

  7. Press the RESET button on the board. MCUboot will now detect the downloaded image and write it to flash. This can take up to a minute and nothing is printed in the terminal while this is processing.

  8. Observe that LED 1 and LED 2 is lit. This indicates that version 2 or higher of the application is running.

Dependencies

This sample uses the following libraries:

From nRF Connect SDK
From nrfxlib
From Zephyr
From MCUboot