Updated on 2022-06-30 GMT+08:00

Firmware Upgrades

Overview

Firmware is like a device driver for the hardware. It is responsible for the underlying work of a system, for example, the basic input/output system (BIOS) on a computer mainboard.

Firmware upgrade, also called firmware over the air (FOTA), allows you to upgrade the firmware of LwM2M or MQTT devices in OTA mode.

Firmware Upgrade for Devices Using LwM2M

The firmware upgrade process for a device using LwM2M is as follows:

1–2: A user uploads a firmware package on the IoTDA console and creates a firmware upgrade task on the console or an application.

3: The LwM2M device reports data to the platform. The platform detects that the device is online and triggers the upgrade negotiation process. (The timeout interval is 24 hours.)

4–5: The platform delivers a command to query the device firmware version and determines whether an upgrade is required based on the target version. (In step 4, the timeout interval for the device to report the firmware version is 3 minutes.)
  • If the returned firmware version is the same as the target version, no upgrade is required.
  • If the returned firmware version is different from the target version, the platform continues the upgrade.
6–7: The platform queries the radio coverage of the cell where the device resides, and obtains the cell ID, reference signal received power (RSRP), and signal to interference plus noise ratio (SINR). (The timeout interval for the reporting of the radio coverage level and cell ID is about 3 minutes.)
  • If the query is successful, the platform calculates the number of concurrent upgrade tasks based on the RSRP and SINR ranges described in the figure below, and continues with step 9.
    • RSRP and SINR in range 0: 50 devices in the cell can be upgraded simultaneously.
    • RSRP in range 0 and SINR in range 1: 10 devices in the cell can be upgraded simultaneously.
    • RSRP in range 1 and SINR in range 2: Only one device in the cell can be upgraded at a time.

    • RSRP and SINR can be queried but are not within any of the three ranges: Only one device in the cell can be upgraded at a time.

      If only a small number of devices can be upgraded simultaneously, you can contact the local carrier to see if coverage can be improved.

  • If the query fails, the process continues with step 8.
8: The platform delivers a command to query the cell ID of the device.
  • If the query is successful, 10 devices in the cell can be upgraded simultaneously.
  • If the query fails, the upgrade fails.

9: The platform subscribes to the firmware upgrade status from the device.

10–11: The platform delivers the package download URL. The device downloads the firmware package from the URL. After the download is complete, the device notifies the platform. (Firmware packages can be downloaded in segments, and resumable download is supported.) (The timeout interval for step 11 is 60 minutes.)

12–13: The platform delivers an upgrade command to the device, and the device performs the upgrade. After the upgrade is complete, the device notifies the platform. (The timeout interval for the device to report the upgrade result and status is 30 minutes.)

14–16: The platform delivers a command to query the firmware upgrade result. After obtaining the result, the platform unsubscribes from the upgrade status and notifies the IoTDA console or application of the upgrade result.

The platform supports resumable download.

Firmware Upgrade for Devices Using MQTT

The firmware upgrade process for a device using MQTT is as follows:

1–2: A user uploads a firmware package on the IoTDA console and creates a firmware upgrade task on the console or an application.

3: The platform checks whether the device is online and triggers the upgrade negotiation process immediately when the device is online. If the device is offline, the platform waits for the device to go online and subscribes to the upgrade topic. After detecting that the device goes online, the platform triggers the upgrade negotiation process. (The timeout interval for the device to go online is within 25 hours.)

4–5: The platform delivers a command to query the device firmware version and determines whether an upgrade is required based on the target version. (The timeout interval for step 5 is 3 minutes.)
  • If the returned firmware version is the same as the target version, no upgrade is required. The upgrade task is marked successful.
  • If the returned firmware version is different from the target version and this version supports upgrades, the platform continues the upgrade.

6–7: The platform delivers the package download URL, token, and package information. The user downloads the software package using HTTPS based on the package download URL and token. The token is valid for 24 hours. (The timeout interval for package download and upgrade status reporting is 24 hours.)

8: The device upgrades the firmware. After the upgrade is complete, the device returns the upgrade result to the platform. (If the version number returned after the device upgrade is the same as the configured version number, the upgrade is successful.)

9: The platform notifies the IoTDA console or application of the upgrade result.

The platform supports resumable download.

Uploading a Firmware Package

