Documentation

Mistake on this page? Email us
Docs › Updating device firmware › Running update campaigns › Configuring, initiating and monitoring an update campaign

Configuring, initiating and monitoring an update campaign

Creating 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 on their attributes or identity.

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

Creating an update campaign

In Portal: Creating 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 > Update campaigns from the menu bar on the left.
  2. 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 Manifest dropdown list.

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

    6. Click Finish.

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.

Using the API: Creating an update campaign


Call POST /v3/update-campaigns/ with the filter ID included in the request message:

  curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/ \
  -H "Authorization: Bearer <access_key>" \
  -H "Content-Type: application/json" \
  -d '{"device_filter": "<filter_id>",
   "root_manifest_id": "<manifest_id>",
   "name": "<name>",
   "description": "<description>"
   }'

Required parameters:

  • device_filter: This is required to create a campaign. This is how you specify which devices a campaign targets. Specify the set of devices to update using the filter ID. This means you need to save a filter using a POST /v3/device-queries request.
  • root_manifest_id: A campaign in the draft phase can have an unspecified root manifest ID, but you need one to start the campaign.
  • campaign_strategy: continuous, one-shot or mesh. The default is one-shot. See the full explanation of continuous campaigns.

Cloning an existing campaign

You can reuse the configuration of a campaign you have already defined by cloning the campaign.

In Device Management Portal, cloning a campaign opens the Edit update campaign screen with the details of the cloned campaign populated.

This option is useful if you want to rerun the same campaign or a similar campaign with a different manifest, for example.

In Portal: Cloning an existing campaign

  1. Go to Firmware update > Update campaigns, and select a campaign.

    The Campaign details pane opens to the right.

  2. Click Clone.

  3. Click Clone in the confirmation popup window.

    This opens the Edit update campaign screen, on which you can modify the campaign details.

    By default, the Name field for the new campaign is set to the cloned campaign's name with the prefix (Cloned). We recommend giving the cloned campaign a meaningful name.

  4. Click Save.

    Device Management saves the cloned campaign in Draft state.

Using the API: Cloning an existing campaign


To clone an existing campaign, use the /v3/update-campaigns/{campaign_id}/clone POST API.

Editing an update campaign

The above steps create the update campaign as a Draft.

In Device Management Portal:

  1. Go to Firmware update > Update campaigns.
  2. Select a campaign you created in the previous step.
  3. A pane opens to the right.
  4. Click the pencil icon to edit.

You can now edit your campaign.

Initiating the update campaign

In Portal: Initiating 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.
  2. Select your active campaign.
  3. A pane opens to the right.
  4. Click Start.

Using the API: Initiating the update campaign


Using POST /v3/update-campaigns/{campaign_id}/start, start the campaign:

    curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/12345678901234567890123456789012/start \
    -H 'Authorization: <access_key>'

You don't need to put anything in the message body other than your authorization header.

Viewing campaign statistics

In Portal: Viewing campaign statistics

You can view campaign statistics using the portal.

These statistics include:

  • How many devices your campaign targeted.
  • How many devices updated successfully.
  • How many device updates are still pending.
  • How many devices failed to update.

In Device Management Portal:

  1. Go to Firmware update > Update campaigns.
  2. Select your active campaign.
  3. A pane opens to the right.
  4. Scroll to the bottom of the pane to see statistics.

Campaign Device Metadata (CDM)

CDM state How the device appears
pending Pending
updated_connector_channel Pending
failed_connector_channel_update Failed
manifestremoved Failed
deregistered Failed
deployed Success

Using the API: Viewing campaign statistics


When a campaign is in the active, stopped or archived phase, you can view campaign statistics:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/{campaign_id}/statistics \
-H "Authorization: Bearer <access_key>" \

This shows:

{
  "object": "list",
  "limit": 50,
  "after": null,
  "order": "ASC",
  "has_more": false,
  "data": [
  {
   "id": "fail",
   "campaign_id": "0172a385c5490000000000010010014e",
   "summary_status": "FAIL",
   "count": 1,
   "created_at": "2020-06-11T14:57:25.673081Z",
   "object": "summary_status"
  },
  {
   "id": "info",
   "campaign_id": "0172a385c5490000000000010010014e",
   "summary_status": "INFO",
   "count": 0,
   "created_at": "2020-06-11T14:57:25.673107Z",
   "object": "summary_status"
  },
  {
   "id": "skipped",
   "campaign_id": "0172a385c5490000000000010010014e",
   "summary_status": "SKIPPED",
   "count": 0,
   "created_at": "2020-06-11T14:57:25.673114Z",
   "object": "summary_status"
  },
  {
   "id": "success",
   "campaign_id": "0172a385c5490000000000010010014e",
   "summary_status": "SUCCESS",
   "count": 0,
   "created_at": "2020-06-11T14:57:25.673119Z",
   "object": "summary_status"
  }
 ]
}

This gives you a summary of the campaign:

  • id: ID of the event type description. Possible values are fail, success, information and skipped.
  • campaign_id: ID of the associated campaign.
  • summary_status: The event type description. Possible values are FAIL, SUCCESS, INFO and SKIPPED. For more information on a device's status, see Event log codes.
  • count: How many devices in the campaign have the given summary status.

Manually stopping a campaign

In Portal: 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.
  2. Select your active campaign.
  3. A pane opens to the right.
  4. Click Stop.

Using the API: Manually stopping a campaign


You can forcibly stop an active campaign:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/<campaign_id>/stop \
-H "Authorization: Bearer <access_key>"

The campaign phase changes to stopped.

Note: If the service has already processed an update operation for a device, the update for that device won't be canceled.

Archiving a campaign

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

In Portal: Archiving a campaign

In Device Management Portal:

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

Using the API: Archiving a campaign


You can archive campaigns to filter finished ones from the main list:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/<campaign_id>/archive
-H "Authorization: Bearer <access_key>"

The campaign phase changes to archived.

Previous Next