Skip to main content

Firmware update over-the-air

The nRF Cloud firmware-over-the-air (FOTA) update service lets you update your device's firmware wirelessly. If you want to update your firmware over a wired connection, use nRF Connect for Desktop. See Updating the DK firmware for an example of the update process.

This page explains concepts related to nRF Cloud FOTA. See Getting started with the FOTA service for a tutorial.

Jobs

The following terms relate to FOTA jobs:

  • Job: The highest level representation of a FOTA job. Holds overall state. Contains the job document and target, along with the overall status and aggregate statistics about its contained executions.
  • Job document: Holds information about the firmware deployed as part of a job. Includes firmware version and type along with links to the actual file.
  • Job target: Specifies which devices the job can deploy to. Can include both a set of device groups (also referred to as tags in code examples and API reference documents) and an explicit list of device identifiers.
  • Job execution: FOTA job as it relates to an individual device. One execution is created for every eligible device specified in the job target.

Firmware types

You can deploy the following firmware types to a device:

  • APP: Updates the application firmware.
  • MODEM: Updates modem firmware with a delta image.
  • MDM_FULL: Overwrites the existing modem firmware and replaces it entirely.
  • BOOT: Updates the MCUboot secondary bootloader on the nRF9160 SiP.
  • SOFTDEVICE: Updates a Bluetoothยฎ Low Energy (LE) device.
  • BOOTLOADER: Updates bootloader firmware on a Bluetooth LE device. Only for firmware built with the nRF5 SDK.
note

Note: The operation of deploying an update is referred to as applying in the REST APIs and some application code.

FOTA job life cycle

The following figure shows the FOTA job life cycle.

FOTA job life cycle

Job states

This section defines FOTA job states.

CREATED

Description: A job starts in the CREATED state. This means that its initial information has been saved, including the job target and job document. Once a job has been created, these fields cannot be changed. However, the job target is not resolved immediately: you can change the devices that a job deploys to by adding devices to device groups (tags) or removing them from the groups.

Transitions:

IN_PROGRESS

Description: Execution rollout of the requested update has started.

Transitions:

COMPLETED

Description: All executions have reached a terminal status.

Transitions:

CANCELLED

Description: Job not executed.

Transitions:

DELETE_IN_PROGRESS

Description: Internal state that means the job record will be deleted. Deleted jobs do not show in your job list.

Job execution life cycle

Job execution states track the progress of individual job executions. Aside from the initial status of QUEUED, progression is entirely based on updates from the device through either MQTT or the REST API.

FOTA job execution life cycle

Pending states

Pending states are used to track the progress of an execution that is currently being performed. The DOWNLOADING and IN_PROGRESS states can be applied multiple times with different status messages to provide more detailed updates.

QUEUED

Description: Execution has been created and a job notification has been sent to the device over MQTT.

Transitions:

DOWNLOADING

Description: Alias of IN_PROGRESS. Can be applied multiple times.

Transitions:

IN_PROGRESS

Description: Job has been received and accepted by the device. Can be applied multiple times.

Transitions:

Terminal states

A terminal state is the ending state of a job execution. An execution in a terminal state is finished and cannot be changed.

SUCCEEDED

Description: Execution was completed successfully. In the case of an APP or MODEM update, an attempt will be made to update the appropriate version numbers in the device's shadow.

CANCELLED

The job was canceled.

FAILED

Description: An error occurred on the device while performing the update.

REJECTED

Description: The device refused to perform the update.

TIMED_OUT

Description: The update took too long to complete. No time limit is currently being enforced.

Job target validation errors

Before a job is transitioned to IN_PROGRESS, its job target is verified. If a job is determined to be invalid, it is moved directly to the CANCELLED state and one of the following errors are provided in the job's status detail field:

  • Empty job target: The provided job target did not contain any eligible devices.
  • Job may not contain Bluetooth LE and IP devices: Job targets must contain either all IP devices or all Bluetooth LE devices.
  • Job specified more than the max number of gateways: Jobs that update Bluetooth LE devices only support up to a maximum number of unique connected gateways. Gateways that are connected to multiple devices within the target are only counted once.
  • Not all gateways support Bluetooth LE updates: A gateway connected to a Bluetooth LE device specified in the job target is not capable of performing FOTA updates on its connected peripherals.

