Creating an update campaign

This tutorial describes how to create and run an update campaign. It shows you how to:

• Create a device filter to target specific devices.
• Create and start a continuous or one-shot update campaign.
• Monitor your update campaign by checking campaign phases.
• Stop your campaign, if necessary.
• Archive your campaign once it is finished.

There are two ways to create and run an update campaign:

• Using Device Management Portal. This tutorial focuses on this method.
• Using the APIs.

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

Prerequisites

Before you start this tutorial, you should have:

• Prepared your development environment.
• Integrated the Device Management Update client into your user application.
• Built an update image for your device:
  • Mbed OS device.
  • Raspberry Pi 3.
• Created a manifest file and uploaded it to the Device Management Portal.

Create a device filter

To distribute a firmware update to remote devices as part of an update campaign, you need to specify which devices this update targets. A device filter lets you select which devices to target based upon their attributes or identity.

In Device Management Portal:

1. Click Device directory on the menu bar on the left.
2. In the grey bar above the list of devices, click the arrow next to Filters. The default is Simple view.
3. From left to right, choose an attribute and operator, and give a value, such as Device ID.
   • Click Add another if you want to combine multiple attributes in one filter.
   • You can also choose an attribute that applies to multiple devices.
   • If you want to use a raw string instead, click Advanced view.
4. Click the small Save disk icon, and give your filter a name.
5. Click Save filter.

Your filter is automatically applied, and lists the devices matching your selected attributes.

Create an update campaign

Once 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.
4. Enter a Name and a Description.
5. Click the toggle to make your campaign continuous. The toggle turns blue. Do not click the toggle if you want your campaign to remain one-shot. The toggle remains grey.
   • If you create a one-shot campaign that includes devices already in a campaign, the campaign will fail to start.
   • If you create a continuous campaign that includes devices already in a campaign, the devices will join the campaign you most recently started.
   • We recommend creating continuous campaigns with a filter containing the existing firmware version of the devices. This avoids having the same device in two active continuous campaigns at the same time.
6. Select your manifest file from the dropdown list.
7. Select your device filter from the filter dropdown list.
8. 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.

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 that you created in the previous step.
3. A pane opens to the right.
4. Click Edit.
5. You can now edit your campaign.

Starting an update campaign

Once you are happy with the update campaign parameters like which manifest to use, targeted devices, and so on, you can start the campaign.

Note: Once your campaign enters this phase, it locks. You cannot change information like 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.

Campaign phases

Active

During this phase, Update sends manifests and waits for responses. If no errors occur, Update stops once it completes active tasks.

You cannot edit the campaign during this phase. You can stop it forcibly if necessary.

The time this phase takes varies from a few seconds to a few weeks, and depends on:

• The campaign configuration.
• The number of devices.
• Device connectivity.
• Manifest install rules.
• And other factors.

Stopping

In this phase, Update cleans up the campaign and releases unused credits. Update does this automatically once it finishes its active tasks. You can also stop the campaign manually if you need to.

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.

Stopped

This phase means that Update has finished everything from the Stopping phase. You can't restart a campaign once you stop it.

For one-shot campaigns:

The update is finished once all devices in the campaign are marked as succeeded or failed and the application starts running. Your devices then reconnect, and the campaign phase changes to Stopped. The update process is now completed.

For continuous campaigns:

Since a continuous campaign has no set end point, if you want to stop it, you must do so manually. Otherwise, manually stopping a campaign isn't usually necessary.

You have successfully updated your device's firmware using Device Management Portal.

If you want to restart a campaign at this point, you need to create a new one.

Archived

Archiving lets you remove old campaigns from search filters. It doesn't matter if all devices updated successfully, the campaign stopped automatically because of an error, or you stopped the campaign manually.

Once you archive a campaign, you cannot un-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.