Mistake on this page? Email us

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:

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.

It automates the following tasks:

  1. Upload the firmware to the Device Management update service.
  2. Create and sign a manifest with the digest of the firmware and its URL.
  3. Upload that manifest to the Device Management update service.

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 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 device, this is the .tar.bz2 file created in the image tutorial.
  • --manifest name is optional, however, providing a name for the manifest file will make it easier to find in the Device Management Portal.

While this command executes, the manifest tool performs the following steps:

  • Uploads the firmware to the Device Management update service.
  • Creates and signs a manifest with the digest of the firmware and its Device Management URL.
  • Uploads that manifest to the Device Management update service.

Note: For Mbed OS devices, the original image flashed to the device should be in .hex format because it contains the bootloader and SOTP secure elements. When updating a device, you should use a <app>_update.bin file as the payload.

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.

(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:

  1. Log in to the Device Management Portal.
  2. Select Firmware update from the left menu.
  3. Select Images.
  4. Click the Upload image button.
  5. Enter a name and a description for the image.
  6. Click the Choose file button and select the file.
  7. Click the Upload firmware image button.
  8. 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 the Device Management Portal:

  1. Log in to the Device Management Portal.
  2. Select Device directory from the left menu.
  3. 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.
  4. Select the device to open the device popup.
  5. 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",
    "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.

Here is where you can find the values:

  • 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.

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

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

  1. Log in to the Device Management Portal.
  2. Select Firmware update from the left menu.
  3. Select the Manifests menu option
  4. Click the Upload manifest button.
  5. Enter a name and a description for the image.
  6. Click the Choose file button and select the file.
  7. Click the Upload firmware manifest button.
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.