Update campaigns using the APIs
This is a step-by-step guide to updating device firmware using the Device Management web APIs.
It assumes:
- You have a Device Management account.
- You are familiar with the cURL command line utility.
- You already have a firmware image you want to upload.
- You already have a firmware manifest describing the image to upload.
- The devices to be updated are all ready, bootstrapped and usable with Device Management.
Tip: You can view the Update service APIs in the API references.
Please check our troubleshooting page if you encounter any issues.
Generating a login token
To use the APIs, you need an authentication token. To see how to generate the token, read Access Device Management with API keys.
You need to use the token in all other requests to authenticate them. The cURL commands are formatted as:
curl -H "Authorization: Bearer <api_key>"
Uploading the firmware image
If your firmware image is greater than or equal to 100 MiB (one hundred mebibytes), you need to upload your firmware image in multiple parts.
Upload the firmware image and give it a name:
curl -X POST https://api.us-east-1.mbedcloud.com/v3/firmware-images \
-H "Authorization: Bearer <api_key>" \
-F datafile=@<../path/to/file.bin> \
-F name="<name>" \
-F description="<description>"
This returns:
{
"created_at":"<timestamp>",
"datafile":"<url>",
"datafile_checksum":"<checksum>",
"datafile_size":<size>,
"description":"<description>",
"etag":"<tag>",
"id":"<device_id>",
"name":"<name>",
"object":"firmware_image",
"updated_at":"<timestamp>"
}
Take note of the datafile field; you'll need it in the next step.
Uploading the firmware manifest
Next, upload a manifest that points to your image:
-
In the firmware manifest file, update the field that points to the image; use the URL in
datafilefrom the step above. -
Sign and encode the manifest using the manifest tool.
-
Upload the signed manifest to the service:
curl -X POST https://api.us-east-1.mbedcloud.com/v3/firmware-manifests \
-H "Authorization: Bearer <api_key>" \
-F datafile=@<../path/to/file.bin> \
-F name="<name>" \
-F description="<description>"
If the upload is successful, the service returns:
{
"created_at":"<timestamp>",
"datafile":"<url>",
"datafile_size":<size>,
"description":"<description>",
"device_class":"<class_id>",
"etag":"<tag>",
"id":"<device_id>",
"name":"<name>",
"object":"firmware-manifest",
"timestamp":"<time>",
"updated_at":"<timestamp>",
"key_table":null
}
The manifest_contents field contains the parsed contents from the manifest. Take note of the id field; you will need it later.
Creating an update campaign
Selecting devices to target
An update campaign needs a list of devices, so you need to construct a filter for the campaign to use.
This exercise uses a filter based on device ID.
Filters are URL-encoded. For example, in the filter id=0164c910000000000010010012a, the URL is encoded to id%3D0164c9100000000000010010012a.
To test it, set the filter on the /devices API:
curl -X GET https://api.us-east-1.mbedcloud.com/v3/devices?filter=<filter> \
-H "Authorization: Bearer <api_key>"
The output from this action shows that a campaign targets a single device (which is what you want for this tutorial):
{
"object":"list",
"limit":50,
"after":null,
"order":"ASC",
"has_more":false,
"data": [
{
"account_id":"<account_id>",
"auto_update":false,
"bootstrap_expiration_date":null,
"bootstrapped_timestamp":"<time>",
"ca_id":"<CA-ID>",
"connector_expiration_date":null,
"created_at":"<timestamp>",
"custom_attributes":{},
"deployed_state":"development",
"deployment":"",
"description":"",
"device_class":"<class_id>",
"device_execution_mode":1,
"device_key":"<key>",
"endpoint_name":"<endpoint_name>",
"endpoint_type":"default",
"enrolment_list_timestamp":null,
"etag":"<tag>",
"firmware_checksum":"<checksum>",
"host_gateway":"",
"id":"<device_id>",
"manifest":"",
"manifest_timestamp":"<time>",
"mechanism":"connector",
"mechanism_url":"",
"name":"<name>",
"object":"device",
"serial_number":"<SN>",
"state":"registered",
"updated_at":"<timestamp>",
"vendor_id":"<vendor_ID>"
}
]
}
Creating a campaign
Now that you have defined the filter you want to use, you need to create an update campaign to target it. You need to specify the filter, the manifest ID, and a campaign name. Without these, you can create the campaign, but it will fail once you try to start it.
When creating a campaign, refer to the filter using the filter ID ("device_filter" : "id=<filter_id>") in the message body of the POST /v3/update-campaigns request.
To create the campaign:
curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/ \
-H "Authorization: Bearer <api_key>" \
-H "Content-Type: application/json" \
-d '{"device_filter": "<filter_id>",
"root_manifest_id": "<manifest_id>",
"name": "<name>",
"description": "<description>",
"campaign_strategy": "continuous"}'
This returns:
{
"created_at":"<timestamp>",
"description":"<description>",
"device_filter":"<filter>",
"etag":"<tag>",
"finished":null,
"id":"<device_id>",
"name":"Demo campaign",
"object":"update-campaign",
"root_manifest_id":"<manifest_id>",
"root_manifest_url":"<url>",
"started_at":null,
"state":"draft",
"updated_at":"<timestamp>",
"when":null,
"phase":"draft",
"approval_required":false,
"autostop_reason":"",
"autostop_success_percent":100.0,
"autostop":true,
"starting_at":null,
"active_at":null,
"stopping_at":null,
"stopped_at":null,
"archived_at":null
}
- 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.
Starting an update campaign
Using the ID returned in previous step, start the campaign with:
curl -X POST https://api.us-east-1.mbedcloud.com/v3/update-campaigns/<campaign_id>/start \
-H "Authorization: Bearer <api_key>"
Checking the progress of an update campaign
You can check the progress of a campaign in one of two ways: checking the phase, or viewing the logs.
Checking a campaign's phase
To check the phase, send a request using the ID returned in the previous step:
curl -X GET https://api.us-east-1.mbedcloud.com/v3/update-campaigns/<campaign_id> \
-H "Authorization: Bearer <api_key>"
This returns campaign data:
{
"created_at":"<timestamp>",
"description":"<description>",
"device_filter":"<filter>",
"etag":"<tag>",
"finished":null,
"id":"<device_id>",
"name":"<name>",
"object":"update-campaign",
"root_manifest_id":"<manifest_id>",
"root_manifest_url":"host/v3/firmware-manifests/<manifest_id>",
"campaign_strategy":"continuous",
"started_at":"<timestamp>",
"state":"publishing",
"updated_at":"<timestamp>",
"when":null,
"phase":"active",
"approval_required":false,
"autostop_reason":"",
"autostop_success_percent":100.0,
"autostop":true,
"starting_at":"<timestamp>",
"active_at":"<timestamp>",
"stopping_at":null,
"stopped_at":null,
"archived_at":null
}
Viewing the logs
Deployments to single devices that are online can finish in minutes, but a large update campaign to many devices can take hours or more to execute. In that case, you might want to review the log of device events to monitor the status of the campaign.
Stopping an active 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 <api_key>"
The campaign phase changes to stopped.
Note: If the service has already processed an update operation for a device, then the update for that device won't be canceled.
Archiving a stopped 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 <api_key>"
The campaign phase changes to archived.