Documentation

Mistake on this page? Email us
Docs › Updating device firmware › Preparing images › Creating and using delta images for Update

Creating and using delta images for Update

This tutorial shows how to create and upload a delta update image.

Note: You can only compile the bsdiff delta tool in Linux. Windows support will be added later.

Note: Delta update is compatible with Device Management Client 3.2 and later, and manifest tool 1.5 and later.

Prerequisites

Before you follow this tutorial, you need:

Delta update for production devices

If you have several different firmware versions running in the field, you must create a separate delta image and update campaign for each. This means you need access to the full, original versioned images, and you must complete the above process for each.

If you know when you created a manifest for a certain version, you can create a device filter in Device Management Portal or through the APIs, using the built-in attribute manifest_timestamp or firmware_checksum to target devices with a specific, previous firmware version.

To check the firmware version using Device Management Portal:

  1. Log in to Device Management Portal.
  2. Go to Device directory.
  3. Click on a device running the firmware you want to replace. A panel opens to the right.
  4. Click on Attributes. Check firmware_checksum or manifest_timestamp. These values correlate to the firmware version.

To check the firmware version using the APIs:

  1. View device information by calling GET /v3/devices/<device_id>:

    curl -X GET https://api.us-east-1.mbedcloud.com/v3/devices/<device_ID> \
-H 'Authorization: Bearer <access key>'

  2. The server returns device data. The following is an abbreviated example:

    {
  ...
  "manifest_timestamp" : "2017-05-22T12:37:55.576563Z",
  "groups" : [ "00000000000000000000000000000000" ],
  "serial_number" : "00000000-0000-0000-0000-000000000000",
  ...
  "firmware_checksum" : "0000000000000000000000000000000000000000000000000000000000000000",
  ...
  "deployed_state" : "development",
  "object" : "device"
}

Creating a delta image and manifest

To create a delta manifest:

  1. Ensure you have addressed all prerequisites.

  2. In the project directory, navigate to the delta-tool folder.

    Note: If the application project is missing the delta-tool folder, copy the folder from the example to your project. For Mbed OS, the delta-tool folder must be ignored in the .mbedignore file.

  3. Compile the patch creation tool bsdiff:

    make -C delta-tool/bsdiff bsdiff

    Note: The delta tool is a Pelion-specific implementation of the generic bsdiff. The generic tool is not compatible with delta creation.

  4. Navigate back to the project root.

  5. Run the delta tool:

    python delta-tool/tools/delta-tool.py \
-b delta-tool/bsdiff/bsdiff \
mbed-cloud-client-example_original_update.bin \
mbed-cloud-client-example_new_update.bin \
-i .manifest_tool.json \
-d delta_image.bin \
-o delta-tool-generated-manifest-configuration.json \
-s 256

    Note: -i .manifest_tool.json is only applicable to developer mode. When creating delta images for production, omit this argument. The .manifest_tool.json file is a byproduct of the manifest-tool init command.

    Note: The file delta-tool-generated-manifest-configuration.json must exist in your project root directory.

    Arguments:

    • -b (--bsdiff-binary): Path to the bsdiff executable binary. Use this parameter if bsdiff is in a location other than the default.
    • -i (--input-config): Manifest tool configuration file. STDIN by default.
    • -d (--delta): Delta file. If -b is given as a parameter, this is the delta output file. If -f is given, it is the delta input file.
    • -o (--output-config): Manifest tool configuration output file. STDOUT by default.
    • -s (--block-size): Block size to pass to the bsdiff delta tool. Device Management Client-configured CoAP Blockwise payload size must be divisible by delta block size.
    • -f (--files): Use this without invoking bsdiff if you have already created a delta file.

    As an example: With a CoAP Blockwise payload size set to 1024 bytes, you can set the delta block size to 128, 256, 512 or 1024 bytes. Bigger delta block sizes result in better delta patch compression but require more RAM on the device side.

  6. Upload delta_image.bin to the Device Management service using Device Management Portal. Store the returned delta image URI. You need it in the next step.

  7. Create the manifest:

    manifest-tool create \
  -i delta-tool-generated-manifest-configuration.json \
  -o delta.manifest \
  -u <**delta image URI**>

    Note: Add --private-key <PEM file> for production manifests. The private key (ECDSA secp256r1 in PEM format) should correspond to the update public key certificate provisioned to a device. The key file path for development devices is in the delta-tool-generated-manifest-configuration.json file.

  8. Upload delta.manifest to the Device Management service using Device Management Portal.

Continue creating an update campaign as you would with a full image.

Creating a delta image for a Linux device

Note: For Linux-based applications, you can find the delta tool as part of the Device Management example application following your initial build and test the process using this example. The path to the delta tool in a Yocto build is mbed-cloud-client-yocto-setup/rpi-build-example/tmp/work/cortexa7hf-neon-vfpv4-poky-linux-gnueabi/mbed-cloud-client/1.0-r0/git/mbed-cloud-client-example/delta-tool.

The process for creating a delta image for Linux is the same as for other platforms, with the exception that the original and new images are <version>.rootfs.tar:

python3 delta_tool/tools/delta-tool.py \
-b
delta_tool/bsdiff/bsdiff previous-update-rootfs.tar latest-update-rootfs.tar \
-d rootfs-delta.bin

By default, the latest build image is linked to latest-update-roofts.tar, and the build before that is linked to previous-update-rootfs.tar.

The Linux build process stores all build images, along with a time stamp, in the root of the application:

mbed-cloud-client-example-image-raspberrypi3-20190510104203.rootfs.tar

See the documentation for more information on creating a full firmware update image for Linux, or creating an initial firmware image.

Previous Next