Device eligibility

Device eligibility is determined by matching the firmware type specified in the job document against the list of supported firmware types in the device's record. Ineligible devices do not prevent a job from executing, but they are not given job executions.

Configuring FOTA support

The options in this section are usually configured automatically over MQTT when using the nRF Connect SDK libraries. The information listed here is a reference for what you should configure in the device shadows to enable FOTA. See the FOTA getting started guide for more information.

IP devices

An IP device can specify the types of firmware it supports using the device.serviceInfo.fota_v2 property in its shadow. Set this property to a list of the firmware types supported by the device.

Gateways

An IP (non-phone) gateway to which a Bluetooth LE device is connected must also indicate in the gateway's shadow that it supports Bluetooth LE FOTA. Configure this through the device.serviceInfo.fota_v2_ble property.

Bluetoothยฎ LE devices

Bluetooth LE devices cannot individually specify supported firmware types. Instead, devices that support secure DFU automatically support APP, MODEM, and SOFTDEVICE updates.

note

Unlike the other eligibility checks, including a peripheral connected to a gateway that does not support Bluetooth LE causes the job to fail.

Execution rollout

When a job is deployed, the job target is resolved to a discrete list of eligible devices. Execution rollout is the process of creating job executions and sending notifications to all of these devices. Because jobs can contain large numbers of devices, executions are rolled out progressively in batches of 25. This means that not all devices receive an execution notification right away.

MQTT job execution notifications

This section explains notifications related to job executions sent over MQTT.

Receiving jobs

Job execution notifications are sent to devices as a JSON tuple using MQTT messages.

Fields:

  • PERIPHERAL_ID: ID of the connected peripheral that is to be updated. Only for Bluetooth LE devices.
  • JOB_ID: UUID for the overall job.
  • FIRMWARE_TYPE: Numeric enum representing the firmware type of the job:
    • APP=0
    • MODEM=1
    • BOOT=2
    • SOFTDEVICE=3
    • BOOTLOADER=4
    • MDM_FULL=5
  • FILE_SIZE: Combined size of all firmware files in bytes.
  • FILE_HOST: Host where the firmware files are stored.
  • FILE_PATH: Space-separated list of paths to the firmware files relative to the FILE_HOST.

IP devices

Notifications for IP devices are sent directly to the respective devices:

  • Topic: prod/<TEAM_ID>/<DEVICE_ID>/jobs/rcv
  • Format: ["<JOB_ID>",<FIRMWARE_TYPE>,<FILE_SIZE>,"<FILE_HOST>","<FILE_PATHS>"]

Bluetooth LE devices

Notifications for Bluetooth LE devices are sent to their connected gateway:

  • Topic: prod/<TEAM_ID>/<GATEWAY_ID>/jobs/ble/rcv
  • Format: ["<PERIPHERAL_ID>","<JOB_ID>",<FIRMWARE_TYPE>,<FILE_SIZE>,"<FILE_HOST>","<FILE_PATHS>"]

Requesting pending jobs

Sometimes, a device cannot receive the initial notification of a pending job execution. In this case, the device can request that a new execution notification is sent for its latest pending job execution.

Record expiration

Both job and job execution records expire one month after reaching a terminal state.

Deleting jobs

You can delete jobs in COMPLETED, CREATED, or CANCELLED states using the REST API. This removes them from your job list.

note

Deleting a job does not delete its executions. Executions remain visible until they expire.

Canceling executions

The job execution state is driven primarily by the device. This means the execution remains in whatever state the device reports. If you want nRF Cloud to end a job execution so the overall job can complete, use the UpdateFOTAJobExecutionStatus endpoint to set the status to CANCELLED. This tells nRF Cloud to stop waiting for a terminal status.

note

Changing an execution's status to CANCELLED does not trigger any behavior on the device itself.

Devices in a bad state before canceling remain in the same state afterwards.