On the IoTDA console, you can upload a firmware package to the Firmware List page for management.

  1. Log in to the IoTDA console.
  2. In the navigation pane, choose Devices > Software/Firmware Upgrades.
  3. On the Firmware List tab page, click Upload.
  4. On the page displayed, set the parameters and click OK to upload a firmware package.

    Fill in the parameters as follows:

    Parameter

    Description

    Firmware File

    Upload a firmware package. The package name cannot contain Chinese characters.

    Firmware Version

    Version of the firmware package. (A device reports the version number after the upgrade. The platform checks whether the version number reported by the device is the same as the value of this parameter. If they are the same, the upgrade is successful.)

    Product

    Select the product model of the corresponding device.

    Source Versions

    Enter the version manually. To add multiple versions, press Enter after inputting one version, and then input the next.

    Currently, you can upload signed firmware packages to the platform, but cannot modify public keys. If you attempt to upload a signed firmware package, the platform uses the available public key to verify the signature. If you have not uploaded the public key or the private key of the signature has changed, the signature verification fails. Consequently, uploading the firmware package fails.

    The function of uploading signed firmware packages will be removed soon. To ensure proper use of firmware upgrades, directly upload the files to be delivered to the device.

Upgrading the Firmware for a Batch of Devices

There are two ways to upgrade the firmware for a batch of devices:

  1. Call the API Creating a Batch Task to create an upgrade task for a batch of devices.
  2. Create a firmware upgrade task on the IoTDA console.

The following describes how to create a firmware upgrade task for a batch of devices on the console.

  1. Log in to the IoTDA console.
  2. In the left navigation pane, choose Devices > Software/Firmware Upgrades, and click Create Upgrade Task.
  3. On the Firmware Upgrades tab page, click Create Task.

  4. In the Set Basic Information pane, set the task name, execution time, and retry policy.

    If Retry is enabled, you can set the number of retry attempts and retry interval. You are advised to set Retry Attempts to 2 and Retry Interval (min) to 5. That is, if the upgrade fails, the upgrade will be retried in 5 minutes. (The maximum number of retry attempts is 5 and the maximum retry interval is 1440 minutes.)

  5. Select a firmware package.

  6. Select the device group to upgrade and click Create Now.

    For details on how to create a group and add devices to the group, see Groups and Tags.

  7. View the result on the task list. You can click View to view the result for each device on the Execution Details page.

    An upgrade task that is being executed cannot be deleted. To delete an upgrade task, manually stop the task first.

Firmware Upgrade Failure Causes

Failure causes reported by the platform:

Error Message

Description

Solution

Device Abnormal is not online

The device is offline or abnormal.

Check the device.

Task Conflict

A task conflict occurs.

Check whether a software upgrade, firmware upgrade, log collection, or device restart task is in progress.

Waiting for the device online timeout

The device does not go online within the specified time.

Check the device.

Wait for the device to report upgrade result timeout

The device does not report the upgrade result within the specified time.

Check the device.

Waiting for report device firmware version timeout

The device does not report the firmware version within the specified time.

Check the device.

Waiting for report cellId timeout

The device does not report the cell ID within the specified time.

Check the device.

Updating timeout and query device version for check timeout

The device does not report the upgrade result or device version within the specified time.

Check the device.

Waiting for device downloaded package timeout

The device does not finish downloading the firmware package within the specified time.

Check the device.

Waiting for device start to update timeout

The device does not start the update within the specified time.

Check the device.

Waiting for device start download package timeout

The device does not start to download the firmware package within the specified time.

Check the device.

Failure causes reported by devices:

Error Message

Description

Solution

Not enough storage for the new firmware package

The storage space is insufficient for the firmware package.

Check the storage space of the device.

Out of memory during downloading process

The memory was insufficient during the download.

Check the device memory.

Connection lost during downloading process

The connection was interrupted during the download.

Check the device connection status.

Integrity check failure for new downloaded package

The integrity check on the firmware package fails.

Check whether the firmware package downloaded is complete.

Unsupported package type

The firmware package type is not supported.

Check whether the device status and firmware package provided by the manufacturer are correct.

Invalid URI

The URI is invalid.

Check whether the download address of the firmware package is correct.

Firmware update failed

The firmware fails to update.

Check the device.

FAQs

The following lists the frequently asked questions about software and firmware upgrades. For more questions, "Software or Firmware Upgrade".
  • Can the Target Version Be Earlier Than the Source Version?
  • How Do I Obtain Software or Firmware Packages and Their Version Numbers?
  • Are Services Interrupted During a Software or Firmware Upgrade?
  • What Should I Do If a Software or Firmware Upgrade Task Is Ended Immediately After Being Created?
  • What Are Common Software or Firmware Upgrade Errors?

APIs

  • Creating a Batch Task
  • Querying the Batch Task List
  • Querying a Batch Task