Docs › Updating device firmware › Updating end-to-end tutorials › Preparing manifests › Creating a firmware manifest

Creating a firmware manifest

This tutorial explains how to create a manifest file for your update image, so that you can use it to remotely update devices. A firmware manifest describes an update image. You upload the manifest to Device Management so that devices can download it during a firmware update. This tutorial guides you through the process of creating the manifest and uploading it to Device Management using the manifest tool.

The tutorial shows you how to:

Create manifests using the manifest tool.
Test a firmware update on a single device.
Prepare a manifest file for use in a campaign.

Note: This tutorial is for development and testing purposes only as it uses self-signed certificates. For production-ready devices, you need to obtain a certificate that the certificate authority has signed. Please see our documentation on external signing tools and hardware security modules.

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.

Creating manifests using the manifest tool

The manifest tool enables you to:

Test the firmware update by creating a manifest file and running a campaign on a single device, using the update device command.
Prepare a manifest file for use in a campaign, using the update prepare command.
Create and sign a manifest with the digest of the firmware and its URL.

Testing a firmware update on a single device

The manifest-tool update device command automates the process of updating a single device, enabling you to test the delivery of your firmware update.

To test the delivery of the firmware update on a device, create a manifest file to update the firmware on a device, using the manifest tool:

manifest-tool update device -p <update image> -D <device id>

<update image> is the file that you want to update the device with. For the:
- Mbed OS device, this is the <app>_update.bin file created in the image tutorial, or a modified <app>_update.bin with new changes you would like to update the device with.
- Raspberry Pi 3, this is .tar.bz2 file created in the image tutorial.
<device id> is the identity or endpoint of the device you want to update.
--no-cleanup is an optional flag that at the end of the update campaign, stops the manifest tool from deleting the:
- Device firmware.
- Manifest.
- Update campaign.

When executing this command, the manifest tool:

Uploads the update image to the Device Management update service.
Creates and signs a manifest file with the digest of the update image and its Device Management URL.
Uploads that manifest to the Device Management update service.
Creates an update campaign using the manifest and a default device filter matching the device ID.
Starts the update campaign.
Waits for the update campaign to finish.
(If the --no-cleanup flag is not used), deletes:
- The device firmware.
- The manifest.
- The update campaign.

Preparing a manifest file for use in a campaign

To update more than one device, you need to create an update campaign that uses a device filter. Using the manifest-tool update prepare command creates a manifest file and uploads it to Device Management, enabling you to prepare for an update campaign.

To prepare a manifest file for an update campaign, create a manifest by running the following command:

manifest-tool create -i  <./path/to/configuration/file.json> -o <./path/to/output.bin>  -k <./path/to/authorization/certificate.pem> -p <./path/to/image/file.bin>

<update image> is the file that you want to update the device with:
- For Mbed OS devices, this is the <app>_update.bin file created in the image tutorial, or a modified <app>_update.bin with new changes you would like to update the device with.
- For Raspberry Pi 3 devices, this is the .tar.bz2 file created in the image tutorial.
--manifest name is optional, but providing a name for the manifest file will make it easier to find in Device Management Portal.

Implementing update priority

Note: Update priority is compatible with Device Management Client 3.4 and later.

See Manifests and update priority for more information on the concept of priority.

Note: The values used below are examples only. Which values you use depends on how you define them in your application. These values must be integers.

Include the priority field in your manifest and set its value to 0, or a number of your choosing, to make an update mandatory. Updates are mandatory by default.
Include the priority field in your manifest and set its value to 1, or another number of your choice, for lower-priority or optional updates.

To enable this feature, create an approval handler that includes a priority field in your application. Device Management checks with the handler when parsing the manifest. If the registered handler has a priority field, the priority passes to the approval handler.

void set_update_authorize_priority_handler(void (*handler)(int32_t request, uint64_t priority));

To reject an update, the handler must call void update_reject(int32_t request, int32_t reason); and give the reason for rejection as an argument (REJECT_REASON_NOT_AUTHORISED or REJECT_REASON_UNAVAILABLE). Device Management then requests approval for the update from the user application. Update client uses the application's registered handler to get update approval.

There is an approval API (void update_authorize(int32_t request);) without a priority field. If your application uses the old API but includes a priority field in the manifest, you will receive a deprecation warning.

See the documentation on the accept API for more information.

(Optional) Creating a manifest file without using the manifest tool

You can manually perform each of the steps the manifest tool takes in its update prepare or update device commands.

Upload the firmware binary

You need to upload the firmware binary to Device Management to use it with the service:

Log in to Device Management Portal.
Select Firmware update from the left menu.
Select Images.
Click the Upload image button.
Enter a name and a description for the image.
Click the Choose file button and select the file.
Click the Upload firmware image button.
Make a note of the firmware URL to use later.

Find the device class and vendor ID

The manifest needs the device vendor ID and class ID. You can find them in Device Management Portal:

Log in to the Device Management Portal.
Select Device directory from the left menu.
Locate your device. If you don't know which one it is, you can use picocom, or a similar tool, to read the serial console of the device and find the device ID: Device Identity 0123456789abcdeffedcba9876543210.
Select the device to open the device popup.
Make a note of the vendor ID and device class to use later.

Create a certificate

Use OpenSSL to create a self-signed certificate for use with Device Management:

openssl ecparam -genkey -name prime256v1 -out key.pem
openssl req -new -sha256 -key key.pem -out csr.csr -subj "/C=XX/ST=STATE/L=LOCATION/O=ORGANIZATION/CN=COMMONNAME"
openssl req -x509 -sha256 -days 365 -key key.pem -in csr.csr -outform der -out certificate.der -subj "/C=XX/ST=STATE/L=LOCATION/O=ORGANIZATION/CN=COMMONNAME"

This creates a certificate called certificate.der and a key called key.pem.

Create a manifest input file

Create a JSON input file called manifest.json for the manifest tool. Open the file, and add this JSON snippet. Then, edit the values:

{
    "encryptionMode" : "none-ecc-secp256r1-sha256",
    "vendorId" : "00112233-4455-6677-8899-aabbccddeeff",
    "classId" : "00112233-4455-6677-8899-aabbccddeeff",
    "payloadUri" : "http://path.to/payload.bin",
    "payloadFile" : "/path/to/payload.bin",
    "priority" : 2,
    "description" : "Description of the update",
    "certificates": [
        { "file" : "certificate.der" }
    ]
}

Note: If you don't want to use the file, you can input many of these values to the manifest tool by using the command-line. See manifest-tool create --help for full details.

The values are:

vendorId: The vendor ID of the device, which you obtained in Find the device class and vendor ID above.
classId: The class ID of the device, which you obtained in Find the device class and vendor ID above.
payloadUri: The URL of the uploaded binary. This is the firmware URL that you obtained in Upload the firmware binary above.
payloadFile: A local copy of the uploaded binary.
priority: The priority of the update attached to the manifest.

Create and sign the manifest using the manifest tool

To sign and encode the manifest:

manifest-tool create -i ./manifest.json -o manifest.bin -k ./key.pem

This creates a file called manifest.bin.

Upload the manifest to Device Management

Upload the firmware manifest to Device Management to use it with the firmware update service:

Log in to Device Management Portal.
Select Firmware update from the left menu.
Select the Manifests menu option
Click the Upload manifest button.
Enter a name and a description for the image.
Click the Choose file button and select the file.
Click the Upload firmware manifest button.

Next step: Creating an update campaign

Now that you have a device that can be remotely updated and a manifest file, you can create an update campaign to distribute updates to remote devices.

Documentation