Mistake on this page? Email us

Tutorial: End to end firmware update

Tip: You need access permission to the private GitHub repos referenced in this section. Please contact us to request access.

There are two methods of updating the firmware on devices connected to Mbed Cloud:

  • Through the Mbed Cloud portal.
  • Using the RESTful APIs:
    • Directly with HTTP APIs.
    • Using the Mbed Cloud SDK.
    • Using the manifest tool.

Both methods use the Update client feature built into Mbed Cloud Client.

In this guide, we explain how to update the firmware using the manifest tool.

The workflow for this guide is:

  1. Set up the device to receive firmware updates.
  2. Configure the Update client.
  3. Build the application.
  4. Transfer the application to the device.
    • Mbed OS devices: Combine the application with the bootloader, and program the device locally.
    • Raspberry Pi 3: Write the Yocto SD image to the SD card, and insert the SD card into the board.
  5. Create a new version of the binary (Mbed OS devices) or a new root file system image (Raspberry Pi 3).
  6. Update the firmware application remotely using Mbed Cloud.:
    1. Upload the new image.
    2. Create and upload a manifest.
    3. Create a device filter.
    4. Create and start an update campaign.
    5. Monitor the campaign's progress, and confirm its successful completion.

Hardware used for this guide

This tutorial follows the quick start and supports the same hardware, running Mbed OS. For Linux support, please see our Linux Update documentation.

Required software tools

Prepare the device

Note: This section is specific to Mbed OS devices, but you can also build and run the Update client on the Raspberry Pi 3.

  1. Open a terminal, and import the example application.

    mbed import
  2. You need a device certificate, which you can get from Mbed Cloud Portal:

    1. Log in to the portal, and click Device identity > Certificates.
    2. Click Actions > Create a developer certificate if a certificate does not exist. Otherwise, use the existing certificate.
    3. The portal creates the certificate as a file called mbed_cloud_dev_credentials.c. Download and add this file to your deployed Mbed Cloud Client example.
  3. Get an API key from the portal.

    1. Log in to the portal, and click Manage access > API keys
    2. Click Create a new API key, give it a useful name and assign it to the developers group.
    3. Copy the API key.
  4. Set up the repository for updates using the manifest tool:

    manifest-tool init -a <api key> -S -d <company domain name> -m "product model ID" --force

    Note: The --force option overrides the default update_default_resources.c that ships with the mbed-cloud-client-example. Note: The "company domain name" and "product model ID" are a string of your choice (alphanumeric only, no special characters, the domain name must contain a '.').

  5. When the command completes, you can see a new directory called .update-certificates in the root directory of the example application. This directory contains the certificate (default.der) and a matching private key (default.key.pem). You can also see a file called .manifest_tool.json, which contains the autogenerated IDs.

    Note: The certificates generated above are not suitable for production environments. You must use them only for testing and development. For details on certificates and key generation, read the manifest tool documentation.

  6. Compile the application. For example, for the K64F platform using the GCC toolchain:

    mbed compile -t GCC_ARM -m K64F -c
  7. This creates the file mbed-cloud-client-example-restricted.bin in your BUILD directory.

  8. Select the bootloader to use for your application. We currently provide three bootloaders in the tools folder:

    1. mbed-bootloader-k64f.bin.
    2. mbed-bootloader-nucleo-f429zi.bin.
    3. mbed-bootloader-ublox-evk-odin-w2.bin.

    For other targets, you need to port the bootloader for your target.

  9. Choose your toolchain. Mbed OS currently supports three toolchains:

    1. GCC_ARM: the arm-none-eabi-gcc toolchain.
    2. ARM: the armcc toolchain.
    3. IAR: the IAR toolchain.
  10. Combine the application with the Mbed bootloader you have just selected. We provide a Python script called in the tools directory.

    Run the following command in the example application’s root directory:

    > python tools/ -b tools/<bootloader> -a BUILD/<target>/<toolchain>/mbed-cloud-client-example-restricted.bin --app-offset 0x20400 --header-offset 0x20000 -o combined.bin

    For example, building on K64F with GCC_ARM, this would be:

    > python tools/ -b tools/mbed-bootloader-k64f.bin -a BUILD/K64F/GCC_ARM/mbed-cloud-client-example-restricted.bin --app-offset 0x20400 --header-offset 0x20000 -o combined.bin
  11. The new file combined.bin contains the Mbed bootloader, the new application and the metadata header that the bootloader uses to verify the application.

    The new file combined.bin contains the Mbed bootloader, the new application and the metadata header that the bootloader uses to verify the application. Note that the --app-offset 0x20400 starting address for the firmware application is the same as the configuration target.mbed_app_start in mbed_app.json. The --header-offset 0x20000 option refers to the location of the firmware metadata header. The locations are platform-specific and compiled into the bootloader.

  12. Connect your device to your computer over USB. It appears as a mass storage device.

  13. Use mbedls to find the drag and drop path (mount_point) and the serial terminal ID (serial_port). For example:

    | platform_name | platform_name_unique | mount_point   | serial_port            | target_id                | daplink_version |
    | K64F          | K64F[0]              | /Volumes/MBED | /dev/tty.usbmodem21332 | 024002019EF64E5C6308B3E4 | 0201            |
  14. Drag and drop the combined.bin image on to the <mount_point> folder, or use one of following commands:

    1. On Windows:

      copy combined.bin <mount_point>
    2. On Mac OS X:

      cp -X combined.bin <mount_point> && sync
    3. On Linux:

      cp combined.bin <mount_point> && sync
  15. When the file has finished copying, set up a serial console at 115200 8N1 to view the device's serial output. For example, you can use picocom with the following commands:

    picocom -b 115200 <serial_port>
  16. Press the Reset button on the device, and watch the terminal console. You see the output from the device. This device is now ready to receive firmware updates! After the device has finished registering with Mbed Cloud, it reports an "endpoint name." You need this to update the device. Your device is now ready to receive firmware updates remotely.

