Documentation

Mistake on this page? Email us
Docs › Updating device firmware › Updating end-to-end tutorials › Setting up › Preparing your environment for building update firmware

Preparing your environment for building update firmware

This tutorial explains how to prepare your development environment so that you can build firmware updates for devices connected to Device Management. It shows you how to:

  • Import the Git repository containing the example code.
  • Get a device certificate.
  • Put the device example into the developer mode.
  • Get an API key.
  • Create an authentication certificate.

This tutorial uses a development workflow for creating update firmware for your devices, to enable you to familiarize yourself with the update interfaces and tools. As such, it uses developer certificates that allow you prototype and test your code. However, to ensure the security of your update firmware, you should modify your process and code once you transition to production code.

Prerequisites

Before you start this tutorial, you should have:

Prepare your development environment

Import the Git repository

The Git repository contains example code for an application that can be updated using Device Management. You need to import this example application into your environment.

To import the Git repository:

  • Open a terminal, and import the example application, using the following command:

    mbed import https://github.com/ARMmbed/mbed-cloud-client-example

Get a device certificate

To update the firmware on your device, you need a certificate. This certificate enables the device to connect to Device Management. For more information about certificates and security, refer to the Device Management Update client documentation.

For this tutorial, you can use a developer certificate. However, when you start to produce devices, you'll need to use a certificate that complies with your security policies, and if appropriate, has been generated using a hardware security module (HSM). For more information about this, see provisioning documentation.

You can get a device certificate from Device Management Portal:

  1. Log in to the portal, and select Device identity > Certificates.
  2. Select New certificate > Create a developer certificate if a certificate does not exist, or Upload a certificate if you have one already.
  3. The portal creates the certificate as a file called mbed_cloud_dev_credentials.c.

Make sure the device is in developer mode

In the file mbed_app.json, ensure the developer-mode value is 1.

Create an authentication certificate

To create a firmware image that can be installed on the device, you need to create an authentication certificate that is delivered with the firmware update. The section Verifying update manifests in the Device Management Update client documentation explains how the device ensures the update is from a trusted source.

Note: In this tutorial, you use the manifest tool to generate the authentication certificate. This enables you to quickly and easily develop the firmware updates for your device. These certificates generated above are not suitable for production environments. Only use them for testing and development. For details on certificates and key generation, read the manifest tool documentation.

For production devices, you should generate certificates using your security practices and, if applicable, a Hardware Security Module (HSM).

To create a default authentication certificate using the manifest tool, you need to:

  • Install the manifest tool.
  • Get an API key so that you can initialize the manifest tool.
  • Generate a default certificate using the manifest tool.
  1. Log in to the portal, and click Access management > API keys.
  2. Click New API key, name it, and assign it to the Developers group.
  3. Copy the API key.

To create a default certificate using the manifest tool, run the following command:

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

Where:

  • -a <api key>: The API key you just created.
  • -d <domain name>: An alphanumeric string (excluding special characters); must include a '.', such as mbed.com.
  • -m "product model ID": An alphanumeric string that enables you to identify the product model you are using.
  • --force: Overrides the default update_default_resources.c for mbed-cloud-client-example, and replaces it with your configuration details.
  • -q: Quiet initialization without prompts for location information.

For example, your command might look like this:

manifest-tool init -a 123456789 -d mbed.com -m "Update Example Project" --force -q

When the command completes, there is a new directory called .update-certificates in the root directory of the example application that contains:

  • The certificate (default.der).
  • A matching private key (default.key.pem).
  • A file called .manifest_tool.json, that stores the data entered in the command.

For more information, refer to the documentation about the manifest tool and manifests.

Additional pre-configuration features

To help develop and test the update process on your device, you can:

  • Increase the size of the download buffer.
  • Enable tracing from Client.

Increasing the download buffer size

You can speed up downloads if you have extra space in your image by giving the Update client larger download buffers. It uses two buffers with the size defined by the symbol MBED_CLOUD_CLIENT_UPDATE_BUFFER.

To change the download buffer size the Update client uses:

  1. Open mbed_cloud_client_user_config.h.

  2. Set MBED_CLOUD_CLIENT_UPDATE_BUFFER to a new value in bytes.

    Note: The buffer size must be at least 1024 bytes.

Enabling Client trace

To enable debug output from the Update client, open mbed_app.json, and in the target_overrides section, set mbed-trace.enable:

    "target_overrides": {
        ...
        "mbed-trace.enable": true
        ...
    },
Previous Next