Updating device firmware

This guide shows how to use the nRF Cloud firmware over-the-air (FOTA) update service.

Requirements

• An nRF Cloud account.
• Any of Nordic Semiconductor's nRF91 Series DKs.
• A project based on nRF Connect SDK using the latest version compatible with your device is recommended.

Considerations

• nRF9160 SiPs using the nRF Cloud FOTA service through the REST API must use modem firmware v1.3.x, which has its own hardware requirements.

• Delta updates to the modem firmware v1.3.x from a previous version are not supported on nRF9160 SiP. It requires a wired connection or Full Modem Firmware Update (FMFU).

• FOTA for application and delta updates has been extensively supported since the early nRF Connect SDK versions. However, the latest nRF Connect SDK release is recommended to get all features.

Getting started

Devices can access the FOTA service through CoAP, REST and MQTT.

Protocol	Authentication	Key differences
CoAP	Datagram Transport Layer Security (DTLS)	Requires onboarding and certificate injection.
REST	JSON Web Token (JWT)	Requires onboarding, but not certificate injection if FOTA is used through the REST API only.
MQTT	Mutual TLS	Requires onboarding, but not certificate injection if FOTA is used through the CoAP API only.

Choose a tab for more information according to your protocol.

CoAP prerequisites for FOTA

When accessing the FOTA service through CoAP:

1. Create device certificates.

2. Onboard the device to nRF Cloud.

3. Enable the CONFIG_NRF_CLOUD_FOTA_POLL Kconfig option to enable FOTA functionality in the application.

   For more information, including supported FOTA types, see Firmware over-the-air (FOTA) updates in the nRF Cloud library documentation for nRF Connect SDK.

4. Provide the supported FOTA types to nRF Cloud by writing a fota_v2 field containing an array of FOTA types into the serviceInfo field in the device's shadow.

For more information, see Device shadows and the FOTA update documentation linked in the previous step.

REST prerequisites for FOTA

When accessing the FOTA service through REST:

1. Create device certificates.

   If you only use the REST API, you do not need to inject the certificates to your device.

2. Onboard the device to nRF Cloud.

   If you use the OnboardDevice endpoint, you can provide the supported FOTA types during onboarding instead of Step 5.

3. Enable the CONFIG_NRF_CLOUD_FOTA_POLL Kconfig option to enable FOTA functionality in the application.

   For more information, including supported FOTA types, see Firmware over-the-air (FOTA) updates in the nRF Cloud library documentation for nRF Connect SDK.

4. To make REST calls, configure a nrf_cloud_rest_context structure as described in the nRF Cloud REST library.

5. Create a JSON Web Token (JWT) for your device. The JWT must either be signed with the private key used to sign the device certificate, or registered with the RegisterPublicKeys endpoint.

   See authentication for the REST API for more information.

6. Provide the supported FOTA types to nRF Cloud by writing a fota_v2 field containing an array of FOTA types into the serviceInfo field in the device's shadow. You do not need to do this if you provided the supported types during onboarding.

   For more information, see Device shadows in nRF Cloud documentation, and Firmware over-the-air (FOTA) updates in the nRF Cloud library documentation for the nRF Connect SDK.

MQTT prerequisites for FOTA

When accessing the FOTA service through MQTT:

1. Create device certificate.

2. Onboard the device to nRF Cloud.

3. Enable the CONFIG_NRF_CLOUD_MQTT Kconfig option to enable FOTA functionality in the application.

   For more information, including supported FOTA types, see Firmware over-the-air (FOTA) updates in the nRF Cloud library documentation for nRF Connect SDK.

4. Provide the supported FOTA types to nRF Cloud by writing a fota_v2 field containing an array of FOTA types into the serviceInfo field in the device's shadow.

For more information, see Device shadows and the FOTA update documentation linked in the previous step.

Once you have met the requirements for your protocol, you can create and initiate FOTA updates using either the nRF Cloud portal or APIs.

Performing a FOTA update in the nRF Cloud portal

This section explains how to update devices through FOTA using the nRF Cloud portal.

Creating a device group

Define the scope of the update job by creating a group containing the target devices. If your target devices are already in a group, you can skip this step.

Creating a FOTA bundle

