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

Warning: If you're visiting this page from Device Management Portal, note that Device Management Client Lite versions 1.0 and later use X.509 certificates. This version of the Pelion documentation (4.2) applies only to pre-alpha versions of Client Lite.

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

1. Cloning the Device Management Client Lite repository.
2. Getting Device Management PSK credentials for the device.
3. Preparing the application for an update.
4. Compiling and flashing Device Management Client.
5. Connecting and performing a firmware update on your device.

Tip: You need access to the restricted GitHub repository referenced in this section. If you cannot access it or other repositories, please contact us.

Tip: You need to read and accept the PSK license in Device Management Portal. You can find it in Device Identity > Client Lite keys > UPLOAD A NEW PRE-SHARED KEY.

Supported boards

You can use this tutorial with the following boards:

* To use Wi-Fi, replace the root folder mbed_app.json with ./configs/wifi_esp8266_v4.json, and update with your own SSID and Password to the configuration file.

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

Prerequisites

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

• A supported board with a network connection.
• Serial connection to your device with open terminal connection (baud rate 115200, 8N1).
• Mbed CLI installed (Mbed CLI 1.8.0 and Mbed OS 5.10 or later versions).
  • Make sure that all Python components are in par with the pip package requirements.txt list from Mbed OS.
• An API key for your Device Management account.
• Updated DAPLink software (version 250 or later), if your board uses DAPLink.
• Tools and accounts.

Clone the Device Management Client Lite repository

Clone the embedded application's GitHub repository to your local computer and navigate to the new folder:

mbed import https://github.com/ARMmbed/mbed-client-lite-example-restricted
cd mbed-client-lite-example-restricted

Getting Device Management PSK credentials for the device

Device Management Portal can generate the mbed_cloud_dev_credentials.c file for you when you upload your PSK:

1. Log in to Device Management Portal.
2. Navigate to Device Identity > Client Lite keys.
3. Click UPLOAD A NEW PRE-SHARED KEY.
4. Click GENERATE RANDOM KEY.
   • This generates a random unique PSK ID and PSK using the browser's crypto library. You can also specify your own PSK ID, and only a random PSK is generated for you.
5. Click Upload.
   • A popup opens with the code you copy into your mbed_cloud_dev_credentials.c file.
   • In the mbed_cloud_dev_credentials.c file, the PSK must be in C format:

     const uint8_t MBED_CLOUD_DEV_BOOTSTRAP_PRE_SHARED_KEY_SECRET[] =
     {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF};
     

6. Click Download generated developer C file and place the downloaded mbed_cloud_dev_credentials.c file in the root of the Device Management Client Lite application.

Preparing the application for an update

1. Set up the repository for updates using the manifest tool:

   manifest-tool init -a <api key> -d "mydomain.com" -m "product model ID" --force -q --psk
   

   Note: The --force option overrides the default update_default_resources.c that ships with the mbed-client-lite-example.

   Note: The mydomain.com and product model ID are a string of your choice (alphanumeric only, no special characters, and the domain name must contain a .).

2. When the command completes, you can see a new directory called .update-certificates in the root directory of the example application. This directory contains the PSK needed for update (default.master.psk).

Note: The certificates generated above are not suitable for production environments. Use them only for testing and development. For details on certificates and key generation, read the manifest tool documentation.

Compiling the application

To compile the application, give the following commands:

mbed target <MCU>
mbed toolchain GCC_ARM
mbed compile

Read more detailed instructions on all the parameters related to Mbed CLI and mbed 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-client-lite-example-restricted.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>

In Device Management Portal:

1. Open Device Management Portal.
2. Navigate to Device directory.
3. If your device is listed, it is connected and available.

Your device is now connected and ready for the firmware update.

Updating the firmware

Read the Update tutorial to learn how to generate the manifest and an update campaign.