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 (FW) candidate Notes
Cypress CYTFM_064B0S2_4343W Wi-Fi Internal flash for credentials + external flash for FW candidate To use mbed-os-example-pelion with the CYTFM_064B0S2_4343W board, check out the cytfm-064b0s2-4343w branch and follow the instructions in Running PDMC example on the CYTFM_064B0S2_4343W.
Cypress CY8CPROTO-062-4343W Wi-Fi QSPIF Build-only
Embedded Planet EP_AGORA Cellular SPIF Build-only
Nuvoton NUMAKER_IOT_M263A Wi-Fi ESP8266 SD card (NUSD) Build-only
Nuvoton NUMAKER_IOT_M487 Wi-Fi ESP8266 SD card (NUSD) Build-only
Nuvoton NUMAKER_PFM_M487 Ethernet SD card (NUSD) Build-only
Nuvoton NUMAKER_PFM_NUC472 Ethernet SD card (NUSD) Build-only
NXP K64F Ethernet Internal flash
NXP K66F Ethernet Internal flash
Renesas GR_LYCHEE Wi-Fi ESP32 External flash (See security limitation of this board) Build-only
Renesas RZ_A1H Ethernet External flash (See security limitation of this board) Build-only
Seeed ARCH_MAX Ethernet SD card Build-only
Seeed WIO_3G Cellular Internal flash Build-only
Seeed WIO_BG96 Cellular Internal flash Build-only
ST DISCO_L475VG_IOT01A Wi-Fi QSPIF Build-only
ST DISCO_L496AG Cellular QSPIF Build-only
ST NUCLEO_F411RE Wi-Fi ESP8266 SD card Build-only
ST NUCLEO_F429ZI Ethernet Internal flash Build-only
ST NUCLEO_F767ZI Ethernet Internal flash Build-only
ST NUCLEO_H743ZI2 Ethernet Internal flash Build-only
ST NUCLEO_L4R5ZI Wi-Fi ESP8266 Internal flash Build-only
ST DISCO_F746NG Ethernet QSPIF Build-only
Uhuru UHURU_RAVEN Wi-Fi ESP32 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 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 mbed-os-example-pelion
    cd mbed-os-example-pelion
    
  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>
      

Compiling and flashing Device Management Client

To compile the example application:

mbed compile

Read more detailed instructions on all parameters related to Mbed CLI.

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 for your region:

  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:

manifest-dev-tool update-v1 \
    --payload-path mbed-os-example-pelion_update.bin \
    --device-id <Device ID> \
    --wait-for-completion

Note: The basic Device Management Client example application relies on an older release of our Device Management Client library for compatibility reasons, which is why you must include the 'update-v1' argument. Visit the migration guide for more information on how to update your applications to use the latest Device Management Client library version.

During the update flow, 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.