Cellular: nRF Cloud CoAP FOTA

The nRF Cloud CoAP FOTA sample demonstrates how to use the nRF Cloud CoAP API to perform Firmware Over-the-Air (FOTA) updates over CoAP on your device. This covers modem, application, and full modem FOTA updates (FMFU). Also, with the nRF9160 DK, it supports SMP FOTA updates to the firmware on the nRF52840 SoC.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
Thingy:91 X	PCA20065	thingy91x	thingy91x/nrf9151/ns
nRF9161 DK	PCA10153	nrf9161dk	nrf9161dk/nrf9161/ns
nRF9160 DK	PCA10090	nrf9160dk	nrf9160dk/nrf9160/ns
nRF9151 DK	PCA10171	nrf9151dk	nrf9151dk/nrf9151/ns

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

The sample requires an nRF Cloud account.

Your device must be onboarded to nRF Cloud. If it is not, follow the instructions in Device on-boarding.

Note

This sample requires modem firmware v1.3.x or later for an nRF9160 SiP and v2.0.0 or later for nRF9161 and nRF9151 SiPs.

External flash

To use the external flash memory on the nRF9160 DK v0.14.0 or later versions, the board controller firmware must be of version v2.0.1. This is the factory firmware version. If you need to program the board controller firmware again, complete the following steps:

1. Download the nRF9160 DK board controller firmware from the nRF9160 DK downloads page.

2. Make sure the PROG/DEBUG SW10 switch on the nRF9160 DK is set to nRF52.

3. Program the board controller firmware (nrf9160_dk_board_controller_fw_2.0.1.hex) using the Programmer app in nRF Connect for Desktop.

Note

The board controller firmware version must be v2.0.1 or higher, which enables the pin routing to external flash.

See Board controller on the nRF9160 DK for more details.

Note

Full modem FOTA requires development kit version 0.14.0 or higher if you are using an nRF9160 DK.

Overview

You can update your device firmware on the nRF Cloud portal or directly through the nRF Cloud CoAP API. See the nRF Cloud Getting Started FOTA documentation for details.

Limitations

This sample requires the network carrier to provide date and time to the modem. Without a valid date and time, the modem cannot generate JSON Web Tokens (JWT) with an expiration time.

User interface

Button 1:

Check for a FOTA update right away without waiting for the timeout.

Setup

You must onboard your device to nRF Cloud for this sample to function. You only need to do this once for each device.

To onboard your device, install nRF Cloud Utils and follow the instructions in the README.

Configuration

See Configuring and building for information about how to permanently or temporarily change the configuration.

Configuration options

Check and configure the following configuration options for the sample:

CONFIG_COAP_FOTA_JOB_CHECK_RATE_MIN - Update check rate

Defines how often the sample checks for FOTA updates. You can modify this value at runtime by adding or updating the "fotaInterval" item in the desired config section of the device’s shadow. Use the nRF Cloud portal or the REST API to perform the config update.

CONFIG_COAP_FOTA_LTE_LED_NUM - LTE LED number

Defines the LED used to indicate the connection to the LTE network.

CONFIG_COAP_FOTA_BUTTON_EVT_NUM - Button number

Defines the button to use for a manual FOTA update check.

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/nrf_cloud_coap_fota in the nRF Connect SDK folder structure.

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

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.

The configuration files for this sample are located in the samples/cellular/nrf_cloud_coap_fota folder. See Configuring and building on how to configure the parameters.

To create a FOTA test version of this sample, change the PATCHLEVEL in the VERSION file.

To enable full modem FOTA, add the following parameter to your build command:

-DEXTRA_CONF_FILE=full_modem_fota.conf

Also, if you are using an nRF9160 DK, specify your development kit version by appending it to the board name. For example, if you are using version 1.0.1, use the board name nrf9160dk@1.0.1/nrf9160/ns in your build command.

To enable SMP FOTA (nRF9160 DK only), add the following parameters to your build command:

• -DEXTRA_CONF_FILE=smp_fota.conf

• -DEXTRA_DTC_OVERLAY_FILE=nrf9160dk_mcumgr_client_uart2.overlay

Once you have flashed your nRF9160 DK, change the switch SW10 to the nRF52 position to be able to flash the nRF52840 firmware on the DK. The nRF52840 device on your DK must be running firmware compatible with SMP, such as the Cellular: SMP Server sample. Otherwise, the CoAP FOTA sample cannot connect to the nRF52840 and will keep trying to connect. Build the Cellular: SMP Server sample for the nrf9160dk/nrf52840 board with the following parameters:

• -DEXTRA_CONF_FILE=overlay-serial.conf

• -DEXTRA_DTC_OVERLAY_FILE=nrf9160dk_nrf52840_mcumgr_svr.overlay

To change Cellular: SMP Server sample’s application version, set the CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION Kconfig option.

Testing

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

1. Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.

2. Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

3. Reset the development kit.