Update the device with a new firmware

Create a new firmware binary with any changes you may require, upload it to Mbed Cloud and update a device.

Tip: We have instructions for building an update image for Raspberry Pi 3. Note that on the Raspberry Pi 3, update images are compressed (.tar.bz2) root file system archives.

Use the manifest tool to start the update:

manifest-tool update device -p <payload name> -D <device id>

You can see the payload file in the last line of the output of mbed compile. For example:

Image: ./BUILD/K64F/GCC_ARM/mbed-cloud-client-example-internal.bin

For Raspberry Pi 3, use the path to the .tar.bz2 update image file instead of the .bin firmware file.

The manifest tool waits for the update to complete, then cleans up the files it created in Mbed Cloud. If you wish to leave those files in Mbed Cloud, use the --no-cleanup option.

Update more than one device

To update more than one device, you need to use a device filter, so you cannot use the manifest-tool update device command. Instead, you can use the manifest-tool update prepare command. This command uploads your firmware, creates a manifest and then uploads the manifest.

manifest-tool update prepare -p <payload name>

Tip: You can provide your manifest with a name to make it easier to identify in the portal by using the --manifest-name option.

When the upload completes, you can use the portal to update devices, as the following sections describe.

Create a device filter

Device filters allow you to target specific devices for update. Create a device filter in the Mbed Cloud portal now to use it in your update campaign later.

  1. Open the Device directory menu.

  2. Click Create new filter.

  3. Click Add attribute.

    FW device filter

    FW device filter

  4. Add a filter on Device name (in this case, the device shown is the only one that has a name).

  5. You can also add Custom attributes and use them for filtering.

  6. Give your filter a name, and save it:

    FW filter save

  7. The new filter is automatically applied to the page, and only devices with the selected attributes appear:

    FW filter done

Create and manage an update campaign

Update campaigns combine a device filter and a manifest to advertise an update to devices. Create an update campaign in the Mbed Cloud portal:

  1. Open the Update firmware menu.

  2. Open the Update campaigns menu.

  3. Click Create campaign.

    FW update campaign

  4. Enter a Name and a Description.

  5. Select the manifest you just uploaded from the dropdown menu.

  6. Select the filter you created from the filter dropdown menu:

    FW New update campaign

  7. Click Save:

    FW New update campaign save

  8. The campaign is in the draft state.

  9. When you are ready to start the update process, click Start:

    FW New update campaign draft

  10. When the update process starts, you see the progress in stages. Wait until all the devices are updated:

    FW New update campaign init

    On the device side, you can see the progress and notifications as soon as the firmware update starts:

    FW update complete

    FW update complete2

  11. When the upgrade completes and the application starts running, the device reconnects:

    FW update complete3

You have successfully updated your device's firmware using the Mbed Cloud portal.