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) for Mbed OS device with the following features:

• Support for latest Mbed OS and Device Management Client releases.
• Support for multiple operating systems.
• Support for developer and production mode provisioning.
• Support for firmware update.
• Support for delta firmware update.
• Support for advanced network stack and Pelion features.

1. Configuring Device Management Client.
2. Compiling and flashing Device Management Client.
3. Connecting and performing a firmware update on your device.

Versions

The Device Management Client version used for the tutorial is 3.0.0 or later.

Here is how the different Device Management Client example application and Mbed OS versions work together:

The highlighted combinations have been tested as part of the release. Other combinations should mostly work as listed, although some minor issues may appear. The PSA configuration is not available for Mbed OS releases older than version 5.14.

Note: If you are using Device Management Client 3.2.0, we recommend you upgrade to 3.3.0 (or later) as soon as possible. In 3.2.0, if an SSL session is stored when the device rebootstraps, a bootstrap loop may render the device unusable. Client 3.3.0 release fixes this issue by clearing the SSL session.

We recommend that you review the release notes for the Client example application and Device Management Client library.

Supported boards

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

• (1) Wi-Fi configurations are available in configs/wifi.json.
  • RAM-optimized configuration for K64F is available in configs/wifi_esp8266_minimal.json.
• (2) Mesh configurations are available in the configs/ folder.
  • (2a) Wi-SUN configuration is available in configs/mesh_wisun.json.
  • (2b) 6LoWPAN configuration is available in configs/mesh_6lowpan.json.
• (3) Ethernet configurations for IPv4 and IPv6 are available in configs/eth_v4.json and configs/eth_v6.json.
• (4) The Platform Security Architecture (PSA) target configuration is available in the configs-psa/ folder.
  • (4a) PSA Wi-Fi configuration is available in configs-psa/wifi.json.
  • (4b) PSA ethernet configuration is available in configs-psa/eth_v4.json.
• (5) For Wi-Fi stacks, you need to add your SSID and password information to the configuration file.

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 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 API key (with Administrators group privilages) 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/ARMmbed/mbed-cloud-client-example
   cd mbed-cloud-client-example
   

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

   mbed config -G CLOUD_SDK_API_KEY <API_KEY>
   mbed target <MCU>
   mbed toolchain GCC_ARM
   

3. Use Mbed CLI to download a developer certificate and to create an update-related configuration for your device:

   mbed device-management init -d arm.com --model-name example-app --force -q
   

Compiling and flashing Device Management Client

To compile the example application:

mbed compile

Read more detailed instructions on the parameters related to Mbed CLI and device-management command.

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.
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:

mbed device-management update device -D <Device ID>

When the update starts, 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.