4. Observe in the terminal window that the application starts. This is indicated by output similar to the following (there is also a lot of additional information about the LTE connection):

   *** Booting nRF Connect SDK v3.1.99-7ff1f906b7b0 ***
   *** Using Zephyr OS v4.1.99-2cc69ef97a5c ***
   Attempting to boot slot 0.
   Attempting to boot from address 0x8200.
   I: Trying to get Firmware version
   I: Verifying signature against key 0.
   I: Hash: 0x3e...f9
   I: Firmware signature verified.
   Firmware version 2
   I: Setting monotonic counter (version: 2, slot: 0)
   �[00:00:00.254,821] <inf> spi_nor: GD25LE255E@0: 32 MiBy flash
   *** Booting My Application v1.0.0-7ff1f906b7b0 ***
   *** Using nRF Connect SDK v3.1.99-7ff1f906b7b0 ***
   *** Using Zephyr OS v4.1.99-2cc69ef97a5c ***
   [00:00:00.311,981] <inf> nrf_cloud_fota_sample: nRF Cloud FOTA Sample, version: 1.0.0
   [00:00:00.689,270] <inf> nrf_cloud_fota_common: Saved job: , type: 7, validate: 0, bl: 0x0
   [00:0:00.699,066] <inf> nrf_cloud_fota_sample: Application Name: N/A
   [00:00:00.705,902] <inf> nrf_cloud_fota_sample: nRF Connect SDK version: 3.1.99-7ff1f906b7b0
   [00:00:00.912,902] <inf> nrf_cloud_credentials: Sec Tag: 16842753; CA: Yes, Client Cert: Yes, Private Key: Yes
   [00:00:00.923,309] <inf> nrf_cloud_credentials: CA Size: 1824, AWS: Likely, CoAP: Likely
   [00:00:00.931,854] <inf> nrf_cloud_fota_sample: nRF Cloud credentials detected!
   [00:00:00.939,605] <inf> nrf_cloud_fota_sample: Enabling connectivity...
   +CGEV: EXCE STATUS 0
   +CEREG: 2,"0901","020A7716",7
   %MDMEV: PRACH CE-LEVEL 0
   +CSCON: 1
   +CGEV: ME PDN ACT 0,0
   +CNEC_ESM: 50,0
   %MDMEV: SEARCH STATUS 2
   +CEREG: 5,"0901","020A7716",7,,,"11100000","11100000"
   [00:00:05.376,922] <inf> nrf_cloud_fota_sample: Connected to LTE
   [00:00:05.415,954] <inf> nrf_cloud_fota_sample: Waiting for modem to acquire network time...
   [00:00:08.425,659] <inf> nrf_cloud_fota_sample: Network time obtained
   [00:00:08.432,525] <inf> nrf_cloud_info: Device ID: 7e699894-79b6-11f0-a2b4-db93a314a2aa
   [00:00:08.447,601] <inf> nrf_cloud_info: IMEI:      359400123456789
   [00:00:08.545,837] <inf> nrf_cloud_info: UUID:      7e699894-79b6-11f0-a2b4-db93a314a2aa
   [00:00:08.560,821] <inf> nrf_cloud_info: Modem FW:  mfw_nrf91x1_2.0.2
   [00:00:08.567,657] <inf> nrf_cloud_info: Protocol:          CoAP
   [00:00:08.574,096] <inf> nrf_cloud_info: Download protocol: CoAP
   [00:00:08.580,535] <inf> nrf_cloud_info: Sec tag:           16842753
   [00:00:08.587,341] <inf> nrf_cloud_info: CoAP JWT Sec tag:  16842753
   [00:00:08.594,146] <inf> nrf_cloud_info: Host name:         coap.nrfcloud.com
   [00:00:10.981,414] <inf> nrf_cloud_coap_transport: Request authorization with JWT
   [00:00:11.336,212] <inf> nrf_cloud_coap_transport: Authorization result_code: 2.01
   [00:00:11.344,299] <inf> nrf_cloud_coap_transport: Authorized
   [00:00:11.350,616] <inf> nrf_cloud_coap_transport: DTLS CID is active
   [00:00:12.139,984] <inf> nrf_cloud_fota_sample: Sending device status...
   [00:00:12.565,460] <inf> nrf_cloud_fota_sample: FOTA enabled in device shadow
   [00:00:12.572,998] <inf> nrf_cloud_fota_poll: Checking for FOTA job...
   [00:00:13.205,413] <inf> nrf_cloud_fota_poll: No pending FOTA job
   [00:00:13.211,975] <inf> nrf_cloud_fota_sample: Checking for shadow delta...
   [00:00:13.554,901] <inf> nrf_cloud_log: Changing cloud log level from:1 to:3
   [00:00:13.562,347] <inf> nrf_cloud_log: Changing cloud logging enabled to:1
   [00:00:14.165,435] <inf> nrf_cloud_fota_sample: Desired interval: 5.000000
   [00:00:14.541,442] <inf> nrf_cloud_fota_sample: Updated shadow delta sent
   [00:00:14.548,645] <inf> nrf_cloud_fota_sample: Checking for FOTA job in 5 minute(s) or when button 1 is pressed
   

Dependencies

This sample uses the following nRF Connect SDK libraries:

• nRF Cloud

• nRF Cloud CoAP

• Modem JWT

• LTE link control

• DK Buttons and LEDs

• Modem information

• AT Host

In addition, it uses the following secure firmware component:

• Trusted Firmware-M