Mistake on this page? Email us

Campaigns with the web APIs

This is a step-by-step guide to updating device firmware using the Device Management web APIs.

It makes the following assumptions:

Tip: You can view the Update service APIs in the API references.

Please check our troubleshooting page if you encounter any issues.

Getting 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 in order to authenticate them. For example, the cURL commands start with:

curl -H "Authorization: Bearer <API-KEY>"

Uploading the firmware image

The first thing to do is upload the firmware image and give it a name:

curl -H "Authorization: Bearer <API-KEY>" \
  -F datafile=@<../path/to/file.bin> \
  -F name="<name>" \
  -F description="<description>" \
  -X POST \
     <host>

You should receive the following information:

{
     "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 a note of datafile; you'll need it in the next step.

Uploading the firmware manifest

Now you need to upload a manifest that points to your image:

  1. In the firmware manifest file, update the field that points at the image; use the URL in datafile from the step above.

  2. Sign and encode the manifest using the manifest tool.

  3. Upload the signed manifest to the service:

curl -H "Authorization: Bearer <API-KEY>" \
     -F datafile=@<../path/to/file.bin> \
     -F name="<name>" \
     -F description="<description>" \
     -X POST \
       <host>

You should receive the following information:

{
     "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.

For this exercise, we will use 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 -H "Authorization: Bearer <API-KEY>" \
    <host>/v3/devices?filter=<filter>

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.

To create the campaign:

  • POST /v3/update-campaigns/
curl -H "Authorization: Bearer <API-KEY>" \
-X POST \
-H "Content-Type: application/json" \
-d '{"device_filter": "<filter>", \
     "root_manifest_id": "<manifest-ID>", \
     "name": "<name>", \
     "description": "<description>"}' \
     <host>/v3/update-campaigns/

This gives the following output:

{
     "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
}

Starting an update campaign

Execute the following with ID returned in previous step:

curl -H "Authorization: Bearer <API-KEY>" \
<host>/v3/update-campaigns/<campaign-ID>/start -X POST

Checking the progress of an update campaign

You can check the progress of a campaign in two ways: checking the phase, or viewing the logs.

Checking a campaign's phase

To check the phase, execute the following command using the ID returned in the previous step:

curl -H "Authorization: Bearer <API-KEY>" \
<host>/v3/update-campaigns/<campaign-ID>

You get the following data structure:

{
     "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>",
     "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 should not take too long, but a large update campaign can take a long time to execute. In that case, you might want to review the log of device events.

Stopping an active campaign

You can forcibly stop an active campaign if you need:

curl -H "Authorization: Bearer <API-KEY>"  \
-X POST \
<host>/v3/update-campaigns/<campaign-ID>/stop

The campaign phase changes to stopped.

Note: If an update operation for a device has already been processed by the service, then the update for that device will not be canceled.

Archiving a stopped campaign

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

curl -H "Authorization: Bearer <API-KEY>"  \
-X POST \
<host>/v3/update-campaigns/<campaign-ID>/archive

The campaign phase will be moved to archived.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.