Documentation

Mistake on this page? Email us
Docs › Developer guide › Command-line tutorial for the Device Management Client Lite example with an Mbed OS device

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

This is a Device Management Client Lite example (pelion-client-lite-example) for Mbed OS device with the following features:

  • Support for Mbed OS 5.15 LTS and the latest Device Management Client Lite releases.
  • Support for developer and production mode provisioning.
  • Support for firmware update.
  • Support for delta firmware update.

Versions

The Device Management Client Lite version used for the tutorial is 1.2.0 or later. It supports Mbed OS 5.15 LTS releases.

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

Supported boards

You can build Client Lite on either a bare-metal or RTOS-enabled configurations. This tutorial is applicable with the following boards and configurations:

Board/MCU configuration file Network stack additional information
NRF52840_DK mbed_app.json Cellular BG96 Quectel, QUEUE-mode, bare-metal
K64F mbed_app_baremetal_tls.json Wi-Fi ESP8266, bare-metal
DISCO-L475VG-IOT01A mbed_app_rtos.json Wi-Fi RTOS
DISCO-L475VG-IOT01A_CELLULAR_ALTAIR mbed_app_rtos.json Cellular ALT1250_PPP, QUEUE-mode, RTOS

Note: QUEUE-mode configuration by default: This means that the service will queue all requests and send them to client only after registration updates. This may slow down device responses.

Optimizations for ROM

For minimal code size, compile the application with extra flag:

--profile profiles/pico_lte_size.json

Network stack-specific configuration

  • For Cellular stacks, you need to:

    • specify the correct "nsapi.default-cellular-apn" (Operator specific).
    • select the correct Radio Access Technology (RAT) "cellular.radio-access-technology". (3 is for Cellular, 9 is for NB-IoT).

  • For Wi-Fi stacks, you need to:

    • add your SSID and password information to the configuration file.

Prerequisites

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

  • Python 3.5 or newer.

  • Serial connection to your device with open terminal connection (baud rate 115200, 8N1).

  • Arm Mbed CLI installed. Make sure all the Python components are in par with the pip package requirements.txt list from Mbed OS.

  • manifest-tool v2.4.1 or later installed.

    Note: The manifest-tool version in Mbed OS requiremements.txt is older and not compatible with Client Lite. This is part of installation steps below.

    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.

  • An access key (with Administrators group privilages) for your Device Management account.

  • Updated DAPLink software (version 250 or later), if your board uses DAPLink.

Configuring Device Management Client Lite

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

    mbed import https://github.com/PelionIoT/pelion-client-lite-example
cd pelion-client-lite-example

  2. Install Python packages:

    pip install -r mbed-os/requirements.txt
pip install -r requirements.txt

    Note: The installation order matters. Install the Client Lite requirements after the Mbed OS requirements as some of them are overwritten.

  3. Create the Izuma key chain file.

    Note: Device Management Portal only shows the access key once. Therefore, we recommend you save this key on a developer machine.

    Create a .pelion-dev-presets.yaml file in your home directory root ($HOME in linux) in the following format:

    usa:
   host: https://api.us-east-1.mbedcloud.com
   api_key: ak_SOME_VERY_SECRET_API_KEY

    To obtain an access key and API host URL, in Device Management Portal, click Access Management > Access keys > New access key. Limit the access to the .pelion-dev-presets.yaml file to your user only.

  4. Download the developer certificate:

    1. Log in to Device Management Portal.
    2. Go to Device identity > Certificates.
    3. Click Actions > Create a developer certificate.
    4. Add a name and optional description for the certificate, and click Create certificate.
    5. Click Download Developer C file to download the file mbed_cloud_dev_credentials.c.

  5. Copy mbed_cloud_dev_credentials.c to the example application root folder.

  6. Configure Mbed CLI to use your board and toolchain:

    mbed target <MCU>
mbed toolchain GCC_ARM

  7. Create the update-related configuration for your device:

    manifest-dev-tool init --gw-preset usa

    The preset API Gateway name corresponds to the name set in the keychain file.

  8. To compile for the K64F device, you need to switch the Mbed TLS version that resides in Mbed OS to the bare-metal variant. Run:

    cd mbed-cloud-client/tools
./setup_optimized_mbedtls.sh
cd ../../

    If you wish to switch back to non bare-metal Mbed TLS version, run:

    cd mbed-cloud-client/tools
clean_optimized_mbedtls.sh
cd ../../

Compiling Device Management Client Lite example

To compile the example application:

mbed compile

Read more detailed instructions on the 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 is listed as a mass storage device.
  2. Drag and drop pelion-client-lite-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

To perform a firmware update on your device, it needs to be connected to Device Management and have a Device ID.

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
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 your device is listed on the Devices page, 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:

manifest-dev-tool update \
    --payload-path pelion-client-lite-example_update.bin \
    --device-id DEVICE_ID \
    --wait-for-completion
  • DEVICE_ID is the device ID you obtained from device console logs or from Device Management Portal.
  • pelion-client-lite-example_update.bin is a build artifact.

Note: Make sure to take the build artifact with the _update.bin suffix.

When the update starts, the client tracing log shows:

[FOTA] ---------------------------------------------------
[FOTA] Updating component MAIN from version 1589797632 to 1589797876
[FOTA] Update priority 0
[FOTA] Update size 281236B
[FOTA] ---------------------------------------------------
[FOTA] Download authorization granted
[FOTA] Downloading firmware. 0%
---
[FOTA] Downloading firmware. 100%
[FOTA] Install authorization granted

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

Demo features of the application

The application provides several custom LwM2M resources for testing how GET, PUT and POST work.

Note: Compiling with -DMCC_EXAMPLE_ENABLE_BLINKY is required for these demo features.

GET request and device notifications

In Device Management Portal:

  1. Select Device directory -> Devices.
  2. Click the Device ID of your device.
  3. Device details pane opens.
  4. Select the RESOURCES tab.
  5. Click on Resource /3200/0/5501.
  6. A pop-up window opens and shows the initial value 0.
  7. Keep the window open. The console shows:
Notification callback: (3200/0/5501) Notification sent to server
Notification callback: (3200/0/5501) Notification delivered

On the board, press Button 1. It increments the button counter by one. You will see the same value appearing on the portal pop-up window, indicating that the device is sending the value as a notification.

PUT request

In Device Management Portal:

  1. Select Device directory -> Devices.

  2. Click the Device ID of your device.

  3. Device details pane opens.

  4. Select the RESOURCES tab.

  5. Click on Resource /3201/0/5853.

  6. A pop-up window opens and shows the initial value 500:500:500:500.

  7. Click the Edit icon on the right. The Put tab is selected by default.

  8. In the Value field, insert a string value, for example:

    100:100:100:100:100:100

  9. Click the Send button.

The console shows:

PUT received, new value: 100:100:100:100:100:100

POST request

In Device Management Portal:

  1. Select Device directory -> Devices.
  2. Click the Device ID of your device.
  3. Device details pane opens.
  4. Select the RESOURCES tab.
  5. Click on Resource /3201/0/5850.
  6. A pop-up window opens and shows text error reading value.
  7. Click the Edit icon on the right.
  8. Select the Post tab.
  9. Click the Send button.

The console shows:

POST executed pattern = 100:100:100:100:100:100
Next