Osamu Koizumi / Mbed OS Pelion-workshop-Grove-sensors

Pelion workshop with Grove sensors.

README.md@18:49062a0d117e, 2018-10-05 (annotated)

Committer:
maclobdell
Date:
Fri Oct 05 13:11:30 2018 -0500
Revision:
18:49062a0d117e
Parent:
12:3f30c0e55a8e 
Update to template version 1.4.1

Who changed what in which revision?

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