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 two image files from a remote server and program them to flash memory.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Build target

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

The sample also requires two signed firmware images that have to be available for download from an HTTP server. The images are generated automatically when building the sample, but you must upload them to a server and configure the location from where they can be downloaded.

Overview

The sample connects to an HTTP server to download one of two signed firmware images:

  • One image has the application version set to 1.

  • The other has the application version set to 2.

The sample updates between the two images, either from version 1 to version 2 or from version 2 to version 1.

By default, the images are saved to the MCUboot second-stage bootloader secondary slot. To be used by MCUboot, the downloaded images must be signed using imgtool.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Configuration options

Check and configure the following Kconfig options:

CONFIG_DOWNLOAD_FILE_V1

This configuration option configures the file name of the version 1 of the update image.

CONFIG_DOWNLOAD_FILE_V2

This configuration option configures the file name of the version 2 of the update image.

Building and running

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

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Specifying the image files

Before building the sample, you must specify where the image files are located. If you do not want to host the files yourself, you can upload them to a public S3 bucket on Amazon Web Services (AWS).

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, perform the following steps:

  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.

Remember to do the following when specifying the filenames:

  • Use the <bucket-name>.s3.<region>.amazonaws.com part of the URL as the hostname of the server hosting the images, without including https://.

  • Specify the file names as the remaining part of the URL.

Follow the steps mentioned in the Specifying the image files section to upload both images.

Testing

After programming the sample to your development kit, test it by performing the following steps:

  1. Upload the file app_update.bin with the application image version 1 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. Remember to rename the file to match the CONFIG_DOWNLOAD_FILE_V1 configuration option.

  2. Configure the application image version to be 2 and rebuild the application.

  3. Upload the file app_update.bin with the application image version 2 to the server you have chosen.

  4. Reset your nRF9160 DK to start the application.

  5. Open a terminal emulator and observe that an output similar to the following is printed:

    ***** Booting Zephyr OS v1.13.99 *****
    
  6. Observe that LED 1 is lit. This indicates that version 1 of the application is running.

  7. Press Button 1 on the nRF9160 DK or type “download” in the terminal emulator to start the download process, and wait until Download complete is printed in the terminal.

  8. Press the RESET button on the kit or type “reset” in the terminal emulator. MCUboot will now detect the downloaded image and program it to flash memory. This can take up to a minute. Nothing is printed in the terminal while the writing is in progress.

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

  10. You can now downgrade the application by repeating the button presses or typing “download” in the terminal emulator. Observe that after the second update only LED 1 is lit. This indicates that the application image has been downgraded to version 1. Any further updates will toggle between the versions.

Dependencies

This sample uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib library:

It uses the following Zephyr libraries:

It also uses the MCUboot bootloader.

In addition, it uses the following secure firmware component: