Documentation

Mistake on this page? Email us
Docs › Connecting devices › End-to-end tutorials › Factory provisioning to firmware update › Update your device's firmware image

Update your device's firmware image

This section explains how to prepare a firmware update and deploy it to your device using an update campaign.

In this section, you use:

  • A manifest
  • A firmware image
  • An update campaign

What is a manifest?

A manifest is a file that contains all the information a device needs to validate and install a firmware update. You upload the manifest to Device Management, so devices can download it during a firmware update. In this tutorial, you create your manifest using the manifest tool.

For more information, see the Manifests and Device Management manifest CLI tool documentation.

What is a firmware image?

A firmware image is a binary that contains the software that your device will run after the update campaign is complete.

To update a device's firmware, you need to provide Device Management with a firmware image that the device can install.

In this tutorial, you change the device's startup message by editing the application_init.cpp file, compile the firmware image, and deploy it to your device using an update campaign.

For more information, see the Firmware images section.

What is an update campaign?

An update campaign defines which devices will receive the candidate image. In this tutorial, you use Device Management Portal to create and run the update campaign.

For more information, see the Campaigns section.

In this section

  1. Install the manifest tool on your computer.
  2. Prepare a firmware image.
  3. Upload the firmware image to Device Management Portal.
  4. Prepare a manifest configuration file.
  5. Create a manifest using the manifest tool.
  6. Upload the manifest to Device Management Portal.
  7. Create an update campaign using Device Management Portal.
  8. Run the update campaign using Device Management Portal.
  9. Verify the campaign was successful using Device Management Portal and the device's terminal.

1. Install the manifest tool

The manifest tool is a cross-platform Python application that is used to create, sign and upload manifests for use with Device Management.

For more information, see the documentation in the manifest tool repository .

We recommend installing the manifest tool on an isolated virtual environment to avoid conflicts with any other Python packages installed on your computer.

If there are not requirement conflicts, you can use the same environment you created for FCU.

  1. Install the latest manifest-tool:

    pip install --upgrade manifest-tool

Note: If your host system Python version is 3.6, use manifest-tool version 2.4.1. Use version 2.5.0 (or newer) for a more up-to-date system. You can specify the version via: pip install manifest-tool==2.4.1.

2. Prepare a new firmware image

In this tutorial, we suggest updating the device's startup message by editing the Device Management Client example's source code.

  1. Go to the file, source/application_init.cpp.

  2. Update the device's startup message by changing "Start Device Management Client" to "Start Device Management Client after update".

  3. To build the image, run:

    mbed compile

3. Upload the image to Device Management Portal

When you upload a new firmware image to Device Management Portal, the Portal provides you with a URL to put in the manifests you send to deployed devices. Devices use this URL to download the firmware image.

  1. Log in to Device Management Portal for your region:

  2. Select Firmware update > images.

  3. Click Upload image.

  4. Populate the Name and Description fields.

  5. Click Choose File and select BUILD/<target>/<toolchain>/mbed-cloud-client-example_update.bin

  6. Click Upload firmware image.

  7. Click the Copy HTTP URL icon, and take note of this URL, because you need it later in the tutorial.

4. Prepare a manifest configuration file

Create a file called manifest.yaml and populate it as follows:

vendor:
    vendor-id: <Vendor ID>
device:
    class-id: <Class ID>
priority: 1
payload:
    url: <Payload URL>
    file-path: <Payload path>
    format: raw-binary
component: MAIN

Where:

  • <Vendor ID> is the device Vendor ID you provisioned during the factory process step.
  • <Class ID> is the device Class ID you provisioned during the factory process step.
  • <Payload URL> is the URL of the uploaded binary, that you copied from Device Management Portal in the Upload the image to Device Management Portal step.
  • <Payload path> is the path to your local copy of the uploaded binary. For example, BUILD/<target>/<toolchain>/mbed-cloud-client-example_update.bin.

5. Create a manifest file

To create a manifest file, run:

manifest-tool create --config manifest.yaml --key <my-update-key.pem> --fw-version 0.0.1 --output manifest.bin

Where:

  • <my-update-key.pem> is the path to your update private key.

6. Upload the manifest file to Device Management Portal

  1. Log in to Device Management Portal for your region:

  2. Select Firmware update > Manifests.

  3. Click Upload manifest.

  4. Populate the Name and Description fields.

  5. From Firmware manifest, click Choose File and select manifest.bin

  6. Click Upload firmware manifest.

7. Create an update campaign

  1. Log in to Device Management Portal for your region:

  2. Select Firmware update > Update campaigns.

  3. Click New campaign.

  4. Click Wizard.

  5. Populate the Name and Description fields.

  6. From the Choose a Campaign Type, select One shot.

  7. Click Next.

  8. From the Manifest list, select the manifest you previously uploaded.

  9. Click Next.

  10. From the Device list, locate your device by its endpoint name and select it.

  11. Click Next.

  12. Click Finish.

8. Start the update campaign

Note: After you start your campaign, it locks. You cannot change information such as the selected manifest or targeted devices.

  1. Go to Firmware update > Update campaigns, and select the campaign you created in the previous step.
  2. A pane opens to the right.
  3. Click Start.

9. Verify your campaign using the device's terminal

You can verify the campaign was successful using Device Management Portal and your device's terminal.

In Device Management Portal

When your campaign is complete, Device Management Portal displays its status as Stopped.

You can check your campaign's status from the Firmware update > Update campaigns in Device Management Portal.

In your device's terminal

Check your device's terminal to verify that its startup message has changed to Start Device Management Client after update.

After your update is complete, your device's terminal displays a message like this:

Firmware download requested
Authorization granted
Priority of request 1
Downloading: [++++++++++++++++++++++++++++++++++++++++++++++++++] 100 %
Download completed
Firmware install requested
Authorization granted
Priority of the request 1
Mbed Bootloader
[DBG ] Update active firmware
[DBG ] Erase active application
[DBG ] Write header
[DBG ] Copy application
[DBG ] Verify application
[DBG ] New active firmware is valid
booting...
Start Device Management Client after update

Consult our troubleshooting information if you encounter any issues with the update process.

Previous Next