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:
- Set up the device to receive firmware updates.
- Configure the Update client.
- Build the application.
- 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.
- Create a new version of the binary (Mbed OS devices) or a new root file system image (Raspberry Pi 3).
- Update the firmware application remotely using Mbed Cloud.:
- Upload the new image.
- Create and upload a manifest.
- Create a device filter.
- Create and start an update campaign.
- Monitor the campaign's progress, and confirm its successful completion.
Hardware used for this guide
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.
Open a terminal, and import the example application.
mbed import https://github.com/ARMmbed/mbed-cloud-client-example-restricted
You need a device certificate, which you can get from Mbed Cloud Portal:
- Log in to the portal, and click Device identity > Certificates.
- Click Actions > Create a developer certificate if a certificate does not exist. Otherwise, use the existing certificate.
- 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.
Get an API key from the portal.
- Log in to the portal, and click Manage access > API keys
- Click Create a new API key, give it a useful name and assign it to the developers group.
- Copy the API key.
Set up the repository for updates using the manifest tool:
manifest-tool init -a <api key> -S https://api.us-east-1.mbedcloud.com -d <company domain name> -m "product model ID" --force
--forceoption overrides the default
update_default_resources.cthat 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 '.').
When the command completes, you can see a new directory called
.update-certificatesin 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.
Compile the application. For example, for the K64F platform using the GCC toolchain:
mbed compile -t GCC_ARM -m K64F -c
This creates the file
Select the bootloader to use for your application. We currently provide three bootloaders in the tools folder:
For other targets, you need to port the bootloader for your target.
Choose your toolchain. Mbed OS currently supports three toolchains:
GCC_ARM: the arm-none-eabi-gcc toolchain.
ARM: the armcc toolchain.
IAR: the IAR toolchain.
Combine the application with the Mbed bootloader you have just selected. We provide a Python script called
Run the following command in the example application’s root directory:
> python tools/combine_bootloader_with_app.py -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/combine_bootloader_with_app.py -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
The new file
combined.bincontains the Mbed bootloader, the new application and the metadata header that the bootloader uses to verify the application.
The new file
combined.bincontains the Mbed bootloader, the new application and the metadata header that the bootloader uses to verify the application. Note that the
--app-offset 0x20400starting address for the firmware application is the same as the configuration
--header-offset 0x20000option refers to the location of the firmware metadata header. The locations are platform-specific and compiled into the bootloader.
Connect your device to your computer over USB. It appears as a mass storage device.
mbedlsto find the drag and drop path (
mount_point) and the serial terminal ID (
serial_port). For example:
mbedls +---------------+----------------------+---------------+------------------------+--------------------------+-----------------+ | platform_name | platform_name_unique | mount_point | serial_port | target_id | daplink_version | +---------------+----------------------+---------------+------------------------+--------------------------+-----------------+ | K64F | K64F | /Volumes/MBED | /dev/tty.usbmodem21332 | 024002019EF64E5C6308B3E4 | 0201 | +---------------+----------------------+---------------+------------------------+--------------------------+-----------------+
Drag and drop the
combined.binimage on to the
<mount_point>folder, or use one of following commands:
copy combined.bin <mount_point>
On Mac OS X:
cp -X combined.bin <mount_point> && sync
cp combined.bin <mount_point> && sync
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
picocomwith the following commands:
picocom -b 115200 <serial_port>
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:
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
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
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.
Open the Device directory menu.
Click Create new filter.
Click Add attribute.
Add a filter on Device name (in this case, the device shown is the only one that has a name).
You can also add Custom attributes and use them for filtering.
Give your filter a name, and save it:
The new filter is automatically applied to the page, and only devices with the selected attributes appear:
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:
Open the Update firmware menu.
Open the Update campaigns menu.
Click Create campaign.
Enter a Name and a Description.
Select the manifest you just uploaded from the dropdown menu.
Select the filter you created from the filter dropdown menu:
The campaign is in the draft state.
When you are ready to start the update process, click Start:
When the update process starts, you see the progress in stages. Wait until all the devices are updated:
On the device side, you can see the progress and notifications as soon as the firmware update starts:
When the upgrade completes and the application starts running, the device reconnects:
You have successfully updated your device's firmware using the Mbed Cloud portal.