The firmware bundle consists of the manifest and binary update file or files in a compressed zip folder. See the UploadFirmware API reference for an example of an update manifest.

If you have created a bundle already, you can skip these steps.

To create a FOTA bundle:

1. Go to the Device Management > Firmware Updates page.

2. In the Bundles card, click the + symbol and select New Bundle.

   A pop-up opens.

3. Specify the required update type, unique name, version, and optional description.

4. Drag and drop the bundle file or click the box to select a file in the file explorer.

5. Click Create/Upload Bundle. The bundle now appears in the Bundles card.

Create and deploy the update job

Once you have a firmware bundle, create and deploy the update job:

1. Click the Create Update button in the upper right corner of the Firmware Updates page.

2. Select the target device group and firmware bundle.

   Select the Deploy now checkbox to deploy the update at the same time as creating it.

   You can also leave this option unselected and deploy later from this page using the Deploy update button.

3. Click the Create Update button. This adds the update job to the Updates card.

   A page opens showing update status, with progress indicators for each job execution.

You can also see an overview of all your update jobs from the Firmware Updates page.

Performing a FOTA update through nRF Cloud Utils

nRF Cloud Utils is collection of scripts for interfacing with nRF Cloud. This section explains how to execute a FOTA job using the nrf_cloud_device_mgmt script.

Prerequisites

• nRF Cloud Utils installed as described in its github project.
• Device(s) with FOTA enabled onboarded to nRF Cloud.
• An nRF Cloud API key. You can find your API key on your nRF Cloud User Account page.

Execution Modes

The script can run in two modes:

• Non-interactive: Executes immediately without prompts if all required information is provided through command-line arguments. This requires the following arguments:

  • --api-key <your_api_key>
  • --name <job_name> (A descriptive name for the FOTA job)
  • --desc <job_description> (A description for the FOTA job)
  • --bundle-id <firmware_bundle_id> (The ID of the firmware bundle previously uploaded to nRF Cloud)
  • One of the following target arguments:
    • --tag <tag_name> (Targets all devices associated with this tag)
    • --dev-id <device_id> (Targets a single specific device ID)

• Interactive: If any of the required arguments for non-interactive mode (excluding --api-key) are omitted, the script will prompt you step-by-step to enter the necessary information (job name, description, bundle selection, target device/tag selection).

note

By default, the script automatically attempts to apply the created FOTA job to the target device(s). However, you can create the job definition without immediately applying it by adding the --defer-apply flag. You can then manually trigger the update later using the ApplyFOTAJob API endpoint or directly from the Firmware Updates dashboard on nRF Cloud.

Examples

• Create and apply a FOTA job non-interactively for a specific device:

  nrf_cloud_device_mgmt --api-key $API_KEY --name "MyModemUpdateV2" --desc "Update modem firmware to v2.0" --bundle-id "fw-modem-v2.0-bundle-id" --dev-id "nrf-XXXXXXXXXXXXXX"

• Create (but do not apply) a FOTA job non-interactively for all devices with a specific tag:

  nrf_cloud_device_mgmt --api-key $API_KEY --name "MyAppUpdateV1.1" --desc "App core update v1.1 for beta testers" --bundle-id "fw-app-v1.1-bundle-id" --tag "beta-testers" --defer-apply

• Create a FOTA job interactively (will prompt for details):

  nrf_cloud_device_mgmt --api-key $API_KEY

Output

If the FOTA update job is created successfully, the script will print the job id. You can use this job id to manage or query the job status using other nRF Cloud FOTA REST API endpoints, such as FetchFOTAJob.

Performing a FOTA update through the REST API

To perform a FOTA update using the REST API:

1. Define the target device group.

2. Create a firmware bundle using UploadFirmware.

   See the reference documentation for more information about bundle format requirements and an example of a manifest. Note the bundle ID.

3. Create a FOTA job using the CreateFOTAJob endpoint with the following JSON-formatted data in the message body:

   • Firmware bundle ID
   • Tags (group name)
   • Job name
   • Job description

   Include "autoApply": "true" to begin the deployment at the same time as the job is created.

4. Deploy the FOTA job with ApplyFOTAJob.

   This initiates the job execution. If you included "autoApply": "true" in your call to create a FOTA job, you do not need to initiate the job execution separately.

5. Check the execution status with FetchFOTAJob.