Documentation

Mistake on this page? Email us

Firmware images

Initial considerations

  • Consider the Update service when you build your firmware. Specifically, ensure you reserve the correct memory regions.
  • The user application interacts with the 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 to have three separate 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 that 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 the Update client performs a firmware update, the Update client generates a metadata header for the new candidate firmware image.
  • A firmware image: Contains the OS, the Update client and the user application.

The Update client and the bootloader

The Update client writes new firmware in a location that the bootloader can access. The bootloader's primary responsibility is to check that 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 the 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, the Update client supports push notifications from the Device Management Update service; the notification is the manifest for the update. Next, the 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.