Cellular: 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 kits:

Hardware platforms	PCA	Board name	Board target
nRF9161 DK	PCA10153	nrf9161dk	`nrf9161dk/nrf9161/ns`
nRF9160 DK	PCA10090	nrf9160dk	`nrf9160dk/nrf9160/ns`
nRF9151 DK	PCA10171	nrf9151dk	`nrf9151dk/nrf9151/ns`

When built for a board target with the */ns variant, 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 Cellular: LwM2M carrier sample to write the certificates to modem before flashing the HTTP application update sample, or use the Cellular: AT Client sample as explained in preparing the Cellular: 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 Cellular: 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 and building 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.

Sending traces over UART on an nRF91 Series DK 

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

Building and running 

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

When built as firmware image for a board target with the */ns variant, 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, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

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 image file, you can 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 nRF91 Series 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 nRF91 Series DK or type “download” in the terminal emulator to start the download process, and wait until Download complete is printed in the terminal.
Press Button 1 on the nRF91 Series DK or type “apply” in the terminal emulator to reboot and apply the update. MCUboot now detects 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