nRF9160: HTTP application update

Requirements
Overview
- Using the LwM2M carrier library
Configuration
- Configuration options
Building and running
Dependencies

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.

Using the LwM2M carrier library 

The application supports the nRF Connect SDK LwM2M carrier library that you can use to connect to the operator’s device management platform. See the library’s documentation for more information and configuration options.

To enable the LwM2M carrier library, add the parameter -DOVERLAY_CONFIG=overlay-carrier.conf to your build command.

The CA root certificates that are needed for modem FOTA are not provisioned in the HTTP application update sample. You can flash the nRF9160: LwM2M carrier sample to write the certificates to modem before flashing the HTTP application update sample, or use the nRF9160: AT Client sample as explained in Preparing the nRF9160: LwM2M Client sample for production. It is also possible to modify the HTTP application update sample project itself to include the certificate provisioning, as demonstrated in the nRF9160: LwM2M carrier sample.

int lwm2m_carrier_event_handler(const lwm2m_carrier_event_t *event)
{
        switch (event->type) {
        case LWM2M_CARRIER_EVENT_INIT:
                carrier_cert_provision();
        ...

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:

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:

Go to AWS S3 console and sign in.
Go to the bucket you have created.
Click Upload and select the file app_update.bin. It is located in the zephyr subfolder of your build directory.
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:

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.
Configure the application image version to be 2 and rebuild the application.
Upload the file app_update.bin with the application image version 2 to the server you have chosen.
Reset your nRF9160 DK to start the application.
Open a terminal emulator and observe that an output similar to the following is printed:
```
***** Booting Zephyr OS v1.13.99 *****
```
Observe that LED 1 is lit. This indicates that version 1 of the application is running.
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.
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.
Observe that LED 1 and LED 2 are lit. This indicates that version 2 or higher of the application is running.
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:

FOTA download

It uses the following sdk-nrfxlib library:

Modem library

It uses the following Zephyr libraries:

It also uses the MCUboot bootloader.

In addition, it uses the following secure firmware component:

Trusted Firmware-M