Creating and using delta images for Update

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

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

Note: Delta update is not compatible with Device Management Client Lite.

Prerequisites

Before you follow this tutorial, you should already have:

• A working C development environment to compile a makefile application, as well as:
  • A copy of the delta-tool folder in your project directory.
  • Manifest tool 1.5.0 or later installed.
  • Run manifest-tool init and all prerequisites for a working build.
  • Python 3 installed with pyasn1 module:
    • python3 -m pip install pyasn1 pyasn1-modules
• Integrated Device Management Update client into your user application.
• Registered your device with Device Management.
• An existing full firmware image running on the device.
• A new full firmware image to run on the device after update.

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 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 <API 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 your project directory, navigate to the delta-tool folder.

3. Compile the patch creation tool bsdiff:

   make -C delta-tool/bsdiff bsdiff
   

   Note: The patch creation tool is an Arm-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:

   python3 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.json
   

   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.
   • -f (--files): Use this without invoking bsdiff if you have already created a delta file.

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.json \
-o delta-manifest-update1.bin \
--payload-format bsdiff-stream -u <upload_uri>

Continue with 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 to previous-update-rootfs.tar.

The Linux build process stores all build images, along with a timestamp, in the root of the application (for example):

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.