Skip to main content

Getting started with firmware over-the-air

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 provisioned, 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 any previous version.

Getting started

Devices can access the FOTA service through MQTT or REST.

ProtocolAuthenticationKey differences
MQTTMutual TLSRequires cloud and certificate provisioning.
RESTJSON Web Token (JWT)Requires cloud provisioning, but not certificate provisioning if FOTA is used through the REST API only.

MQTT preparations

When accessing the FOTA service through MQTT:

  1. Create device certificate.

  2. Provision the device to your account.

  3. Enable the CONFIG_NRF_CLOUD_MQTT 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 preparations

When accessing the FOTA service through REST:

  1. Create device certificates.

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

  2. Provision the device to your account.

    If you use the ProvisionDevices endpoint, you can provide the supported FOTA types during provisioning 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 be signed with either the private key used to sign the device certificate, or registered with the RegisterPublicKeyss 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 provisioning.

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

Performing a FOTA update through the REST API

To perform a FOTA update using the REST API:

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

  2. Create a FOTA job using CreateFOTAJob 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.

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

  4. Check the execution status with FetchFOTAJob.

Performing a FOTA update in the nRF Cloud portal

Follow the steps in this section to perform a FOTA update through the nRF Cloud portal:

  1. Log in to nRF Cloud.
  2. Open the Device Management > Devices page.
  3. Select one or more devices that have FOTA enabled.
  4. In the Actions menu above your devices, select Add to Group.
  5. Follow the instructions in the dialog to create a group and add your devices to it.

Once the target devices are in a group, create and upload a firmware bundle. This 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:

  1. Go to the Device Management > Firmware Updates page.
  2. In the Bundles card, click the three-dot menu and select New Bundle. A pop-up appears.
  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:

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

    If you have already created an update, the card shows your update history instead of the Create Update button.

  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.

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

    A page opens showing update status and progress.

  4. If you did not deploy the update when you created it, you can deploy it at any time from this page using the Deploy update button.

The progress indicators show each job execution.