Upgrade device firmware#

If you would like to upgrade the firmware of devices using the Azure IoT Hub, follow the instruction below.

Prerequisites#

At least one synchronized Coiote IoT DM - Azure IoT Hub device.
A firmware file hosted on an HTTP server that is reachable by the Coiote IoT DM server.

Note

In this stage of integration, no authentication method is supported for this endpoint - it is required that the firmware is publicly available (or hosted in a private network but with access granted for the Coiote IoT DM server).

Scheduling a firmware upgrade#

Introduction#

The process of upgrading device firmware for Azure IoT Hub devices synchronized with Coiote IoT DM is based on two main elements: the Azure Direct Method mechanism and the Coiote IoT DM Firmware Upgrade task. In the process, the Azure scheduleFirmwareUpdate direct method is invoked, enabling the Coiote IoT DM to download the specified firmware file and add it to its resources. Then, an XML task is scheduled in Coiote IoT DM and the upgrade is performed on the device.

Info

For firmware file recognition in Coiote IoT DM, global identifiers are used. This means that it is recommended to name your firmware files using the format: yourdomainName + randomized value. If the same firmware file name is used again, then Coiote IoT DM will be able to utilize the once downloaded resource without the need to download it again.

Step 1: Invoking the Azure scheduleFirmwareUpdate direct method#

To initiate the firmware upgrade procedure for your device:

Go to your Azure hub account and under Explorers, select IoT devices.
From the list, choose the device for which you want to upgrade the firmware.
In the device view, select the Direct Method tab.

Provide data for the following fields:

FOTA direct method configuration

Method Name - paste the scheduleFirmwareUpdate direct method name here.

Payload - use the following payload with firmware upgrade parameters (remember to replace the example values where needed):

{
  "name": "anjay-firmware",
  "firmwareUrl": "https://example.repository.com/artifactory/gitlfs/demo.fw-pkg",
  // optional - default="1200s", any valid duration in format "<length><unit>"
  "timeout": "1200s",
  // optional - default="COAP"
  "protocolType": "COAP",
  // optional - default=null <-> keep firmware file forever, any valid duration in format "<length><unit>" or null
  "retentionPeriod": "300s",
  // optional - default=""
  "description": "This is anjay demo firmware",
  // optional - default=false
  "useQuota": false,
  // optional - default=false
  "useCachedData": false,
  // optional - default=false
  "resumeAfterDownlinkFailure": false,
  // optional - default="Pull", possible values = ["Pull", "Push"]
  "imageDeliveryMethod": "Pull",
  // optional - default="WithoutObservations", possible values = ["ObservationTrigger", "WithoutObservations", "ObservationBased", "SendBased"]
  "upgradeStrategy": "WithoutObservations",
  // optional - default="always", possible values = ["always", "weekends", "nights-home", "nights-enterprise-weekends", "nights-enterprise", user-defined schedules]
  "schedule": "always"
}

Connection timeout - specify a timeout for the Azure - Coiote IoT DM connection (the recommended value is not less than 5 seconds).
Method timeout - specify a timeout for direct method result notification.

Once you have provided the required data, click Invoke method.
After a short moment, you should be able to see the direct method result in the Result field.
- The 200 as the "status" parameter value means that the firmware upgrade task was completed successfully.
- Importantly, the result "payload" value will be needed for other FOTA actions like status check or cancellation, so be sure to copy it to your clipboard if needed.

Tip

Out of all the parameters provided in Firmware upgrade direct method payload, only two are mandatory:

name - the unique file name used for firmware identification.
firmwareUrl - the URL used by Coiote IoT DM to download the firmware file and include it as a resource.

Therefore it is correct to include only those two in the payload, as in here:

{
"name": "anjay-firmware",
"firmwareUrl": "https://example.repository.com/artifactory/gitlfs/demo.fw-pkg",
}

Step 2: Checking the firmware upgrade result#

To check the status of a scheduled firmware upgrade, follow these steps:

In the Direct Method tab of your device, provide data for the following fields:
- Method Name - paste the checkFirmwareUpdateStatus direct method name here.
- Payload - use the payload displayed in the Firmware upgrade result field (remember to replace the placeholder value with your copied value):
```
{
"fotaId": "fotaIdReturnedByScheduleOperation"
}
```
Click Invoke method.
Check the direct method status in the Result field:

Step 3: Checking Coiote IoT DM FOTA task execution#

Once you have executed the Azure-side steps of the procedure, you can check its status from the side of Coiote IoT DM.

Go to your Coiote IoT DM account and in the Device Inventory, select your device.
In the Device Management Center, enter the LwM2M firmware tab.
Check the status of the FOTA task execution for your device:
- In the Current firmware section, check if the device firmware is updated to the newest version.
- In the Installation history section, check if the lwm2mFirmwareUpdate task invoked earlier by the Azure scheduleFirmwareUpdate direct method has been completed with success.

Cancelling the firmware upgrade procedure#

To cancel the firmware upgrade procedure, follow these steps:

In the Direct Method tab of your device, provide data for the following fields:
- Method Name - paste the cancelFirmwareUpdate direct method name here.
- Payload - use the payload displayed in the Firmware upgrade result field (remember to replace the placeholder value with your copied value):
```
{
"fotaId": "fotaIdReturnedByScheduleOperation"
}
```
Click Invoke method.
Check the direct method status in the Result field: