Firmware images

Initial considerations

• Ensure you reserve the correct memory regions.
• The user application interacts with Update client. You can provide callbacks to allow the application to approve an update, as the client tutorial explains.

Updatable firmware images

To update firmware, you need three things:

• A bootloader. When the microcontroller is on, it automatically executes from the start address, which on many Mbed boards is at memory address 0x0 at the beginning of the flash. The bootloader is typically placed at this location, so it gets the control first when the device boots. The bootloader is never updated. It is the singular piece of code that guarantees that only a valid firmware image ever loads on the device.

• A metadata header: Contains information about the firmware, which the bootloader uses to validate the firmware before loading it. The metadata header is generated from the firmware image in two conditions:

  1. When you build the initial firmware image, a build tool generates the metadata header and combines the firmware image with the bootloader and the metadata header, into a single large binary.
  2. When Update client performs a firmware update, Update client generates a metadata header for the new candidate firmware image.

• A firmware image: Contains the OS, Update client and the user application.

Delta images

After you have an initial image on your device, you can generate a delta image for following update campaigns. A delta image contains the information necessary to create the new image from the old one. This means you only need to transmit the delta, not a full new image, to the device. Delta update can save bandwidth and energy for NB-IoT devices, or when installing large firmware images with only small code changes. Using a delta image can also reduce the amount of time needed for an update campaign. Delta images support the priority field.

Note: Delta update is compatible with Device Management Client 3.2 and later.

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

You need two tools to build a delta image:

• The delta tool, which compares two firmware images and creates a file outlining the differences between them, as well as information Update client needs to put those changes in the right place.
  • For your own project, you can copy the delta-tool folder to the example application directory to any suitable place, and add that project under the application you are compiling.
  • Add delta-tool/* to .mbedignore. Otherwise, because the delta tool and Update client share code, having both in the same directory will cause compilation issues.
• The latest manifest tool.

You need access to the full image currently running on the device, as well as the full images of any previous versions for which you want to create a delta.

For more information, see the full tutorial on creating delta images and manifests.

Update client and the bootloader

Update client writes new firmware in a location the bootloader can access. The bootloader's primary responsibility is to check there were no errors while Update client was writing the new firmware. To achieve this, the bootloader performs the following actions:

1. Checks the integrity of the active firmware by calculating the hash of the active image and comparing it to the one in the metadata header.

2. Handles new images, if any exist:

   1. Checks the integrity of each new image (if any exist) by checking the hash against its corresponding metadata header.

   2. If newer, applicable images exist, the bootloader copies the newest image to the active application memory region.

3. Forwards the control to the start of the application binary. The application containing Update client has now gained control and can receive further updates.

The Update client in the application is inactive until it receives a notification from one of its update sources. The Update client does not require a specific transport. We provide a LwM2M source for manifests and an HTTP source for firmware. With the LwM2M source, Update client supports push notifications from the Device Management Update service; the notification is the manifest for the update. Next, Update client:

1. Downloads the new manifest (if the manifest was not a push notification).
2. Verifies the manifest authenticity and applicability.
3. Parses the manifest to obtain the firmware URI.
4. Fetches the firmware from one of its update sources.
5. Writes the firmware into a spare image slot in storage.
6. Reboots and hands control back to the bootloader.

Building firmware

This step only builds the application; the bootloader remains untouched. The application must follow the same memory layout as the original application.