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:

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:

   • United States.

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.