Command-line tutorial for the advanced Device Management Client example with an Mbed OS device

This is an advanced Device Management Client example (mbed-cloud-client-example), written using Device Management Client 4.7.0 and Mbed OS 6.5.0.

Supported boards

You can use this tutorial with the following boards. The default stack configuration is in the mbed_app.json file.

• (1) RAM-optimized Wi-Fi configuration is available in configs/wifi_esp8266_minimal.json. This configuration uses only an internal flash storage and does not require an SD card.
• (2) Wi-SUN configuration is available in mesh_wisun.json and uses custom target names: NUCLEO_F429ZI, NUCLEO_F429ZI_AGGRESSIVE, MIMXRT1050_EVK, MIMXRT1050_EVK_AGGRESSIVE. The AGGRESSIVE configurations are suitable for very small deployments (<10 devices) for quick testing.
• (3) For Wi-Fi stacks, you need to add your SSID and password information to the configuration file.
• (4) The Platform Security Architecture (PSA) target configuration is available in the configs-psa/ folder.
  • (4a) PSA ethernet configuration is available in configs-psa/eth_v4.json.
  • (4b) PSA ethernet configuration for ATECC608A secure element is available in configs-psa/eth_v4_with_se_atmel.json. For the full secure element tutorial, see Connecting to Device Management with a pre-provisioned ATECC608A secure element.

Note: The --app-config option does not support relative paths used for linking the bootloader binary files, thus all configuration files must be copied to the application root-level. Alternatively, you can also copy the configuration file over the default mbed_app.json.

For Mesh, we recommend that you use a router compiled with same version of Mbed OS as the application. For Wi-SUN stack, also the Wi-SUN certificates (configs/wisun_certificates.h) need to match between the application and the router. See the GitHub repository for the Device Management-enabled managed Izuma Border Router or the unmanaged Nanostack Border Router.

Prerequisites

To work with the Device Management Client example application, you need:

• A supported board with a network connection and an SD card attached.

• Serial connection to your device with open terminal connection (baud rate 115200, 8N1).

• Arm Mbed CLI installed. See installation instructions.

  • Make sure that all the Python components are in par with the pip package requirements.txt list from Mbed OS.

• An access key (with Administrators group privileges) for your Device Management account.

• Updated DAPLink software (version 250 or later), if your board uses DAPLink.

Configuring Device Management Client

1. Clone the embedded application's GitHub repository to your local computer and navigate to the new folder:

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

2. Configure Mbed CLI to use your Device Management account and board:

   mbed target <MCU>
   mbed toolchain GCC_ARM
   

3. Download a developer certificate from Device Management Portal.

4. Copy the mbed_cloud_dev_credentials.c file to the root folder of the example application.

5. Create update-related configuration and credentials using the manifest-tool python package:

   1. Upgrade to manifest-tool version 2.4.1 or higher:

      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. Initialize the developer environment:

      manifest-dev-tool init --access-key <Device Management access key>
      

      Note: When you create a firmware update image for a deployed device, you must use the same update-related configuration and credentials (update private key, public key certificate, update_default_resources.c and configuration files) you used in the original device firmware image. Therefore, you need to skip running this command as your environment should be already initialized.

Compiling and flashing Device Management Client

To compile the example application:

mbed compile

For more information about Mbed CLI parameters, please see the Mbed OS documentation site.

Flashing the binary to the device

To flash the binary to the device:

1. Connect the device to your computer over USB. It's listed as a mass storage device.
2. Drag and drop mbed-cloud-client-example.bin to the device. This flashes the binary to the device. You should see the LED blink rapidly; wait for it to stop.

Connecting and performing a firmware update on your device

Checking the device connection and obtaining the Device ID

1. Press the Reset button to restart the device.
2. Obtain your device's Device ID either from device console logs or from Device Management Portal.

When the client has successfully connected, the terminal shows:

Client registered
Endpoint Name: <Endpoint name>
Device ID: <Device ID>

To verify the connection with Device Management Portal:

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

   • United States.

2. Select Device directory from the menu on the left.

3. When your device is listed on the Devices page, it is connected and available.

Your device is now connected and ready for the firmware update. For development devices, the Endpoint name and Device ID are identical.

Updating the firmware

To update the firmware on your device:

manifest-dev-tool update \
    --payload-path mbed-cloud-client-example_update.bin \
    --device-id <Device ID> \
    --wait-for-completion

During the update flow, the client tracing log shows:

Firmware download requested
Authorization granted
Downloading: [++++++++++++++++++++++++++++++++++++++++++++++++++] 100 %
Download completed
Firmware install requested
Authorization granted

After this, the device reboots automatically and registers to Device Management.