nRF9160: HTTP application update

The HTTP application update sample demonstrates how to do a basic firmware over-the-air (FOTA) 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 the MCUboot bootloader secondary slot. To be used by MCUboot, the downloaded image must be signed using imgtool.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Build target

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

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.

You can also configure it to use TF-M instead of Secure Partition Manager.

Building and running

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

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

The sample is built as a non-secure firmware image for the nrf9160dk_nrf9160_ns 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 by configuring the following Kconfig options:

  • CONFIG_DOWNLOAD_HOST - it specifies the hostname of the server where the image file is located.

  • CONFIG_DOWNLOAD_FILE - it specifies the name of the image file.

To configure these Kconfig options, follow these steps:

  1. Select Project > Configure nRF Connect SDK Project.

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

  3. Click Configure to save the configuration.

If you do not want to host the image file, you can also upload it to a public S3 bucket on Amazon Web Services (AWS).

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

To upload the file to a public S3 bucket, do the following:

  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. It is 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.

You can then configure the CONFIG_DOWNLOAD_HOST and CONFIG_DOWNLOAD_FILE options as mentioned in the Specifying the image file section, noting the following:

  • Use the <bucket-name>.s3.<region>.amazonaws.com part of the URL for the download hostname. Do not include https://.

  • Use the remaining part of the URL as the file name.

Testing

After programming the sample to your development kit, 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 app_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 app_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 kit. 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 nRF Connect SDK libraries:

It uses the following sdk-nrfxlib library:

It uses the following Zephyr libraries:

Also, it uses the following MCUboot library: