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 using Programmer 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.
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 deployed:
- The deploy event begins the execution of the job. During the processing of this event, the job target is validated and the full set of eligible devices is resolved. If the job target is successfully validated, the job is then transitioned to IN_PROGRESS and execution rollout is started. If an error occurs during validation, the job is transitioned to CANCELLED and an appropriate error is added to the
statusDetailfield.- Target valid: IN_PROGRESS.
- Target invalid: CANCELLED.
- The deploy event begins the execution of the job. During the processing of this event, the job target is validated and the full set of eligible devices is resolved. If the job target is successfully validated, the job is then transitioned to IN_PROGRESS and execution rollout is started. If an error occurs during validation, the job is transitioned to CANCELLED and an appropriate error is added to the
- Job canceled: CANCELLED.
- Job deleted: DELETE_IN_PROGRESS.
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:
- Job canceled: CANCELLED.
- All executions in terminal states:
- ➔ COMPLETED.
COMPLETED¶
Click to expand
Description: All executions have reached a terminal status.
Transitions:
- Job deleted:
CANCELLED¶
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.
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
- ➔ IN_PROGRESS
- ➔ Any terminal state.
DOWNLOADING¶
Click to expand
Description: The device is downloading the firmware image. Can be applied multiple times.
Transitions:
- ➔ DOWNLOADING
- ➔ IN_PROGRESS
- ➔ Any terminal state.
IN_PROGRESS¶
Click to expand
Description: Job has been received and accepted by the device. Can be applied multiple times.
Transitions:
- ➔ IN_PROGRESS
- ➔ Any terminal state.
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:
|
| 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.