Cellular: nRF Cloud MQTT FOTA

The nRF Cloud MQTT FOTA sample demonstrates how to use the nRF Cloud MQTT API to perform Firmware Over-the-Air (FOTA) updates over MQTT 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 present on the DK board (not a separate device).

When using MQTT, the FOTA update support is almost entirely implemented by enabling the CONFIG_NRF_CLOUD_FOTA option, which is implicitly enabled by CONFIG_NRF_CLOUD_MQTT.

However, even with the CONFIG_NRF_CLOUD_FOTA Kconfig option enabled, applications must still reboot themselves manually after FOTA download completion, and must still update their Device Shadow to reflect FOTA support.

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 onboarding.

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 MQTT API. See the nRF Cloud Getting Started FOTA documentation for details.

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_CLOUD_CONNECTION_RETRY_TIMEOUT_SECONDS

(int) Cloud connection retry timeout (seconds)

If connecting to nRF Cloud takes longer than this timeout, it will be reattempted.

CONFIG_CLOUD_READY_TIMEOUT_SECONDS

(int) Cloud readiness timeout (seconds)

If the connection to nRF Cloud does not become ready within this timeout, the sample will reset its connection and try again.

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_mqtt_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_mqtt_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 target. For example, if you are using version 0.14.0, use the board target nrf9160dk@0.14.0/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 MQTT FOTA sample cannot connect to the nRF52840 and will keep trying to connect. Build the Cellular: SMP Server sample for the nrf9160dk/nrf52840 board target 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 My Application v1.0.0-f135319f826e ***
   *** Using nRF Connect SDK v3.1.99-f135319f826e ***
   *** Using Zephyr OS v4.2.99-be1a9fd0eeca ***
   [00:00:00.255,889] <inf> nrf_cloud_mqtt_fota: nRF Cloud MQTT FOTA Sample, version: 1.0.0
   [00:00:00.255,920] <inf> nrf_cloud_mqtt_fota: Reset reason: 0x1
   [00:00:00.828,735] <inf> nrf_cloud_credentials: Sec Tag: 16842753; CA: Yes, Client Cert: Yes, Private Key: Yes
   [00:00:00.828,765] <inf> nrf_cloud_credentials: CA Size: 1824, AWS: Likely, CoAP: Likely
   [00:00:00.828,796] <inf> nrf_cloud_mqtt_fota: nRF Cloud credentials detected!
   [00:00:00.829,589] <inf> nrf_cloud_mqtt_fota: Enabling connectivity...
   +CGEV: EXCE STATUS 0
   +CEREG: 2,"81A6","03229B10",7
   %MDMEV: PRACH CE-LEVEL 0
   +CSCON: 1
   +CGEV: ME PDN ACT 0
   %MDMEV: SEARCH STATUS 2
   +CEREG: 1,"81A6","03229B10",7,,,"11100000","11100000"
   [00:00:02.471,496] <inf> nrf_cloud_mqtt_fota: Connected to LTE
   +CGEV: IPV6 0
   [00:00:05.473,724] <inf> nrf_cloud_info: Device ID: 12345678-1234-5678-9abc-def012345678
   [00:00:05.474,395] <inf> nrf_cloud_info: IMEI:      359404230026479
   [00:00:05.474,575] <inf> nrf_cloud_info: UUID:      12345678-1234-5678-9abc-def012345678
   [00:00:05.474,822] <inf> nrf_cloud_info: Modem FW:  mfw_nrf91x1_2.0.3
   [00:00:05.474,853] <inf> nrf_cloud_info: Protocol:          MQTT
   [00:00:05.474,884] <inf> nrf_cloud_info: Download protocol: HTTPS
   [00:00:05.474,884] <inf> nrf_cloud_info: Sec tag:           16842753
   [00:00:05.474,914] <inf> nrf_cloud_info: Host name:         mqtt.nrfcloud.com
   [00:00:05.474,945] <inf> nrf_cloud_mqtt_fota: Connecting to nRF Cloud...
   [00:00:08.681,701] <inf> nrf_cloud_mqtt_fota: Connection to nRF Cloud ready
   [00:00:08.681,793] <inf> nrf_cloud_info: Team ID:   12345678-1234-5678-9abc-def012345670
   

Dependencies

This sample uses the following nRF Connect SDK libraries:

• nRF Cloud

• LTE link control

• DK Buttons and LEDs

• Modem information

• AT Host

In addition, it uses the following secure firmware component:

• Trusted Firmware-M