Skip to main content

Updating Device Firmware

Introduction#

The nRF Cloud Firmware-Over-the-Air (FOTA) Updates Service provides a way for you to update your device's firmware wirelessly. If you would like to update your firmware in a wired manner, we recommend using the nRF Connect for Desktop tool.

This document describes the inner workings of FOTA. See also the Getting Started with the FOTA Service guide.

Terms#

Job Document#

Holds information about the firmware that is to be deployed as part of a job. Includes firmware version and type along with links to the actual files.

Job Target#

Specifies which devices the job can apply to. Can include both a set of tags (groups) and an explicit list of device identifiers.

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 executions. You can think of Jobs as containing executions.

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 Type#

Type of a firmware bundle that can be applied to a device

  • APP
  • MODEM
  • BOOT
  • SOFTDEVICE
  • BOOTLOADER

FOTA Life Cycle#

Job Life Cycle#

FOTA Job  Life Cycle

Job States#


CREATED#

Description - Jobs initially start in the CREATED state. This simply means that its initial information has been saved, including the Job Target and Job Document. Once a job has been created, these fields are immutable. However, the Job Target is not resolved until later on. This means that you can change the devices that a job will apply to by adding/removing devices from referenced tags.

Transitions


IN_PROGRESS#

Description - Execution Rollout has been started and the requested update is currently being performed.

Transitions


COMPLETED#

Description - All executions have reached a terminal status.

Transitions


CANCELLED#

Description - Job will not be executed

Transitions


DELETE_IN_PROGRESS#

Description - Internal state the means the job record will be deleted at some point in the future. DELETED jobs will not show up in the user's 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 via 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#

Terminal states are the final ending state of a Job Execution. An execution in a terminal state is considered done, and cannot be changed once applied.


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#

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 will be 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 will not stop a job from executing, they just won't be given Job Executions.

Configuring FOTA Support#

What follows is usually configured automatically over MQTT when using the nRF Connect SDK libraries. This information is listed here as a reference of what should be configured in the device shadows to enable FOTA. See the FOTA Getting Started Guide for more information.

All IP Devices#

IP devices can specify what types of firmware they support using the device.serviceInfo.fota_v2 property in their shadow. This property should be set to a list of the Firmware Types supported by the device.

Gateways#

IP gateways (i.e., not phone gateways) to which the Bluetooth LE device is connected must also indicate in their shadow that they support Bluetooth LE FOTA. This is configured through the device.serviceInfo.fota_v2_ble property.

Bluetooth® LE Devices#

Bluetooth LE devices cannot individually specify their supported firmware types. Instead, devices that support secure DFU will 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 will cause the job to fail.

Execution Rollout#

When a job is applied, its 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 potentially contain very large numbers of devices, executions are rolled out progressively in batches of 25. This means that not every device will receive its execution right away and may have to wait several minutes.

MQTT Job Execution Notifications#

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](@Firmware Type) of the job
      • APP = 0
      • MODEM = 1
      • BOOT = 2
      • SOFTDEVICE = 3
      • BOOTLOADER = 4
  • FILE_SIZE
    • Combined size in bytes of all firmware files
  • 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/<TENANT_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/<TENANT_ID>/<GATEWAY_ID>/jobs/ble/rcv

Format: ["<PERIPHERAL_ID>","<JOB_ID>",<FIRMWARE_TYPE>,<FILE_SIZE>,"<FILE_HOST>","<FILE_PATHS>"]

Requesting Pending Jobs#

Sometimes a devices is not able to receive the initial notification of an pending job execution. In this case, the device can request that a new execution notification be sent for its latest Pending job execution.

Record Expiration#

Both Job and Job Execution records expire one month after reaching terminal status.

Deleting Jobs#

Jobs in the COMPLETED, CREATED, or CANCELLED states can be deleted using the REST API. This will remove them from your job list.

note

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

Cancelling Executions#

Job Execution state is primarily driven by the device. This means that ultimately, the execution will remain in whatever state the device tells it to. However, there can be cases where you want nRFCloud to "give up" on a job execution so that the overall job can complete. This can be done using the UpdateFOTAJobExecutionStatus endpoint, and setting the status to CANCELLED. This is effectively the same as the device updating the execution status itself. It is important to note that this merely tells nRFCloud to stop waiting for a terminal status, and does not trigger any special cancellation behavior on the device itself.

caution

Changing an execution's status to CANCELLED will NOT trigger any behavior on the device itself. Devices in a bad state before cancelling, will be in the same state afterwards.