Skip to content

Overview of firmware update over-the-air

The nRF Cloud firmware-over-the-air (FOTA) update service lets you update your device's firmware wirelessly.

This page explains concepts related to nRF Cloud FOTA. See the FOTA guide for instructional information on how to update your devices.

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.

Jobs

The following terms relate to FOTA jobs.

Term Definition
Job The highest level representation of a FOTA job. Holds overall state. Contains the job document, target, and aggregate statistics about its contained executions.
Deploy, deployment The action of creating and starting a FOTA job. This is called applying an update in some APIs and application code.
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 or execution state Specifies where in the FOTA process the job or execution is. See job states.
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 references) 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.

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.

Firmware types

You can deploy the following firmware types to a device.

Type Description
APP Updates the application firmware.
MODEM Updates modem firmware with a delta image. Modem firmware (both MODEM and MDM_FULL) images and bundles are controlled by Nordic Semiconductor, and cannot be uploaded to nRF Cloud.
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.

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

Gateway and Bluetooth LE devices

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.

FOTA job life cycle

The following figure shows the FOTA job life cycle.

FOTA job life cycle

Job cancellation

You can cancel a job in the CREATED or IN_PROGRESS state.

Job states

This section explains what happens during the FOTA process according to states.

CREATED

Click to expand

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:

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.

Validation errors
Validation error Description
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.

IN_PROGRESS

Click to expand

Description: Execution rollout of the requested update has started.

Transitions:

COMPLETED

Click to expand

Description: All executions have reached a terminal status.

Transitions:

CANCELLED

Click to expand

Description: Job not executed.

Transitions:

DELETE_IN_PROGRESS

Click to expand

Description: An 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 FOTA progress for a single device. 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 a job execution. The DOWNLOADING and IN_PROGRESS states can be applied multiple times with different status messages to provide more detailed updates.

QUEUED

Click to expand

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

Transitions:

DOWNLOADING

Click to expand

Description: The device is downloading the firmware image. Can be applied multiple times.

Transitions:

IN_PROGRESS

Click to expand

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

Click to expand

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

Click to expand

The job execution was canceled. You can set this state manually if a device cannot update and prevents the job from finishing.

FAILED

Click to expand

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

REJECTED

Click to expand

Description: The device refused to perform the update.

TIMED_OUT

Click to expand

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

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.

Deleting jobs

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

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.

FOTA retry groups and jobs

If a job execution fails, a new job and a new device group will be created after the job completes. The new group contains all failed devices, and the new job has the following:

  • The same job document as the original job.
  • The new device group as its only target.

The job appears in the portal's list of jobs along with all previous jobs. In the REST API, it appears in the server's response to the ListFOTAJobs endpoint. You can deploy or delete the retry job at any time, in the same manner as deploying or deleting any other FOTA job.

If you deploy the retry FOTA job and any of its job executions fail, another retry job and group will be created with devices that failed in the retry.

The name of the retry job is the original job name, followed by Retry for the first retry job. If a retry job fails, subsequent retry jobs will be named with the suffix Retry 2, Retry 3, and so on.

The name of the retry group is retry followed by the job name and ID of the failed job. For example, if the job with failures is named update-my-devices, with a job ID bce6075f-9594-480d-998e-62fb5fa5334c, the retry group will be named retry-update-my-devices-bce6075f-9594-480d-998e-62fb5fa5334c.

MQTT job execution notifications

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

Receiving jobs

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

Notifications

The following table lists fields in job execution notifications.

Field Description
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 the latest queued job execution

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

  • Topic: prod/<TEAM_ID>/<DEVICE_ID>/jobs/req
  • Format: A JSON array tuple containing [""] to get the latest queued job execution, or the job ID of a specific job execution.