Renesas / Mbed OS pelion-example-common

Generic Pelion Device Management example for various Renesas-based boards.

DEPRECATED

This example application is not maintained and not recommended. It uses an old version of Mbed OS, Pelion DM, and Arm toolchain. It doesn't work with Mbed Studio.

Please use: https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-pelion/

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

https://os.mbed.com/media/cache/platforms/GR-LYCHEE_and_cam.png.250x250_q85.png https://os.mbed.com/media/cache/platforms/GR-PEACH_C_trans.png.250x250_q85.png

Follow the Quick-Start instructions: https://cloud.mbed.com/quick-start

Example functionality

This example showcases the following device functionality:

  • On user button click, increment Pelion LWM2M button resource.
  • Allow the user to change the state of the board LED from Pelion LWM2M led_state resource and PUT request.

Instructions to use this program with Mbed CLI


1. Import the application into your desktop:

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


2. Install the CLOUD_SDK_API_KEY

mbed config -G CLOUD_SDK_API_KEY <PELION_DM_API_KEY>

For instructions on how to generate your API key, please see the documentation.

3. Initialize firmware credentials (done once per repository). You can use the following command:

mbed dm init -d "<your company name in Pelion DM>" --model-name "<product model identifier>" -q --force

If above command do not work for your Mbed CLI, please consider upgrading Mbed CLI to version 1.8.x or above.

4. Compile and program:

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

(supported toolchains : GCC_ARM / ARM / IAR)

Note

