Docs › Updating device firmware › Device Management Update using the APIs › Firmware update using the APIs

Firmware update using the APIs

This tutorial shows how to do a firmware update using the Device Management Service APIs. See Using the APIs if you haven't worked with them before.

Note: Follow this tutorial after you have set up your environment, integrated Device Management Client into your application, compiled a firmware image and created a manifest.

There is also a tutorial for firmware updates using Device Management Portal.

The update process

Although there are differences in the processes for setting up an updatable development or production device, the update process for both is the same:

Generate a login token.
Upload your firmware image.
Upload your manifest.
Define and create your campaign.
Run the campaign.
Campaign completion and further actions.
1. Archive a campaign.
2. View campaign statistics.

To use the APIs, you need an authentication token or access key. To generate a key, read Access Device Management with access keys.

You need the key in all other requests to authenticate them. For example, each cURL command includes:

curl -H "Authorization: Bearer <access_key>"

Upload the firmware image

Earlier in this workflow, you compiled a firmware image. Now, upload it to Device Management.

If your firmware image is larger than 100 MiB (one hundred mebibytes) total, follow the directions to upload a large firmware image.

If your image is smaller than 100 MiB total, upload your full firmware or delta update image:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/firmware-images/
-F datafile=@<../path_to_file.bin> \
-F name="<name>" \
-F description="<description>"

Required parameters:

datafile.
name and description are optional.
This endpoint requires -F multipart/form-data, whereas most endpoints require application/json.

This returns:

{
 "created_at":"<timestamp>",
 "datafile":"<HTTP URL>",
 "datafile_checksum":"<checksum>",
 "datafile_size":<size>,
 "description":"<description>",
 "etag":"<tag>",
 "id":"<device_id>",
 "name":"<name>",
 "object":"firmware-image",
 "updated_at":"<timestamp>",
 "short_datafile":"<COAP URL>"
}

Note the CoAP URL of the uploaded image. This is recorded as the value of short_datafile. When you create the manifest input file, you will set "payloadUri" : "<COAP URL>".

Upload your manifest

Note: If you have not yet created a manifest that points to your image, do that now.

Prepare the manifest to use in a campaign:

In the firmware manifest file, update the payloadUri field that points at the image; use the URL in datafile from the step above:
```
`"payloadUri" : "<../path/to/file/FULL_EXAMPLE/mbed-cloud-client-example-internal/file.bin`>"
```
Sign and encode the manifest using the manifest tool.
Upload the signed manifest to the service. Note that this endpoint, like that to upload a firmware image, requires data as a multipart form:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/manifests
     -H "Authorization: Bearer <access_key>" \
     -F datafile=@<../path/to/file.bin> \
     -F name="<name>" \
     -F description="<description>"

You will 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
}

Define and create your campaign

Create a device filter.

You can refer to the filter later using the filter ID.
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: Either continuous or one-shot. The default is one-shot. See the full explanation of continuous campaigns.

Run the 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.

Further actions

After your campaign has finished, you can archive it or view campaign statistics.

Archive 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 <access_key>"

The campaign phase changes to archived.

View campaign statistics

Campaign statistics show you how many devices in a campaign failed, succeeded, are still pending or were skipped.

When a campaign is in the active, stopped or archived phase, you can call GET /v3/update-campaigns/{campaign_id}/statistics/ to view campaign statistics:

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

You get the following information:

{
     "created_at":"<timestamp>",
     "success_count":0,
     "failed_count":0,
     "pending_count":1,
     "total_count":1
}

Documentation