Campaigns

An update campaign defines which device or devices receive a firmware update and the firmware image that is installed.

Defining campaigns: manifests and filters

A campaign is built around a manifest sent to the device and a filter that determines which devices receive the manifest.

Devices that receive a manifest may reject the update if it does not match the compatibility fields or rules defined in the manifest. This is to avoid firmware created for a specific model or for use by a particular vendor being updated on an incompatible or inappropriate device.

Tip: You may want to use the manifest tool to update a single device, or to upload the firmware and manifest to speed up the development cycle. See the manifest tool documentation for details.

Campaign types

Device Management supports three campaign strategies:

• Use a continuous campaign to apply the same update to a changing pool of devices over a period of time. The campaign updates any known devices first, but stays open so new devices receive the update once they register.

  Tip: Continuous campaigns are available for commercial accounts. See Choosing your account type for more information about the other benefits of commercial accounts and how to upgrade a free account to a commercial account.

• Use a one-shot campaign to apply an update to a static group of devices. This could be a test group, a set of devices in a region, or a field trial.

  For more information, see an explanation of filters or the Update service API documentation.

  Tip: With a free-tier account, you can perform up to 200 one-shot update campaigns each month. With a commercial account, you can perform an unlimited number. See Choosing your account type for more information about the other benefits of commercial accounts and how to upgrade a free account to a commercial account.

• Use a mesh campaign to update the nodes that make up a Wi-SUN mesh network, which is a group of devices that connect to each other and cooperate with one another to route data within the network. The nodes of a mesh network connect to Device Management through a border router.

  Device Management orchestrates Wi-SUN mesh campaigns to ensure minimum disruption to the network caused by the reboot required when you update device firmware.

  The mesh campaign updates the nodes connected through each border router separately, treating each border router as a sub-campaign.

  

Each sub-campaign updates the nodes connected through a specific border router in three stages:

1. Device Management sends a manifest to each border router, which sends the manifest to all of the nodes connected to the border router.

   When a node receives the manifest, it sends an acknowledgement notification to the Device Management notification service.

2. Device Management sends the border router a link to the firmware candidate, and the border router downloads the candidate image and sends it to all of the nodes connected to the border router.

   When a node successfully receives all of the packets of the candidate image, it sends an acknowledgement notification to the Device Management notification service.

3. Device Management sends an activation command to the border router, which sends the command to all of the nodes connected to the border router.

   When a node receives the activation command, it waits a configurable amount of time before rebooting.

Device Management proceeds from one stage to the next based on:

• A dynamic time period, which the border router estimates it will take for all nodes to complete this stage.

  During this period, Device Management waits for nodes to acknowledge successful completion of the current step. If all nodes acknowledge completing the step during this period, Device Management immediately begins the next step of the sub-campaign.

• A configurable threshold number of devices you define in Device Management.

  If at the end of the configurable time period all nodes have not acknowledged completing the current step, Device Management checks whether at least the threshold number of devices have completed the step. If the threshold number of devices completed the current step, Device Management begins the next step of the sub-campaign. Otherwise, Device Management ends the campaign, releases the border router and marks the device status in the campaign as failed.

Network traffic

See the guide to network traffic for an example calculation of messages between the device and service during an update.