This platform and application is suitable for evaluation and initial development. For production purposes, we recommend to use a different variant with built-in security features - for more information please contact Renesas (https://en-support.renesas.com/mytickets)

README.md@0:6d2053b84a92, 2018-12-15 (annotated)

Committer:
MACRUM
Date:
Sat Dec 15 12:47:53 2018 +0900
Revision:
0:6d2053b84a92
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MACRUM 0:6d2053b84a92 1 # Simple Pelion Device Management Client - template application
MACRUM 0:6d2053b84a92 2
MACRUM 0:6d2053b84a92 3 (aka Simple Mbed Cloud Client template)
MACRUM 0:6d2053b84a92 4
MACRUM 0:6d2053b84a92 5 ## Overview
MACRUM 0:6d2053b84a92 6
MACRUM 0:6d2053b84a92 7 This is a template application for platform vendors. 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.
MACRUM 0:6d2053b84a92 8
MACRUM 0:6d2053b84a92 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.
MACRUM 0:6d2053b84a92 10
MACRUM 0:6d2053b84a92 11 There is a mirror version of the stable (master) template application on [this location](https://os.mbed.com/teams/mbed-os-examples/code/mbed-cloud-example) to facilitate the fork and publish on os.mbed.com.
MACRUM 0:6d2053b84a92 12
MACRUM 0:6d2053b84a92 13 ## Table of Contents
MACRUM 0:6d2053b84a92 14
MACRUM 0:6d2053b84a92 15 1. [Getting started with the application](#getting-started-with-the-application)
MACRUM 0:6d2053b84a92 16 2. [Porting to a new platform](#porting-to-a-new-platform)
MACRUM 0:6d2053b84a92 17 3. [Enabling firmware updates](#enabling-firmware-updates)
MACRUM 0:6d2053b84a92 18 4. [Automated testing](#automated-testing)
MACRUM 0:6d2053b84a92 19 5. [Known issues](#known-issues)
MACRUM 0:6d2053b84a92 20
MACRUM 0:6d2053b84a92 21 ## Getting started with the application
MACRUM 0:6d2053b84a92 22
MACRUM 0:6d2053b84a92 23 This is a summary of the process for developers to get started and get a device connected to Pelion Device Management Client.
MACRUM 0:6d2053b84a92 24
MACRUM 0:6d2053b84a92 25 ### Mbed Online IDE
MACRUM 0:6d2053b84a92 26
MACRUM 0:6d2053b84a92 27 1. Import the application into the Online IDE.
MACRUM 0:6d2053b84a92 28 2. Add the API key to establish connection.
MACRUM 0:6d2053b84a92 29 3. Install the developer certificate.
MACRUM 0:6d2053b84a92 30 4. Compile and program.
MACRUM 0:6d2053b84a92 31
MACRUM 0:6d2053b84a92 32 ### Mbed CLI tools
MACRUM 0:6d2053b84a92 33
MACRUM 0:6d2053b84a92 34 1. Import the application into your desktop:
MACRUM 0:6d2053b84a92 35
MACRUM 0:6d2053b84a92 36 ```
MACRUM 0:6d2053b84a92 37 mbed import https://os.mbed.com/teams/mbed-os-examples/code/mbed-cloud-example
MACRUM 0:6d2053b84a92 38 cd mbed-cloud-example
MACRUM 0:6d2053b84a92 39 ```
MACRUM 0:6d2053b84a92 40
MACRUM 0:6d2053b84a92 41 2. Download the developer certificate from the Pelion Device Management [portal](https://portal.mbedcloud.com).
MACRUM 0:6d2053b84a92 42 3. Compile and program:
MACRUM 0:6d2053b84a92 43
MACRUM 0:6d2053b84a92 44 ```
MACRUM 0:6d2053b84a92 45 mbed compile -t <toolchain> -m <target> -f
MACRUM 0:6d2053b84a92 46 ```
MACRUM 0:6d2053b84a92 47
MACRUM 0:6d2053b84a92 48 ## Porting to a new platform
MACRUM 0:6d2053b84a92 49
MACRUM 0:6d2053b84a92 50 ### Requirements
MACRUM 0:6d2053b84a92 51
MACRUM 0:6d2053b84a92 52 The hardware requirements for Mbed OS platforms to support Pelion Client are [here](https://cloud.mbed.com/docs/current/cloud-requirements/index.html).
MACRUM 0:6d2053b84a92 53
MACRUM 0:6d2053b84a92 54 In general, to start creating a secure connected product, you need a microcontroller that has the following features:
MACRUM 0:6d2053b84a92 55
MACRUM 0:6d2053b84a92 56 * RAM: 96K or more
MACRUM 0:6d2053b84a92 57 * Flash: 512K or more
MACRUM 0:6d2053b84a92 58 * True Random Number Generator (TRNG)
MACRUM 0:6d2053b84a92 59 * Real Time Clock (RTC)
MACRUM 0:6d2053b84a92 60
MACRUM 0:6d2053b84a92 61 Additionally, to use the Device Management Client, the microcontroller needs to support the following in Mbed OS (latest version preferred) or in a compatible driver library:
MACRUM 0:6d2053b84a92 62
MACRUM 0:6d2053b84a92 63 * A storage device (SDcard, SPI Flash, Data Flash)
MACRUM 0:6d2053b84a92 64 * IP connectivity (Ethernet, Wi-Fi, Cellular, 6LoWPAN, Thread)
MACRUM 0:6d2053b84a92 65
MACRUM 0:6d2053b84a92 66 For the Firmware update over the air (FOTA), you need the following:
MACRUM 0:6d2053b84a92 67
MACRUM 0:6d2053b84a92 68 * [FlashIAP](https://github.com/ARMmbed/mbed-os/blob/master/drivers/FlashIAP.h) - Flash In-Application Programming (IAP).
MACRUM 0:6d2053b84a92 69 * [Mbed Bootloader](https://github.com/ARMmbed/mbed-bootloader) or a compatible bootloader.
MACRUM 0:6d2053b84a92 70 * TCP connection - the current Firmware Download client only supports HTTP download over TCP (this will be resolved in a future release, so that CoAP blockwise transfer will be used for UDP connections).
MACRUM 0:6d2053b84a92 71
MACRUM 0:6d2053b84a92 72 ### References
MACRUM 0:6d2053b84a92 73
MACRUM 0:6d2053b84a92 74 * Check which Mbed OS platforms are supported in the [Pelion Device Management quick-start guide](https://cloud.mbed.com/quick-start).
MACRUM 0:6d2053b84a92 75 * Check which storage options are available [here](https://os.mbed.com/docs/latest/reference/storage.html).
MACRUM 0:6d2053b84a92 76 * Check which network options are available [here](https://os.mbed.com/docs/latest/reference/network-socket.html).
MACRUM 0:6d2053b84a92 77
MACRUM 0:6d2053b84a92 78
MACRUM 0:6d2053b84a92 79 ### Porting steps
MACRUM 0:6d2053b84a92 80
MACRUM 0:6d2053b84a92 81 Supporting a new derivative platform requires the following steps:
MACRUM 0:6d2053b84a92 82
MACRUM 0:6d2053b84a92 83 * Fork the template and create an example application for your platform in https://os.mbed.com/teams/your-team
MACRUM 0:6d2053b84a92 84 * Change the connectivity interface. Ethernet is the default - see `main.cpp`.
MACRUM 0:6d2053b84a92 85 * Change the filesystem and/or the block device for storage. FAT filesystem over SD card is the default. See `main.cpp`.
MACRUM 0:6d2053b84a92 86 * (Optional) Make minor changes in `mbed_app.json` to support multiple platforms with same connectivity and storage.
MACRUM 0:6d2053b84a92 87 * (Recommended) Remove information and files not related to the platform you're porting.
MACRUM 0:6d2053b84a92 88
MACRUM 0:6d2053b84a92 89 <span class="notes">**Note:** Make sure that the application works out-of-the-box and no changes are required in the `main.cpp` file nor `mbed_app.json`. The goal is to deliver a great UX to our developers.</span>
MACRUM 0:6d2053b84a92 90
MACRUM 0:6d2053b84a92 91 ### Porting example
MACRUM 0:6d2053b84a92 92
MACRUM 0:6d2053b84a92 93 In this example, an app with an SD card and on-chip Ethernet is taken to a custom board that has an MCU + Wi-Fi module.
MACRUM 0:6d2053b84a92 94
MACRUM 0:6d2053b84a92 95 #### Changing the storage option
MACRUM 0:6d2053b84a92 96
MACRUM 0:6d2053b84a92 97 <span class="notes">**Note:** From Mbed OS 5.10+, block device drivers have been moved to `mbed-os/components/storage/blockdevice` and many platforms have a default block device interface. </span>
MACRUM 0:6d2053b84a92 98
MACRUM 0:6d2053b84a92 99 ##### Non-default storage configuration
MACRUM 0:6d2053b84a92 100
MACRUM 0:6d2053b84a92 101 If you wish to override the default storage configuration or add support for storage, you can add the configuration into the `mbed_app.json` file. For example:
MACRUM 0:6d2053b84a92 102
MACRUM 0:6d2053b84a92 103 ```json
MACRUM 0:6d2053b84a92 104 "NUCLEO_F429ZI": {
MACRUM 0:6d2053b84a92 105 "target.features_add" : ["STORAGE"],
MACRUM 0:6d2053b84a92 106 "target.components_add": ["SD"],
MACRUM 0:6d2053b84a92 107 "sd.SPI_MOSI" : "PE_6",
MACRUM 0:6d2053b84a92 108 "sd.SPI_MISO" : "PE_5",
MACRUM 0:6d2053b84a92 109 "sd.SPI_CLK" : "PE_2",
MACRUM 0:6d2053b84a92 110 "sd.SPI_CS" : "PE_4"
MACRUM 0:6d2053b84a92 111 }
MACRUM 0:6d2053b84a92 112 ```
MACRUM 0:6d2053b84a92 113
MACRUM 0:6d2053b84a92 114 ##### Example of default storage configuration using Mbed OS 5.10+
MACRUM 0:6d2053b84a92 115
MACRUM 0:6d2053b84a92 116 1. Include the header files for the FAT file system:
MACRUM 0:6d2053b84a92 117
MACRUM 0:6d2053b84a92 118 ```cpp
MACRUM 0:6d2053b84a92 119 #include "FATFileSystem.h"
MACRUM 0:6d2053b84a92 120 ```
MACRUM 0:6d2053b84a92 121
MACRUM 0:6d2053b84a92 122 2. Declare the global object for the default block device driver:
MACRUM 0:6d2053b84a92 123
MACRUM 0:6d2053b84a92 124 ```cpp
MACRUM 0:6d2053b84a92 125 BlockDevice* bd = BlockDevice::get_default_instance();
MACRUM 0:6d2053b84a92 126 ```
MACRUM 0:6d2053b84a92 127
MACRUM 0:6d2053b84a92 128 3. Declare the global objects for the file system:
MACRUM 0:6d2053b84a92 129
MACRUM 0:6d2053b84a92 130 ```cpp
MACRUM 0:6d2053b84a92 131 FATFileSystem fs("sd", bd);
MACRUM 0:6d2053b84a92 132 ```
MACRUM 0:6d2053b84a92 133
MACRUM 0:6d2053b84a92 134 ##### Example of SD card configuration using Mbed OS 5.9 and older
MACRUM 0:6d2053b84a92 135
MACRUM 0:6d2053b84a92 136 1. Add the SD card driver (`sd-driver.lib`) if it is not already added. On the command line:
MACRUM 0:6d2053b84a92 137
MACRUM 0:6d2053b84a92 138 ```
MACRUM 0:6d2053b84a92 139 mbed add https://github.com/armmbed/sd-driver
MACRUM 0:6d2053b84a92 140 ```
MACRUM 0:6d2053b84a92 141
MACRUM 0:6d2053b84a92 142 2. Include the header files for the SD driver and FAT file system:
MACRUM 0:6d2053b84a92 143
MACRUM 0:6d2053b84a92 144 ```cpp
MACRUM 0:6d2053b84a92 145 #include "SDBlockDevice.h"
MACRUM 0:6d2053b84a92 146 #include "FATFileSystem.h"
MACRUM 0:6d2053b84a92 147 ```
MACRUM 0:6d2053b84a92 148
MACRUM 0:6d2053b84a92 149 3. Declare the global objects for the SD card and file system:
MACRUM 0:6d2053b84a92 150
MACRUM 0:6d2053b84a92 151 ```cpp
MACRUM 0:6d2053b84a92 152 SDBlockDevice bd(SPI_MOSI, SPI_MISO, SPI_CLK, SPI_CS);
MACRUM 0:6d2053b84a92 153 FATFileSystem fs("sd", &sd);
MACRUM 0:6d2053b84a92 154 ```
MACRUM 0:6d2053b84a92 155
MACRUM 0:6d2053b84a92 156 <span class="notes">**Note:** The `SPI_*` macros represent the pin names. The names can be defined in a variety of places including the sd-driver, your project’s configuration file (`mbed_app.json`) or the `pinnames.h` file for the target that defines the default pin names. You can use other pin names depending on the platform and the connections.</span>
MACRUM 0:6d2053b84a92 157
MACRUM 0:6d2053b84a92 158 For example, if the SPI signals for the SD card interface are connected on an Arduino compatible shield, you may define them like this:
MACRUM 0:6d2053b84a92 159
MACRUM 0:6d2053b84a92 160 ```cpp
MACRUM 0:6d2053b84a92 161 SDBlockDevice sd(D11, D12, D13, D10);
MACRUM 0:6d2053b84a92 162 ```
MACRUM 0:6d2053b84a92 163
MACRUM 0:6d2053b84a92 164 <span class="notes">**Note:** The default mounting point is `sd`. This can be overridden in the `mbed_app.json` file using `PAL_FS_MOUNT_POINT_PRIMARY` and `PAL_FS_MOUNT_POINT_SECONDARY`. See [documentation](https://cloud.mbed.com/docs/current/porting/port-filesystem.html).</span>
MACRUM 0:6d2053b84a92 165
MACRUM 0:6d2053b84a92 166 ##### For SPI Flash (devices that support SFDP)
MACRUM 0:6d2053b84a92 167
MACRUM 0:6d2053b84a92 168 <Please note that this section of the document is under construction. More information is needed.>
MACRUM 0:6d2053b84a92 169
MACRUM 0:6d2053b84a92 170 1. Add the SPI Flash driver (`spif-driver`) if it is not already added:
MACRUM 0:6d2053b84a92 171
MACRUM 0:6d2053b84a92 172 ```
MACRUM 0:6d2053b84a92 173 mbed add https://github.com/armmbed/spif-driver
MACRUM 0:6d2053b84a92 174 ```
MACRUM 0:6d2053b84a92 175
MACRUM 0:6d2053b84a92 176 2. Include the header files for the SPI Flash driver and LitteFS file system. For SPI Flash, we recommend LittleFS file system which supports wear leveling:
MACRUM 0:6d2053b84a92 177
MACRUM 0:6d2053b84a92 178 ```cpp
MACRUM 0:6d2053b84a92 179 #include "SPIFBlockDevice.h"
MACRUM 0:6d2053b84a92 180 #include "LittleFileSystem.h"
MACRUM 0:6d2053b84a92 181 ```
MACRUM 0:6d2053b84a92 182
MACRUM 0:6d2053b84a92 183 3. Declare the global objects for the SD card and file system:
MACRUM 0:6d2053b84a92 184
MACRUM 0:6d2053b84a92 185 ```cpp
MACRUM 0:6d2053b84a92 186 SPIFBlockDevice spif(SPI_MOSI, SPI_MISO, SPI_CLK, SPI_CS);
MACRUM 0:6d2053b84a92 187 LittleFileSystem fs("fs", &spif);
MACRUM 0:6d2053b84a92 188 ```
MACRUM 0:6d2053b84a92 189
MACRUM 0:6d2053b84a92 190 4. Update the construction of the `SimpleMbedCloudClient` object to pass in the file system and block device:
MACRUM 0:6d2053b84a92 191
MACRUM 0:6d2053b84a92 192 ```cpp
MACRUM 0:6d2053b84a92 193 SimpleMbedCloudClient client(&net, &spif, &fs);
MACRUM 0:6d2053b84a92 194 ```
MACRUM 0:6d2053b84a92 195
MACRUM 0:6d2053b84a92 196 #### Changing the network interface
MACRUM 0:6d2053b84a92 197
MACRUM 0:6d2053b84a92 198 <span class="notes">**Note:** From Mbed OS 5.10, platforms have a default network interface defined in `mbed-os/targets/targets.json`. If you wish to override the default configuration, you can add the configuration into the `mbed_app.json` file.</span>
MACRUM 0:6d2053b84a92 199
MACRUM 0:6d2053b84a92 200 ##### Non-default network configuration
MACRUM 0:6d2053b84a92 201
MACRUM 0:6d2053b84a92 202 If you wish to override the default network configuration, you can add the configuration into the `mbed_app.json` file. For example:
MACRUM 0:6d2053b84a92 203
MACRUM 0:6d2053b84a92 204 ```json
MACRUM 0:6d2053b84a92 205 "NUCLEO_F429ZI": {
MACRUM 0:6d2053b84a92 206 "target.network-default-interface-type" : "WIFI",
MACRUM 0:6d2053b84a92 207 "esp8266.rx" : "D0",
MACRUM 0:6d2053b84a92 208 "esp8266.tx" : "D1",
MACRUM 0:6d2053b84a92 209 "esp8266.provide-default" : true,
MACRUM 0:6d2053b84a92 210 "nsapi.default-wifi-security" : "WPA_WPA2",
MACRUM 0:6d2053b84a92 211 "nsapi.default-wifi-ssid" : "\"SSID\"",
MACRUM 0:6d2053b84a92 212 "nsapi.default-wifi-password" : "\"Password\""
MACRUM 0:6d2053b84a92 213 }
MACRUM 0:6d2053b84a92 214 ```
MACRUM 0:6d2053b84a92 215
MACRUM 0:6d2053b84a92 216 ##### Example of network initialization for Ethernet using Mbed OS 5.10+
MACRUM 0:6d2053b84a92 217
MACRUM 0:6d2053b84a92 218 1. Declare the network interface object:
MACRUM 0:6d2053b84a92 219
MACRUM 0:6d2053b84a92 220 ```
MACRUM 0:6d2053b84a92 221 EthernetInterface * net = NetworkInterface::get_default_instance();
MACRUM 0:6d2053b84a92 222 ```
MACRUM 0:6d2053b84a92 223
MACRUM 0:6d2053b84a92 224 2. Connect the interface:
MACRUM 0:6d2053b84a92 225
MACRUM 0:6d2053b84a92 226 ```
MACRUM 0:6d2053b84a92 227 status = net->connect();
MACRUM 0:6d2053b84a92 228 ```
MACRUM 0:6d2053b84a92 229
MACRUM 0:6d2053b84a92 230 3. When the Client is started, pass the network interface:
MACRUM 0:6d2053b84a92 231 ```
MACRUM 0:6d2053b84a92 232 SimpleMbedCloudClient client(net, &sd, &fs);
MACRUM 0:6d2053b84a92 233 ```
MACRUM 0:6d2053b84a92 234
MACRUM 0:6d2053b84a92 235 ##### Example of network initialization for Wi-Fi using Mbed OS 5.10+
MACRUM 0:6d2053b84a92 236
MACRUM 0:6d2053b84a92 237 1. Declare the network interface object:
MACRUM 0:6d2053b84a92 238
MACRUM 0:6d2053b84a92 239 ```
MACRUM 0:6d2053b84a92 240 WiFiInterface *net = WiFiInterface::get_default_instance();
MACRUM 0:6d2053b84a92 241 ```
MACRUM 0:6d2053b84a92 242
MACRUM 0:6d2053b84a92 243 2. Connect the interface:
MACRUM 0:6d2053b84a92 244
MACRUM 0:6d2053b84a92 245 ```
MACRUM 0:6d2053b84a92 246 status = net->connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
MACRUM 0:6d2053b84a92 247 ```
MACRUM 0:6d2053b84a92 248
MACRUM 0:6d2053b84a92 249 3. When the Client is started, pass the network interface:
MACRUM 0:6d2053b84a92 250
MACRUM 0:6d2053b84a92 251 ```
MACRUM 0:6d2053b84a92 252 SimpleMbedCloudClient client(net, &sd, &fs);
MACRUM 0:6d2053b84a92 253 ```
MACRUM 0:6d2053b84a92 254
MACRUM 0:6d2053b84a92 255
MACRUM 0:6d2053b84a92 256 ##### Example of network initialization for Ethernet using Mbed OS 5.9 and older versions
MACRUM 0:6d2053b84a92 257
MACRUM 0:6d2053b84a92 258 The Ethernet interface is included within Mbed OS, so you do not need to add a library.
MACRUM 0:6d2053b84a92 259
MACRUM 0:6d2053b84a92 260 1. Include the header file for the interface:
MACRUM 0:6d2053b84a92 261
MACRUM 0:6d2053b84a92 262 ```
MACRUM 0:6d2053b84a92 263 #include "EthernetInterface.h"
MACRUM 0:6d2053b84a92 264 ```
MACRUM 0:6d2053b84a92 265
MACRUM 0:6d2053b84a92 266 2. Declare the network interface object:
MACRUM 0:6d2053b84a92 267
MACRUM 0:6d2053b84a92 268 ```
MACRUM 0:6d2053b84a92 269 EthernetInterface net;
MACRUM 0:6d2053b84a92 270 ```
MACRUM 0:6d2053b84a92 271
MACRUM 0:6d2053b84a92 272 3. Connect the interface:
MACRUM 0:6d2053b84a92 273
MACRUM 0:6d2053b84a92 274 ```
MACRUM 0:6d2053b84a92 275 status = net.connect();
MACRUM 0:6d2053b84a92 276 ```
MACRUM 0:6d2053b84a92 277
MACRUM 0:6d2053b84a92 278 4. When the Client is started, pass the network interface:
MACRUM 0:6d2053b84a92 279
MACRUM 0:6d2053b84a92 280 ```
MACRUM 0:6d2053b84a92 281 SimpleMbedCloudClient client(&net, &sd, &fs);
MACRUM 0:6d2053b84a92 282 ```
MACRUM 0:6d2053b84a92 283
MACRUM 0:6d2053b84a92 284 ##### Example of network initialization for Wi-Fi using Mbed OS 5.9 and older versions
MACRUM 0:6d2053b84a92 285
MACRUM 0:6d2053b84a92 286 This example references the ESP8266 Wi-Fi module, but the instructions are applicable to other modules.
MACRUM 0:6d2053b84a92 287
MACRUM 0:6d2053b84a92 288 1. Add the ESP8266 Wi-Fi interface driver (esp8266-driver) if it is not already added:
MACRUM 0:6d2053b84a92 289
MACRUM 0:6d2053b84a92 290 ```
MACRUM 0:6d2053b84a92 291 mbed add https://github.com/ARMmbed/esp8266-driver
MACRUM 0:6d2053b84a92 292 ```
MACRUM 0:6d2053b84a92 293
MACRUM 0:6d2053b84a92 294 <span class="notes">**Note:** You may have to update the firmware inside the ESP8266 module.</span>
MACRUM 0:6d2053b84a92 295
MACRUM 0:6d2053b84a92 296 2. Include the header file for the interface:
MACRUM 0:6d2053b84a92 297
MACRUM 0:6d2053b84a92 298 ```cpp
MACRUM 0:6d2053b84a92 299 #include "ESP8266Interface.h"
MACRUM 0:6d2053b84a92 300 ```
MACRUM 0:6d2053b84a92 301
MACRUM 0:6d2053b84a92 302 3. Declare the network interface object:
MACRUM 0:6d2053b84a92 303
MACRUM 0:6d2053b84a92 304 ```cpp
MACRUM 0:6d2053b84a92 305 ESP8266Interface net(D1, D0);
MACRUM 0:6d2053b84a92 306 ```
MACRUM 0:6d2053b84a92 307
MACRUM 0:6d2053b84a92 308 4. Connect the interface:
MACRUM 0:6d2053b84a92 309
MACRUM 0:6d2053b84a92 310 ```cpp
MACRUM 0:6d2053b84a92 311 nsapi_error_t status = net.connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
MACRUM 0:6d2053b84a92 312 ```
MACRUM 0:6d2053b84a92 313
MACRUM 0:6d2053b84a92 314 5. When the Client is started, pass the network interface:
MACRUM 0:6d2053b84a92 315
MACRUM 0:6d2053b84a92 316 ```cpp
MACRUM 0:6d2053b84a92 317 SimpleMbedCloudClient client(&net, &sd, &fs);
MACRUM 0:6d2053b84a92 318 ```
MACRUM 0:6d2053b84a92 319
MACRUM 0:6d2053b84a92 320 6. Add the Wi-Fi credentials information in `mbed_app.json` (located at the top level of the example project):
MACRUM 0:6d2053b84a92 321
MACRUM 0:6d2053b84a92 322 ```json
MACRUM 0:6d2053b84a92 323 "config": {
MACRUM 0:6d2053b84a92 324 "wifi-ssid": {
MACRUM 0:6d2053b84a92 325 "help": "WiFi SSID",
MACRUM 0:6d2053b84a92 326 "value": "\"SSID\""
MACRUM 0:6d2053b84a92 327 },
MACRUM 0:6d2053b84a92 328 "wifi-password": {
MACRUM 0:6d2053b84a92 329 "help": "WiFi Password",
MACRUM 0:6d2053b84a92 330 "value": "\"PASSWORD\""
MACRUM 0:6d2053b84a92 331 }
MACRUM 0:6d2053b84a92 332 }
MACRUM 0:6d2053b84a92 333 ```
MACRUM 0:6d2053b84a92 334
MACRUM 0:6d2053b84a92 335 #### Changing the target MCU
MACRUM 0:6d2053b84a92 336
MACRUM 0:6d2053b84a92 337 To change the target board to another board that is supported by Mbed OS, simply change the target name.
MACRUM 0:6d2053b84a92 338
MACRUM 0:6d2053b84a92 339 ##### Using the command line
MACRUM 0:6d2053b84a92 340
MACRUM 0:6d2053b84a92 341 Use the -m option. For example:
MACRUM 0:6d2053b84a92 342
MACRUM 0:6d2053b84a92 343 ```
MACRUM 0:6d2053b84a92 344 mbed compile -m Hexiwear -t GCC_ARM
MACRUM 0:6d2053b84a92 345 ```
MACRUM 0:6d2053b84a92 346
MACRUM 0:6d2053b84a92 347 ##### Using the online compiler
MACRUM 0:6d2053b84a92 348
MACRUM 0:6d2053b84a92 349 Click the platform name on the top right corner, then select another platform.
MACRUM 0:6d2053b84a92 350
MACRUM 0:6d2053b84a92 351 ##### Using an IDE
MACRUM 0:6d2053b84a92 352
MACRUM 0:6d2053b84a92 353 First re-export (create project files) for the target with the command line. For example:
MACRUM 0:6d2053b84a92 354
MACRUM 0:6d2053b84a92 355 ```
MACRUM 0:6d2053b84a92 356 mbed export -m Hexiwear -i uvision
MACRUM 0:6d2053b84a92 357 ```
MACRUM 0:6d2053b84a92 358
MACRUM 0:6d2053b84a92 359 #### Creating a custom target board
MACRUM 0:6d2053b84a92 360
MACRUM 0:6d2053b84a92 361 Read the Mbed OS [Contributing](https://os.mbed.com/docs/latest/reference/porting-targets.html) documentation on how to add a new target.
MACRUM 0:6d2053b84a92 362
MACRUM 0:6d2053b84a92 363 #### Update the application logic
MACRUM 0:6d2053b84a92 364
MACRUM 0:6d2053b84a92 365 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.
MACRUM 0:6d2053b84a92 366
MACRUM 0:6d2053b84a92 367 By default, there is a Ticker object, which fires every five seconds and invokes a callback function:
MACRUM 0:6d2053b84a92 368
MACRUM 0:6d2053b84a92 369 ```cpp
MACRUM 0:6d2053b84a92 370 Ticker timer;
MACRUM 0:6d2053b84a92 371 timer.attach(eventQueue.event(&fake_button_press), 5.0);
MACRUM 0:6d2053b84a92 372 ```
MACRUM 0:6d2053b84a92 373
MACRUM 0:6d2053b84a92 374 This callback function changes the `button_res` resource:
MACRUM 0:6d2053b84a92 375
MACRUM 0:6d2053b84a92 376 ```cpp
MACRUM 0:6d2053b84a92 377 void fake_button_press() {
MACRUM 0:6d2053b84a92 378 int v = button_res->get_value_int() + 1;
MACRUM 0:6d2053b84a92 379
MACRUM 0:6d2053b84a92 380 button_res->set_value(v);
MACRUM 0:6d2053b84a92 381
MACRUM 0:6d2053b84a92 382 printf("Simulated button clicked %d times\n", v);
MACRUM 0:6d2053b84a92 383 }
MACRUM 0:6d2053b84a92 384 ```
MACRUM 0:6d2053b84a92 385
MACRUM 0:6d2053b84a92 386 If you want to change this to an actual button, here is how to do it:
MACRUM 0:6d2053b84a92 387
MACRUM 0:6d2053b84a92 388 1. Remove:
MACRUM 0:6d2053b84a92 389
MACRUM 0:6d2053b84a92 390 ```cpp
MACRUM 0:6d2053b84a92 391 Ticker timer;
MACRUM 0:6d2053b84a92 392 timer.attach(eventQueue.event(&fake_button_press), 5.0);
MACRUM 0:6d2053b84a92 393 ```
MACRUM 0:6d2053b84a92 394
MACRUM 0:6d2053b84a92 395 2. Declare an `InterruptIn` object on the button, and attach the callback function to the `fall` handler:
MACRUM 0:6d2053b84a92 396
MACRUM 0:6d2053b84a92 397 ```cpp
MACRUM 0:6d2053b84a92 398 InterruptIn btn(BUTTON1);
MACRUM 0:6d2053b84a92 399 btn.fall(eventQueue.event(&fake_button_press), 5.0);
MACRUM 0:6d2053b84a92 400 ```
MACRUM 0:6d2053b84a92 401
MACRUM 0:6d2053b84a92 402 3. Rename `fake_button_press` to `real_button_press`.
MACRUM 0:6d2053b84a92 403
MACRUM 0:6d2053b84a92 404
MACRUM 0:6d2053b84a92 405 #### Pelion Client v1.3.x SOTP-specific changes
MACRUM 0:6d2053b84a92 406
MACRUM 0:6d2053b84a92 407 The version v1.3+ introduces a new feature called Software One-Time Programming (SOTP) that makes use of the internal flash of the MCU as an One-Time-Programmable section. It stores the keys required to decrypt the credentials stored in the persistent storage. Read more on this in the [porting documentation](https://cloud.mbed.com/docs/current/porting/changing-a-customized-porting-layer.html#rtos-module) under the RTOS module section.
MACRUM 0:6d2053b84a92 408
MACRUM 0:6d2053b84a92 409 The flash must be divided into two sections (default 2, maximum 2) for your target. You need to modify the `mbed_app.json` file as follows:
MACRUM 0:6d2053b84a92 410
MACRUM 0:6d2053b84a92 411 1. Add a section to the `target_overrides` with SOTP addresses and sizes.
MACRUM 0:6d2053b84a92 412
MACRUM 0:6d2053b84a92 413 You can find the memory map information in the reference manual of your MCU. Note the sectors should be placed at the last two sectors of the flash, so the SOTP region is preserved during drag and drop programming of binaries. This is an example for the NUCLEO_F429ZI board:
MACRUM 0:6d2053b84a92 414
MACRUM 0:6d2053b84a92 415 ```json
MACRUM 0:6d2053b84a92 416 "NUCLEO_F429ZI": {
MACRUM 0:6d2053b84a92 417 "app.sotp-section-1-address": "(0x081C0000)",
MACRUM 0:6d2053b84a92 418 "app.sotp-section-1-size" : "(128*1024)",
MACRUM 0:6d2053b84a92 419 "app.sotp-section-2-address": "(0x081E0000)",
MACRUM 0:6d2053b84a92 420 "app.sotp-section-2-size" : "(128*1024)"
MACRUM 0:6d2053b84a92 421 }
MACRUM 0:6d2053b84a92 422 ```
MACRUM 0:6d2053b84a92 423
MACRUM 0:6d2053b84a92 424 2. Add the macro definition to the "config" section. Note that the address and size macros are already provided. You only need to add the macro for the number of sections:
MACRUM 0:6d2053b84a92 425
MACRUM 0:6d2053b84a92 426 ```json
MACRUM 0:6d2053b84a92 427 "sotp-num-sections": {
MACRUM 0:6d2053b84a92 428 "help": "Number of SOTP sections",
MACRUM 0:6d2053b84a92 429 "macro_name": "PAL_INT_FLASH_NUM_SECTIONS",
MACRUM 0:6d2053b84a92 430 "value": null
MACRUM 0:6d2053b84a92 431 }
MACRUM 0:6d2053b84a92 432 ```
MACRUM 0:6d2053b84a92 433
MACRUM 0:6d2053b84a92 434 ## Enabling firmware updates
MACRUM 0:6d2053b84a92 435
MACRUM 0:6d2053b84a92 436 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.
MACRUM 0:6d2053b84a92 437
MACRUM 0:6d2053b84a92 438 For full documentation about bootloaders and firmware update, read the following documents:
MACRUM 0:6d2053b84a92 439
MACRUM 0:6d2053b84a92 440 - [Introduccion to bootloaders](https://os.mbed.com/docs/latest/porting/bootloader.html)
MACRUM 0:6d2053b84a92 441 - [Creating and using a bootloader](https://os.mbed.com/docs/latest/tutorials/bootloader.html)
MACRUM 0:6d2053b84a92 442 - [Bootloader configuration in Mbed OS](https://os.mbed.com/docs/latest/tools/configuring-tools.html)
MACRUM 0:6d2053b84a92 443 - [Mbed Bootloader for Pelion Device Management Client](https://github.com/ARMmbed/mbed-bootloader)
MACRUM 0:6d2053b84a92 444 - [Updating devices with Arm Mbed CLI](https://os.mbed.com/docs/latest/tools/cli-update.html)
MACRUM 0:6d2053b84a92 445
MACRUM 0:6d2053b84a92 446 This is a summary to use Arm Mbed OS managed bootloaders.
MACRUM 0:6d2053b84a92 447
MACRUM 0:6d2053b84a92 448 #### Preparing a bootloader
MACRUM 0:6d2053b84a92 449
MACRUM 0:6d2053b84a92 450 If Mbed OS contains a default pre-built bootloader in `mbed-os/feature/FEATURE_BOOTLOADER`, then you can skip this section.
MACRUM 0:6d2053b84a92 451
MACRUM 0:6d2053b84a92 452 Otherwise, you'll need to compile the [mbed-bootloader](https://github.com/armmbed/mbed-bootloader) and add it to your application. Once it's done, we recommend to send a Pull-Requests to [Mbed OS](https://github.com/ARMmbed/mbed-os) to contribute with a default bootloader for your Mbed Enabled platform.
MACRUM 0:6d2053b84a92 453
MACRUM 0:6d2053b84a92 454 You can see an example of bootloader configuration for the `NUCLEO_F429ZI` in `bootloader/mbed_app.json`. This is compatible with the `mbed_app.json` configuration in this template application.
MACRUM 0:6d2053b84a92 455
MACRUM 0:6d2053b84a92 456 <span class="notes">**Note:** Make sure the configuration for the bootloader (`mbed_app.json`) corresponds with the configuration of your application's `mbed_app.json`, otherwise the bootloader may not be able to find an application or apply the new firmware.</span>
MACRUM 0:6d2053b84a92 457
MACRUM 0:6d2053b84a92 458 #### Enabling the application to use a bootloader
MACRUM 0:6d2053b84a92 459
MACRUM 0:6d2053b84a92 460 ##### Option 1: default & prebuilt bootloader
MACRUM 0:6d2053b84a92 461
MACRUM 0:6d2053b84a92 462 If Mbed OS contains a prebuilt bootloader for the target, then you can indicate to use it in the `mbed_app.json`. For example:
MACRUM 0:6d2053b84a92 463
MACRUM 0:6d2053b84a92 464 ```
MACRUM 0:6d2053b84a92 465 {
MACRUM 0:6d2053b84a92 466 "target_overrides": {
MACRUM 0:6d2053b84a92 467 "K64F": {
MACRUM 0:6d2053b84a92 468 "target.features_add": ["BOOTLOADER"]
MACRUM 0:6d2053b84a92 469 }
MACRUM 0:6d2053b84a92 470 }
MACRUM 0:6d2053b84a92 471 }
MACRUM 0:6d2053b84a92 472 ```
MACRUM 0:6d2053b84a92 473
MACRUM 0:6d2053b84a92 474 ##### Option 2: custom bootloader
MACRUM 0:6d2053b84a92 475
MACRUM 0:6d2053b84a92 476 If you'd like to overide a default bootloader or use a custom one available in the application, then indicate the path to the booloader, `app_offset` and `header_offset` parameters in `mbed_app.json`. For example:
MACRUM 0:6d2053b84a92 477
MACRUM 0:6d2053b84a92 478 ```
MACRUM 0:6d2053b84a92 479 "target_overrides": {
MACRUM 0:6d2053b84a92 480 "K64F": {
MACRUM 0:6d2053b84a92 481 "target.app_offset": "0xa400",
MACRUM 0:6d2053b84a92 482 "target.header_offset": "0xa000",
MACRUM 0:6d2053b84a92 483 "target.bootloader_img": "bootloader/my_bootloader.bin"
MACRUM 0:6d2053b84a92 484 }
MACRUM 0:6d2053b84a92 485 }
MACRUM 0:6d2053b84a92 486 ```
MACRUM 0:6d2053b84a92 487
MACRUM 0:6d2053b84a92 488 You may need to specify `header_format` as well. You could include the default header format from [Mbed OS](https://github.com/ARMmbed/mbed-os/blob/master/features/FEATURE_BOOTLOADER/mbed_lib.json) by adding `"target.features_add": ["BOOTLOADER"]`.
MACRUM 0:6d2053b84a92 489
MACRUM 0:6d2053b84a92 490 #### Verifying that firmware update works
MACRUM 0:6d2053b84a92 491
MACRUM 0:6d2053b84a92 492 Follow these steps to generate a manifest, compile and perform a firmware update of your device:
MACRUM 0:6d2053b84a92 493
MACRUM 0:6d2053b84a92 494 1. Configure the API key for your Pelion account.
MACRUM 0:6d2053b84a92 495
MACRUM 0:6d2053b84a92 496 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:
MACRUM 0:6d2053b84a92 497
MACRUM 0:6d2053b84a92 498 ```
MACRUM 0:6d2053b84a92 499 mbed config -G CLOUD_SDK_API_KEY <your-api-key>
MACRUM 0:6d2053b84a92 500 ```
MACRUM 0:6d2053b84a92 501
MACRUM 0:6d2053b84a92 502 2. Initialize the device management feature:
MACRUM 0:6d2053b84a92 503
MACRUM 0:6d2053b84a92 504 ```
MACRUM 0:6d2053b84a92 505 mbed dm init -d "company.com" --model-name "product-model" -q --force
MACRUM 0:6d2053b84a92 506 ```
MACRUM 0:6d2053b84a92 507
MACRUM 0:6d2053b84a92 508 3. Compile the application, include the firware update credentials generated before, merge with the bootloader and program the device:
MACRUM 0:6d2053b84a92 509
MACRUM 0:6d2053b84a92 510 ```
MACRUM 0:6d2053b84a92 511 mbed compile -t <toolchain> -m <target> -c -f
MACRUM 0:6d2053b84a92 512 ```
MACRUM 0:6d2053b84a92 513
MACRUM 0:6d2053b84a92 514 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.
MACRUM 0:6d2053b84a92 515
MACRUM 0:6d2053b84a92 516 5. Update the firmware of the device through Mbed CLI:
MACRUM 0:6d2053b84a92 517
MACRUM 0:6d2053b84a92 518 ```
MACRUM 0:6d2053b84a92 519 mbed dm update device -D <device ID> -t <toolchain> -m <target>
MACRUM 0:6d2053b84a92 520 ```
MACRUM 0:6d2053b84a92 521
MACRUM 0:6d2053b84a92 522 Inspect the logs on the device to see the update progress. It should look similar to:
MACRUM 0:6d2053b84a92 523
MACRUM 0:6d2053b84a92 524 ```
MACRUM 0:6d2053b84a92 525 Firmware download requested
MACRUM 0:6d2053b84a92 526 Authorization granted
MACRUM 0:6d2053b84a92 527 Downloading: [+++- ] 6 %
MACRUM 0:6d2053b84a92 528 ```
MACRUM 0:6d2053b84a92 529
MACRUM 0:6d2053b84a92 530 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.
MACRUM 0:6d2053b84a92 531
MACRUM 0:6d2053b84a92 532 ## Automated testing
MACRUM 0:6d2053b84a92 533
MACRUM 0:6d2053b84a92 534 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`.
MACRUM 0:6d2053b84a92 535
MACRUM 0:6d2053b84a92 536 For details on Simple Pelion Client testing, refer to the documentation [here](https://github.com/ARMmbed/simple-mbed-cloud-client#testing).
MACRUM 0:6d2053b84a92 537
MACRUM 0:6d2053b84a92 538 This template application contains a working application and tests passing for the `K64F` and `K66F` platforms.
MACRUM 0:6d2053b84a92 539
MACRUM 0:6d2053b84a92 540 ## Known issues
MACRUM 0:6d2053b84a92 541
MACRUM 0:6d2053b84a92 542 Please check the issues reported on github.