Documentation

Mistake on this page? Email us

Command line tutorial for Device Management Client with an Mbed OS device

This tutorial covers an end-to-end flow for using the Device Management Client example application:

  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 2.0.0 or later.

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

Device Management Client 2.0.0 2.2.0 3.0.0 3.1.0
Mbed OS 5.10 Works out-of-box Works out-of-box with SOTP-ESFS legacy storage Works out-of-box with SOTP-ESFS legacy storage Changes required
Mbed OS 5.11 Works out-of-box Works out-of box Works out-of box Changes required
Mbed OS 5.12 Changes required Works out-of box Works out-of box Works out-of-box

The highlighted combinations have been tested as part of the release. Other combinations should mostly work as listed, although some minor issues may appear. Changes required generally means that some changes are required for the combination.

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

Note: Usage of new network callback handling in the client example application version 3.1.0 or onwards is not directly compatible with Mbed OS 5.11 or older.

Note: The Client example application 2.2.0 or later implements secure storage using KVStore, which is supported for version Mbed OS 5.11 or later. If you want to use version 2.2.0 of Client with ESFS-SOTP configuration, support is provided in the configs/legacy_storage/ folder. KVStore is not compatible with ESFS-SOTP, thus existing devices should continue using the legacy configuration.

Supported boards

You can use this tutorial with the following boards:

Board/MCU Default stack DAPLink or STLink Notes
K64F Ethernet DAPLink (1), (2), (3)
K66F Ethernet DAPLink
NUCLEO_F429ZI Ethernet STLink
NUCLEO_F411RE Wi-Fi * STLink (2)
UBLOX_EVK_ODIN_W2 Wi-Fi * STLink (2)
CY8CKIT_062_WIFI_BT_PSA Wi-Fi * STLink (2), (3)
LPC55S69_NS Wi-Fi * DAPlink (2), (3)

(1) Wi-Fi and Mesh configurations are available in the configs/ folder for these targets. For example the RAM-optimized configuration for K64F is available in configs/wifi_esp8266_minimal.json. (2) For Wi-Fi stacks, you need to add your SSID and password information to the mbed_app.json file. (3) The PSA target configuration is available in configs-psa/ folder.

Prerequisites

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

  • A supported board with a network connection and an SD card attached. (See advanced instructions for boards without internal SD card adapter).
  • Serial connection to your device with open terminal connection (baud rate 115200, 8N1).
  • Mbed CLI pre-installed (Mbed CLI 1.8.0 and Mbed OS 5.10 or later versions).
    • You need to make sure that all the 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.

For instructions, see:

Note: The --app-config option is not supported, as the application configuration files contain relative paths to the bootloader files.

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 all 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 the Device Management Portal.

The terminal gives the following information when the Client has successfully connected:

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

To check with Device Management Portal:

  1. Open Device Management Portal.
  2. Navigate to Device directory.
  3. When your device is listed, 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 you can see the following log in Client tracing:

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.