Documentation

Mistake on this page? Email us
Docs › Updating device firmware › Preparing manifests › Creating a firmware manifest

Creating a firmware manifest

This tutorial explains how to create a manifest file for your update image, so you can use it to remotely update devices. A firmware manifest describes an update image. You upload the manifest to Device Management, so 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.

Note: This tutorial is based on manifest tool v1.5 and is not directly compatible with manifest tool v2.0.0 or higher.

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

Creating manifests using the manifest tool

With the manifest tool, you can:

  • 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, so you can 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 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 the .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 first create a device filter.

Once you have a device filter, use the manifest-tool update prepare command to create a manifest file and upload it to Device Management.

To prepare a manifest file for an update campaign run:

manifest-tool update prepare -p <payload>

  • <payload> is the file that you want to update the device with:

    Arguments

    • -i: path to the input JSON configuration file.

    • -o: path to the output binary file.

    • -k: path to PEM-format certificate. Not required if you use manifest-tool init, which generates a certificate.

    • -p: path to the firmware image binary associated with your update campaign.

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

You can optionally provide a name and description for the payload:

manifest-tool update prepare -p <payload> -n <PAYLOAD_NAME> -d <PAYLOAD_DESCRIPTION>\
    --manifest-name <MANIFEST_NAME> --manifest-description <MANIFEST_DESCRIPTION>

Once manifest-tool update prepare runs, the manifest file is automatically uploaded to Device Management.

Note: Both methods of creating a manifest use the defaults created by manifest-tool init command as described in the Setting up page. You can override each default using an input file or command-line arguments. See Generating a manifest for more details.

Advanced manifest features

This sections explains various advanced features that you implement using the manifest. These are restricted to certain customers or client versions.

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

Register this handler with Device Management:

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 receive a deprecation warning.

See the documentation on the accept API for more information.

Implementing component update

Note: This feature is available to select customers only and requires manifest tool version 2.0.0.

To enable component update, specify the component and version you're updating to by adding --component-name <NAME> and --fw-version <1.2.3> to the manifest-create command.

Implementing manifest deferral and resuming download

Note: This functionality is available to select customers only.

If you are using manifest tool version 2.0.0 or later, you can also configure your application to defer an update when the service delivers the manifest. The application marks the device as busy, and the device keeps the manifest in nonvolatile storage.

While the device is busy, Device Management won't send it more manifests. Depending on your application configuration, your application can release the device to download the image and install it, or the device prompts the application to continue with the update the next time the device registers with the service.

Update will continue retrying manifest delivery until the device acknowledges the manifest or reports an error. You can also configure your application on the device to reject an update, in which case the service reports an error.

Similarly, if the device receives a manifest and begins downloading the new firmware image, Device Management can resume the download from where it left off if the download is interrupted.

(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 new firmware image and copy the candidate image URL

When you upload a new firmware image to Device Management, Device Management provides you with a URL to put in the manifests you send to deployed devices.

Devices use this URL to download the candidate firmware image.

To upload the firmware binary to Device Management and obtain the candidate image URL:

  1. Log in to Device Management Portal.

  2. Select Firmware update > Images from the left menu.

  3. Click the Upload image button.

  4. Enter a name and a description for the image.

  5. Click the Choose file button and select the file.

  6. Click the Upload firmware image button.

    You can now find the new image on the Firmware image management screen.

  7. Click the name of the new image to open the Firmware image details pane.

  8. Copy the candidate image URL:

    • If your device application is based on Device Management Client, click Copy HTTP URL button in the open the Firmware image details pane to copy the candidate image URL.

    • If your device application is based on Device Management Client Lite and uses the CoAP protocol, click the Copy COAP URL button in the open the Firmware image details pane. Otherwise, click the Copy HTTP URL button in the open the Firmware image details pane to copy the full candidate image URL.

    When you create the manifest input file, you will set "payloadUri" : "<COAP HTTP>" or "payloadUri" : "<COAP URL>".

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:

  1. Log in to 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" : "<COAP URL>",
    "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 you obtained in Upload the new firmware image and copy the candidate image URL 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.

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.

Previous Next