Updating device firmware

There are two methods to update device firmware:

• Portal (this tutorial uses this method).
• Through the APIs.

Before you follow this tutorial, make sure you have met all prerequisites.

The update process

Although the processes to set up an updatable development or production device are different, the process to update each is the same:

1. Upload your firmware image.
2. Upload your manifest.
3. Define and create your campaign.
4. Run the campaign.
5. Campaign completion and further actions.
   1. Archive a campaign.
   2. View campaign statistics.

Upload the firmware image to Device Management

When you upload a new firmware image to Device Management, Device Management provides you with a URL to put in the manifests you send to deployed devices.

Devices use this URL to download the candidate firmware image.

To upload the firmware binary to Device Management and obtain the candidate image URL:

1. Log in to Device Management Portal.

2. Select Firmware update > Images from the left menu.

3. Click the Upload image button.

4. Enter a name and a description for the image.

5. Click the Choose file button and select the file.

6. Click the Upload firmware image button.

   You can now find the new image on the Firmware image management screen.

Upload the manifest to Device Management

Upload the firmware manifest to Device Management to use it with the firmware update service:

1. Log in to Device Management Portal.
2. Select Firmware update from the left menu.
3. Select the Manifests menu option.
4. Click the Upload manifest button.
5. Enter a name and description for the manifest.
6. Click the Choose file button, and select the file.
7. Click the Upload firmware manifest button.

Create a device filter

Define the target devices for an update campaign by setting a device filter.

Filter example for mesh network campaigns

Mesh campaigns target devices behind border routers.

To filter all devices behind a set of border routers:

1. Filter all devices related to specific border routers by setting:

   Network ID is in <ID of the border router 1>,<ID of the border router 2>,<ID of the border router n>

   For example, Network ID is equal to 01771abc60de000000000001001abcd0

   This filter returns all devices related to the network IDs you specify, including the border router themselves.

   However, you must not update border routers together with nodes as they are devices of different types and require different images.

2. To remove the border router from the filter and target only the nodes behind the border router, add this filtering criteria to your filter:

   Endpoint type is equal to routernode

3. To update only devices that are registered at the time you define the filter, set:

   State is equal to Registered

Example filter for REST APIs: net_id__eq=<border_router_ID>&endpoint_type__eq=routernode&state__eq=registered

Create an update campaign

After you have created a device filter, you can create an update campaign.

In Device Management Portal:

1. Click the Firmware update option from the menu bar on the left.
2. Click Update campaigns.
3. Click New campaign.

   1. Enter a Name and a Description.

   2. Select a campaign type: One shot, Continuous or Mesh campaign.

      For more information, see Campaign types.

   3. For a mesh campaign, configure values for:

      • Acknowledged devices under one border router - The percentage of nodes that must acknowledge completion of each stage of the campaign before Device Management begins the next step of the sub-campaign.

        For example, if you set this parameter to 90, after Device Management sends the manifest to the border router, it does not send the command for the devices to start downloading the candidate image if at least 90% of the devices in the campaign acknowledge receiving the manifest. Then, Device Management does not send the command for the devices to install the candidate image - which is the next stage in the campaign - if at least 90% of the devices in the campaign have acknowledged successfully downloading the candidate image.

      • Activation delay - The amount of time a device waits before installing the new firmware after the device receives the activation command from the border router.

      For more information about the mesh campaign process, see Campaign types.

   4. Select your manifest file from the dropdown list.

   5. Select your device filter from the filter dropdown list.

   6. Click Save.

Note: Device Management Portal refers to the estimated number of devices included in a campaign. This is because the filter only includes registered devices when the campaign starts. If a device deregisters in the meantime, it is not included in the campaign.

Consult our troubleshooting information if you encounter any issues with the update process.

Editing an update campaign

The above steps create the update campaign as a Draft.

In Device Management Portal:

1. Click Firmware update.
2. Select a campaign you created in the previous step.
3. A pane opens to the right.
4. Click Edit.

You can now edit your campaign.

Start the update campaign

After you are happy with the update campaign parameters, such as which manifest to use and targeted devices, you can start the campaign.

Note: After your campaign enters this phase, it locks. You cannot change information such as the selected manifest or targeted devices.

In Device Management Portal:

1. Go to Firmware update > Update campaigns, and select your active campaign.
2. A pane opens to the right.
3. Click Start.

Manually stopping a campaign

Note: Manually stopping the campaign is not a required step, unless you have reason to stop it before it would normally finish.

In Device Management Portal:

1. Go to Firmware update > Update campaigns and select your active campaign.
2. A pane opens to the right.
3. Click Stop.

Archiving a campaign

After you archive a campaign, you cannot de-archive it. You can then delete archived campaigns if you want.

In Device Management Portal:

1. Go to Firmware update > Update campaigns, and select your active campaign.
2. A pane opens to the right.
3. Click Archive.