Documentation

Mistake on this page? Email us

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

This is a basic Device Management Client example (mbed-os-example-pelion) for an Mbed OS device with:

  • Support for latest Mbed OS and Device Management Client releases.
  • Support for developer mode provisioning.
  • Support for firmware update.

There is a more advanced example of the client with support for multiple operating systems in the mbed-cloud-client-example repository. The underlying client library is the same for both. This Mbed OS only example is simpler because it only supports one OS with a limited set of demonstrated features. To develop in Linux and Mbed OS at the same time, use the advanced example application.

Note: To work in production mode or use more advanced client features, use the mbed-cloud-client-example.

Supported boards

This table lists the supported boards:

Board Connectivity Storage for credentials and firmware candidate Notes
NXP K64F Ethernet Internal flash
NXP K66F Ethernet Internal flash
ST NUCLEO_F429ZI Ethernet Internal flash
ST NUCLEO_F411RE Wi-Fi ESP8266 SD card
Ublox UBLOX_EVK_ODIN_W2 Wi-Fi SD card
ST DISCO_L475VG_IOT01A Wi-Fi QSPIF Build-only
Ublox UBLOX_C030_U201 Cellular SD card Build-only
Ublox UBLOX_C030_R412M Cellular SD card Build-only
Embedded Planet EP_AGORA Cellular SPIF Build-only
ST NUCLEO_H743ZI2 Ethernet Internal flash Build-only
ST NUCLEO_L4R5ZI Wi-Fi ESP8266 Internal flash Build-only
Nuvoton NUMAKER_PFM_M487 Ethernet SD card (NUSD) Build-only
Nuvoton NUMAKER_IOT_M487 Wi-Fi ESP8266 SD card (NUSD) Build-only
Seeed ARCH_MAX Ethernet SD card Build-only
Seeed Wio 3G Cellular Internal flash Build-only
Renesas RZ_A1H Ethernet External flash (See security limitation of this board) Build-only
Renesas GR_LYCHEE Wi-Fi (ESP32) External flash (See security limitation of this board) Build-only
Uhuru UHURU_RAVEN Wi-Fi (ESP32) Internal flash Build-only
ST NUCLEO_F767ZI Ethernet Internal flash Build-only

Build-only = This target is currently verified only at the compilation, not at runtime.

Prerequisites

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

  • A supported board with a network connection and an external storage if listed in table above.
  • Serial connection to your device with open terminal connection (baud rate 115200, 8N1).
  • Arm Mbed CLI installed.
    • Make sure all the Python components align with the pip package requirements.txt list from Mbed OS.
  • An API 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 mbed-os-example-pelion
    cd mbed-os-example-pelion
    
  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 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 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-os-example-pelion.bin to the device. This flashes the binary to the device. Wait for the LED to stop blinking rapidly.

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
Account ID: <Account ID>
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 the Devices page lists your device, the device 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.

Interacting with the application through the serial port

  • Press Enter through Putty/minicom to simulate a button press.
  • Press i to print the endpoint name.
  • Press Ctrl-C to deregister.
  • Press r to reset the storage and reboot (Note: This generates a new device ID!).

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:

Update progress = 0%
...
Update progress = 99%
Update progress = 100%

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