Skip to content

Updating device firmware

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

Requirements

This guide is written for devices using the nRF9160 SiP. Devices using the nRF Cloud FOTA service must be onboarded, but are not required to use MQTT.

Thingy:91 and nRF9160 DK devices are factory programmed with older versions of Asset Tracker v1 and modem firmware. Asset Tracker v1 is now deprecated. To update devices using the nRF Cloud FOTA service, you must first program a version of Asset Tracker v2 (or another nRF Cloud FOTA-enabled application) based on the nRF Connect SDK v1.5.0 or later.

Precompiled images for the Thingy:91 and nRF9160 DK are available.

Note

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

You cannot use the nRF Cloud FOTA service to upgrade to modem firmware v1.3.x from a previous version. Updating to v1.3.x requires a wired connection.

Getting started

Devices can access the FOTA service through MQTT or REST.

Protocol Authentication Key differences
MQTT Mutual TLS 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.

Choose a tab for more information according to your protocol.

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.

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 ProvisionDevices endpoint, you can provide the supported FOTA types during onboarding instead of Step 5.

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

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

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

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.

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.