Advantech / Mbed OS pelion-example-common

Generic Pelion Device Management example for various Advantech modules.

This example is known to work great on the following platforms:

Example Functionality

This example showcases the following device functionality:

  • On timer button increment, simulate Pelion LWM2M button resource change

Use this example with Mbed CLI

1. Import the application into your desktop:

mbed import https://os.mbed.com/teams/Advantech/code/pelion-example-common
cd pelion-example-common

2. Download your developer certificate from pelion portal

3. Compile the program

mbed compile -t <toolchain> -m <TARGET_BOARD>

(supported toolchains : GCC_ARM / ARM / IAR)

4. Copy the binary file pelion-example-common.bin to your mbed device.

README.md@0:43ff9e3bc244, 2019-03-12 (annotated)

Committer:
chuanga
Date:
Tue Mar 12 13:48:39 2019 +0800
Revision:
0:43ff9e3bc244
copying sources from github repository

Who changed what in which revision?

UserRevisionLine numberNew contents of line
chuanga 0:43ff9e3bc244 1 # Pelion Device Ready example - template application
chuanga 0:43ff9e3bc244 2
chuanga 0:43ff9e3bc244 3 (aka Simple Mbed Cloud Client template)
chuanga 0:43ff9e3bc244 4
chuanga 0:43ff9e3bc244 5 ## Overview
chuanga 0:43ff9e3bc244 6
chuanga 0:43ff9e3bc244 7 This is a template application to showcase device management capabilities. It demonstrates how to create a simple application that can connect to the Pelion IoT Platform service, register resources and get ready to receive a firmware update.
chuanga 0:43ff9e3bc244 8
chuanga 0:43ff9e3bc244 9 It's intended to be forked and customized to add platform-specific features (such as sensors and actuators) and configure the connectivity and storage to work **out-of-the-box**. The template application works in **developer mode** by default.
chuanga 0:43ff9e3bc244 10
chuanga 0:43ff9e3bc244 11 There is a mirror version of the stable (master) template application on [this location](https://os.mbed.com/teams/mbed-os-examples/code/pelion-ready-example) to facilitate the fork and publish on https://os.mbed.com.
chuanga 0:43ff9e3bc244 12
chuanga 0:43ff9e3bc244 13 ## Board specific example applications
chuanga 0:43ff9e3bc244 14
chuanga 0:43ff9e3bc244 15 There are a number of applications that make usage of the Simple Pelion DM Client library.
chuanga 0:43ff9e3bc244 16
chuanga 0:43ff9e3bc244 17 The Pelion [Quick-Start](https://cloud.mbed.com/quick-start) is an initiative to support Mbed Partner's platforms while delivering a great User Experience to Mbed Developers.
chuanga 0:43ff9e3bc244 18
chuanga 0:43ff9e3bc244 19 ## Getting started with the application
chuanga 0:43ff9e3bc244 20
chuanga 0:43ff9e3bc244 21 This is a summary of the process for developers to get started and get a device connected to Pelion Device Management.
chuanga 0:43ff9e3bc244 22
chuanga 0:43ff9e3bc244 23 ### Using Mbed Online IDE
chuanga 0:43ff9e3bc244 24
chuanga 0:43ff9e3bc244 25 1. Import the application into the Online IDE.
chuanga 0:43ff9e3bc244 26 2. Add the API key to establish connection.
chuanga 0:43ff9e3bc244 27 3. Install the developer certificate.
chuanga 0:43ff9e3bc244 28 4. Compile and program.
chuanga 0:43ff9e3bc244 29
chuanga 0:43ff9e3bc244 30 ### Using Mbed CLI
chuanga 0:43ff9e3bc244 31
chuanga 0:43ff9e3bc244 32 1. Import the application into your desktop:
chuanga 0:43ff9e3bc244 33
chuanga 0:43ff9e3bc244 34 ```
chuanga 0:43ff9e3bc244 35 mbed import https://github.com/ARMmbed/pelion-ready-example
chuanga 0:43ff9e3bc244 36 cd pelion-ready-example
chuanga 0:43ff9e3bc244 37 ```
chuanga 0:43ff9e3bc244 38
chuanga 0:43ff9e3bc244 39 2. Configure the API key for your Pelion Portal account.
chuanga 0:43ff9e3bc244 40
chuanga 0:43ff9e3bc244 41 If you don't have an API key available, then login in [Pelion IoT Platform portal](https://portal.mbedcloud.com/), navigate to 'Access Management', 'API keys' and create a new one. Then specify the API key as global `mbed` configuration:
chuanga 0:43ff9e3bc244 42
chuanga 0:43ff9e3bc244 43 ```
chuanga 0:43ff9e3bc244 44 mbed config -G CLOUD_SDK_API_KEY <your-api-key>
chuanga 0:43ff9e3bc244 45 ```
chuanga 0:43ff9e3bc244 46
chuanga 0:43ff9e3bc244 47 3. Install the device management certificate:
chuanga 0:43ff9e3bc244 48
chuanga 0:43ff9e3bc244 49 ```
chuanga 0:43ff9e3bc244 50 mbed dm init -d "company.com" --model-name "product-model" -q --force
chuanga 0:43ff9e3bc244 51 ```
chuanga 0:43ff9e3bc244 52
chuanga 0:43ff9e3bc244 53 4. Compile and program:
chuanga 0:43ff9e3bc244 54
chuanga 0:43ff9e3bc244 55 ```
chuanga 0:43ff9e3bc244 56 mbed compile -t <toolchain> -m <target> -f
chuanga 0:43ff9e3bc244 57 ```
chuanga 0:43ff9e3bc244 58
chuanga 0:43ff9e3bc244 59 #### Update the application logic
chuanga 0:43ff9e3bc244 60
chuanga 0:43ff9e3bc244 61 The template example uses a ticker object to periodically fire a software interrupt to simulate button presses. Let’s say you want to make an actual button press.
chuanga 0:43ff9e3bc244 62
chuanga 0:43ff9e3bc244 63 By default, there is a Ticker object, which fires every five seconds and invokes a callback function:
chuanga 0:43ff9e3bc244 64
chuanga 0:43ff9e3bc244 65 ```cpp
chuanga 0:43ff9e3bc244 66 Ticker timer;
chuanga 0:43ff9e3bc244 67 timer.attach(eventQueue.event(&fake_button_press), 5.0);
chuanga 0:43ff9e3bc244 68 ```
chuanga 0:43ff9e3bc244 69
chuanga 0:43ff9e3bc244 70 This callback function changes the `button_res` resource:
chuanga 0:43ff9e3bc244 71
chuanga 0:43ff9e3bc244 72 ```cpp
chuanga 0:43ff9e3bc244 73 void fake_button_press() {
chuanga 0:43ff9e3bc244 74 int v = button_res->get_value_int() + 1;
chuanga 0:43ff9e3bc244 75
chuanga 0:43ff9e3bc244 76 button_res->set_value(v);
chuanga 0:43ff9e3bc244 77
chuanga 0:43ff9e3bc244 78 printf("Simulated button clicked %d times\n", v);
chuanga 0:43ff9e3bc244 79 }
chuanga 0:43ff9e3bc244 80 ```
chuanga 0:43ff9e3bc244 81
chuanga 0:43ff9e3bc244 82 If you want to change this to an actual button, here is how to do it:
chuanga 0:43ff9e3bc244 83
chuanga 0:43ff9e3bc244 84 1. Remove:
chuanga 0:43ff9e3bc244 85
chuanga 0:43ff9e3bc244 86 ```cpp
chuanga 0:43ff9e3bc244 87 Ticker timer;
chuanga 0:43ff9e3bc244 88 timer.attach(eventQueue.event(&fake_button_press), 5.0);
chuanga 0:43ff9e3bc244 89 ```
chuanga 0:43ff9e3bc244 90
chuanga 0:43ff9e3bc244 91 2. Declare an `InterruptIn` object on the button, and attach the callback function to the `fall` handler:
chuanga 0:43ff9e3bc244 92
chuanga 0:43ff9e3bc244 93 ```cpp
chuanga 0:43ff9e3bc244 94 InterruptIn btn(BUTTON1);
chuanga 0:43ff9e3bc244 95 btn.fall(eventQueue.event(&fake_button_press), 5.0);
chuanga 0:43ff9e3bc244 96 ```
chuanga 0:43ff9e3bc244 97
chuanga 0:43ff9e3bc244 98 3. Rename `fake_button_press` to `real_button_press`.
chuanga 0:43ff9e3bc244 99
chuanga 0:43ff9e3bc244 100 ## Enabling firmware updates
chuanga 0:43ff9e3bc244 101
chuanga 0:43ff9e3bc244 102 Mbed OS 5.10 and Mbed CLI 1.8 simplifies the process to enable and perform Firmware Updates. Here is a summary on how to configure the device and verify its correct behaviour.
chuanga 0:43ff9e3bc244 103
chuanga 0:43ff9e3bc244 104 For full documentation about bootloaders and firmware update, read the following documents:
chuanga 0:43ff9e3bc244 105
chuanga 0:43ff9e3bc244 106 - [Introduccion to bootloaders](https://os.mbed.com/docs/latest/porting/bootloader.html)
chuanga 0:43ff9e3bc244 107 - [Creating and using a bootloader](https://os.mbed.com/docs/latest/tutorials/bootloader.html)
chuanga 0:43ff9e3bc244 108 - [Bootloader configuration in Mbed OS](https://os.mbed.com/docs/latest/tools/configuring-tools.html)
chuanga 0:43ff9e3bc244 109 - [Mbed Bootloader for Pelion Device Management Client](https://github.com/ARMmbed/mbed-bootloader)
chuanga 0:43ff9e3bc244 110 - [Updating devices with Arm Mbed CLI](https://os.mbed.com/docs/latest/tools/cli-update.html)
chuanga 0:43ff9e3bc244 111
chuanga 0:43ff9e3bc244 112 This is a summary to use Arm Mbed OS managed bootloaders.
chuanga 0:43ff9e3bc244 113
chuanga 0:43ff9e3bc244 114 #### Verifying that firmware update works
chuanga 0:43ff9e3bc244 115
chuanga 0:43ff9e3bc244 116 Follow these steps to generate a manifest, compile and perform a firmware update of your device:
chuanga 0:43ff9e3bc244 117
chuanga 0:43ff9e3bc244 118 1. Configure the API key for your Pelion account.
chuanga 0:43ff9e3bc244 119
chuanga 0:43ff9e3bc244 120 If you don't have an API key available, then login in [Pelion IoT Platform portal](https://portal.mbedcloud.com/), navigate to 'Access Management', 'API keys' and create a new one. Then specify the API key as global `mbed` configuration:
chuanga 0:43ff9e3bc244 121
chuanga 0:43ff9e3bc244 122 ```
chuanga 0:43ff9e3bc244 123 mbed config -G CLOUD_SDK_API_KEY <your-api-key>
chuanga 0:43ff9e3bc244 124 ```
chuanga 0:43ff9e3bc244 125
chuanga 0:43ff9e3bc244 126 2. Initialize the device management feature:
chuanga 0:43ff9e3bc244 127
chuanga 0:43ff9e3bc244 128 ```
chuanga 0:43ff9e3bc244 129 mbed dm init -d "company.com" --model-name "product-model" -q --force
chuanga 0:43ff9e3bc244 130 ```
chuanga 0:43ff9e3bc244 131
chuanga 0:43ff9e3bc244 132 3. Compile the application, include the firware update credentials generated before, merge with the bootloader and program the device:
chuanga 0:43ff9e3bc244 133
chuanga 0:43ff9e3bc244 134 ```
chuanga 0:43ff9e3bc244 135 mbed compile -t <toolchain> -m <target> -c -f
chuanga 0:43ff9e3bc244 136 ```
chuanga 0:43ff9e3bc244 137
chuanga 0:43ff9e3bc244 138 4. Open a serial terminal, verify the application boots and is able to register to the Device Management service. Write down the `<endpoint ID>`, as it's required to identify the device to perform a firmware update.
chuanga 0:43ff9e3bc244 139
chuanga 0:43ff9e3bc244 140 5. Update the firmware of the device through Mbed CLI:
chuanga 0:43ff9e3bc244 141
chuanga 0:43ff9e3bc244 142 ```
chuanga 0:43ff9e3bc244 143 mbed dm update device -D <device ID> -t <toolchain> -m <target>
chuanga 0:43ff9e3bc244 144 ```
chuanga 0:43ff9e3bc244 145
chuanga 0:43ff9e3bc244 146 Inspect the logs on the device to see the update progress. It should look similar to:
chuanga 0:43ff9e3bc244 147
chuanga 0:43ff9e3bc244 148 ```
chuanga 0:43ff9e3bc244 149 Firmware download requested
chuanga 0:43ff9e3bc244 150 Authorization granted
chuanga 0:43ff9e3bc244 151 Downloading: [+++- ] 6 %
chuanga 0:43ff9e3bc244 152 ```
chuanga 0:43ff9e3bc244 153
chuanga 0:43ff9e3bc244 154 When the download completes, the firmware is verified. If everything is OK, the firmware update is applied, the device reboots and attemps to connect to the Device Management service again. The `<endpoint ID>` should be preserved.
chuanga 0:43ff9e3bc244 155
chuanga 0:43ff9e3bc244 156 ## Automated testing
chuanga 0:43ff9e3bc244 157
chuanga 0:43ff9e3bc244 158 The Simple Pelion Client provides Greentea tests to confirm your platform works as expected. The network and storage configuration is already defined in Mbed OS 5.10, but you may want to override the configuration in `mbed_app.json`.
chuanga 0:43ff9e3bc244 159
chuanga 0:43ff9e3bc244 160 For details on Simple Pelion Client testing, refer to the documentation [here](https://github.com/ARMmbed/simple-mbed-cloud-client#testing).
chuanga 0:43ff9e3bc244 161
chuanga 0:43ff9e3bc244 162 This template application contains a working application and tests passing for the `K64F` and `K66F` platforms.