Cellular: nRF Cloud REST FOTA
The REST FOTA sample demonstrates how to use the nRF Cloud REST API to perform Firmware Over-the-Air (FOTA) updates on your device.
Requirements
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
Board target |
|---|---|---|---|
PCA10153 |
|
||
PCA10090 |
|
||
PCA10171 |
|
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 requires an nRF Cloud account and modem firmware v1.3.x or later for an nRF9160 DK, or modem firmware v2.x.x for the nRF91x1 DKs.
Note
Full modem FOTA requires development kit version 0.14.0 or higher if you are using an nRF9160 DK.
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:
Download the nRF9160 DK board controller firmware from the nRF9160 DK downloads page.
Make sure the PROG/DEBUG SW10 switch on the nRF9160 DK is set to nRF52.
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.
Overview
You can update your device firmware on the nRF Cloud portal or directly through the nRF Cloud REST 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 JWTs with an expiration time.
User interface
If you want to perform an update check immediately, press the button configured by the Kconfig option CONFIG_REST_FOTA_BUTTON_EVT_NUM. This will bypass the wait time specified by the CONFIG_REST_FOTA_JOB_CHECK_RATE_MIN option.
If you have the option CONFIG_REST_FOTA_DO_JITP enabled and you press the button configured by the CONFIG_REST_FOTA_BUTTON_EVT_NUM option when prompted at startup, it will request just-in-time provisioning (JITP) through REST with nRF Cloud. This is useful when initially provisioning and associating a device on nRF Cloud. You only need to do this once for each device.
If you have enabled the CONFIG_REST_FOTA_ENABLE_LED option, an LED configured by the CONFIG_REST_FOTA_LED_NUM option indicates the state of the connection to the LTE network.
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_REST_FOTA_JOB_CHECK_RATE_MIN - Update check rate
This configuration option 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_REST_FOTA_DL_TIMEOUT_MIN - Download timeout value
This configuration option defines how long to wait for a download to complete.
- CONFIG_REST_FOTA_ENABLE_LED - Enable LED
This configuration option defines if the LED will be used to indicate connection to the LTE network.
- CONFIG_REST_FOTA_LED_NUM - Enable LED
This configuration option defines if the LED is to be used.
- CONFIG_REST_FOTA_BUTTON_EVT_NUM - Button number
This configuration option defines the button to use for device interactions.
- CONFIG_REST_FOTA_DO_JITP - Enable prompt to perform JITP using REST
This configuration option defines if the application will prompt the user for just-in-time provisioning on startup.
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_rest_fota 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.
The configuration file for this sample is located in samples/cellular/nrf_cloud_rest_fota.
See Configuring and building for information on how to configure the parameters.
To create a FOTA test version of this sample, add the following parameter to your build command:
-DEXTRA_CONF_FILE=overlay_fota_test.conf
To enable full modem FOTA, add the following parameter to your build command:
-DEXTRA_CONF_FILE=overlay_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=overlay_smp_fota.conf-DEXTRA_DTC_OVERLAY_FILE=nrf9160dk_mcumgr_client_uart2.overlay
The nRF52840 device on your DK must be running an SMP compatible firmware, such as the Cellular: SMP Server sample.
Build the Cellular: SMP Server sample for the nrf9160dk/nrf52840 board with the following parameters:
-DEXTRA_CONF_FILE=overlay_smp_fota.conf-DEXTRA_DTC_OVERLAY_FILE=nrf9160dk_mcumgr_client_uart2.overlay
To change Cellular: SMP Server sample’s application version, set the CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION Kconfig option.
Dependencies
This sample uses the following nRF Connect SDK libraries:
In addition, it uses the following secure firmware component: