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

Pelion workshop with Grove sensors.

README.md@12:3f30c0e55a8e, 2018-05-10 (annotated)

Committer:
maclobdell
Date:
Thu May 10 06:28:36 2018 -0500
Revision:
12:3f30c0e55a8e
Child:
18:49062a0d117e
add license, readme, resources file

Who changed what in which revision?

UserRevisionLine numberNew contents of line
maclobdell 12:3f30c0e55a8e 1 # Simple Mbed Cloud Client template application
maclobdell 12:3f30c0e55a8e 2
maclobdell 12:3f30c0e55a8e 3 ## Overview
maclobdell 12:3f30c0e55a8e 4
maclobdell 12:3f30c0e55a8e 5 This is a template application for platform vendors. It demonstrates how to create a simple Mbed Cloud Client application that can connect to Mbed Cloud, register resources and get ready to receive a firmware update.
maclobdell 12:3f30c0e55a8e 6
maclobdell 12:3f30c0e55a8e 7 It's intended to be customized to add platform-specific features (such as sensors and actuators) and configure the connectivity and storage to work **out-of-the-box**. The Simple Mbed Cloud Client template application works in **developer mode** by default.
maclobdell 12:3f30c0e55a8e 8
maclobdell 12:3f30c0e55a8e 9 ## Setup process
maclobdell 12:3f30c0e55a8e 10
maclobdell 12:3f30c0e55a8e 11 This is a summary of the process for developers to get started and get a device connected to Mbed Cloud.
maclobdell 12:3f30c0e55a8e 12
maclobdell 12:3f30c0e55a8e 13 ### Mbed Online IDE
maclobdell 12:3f30c0e55a8e 14
maclobdell 12:3f30c0e55a8e 15 1. Import the application into the Online IDE.
maclobdell 12:3f30c0e55a8e 16 2. Add the API key to establish connection to Mbed Cloud.
maclobdell 12:3f30c0e55a8e 17 3. Install the developer certificate.
maclobdell 12:3f30c0e55a8e 18 4. Compile and program.
maclobdell 12:3f30c0e55a8e 19
maclobdell 12:3f30c0e55a8e 20 ### Mbed CLI tools
maclobdell 12:3f30c0e55a8e 21
maclobdell 12:3f30c0e55a8e 22 1. Import the application in developer's desktop:
maclobdell 12:3f30c0e55a8e 23
maclobdell 12:3f30c0e55a8e 24 ```
maclobdell 12:3f30c0e55a8e 25 mbed import https://os.mbed.com/teams/mbed-os-examples/code/mbed-cloud-example
maclobdell 12:3f30c0e55a8e 26 cd mbed-cloud-example
maclobdell 12:3f30c0e55a8e 27 ```
maclobdell 12:3f30c0e55a8e 28
maclobdell 12:3f30c0e55a8e 29 2. Download the developer certificate from Mbed Cloud.
maclobdell 12:3f30c0e55a8e 30 3. Compile and program:
maclobdell 12:3f30c0e55a8e 31
maclobdell 12:3f30c0e55a8e 32 ```
maclobdell 12:3f30c0e55a8e 33 mbed compile -t <toolchain> -m <target> -f
maclobdell 12:3f30c0e55a8e 34 ```
maclobdell 12:3f30c0e55a8e 35
maclobdell 12:3f30c0e55a8e 36 ## Porting to a new platform
maclobdell 12:3f30c0e55a8e 37
maclobdell 12:3f30c0e55a8e 38 ### Requirements
maclobdell 12:3f30c0e55a8e 39
maclobdell 12:3f30c0e55a8e 40 The hardware requirements for Mbed OS platforms to support Mbed Cloud Client are [here](https://cloud.mbed.com/docs/current/cloud-requirements/index.html).
maclobdell 12:3f30c0e55a8e 41
maclobdell 12:3f30c0e55a8e 42 In general, to start creating a secure connected product, you need a microcontroller that has the following features.
maclobdell 12:3f30c0e55a8e 43 * RAM: 96K or more
maclobdell 12:3f30c0e55a8e 44 * Flash: 512K or more
maclobdell 12:3f30c0e55a8e 45 * True Random Number Generator (TRNG)
maclobdell 12:3f30c0e55a8e 46 * Real Time Clock (RTC)
maclobdell 12:3f30c0e55a8e 47
maclobdell 12:3f30c0e55a8e 48 Additionally, to use Mbed Cloud Client, the microcontroller needs to support the following in Mbed OS (latest version preferred) or in a compatible driver library:
maclobdell 12:3f30c0e55a8e 49 * A storage device (SDcard, SPI Flash, Data Flash)
maclobdell 12:3f30c0e55a8e 50 * IP connectivity (Ethernet, WiFi, Cellular, 6LoWPAN, Thread)
maclobdell 12:3f30c0e55a8e 51
maclobdell 12:3f30c0e55a8e 52 For the Firmware update over the air (FOTA), you need the following:
maclobdell 12:3f30c0e55a8e 53 * [FlashIAP](https://github.com/ARMmbed/mbed-os/blob/master/drivers/FlashIAP.h) - Flash In-Application Programming (IAP)
maclobdell 12:3f30c0e55a8e 54 * [Mbed Bootloader](https://github.com/ARMmbed/mbed-bootloader) or a bootloader compatible with Mbed Cloud Client.
maclobdell 12:3f30c0e55a8e 55
maclobdell 12:3f30c0e55a8e 56 ### References
maclobdell 12:3f30c0e55a8e 57
maclobdell 12:3f30c0e55a8e 58 * Check which Mbed OS platforms are supported in the [Mbed Cloud quick-start guide](https://cloud.test.mbed.com/quick-start).
maclobdell 12:3f30c0e55a8e 59 * Check which storage options are available [here](https://os.mbed.com/docs/v5.8/reference/storage.html).
maclobdell 12:3f30c0e55a8e 60 * Check which network options are available [here](https://os.mbed.com/docs/v5.8/reference/network-socket.html).
maclobdell 12:3f30c0e55a8e 61
maclobdell 12:3f30c0e55a8e 62
maclobdell 12:3f30c0e55a8e 63 ### Porting steps
maclobdell 12:3f30c0e55a8e 64
maclobdell 12:3f30c0e55a8e 65 Supporting a new derivative platform requires the following steps:
maclobdell 12:3f30c0e55a8e 66
maclobdell 12:3f30c0e55a8e 67 * Fork the template and create an example application for your platform in https://os.mbed.com.
maclobdell 12:3f30c0e55a8e 68 * (Optional) Change the connectivity interface. Ethernet is the default - see `main.cpp`.
maclobdell 12:3f30c0e55a8e 69 * (Optional) Change the filesystem and/or the block device for storage. FAT filesystem over SD card is the default. See `main.cpp`.
maclobdell 12:3f30c0e55a8e 70 * (Optional) Make minor changes in `mbed_app.json` to support multiple platforms with same connectivity and storage.
maclobdell 12:3f30c0e55a8e 71
maclobdell 12:3f30c0e55a8e 72 <span class="notes">**Note:** Make sure that the application works out-of-the-box and no changes are required in the `main.cpp` file. The goal is to deliver a great UX to our developers.</span>
maclobdell 12:3f30c0e55a8e 73
maclobdell 12:3f30c0e55a8e 74 ### Porting example
maclobdell 12:3f30c0e55a8e 75
maclobdell 12:3f30c0e55a8e 76 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 77
maclobdell 12:3f30c0e55a8e 78 #### Changing the storage option
maclobdell 12:3f30c0e55a8e 79
maclobdell 12:3f30c0e55a8e 80 ##### For an SD card
maclobdell 12:3f30c0e55a8e 81
maclobdell 12:3f30c0e55a8e 82 1. Add the SD card driver (`sd-driver.lib`) if it is not already added.
maclobdell 12:3f30c0e55a8e 83
maclobdell 12:3f30c0e55a8e 84 On the command line:
maclobdell 12:3f30c0e55a8e 85
maclobdell 12:3f30c0e55a8e 86 ```
maclobdell 12:3f30c0e55a8e 87 mbed add https://github.com/armmbed/sd-driver
maclobdell 12:3f30c0e55a8e 88 ```
maclobdell 12:3f30c0e55a8e 89
maclobdell 12:3f30c0e55a8e 90 2. In the online compiler, click **Import**, then click here to import from URL.
maclobdell 12:3f30c0e55a8e 91 3. Then enter https://github.com/armmbed/sd-driver for the **Source URL** and **Import As:** Library.
maclobdell 12:3f30c0e55a8e 92 4. Include the header files for the SD driver and FAT file system:
maclobdell 12:3f30c0e55a8e 93
maclobdell 12:3f30c0e55a8e 94 ```cpp
maclobdell 12:3f30c0e55a8e 95 #include "SDBlockDevice.h"
maclobdell 12:3f30c0e55a8e 96 #include "FATFileSystem.h"
maclobdell 12:3f30c0e55a8e 97 ```
maclobdell 12:3f30c0e55a8e 98
maclobdell 12:3f30c0e55a8e 99 5. Declare the global objects for the SD card and file system.
maclobdell 12:3f30c0e55a8e 100
maclobdell 12:3f30c0e55a8e 101 ```cpp
maclobdell 12:3f30c0e55a8e 102 SDBlockDevice bd(SPI_MOSI, SPI_MISO, SPI_CLK, SPI_CS);
maclobdell 12:3f30c0e55a8e 103 FATFileSystem fs("sd", &sd);
maclobdell 12:3f30c0e55a8e 104 ```
maclobdell 12:3f30c0e55a8e 105
maclobdell 12:3f30c0e55a8e 106 <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 107
maclobdell 12:3f30c0e55a8e 108 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 109
maclobdell 12:3f30c0e55a8e 110 ```cpp
maclobdell 12:3f30c0e55a8e 111 SDBlockDevice sd(D11, D12, D13, D10);
maclobdell 12:3f30c0e55a8e 112 ```
maclobdell 12:3f30c0e55a8e 113
maclobdell 12:3f30c0e55a8e 114 ##### For SPI Flash (devices that support SFDP)
maclobdell 12:3f30c0e55a8e 115
maclobdell 12:3f30c0e55a8e 116 <Please note that this section of the document is under construction. More information is needed.>
maclobdell 12:3f30c0e55a8e 117
maclobdell 12:3f30c0e55a8e 118 1. Add the SPI Flash driver (`spif-driver`) if it is not already added.
maclobdell 12:3f30c0e55a8e 119
maclobdell 12:3f30c0e55a8e 120 ```
maclobdell 12:3f30c0e55a8e 121 mbed add https://github.com/ARMmbed/spif-driver
maclobdell 12:3f30c0e55a8e 122 ```
maclobdell 12:3f30c0e55a8e 123
maclobdell 12:3f30c0e55a8e 124 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 125
maclobdell 12:3f30c0e55a8e 126 ```cpp
maclobdell 12:3f30c0e55a8e 127 #include "SPIFBlockDevice.h"
maclobdell 12:3f30c0e55a8e 128 #include "LittleFileSystem.h"
maclobdell 12:3f30c0e55a8e 129 ```
maclobdell 12:3f30c0e55a8e 130
maclobdell 12:3f30c0e55a8e 131 3. Declare the global objects for the SD card and file system:
maclobdell 12:3f30c0e55a8e 132
maclobdell 12:3f30c0e55a8e 133 ```cpp
maclobdell 12:3f30c0e55a8e 134 SPIFBlockDevice spif(SPI_MOSI, SPI_MISO, SPI_CLK, SPI_CS);
maclobdell 12:3f30c0e55a8e 135 LittleFileSystem fs("fs", &spif);
maclobdell 12:3f30c0e55a8e 136 ```
maclobdell 12:3f30c0e55a8e 137
maclobdell 12:3f30c0e55a8e 138 4. Update the construction of the `SimpleMbedCloudClient` object to pass in the file system and block device:
maclobdell 12:3f30c0e55a8e 139
maclobdell 12:3f30c0e55a8e 140 ```cpp
maclobdell 12:3f30c0e55a8e 141 SimpleMbedCloudClient client(&net, &spif, &fs);
maclobdell 12:3f30c0e55a8e 142 ```
maclobdell 12:3f30c0e55a8e 143
maclobdell 12:3f30c0e55a8e 144 #### Changing the network interface
maclobdell 12:3f30c0e55a8e 145
maclobdell 12:3f30c0e55a8e 146 ##### For Ethernet
maclobdell 12:3f30c0e55a8e 147
maclobdell 12:3f30c0e55a8e 148 The Ethernet interface is included within Mbed OS, so you do not need to add a library.
maclobdell 12:3f30c0e55a8e 149
maclobdell 12:3f30c0e55a8e 150 1. Include the header file for the interface.
maclobdell 12:3f30c0e55a8e 151
maclobdell 12:3f30c0e55a8e 152 ```
maclobdell 12:3f30c0e55a8e 153 #include "EthernetInterface.h"
maclobdell 12:3f30c0e55a8e 154 ```
maclobdell 12:3f30c0e55a8e 155
maclobdell 12:3f30c0e55a8e 156 2. Declare the network interface object.
maclobdell 12:3f30c0e55a8e 157
maclobdell 12:3f30c0e55a8e 158 ```
maclobdell 12:3f30c0e55a8e 159 EthernetInterface net;
maclobdell 12:3f30c0e55a8e 160 ```
maclobdell 12:3f30c0e55a8e 161
maclobdell 12:3f30c0e55a8e 162 3. Connect the interface.
maclobdell 12:3f30c0e55a8e 163
maclobdell 12:3f30c0e55a8e 164 ```
maclobdell 12:3f30c0e55a8e 165 status = net.connect();
maclobdell 12:3f30c0e55a8e 166 ```
maclobdell 12:3f30c0e55a8e 167
maclobdell 12:3f30c0e55a8e 168 4. When the Mbed Cloud Client is started, pass the network interface.
maclobdell 12:3f30c0e55a8e 169
maclobdell 12:3f30c0e55a8e 170 ```
maclobdell 12:3f30c0e55a8e 171 SimpleMbedCloudClient client(&net, &sd, &fs);
maclobdell 12:3f30c0e55a8e 172 ```
maclobdell 12:3f30c0e55a8e 173
maclobdell 12:3f30c0e55a8e 174 ##### For WiFi
maclobdell 12:3f30c0e55a8e 175
maclobdell 12:3f30c0e55a8e 176 This example references the ESP8266 WiFi module, but the instructions are applicable to other modules.
maclobdell 12:3f30c0e55a8e 177
maclobdell 12:3f30c0e55a8e 178 1. Add the ESP8266 WiFi interface driver (esp8266-driver) if it is not already added.
maclobdell 12:3f30c0e55a8e 179
maclobdell 12:3f30c0e55a8e 180 ```
maclobdell 12:3f30c0e55a8e 181 Mbed add https://github.com/ARMmbed/esp8266-driver
maclobdell 12:3f30c0e55a8e 182 ```
maclobdell 12:3f30c0e55a8e 183
maclobdell 12:3f30c0e55a8e 184 <span class="notes">**Note:** You may have to update the firmware inside the ESP8266 module.</span>
maclobdell 12:3f30c0e55a8e 185
maclobdell 12:3f30c0e55a8e 186 2. Include the header file for the interface.
maclobdell 12:3f30c0e55a8e 187
maclobdell 12:3f30c0e55a8e 188 ```cpp
maclobdell 12:3f30c0e55a8e 189 #include "ESP8266Interface.h"
maclobdell 12:3f30c0e55a8e 190 ```
maclobdell 12:3f30c0e55a8e 191
maclobdell 12:3f30c0e55a8e 192 3. Add the driver configuration information in `mbed_app.json` (located at the top level of the Mbed Cloud Connect example project).
maclobdell 12:3f30c0e55a8e 193
maclobdell 12:3f30c0e55a8e 194 ```json
maclobdell 12:3f30c0e55a8e 195 "config": {
maclobdell 12:3f30c0e55a8e 196 "wifi-ssid": {
maclobdell 12:3f30c0e55a8e 197 "help": "WiFi SSID",
maclobdell 12:3f30c0e55a8e 198 "value": "\"SSID\""
maclobdell 12:3f30c0e55a8e 199 },
maclobdell 12:3f30c0e55a8e 200 "wifi-password": {
maclobdell 12:3f30c0e55a8e 201 "help": "WiFi Password",
maclobdell 12:3f30c0e55a8e 202 "value": "\"PASSWORD\""
maclobdell 12:3f30c0e55a8e 203 }
maclobdell 12:3f30c0e55a8e 204 }
maclobdell 12:3f30c0e55a8e 205 ```
maclobdell 12:3f30c0e55a8e 206
maclobdell 12:3f30c0e55a8e 207 4. Declare the network interface object.
maclobdell 12:3f30c0e55a8e 208
maclobdell 12:3f30c0e55a8e 209 ```cpp
maclobdell 12:3f30c0e55a8e 210 ESP8266Interface net(D1, D0);
maclobdell 12:3f30c0e55a8e 211 ```
maclobdell 12:3f30c0e55a8e 212
maclobdell 12:3f30c0e55a8e 213 5. Connect the interface.
maclobdell 12:3f30c0e55a8e 214
maclobdell 12:3f30c0e55a8e 215 ```cpp
maclobdell 12:3f30c0e55a8e 216 nsapi_error_t status = net.connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
maclobdell 12:3f30c0e55a8e 217 ```
maclobdell 12:3f30c0e55a8e 218
maclobdell 12:3f30c0e55a8e 219 6. When the Mbed Cloud Client is started, pass the network interface.
maclobdell 12:3f30c0e55a8e 220
maclobdell 12:3f30c0e55a8e 221 ```cpp
maclobdell 12:3f30c0e55a8e 222 SimpleMbedCloudClient client(&net, &sd, &fs);
maclobdell 12:3f30c0e55a8e 223 ```
maclobdell 12:3f30c0e55a8e 224
maclobdell 12:3f30c0e55a8e 225 #### Changing the target MCU
maclobdell 12:3f30c0e55a8e 226
maclobdell 12:3f30c0e55a8e 227 To change the target board to another board that is supported by Mbed OS, simply change the target name.
maclobdell 12:3f30c0e55a8e 228
maclobdell 12:3f30c0e55a8e 229 ##### Using the command line
maclobdell 12:3f30c0e55a8e 230
maclobdell 12:3f30c0e55a8e 231 Use the -m option.
maclobdell 12:3f30c0e55a8e 232
maclobdell 12:3f30c0e55a8e 233 ```
maclobdell 12:3f30c0e55a8e 234 mbed compile -m Hexiwear -t GCC_ARM
maclobdell 12:3f30c0e55a8e 235 ```
maclobdell 12:3f30c0e55a8e 236
maclobdell 12:3f30c0e55a8e 237 ##### Using the online compiler
maclobdell 12:3f30c0e55a8e 238
maclobdell 12:3f30c0e55a8e 239 Click the platform name on the top right corner, then select another platform.
maclobdell 12:3f30c0e55a8e 240
maclobdell 12:3f30c0e55a8e 241 ##### Using an IDE
maclobdell 12:3f30c0e55a8e 242
maclobdell 12:3f30c0e55a8e 243 First re-export (create project files) for the target with the command line.
maclobdell 12:3f30c0e55a8e 244
maclobdell 12:3f30c0e55a8e 245 ```
maclobdell 12:3f30c0e55a8e 246 mbed export -m Hexiwear -i uvision
maclobdell 12:3f30c0e55a8e 247 ```
maclobdell 12:3f30c0e55a8e 248
maclobdell 12:3f30c0e55a8e 249 #### Creating a custom target board
maclobdell 12:3f30c0e55a8e 250
maclobdell 12:3f30c0e55a8e 251 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 252
maclobdell 12:3f30c0e55a8e 253 #### Update the application logic
maclobdell 12:3f30c0e55a8e 254
maclobdell 12:3f30c0e55a8e 255 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 256
maclobdell 12:3f30c0e55a8e 257 By default, there is a Ticker object, which fires every five seconds and invokes a callback function.
maclobdell 12:3f30c0e55a8e 258
maclobdell 12:3f30c0e55a8e 259 ```cpp
maclobdell 12:3f30c0e55a8e 260 Ticker timer;
maclobdell 12:3f30c0e55a8e 261 timer.attach(eventQueue.event(&fake_button_press), 5.0);
maclobdell 12:3f30c0e55a8e 262 ```
maclobdell 12:3f30c0e55a8e 263
maclobdell 12:3f30c0e55a8e 264 This callback function changes the `button_res` resource:
maclobdell 12:3f30c0e55a8e 265
maclobdell 12:3f30c0e55a8e 266 ```cpp
maclobdell 12:3f30c0e55a8e 267 void fake_button_press() {
maclobdell 12:3f30c0e55a8e 268 int v = button_res->get_value_int() + 1;
maclobdell 12:3f30c0e55a8e 269
maclobdell 12:3f30c0e55a8e 270 button_res->set_value(v);
maclobdell 12:3f30c0e55a8e 271
maclobdell 12:3f30c0e55a8e 272 printf("Simulated button clicked %d times\n", v);
maclobdell 12:3f30c0e55a8e 273 }
maclobdell 12:3f30c0e55a8e 274 ```
maclobdell 12:3f30c0e55a8e 275
maclobdell 12:3f30c0e55a8e 276 If you want to change this to an actual button, here is how to do it:
maclobdell 12:3f30c0e55a8e 277
maclobdell 12:3f30c0e55a8e 278 1. Remove:
maclobdell 12:3f30c0e55a8e 279
maclobdell 12:3f30c0e55a8e 280 ```cpp
maclobdell 12:3f30c0e55a8e 281 Ticker timer;
maclobdell 12:3f30c0e55a8e 282 timer.attach(eventQueue.event(&fake_button_press), 5.0);
maclobdell 12:3f30c0e55a8e 283 ```
maclobdell 12:3f30c0e55a8e 284
maclobdell 12:3f30c0e55a8e 285 1. Declare an `InterruptIn` object on the button, and attach the callback function to the `fall` handler:
maclobdell 12:3f30c0e55a8e 286
maclobdell 12:3f30c0e55a8e 287 ```cpp
maclobdell 12:3f30c0e55a8e 288 InterruptIn btn(BUTTON1);
maclobdell 12:3f30c0e55a8e 289 btn.fall(eventQueue.event(&fake_button_press), 5.0);
maclobdell 12:3f30c0e55a8e 290 ```
maclobdell 12:3f30c0e55a8e 291
maclobdell 12:3f30c0e55a8e 292 1. Rename `fake_button_press` to `real_button_press`.
maclobdell 12:3f30c0e55a8e 293
maclobdell 12:3f30c0e55a8e 294
maclobdell 12:3f30c0e55a8e 295 #### Updating the LwM2M objects
maclobdell 12:3f30c0e55a8e 296
maclobdell 12:3f30c0e55a8e 297 See guide at [TODO]
maclobdell 12:3f30c0e55a8e 298
maclobdell 12:3f30c0e55a8e 299 ## Enabling firmware updates
maclobdell 12:3f30c0e55a8e 300
maclobdell 12:3f30c0e55a8e 301 To enable firmware updates, a compatible bootloader needs to be added in the `tools/` folder. The process to merge the application with the bootloader currently only works when building with Mbed CLI. In the future, this combine process will be done automatically by Mbed tools.
maclobdell 12:3f30c0e55a8e 302
maclobdell 12:3f30c0e55a8e 303 1. Compile [mbed-bootloader](https://github.com/armmbed/mbed-bootloader) for the platform and storage configuration used in this application. Place the binary in the tools folder.
maclobdell 12:3f30c0e55a8e 304
maclobdell 12:3f30c0e55a8e 305 1. Add a section to `mbed_app.json` under `target_overrides` with the bootloader configuration. For example:
maclobdell 12:3f30c0e55a8e 306
maclobdell 12:3f30c0e55a8e 307 ```json
maclobdell 12:3f30c0e55a8e 308 "K64F": {
maclobdell 12:3f30c0e55a8e 309 "target.mbed_app_start" : "0x0000a400",
maclobdell 12:3f30c0e55a8e 310 "update-client.bootloader-details" : "0x00007188",
maclobdell 12:3f30c0e55a8e 311 "sotp-section-1-address" : "(32*1024)",
maclobdell 12:3f30c0e55a8e 312 "sotp-section-1-size" : "( 4*1024)",
maclobdell 12:3f30c0e55a8e 313 "sotp-section-2-address" : "(36*1024)",
maclobdell 12:3f30c0e55a8e 314 "sotp-section-2-size" : "( 4*1024)",
maclobdell 12:3f30c0e55a8e 315 "update-client.application-details": "(40*1024)"
maclobdell 12:3f30c0e55a8e 316 }
maclobdell 12:3f30c0e55a8e 317 ```
maclobdell 12:3f30c0e55a8e 318
maclobdell 12:3f30c0e55a8e 319 Next, instruct your users to do the following:
maclobdell 12:3f30c0e55a8e 320
maclobdell 12:3f30c0e55a8e 321 1. Install the [manifest tool](https://github.com/armmbed/manifest-tool).
maclobdell 12:3f30c0e55a8e 322 1. Generate an update certificate:
maclobdell 12:3f30c0e55a8e 323
maclobdell 12:3f30c0e55a8e 324 ```
maclobdell 12:3f30c0e55a8e 325 $ manifest-tool init -a YOUR_MBED_CLOUD_API_KEY -d yourdomain.com -m device-model-id -q --force
maclobdell 12:3f30c0e55a8e 326 ```
maclobdell 12:3f30c0e55a8e 327
maclobdell 12:3f30c0e55a8e 328 <span class="notes">**Note:** Make sure to replace `YOUR_MBED_CLOUD_API_KEY` with an Mbed Cloud API key.
maclobdell 12:3f30c0e55a8e 329
maclobdell 12:3f30c0e55a8e 330 1. Build the application and combine it with the bootloader:
maclobdell 12:3f30c0e55a8e 331
maclobdell 12:3f30c0e55a8e 332 ```
maclobdell 12:3f30c0e55a8e 333 $ mbed compile -m YOUR_TARGET -t GCC_ARM
maclobdell 12:3f30c0e55a8e 334 $ tools/combine_bootloader_with_app.py -m YOUR_TARGET -a BUILD/YOUR_TARGET/GCC_ARM/simple-mbed-cloud-client-example_application.bin -o combined.bin
maclobdell 12:3f30c0e55a8e 335 ```
maclobdell 12:3f30c0e55a8e 336
maclobdell 12:3f30c0e55a8e 337 1. Flash `combined.bin` to the development board.
maclobdell 12:3f30c0e55a8e 338 1. Write down the endpoint ID of the board. You need it to start the update.
maclobdell 12:3f30c0e55a8e 339
maclobdell 12:3f30c0e55a8e 340 Now, a firmware update can be scheduled as explained in the [Mbed Cloud documentation](https://cloud.mbed.com/docs/current/updating-firmware/index.html). You can do it with the manifest tool itself or via the Mbed Cloud portal. Here we explain how to do it with the manifest tool.
maclobdell 12:3f30c0e55a8e 341
maclobdell 12:3f30c0e55a8e 342 1. Change the application, for example by changing some strings in `main.cpp`.
maclobdell 12:3f30c0e55a8e 343 1. Compile the application:
maclobdell 12:3f30c0e55a8e 344
maclobdell 12:3f30c0e55a8e 345 ```
maclobdell 12:3f30c0e55a8e 346 $ mbed compile -m YOUR_TARGET -t GCC_ARM
maclobdell 12:3f30c0e55a8e 347 ```
maclobdell 12:3f30c0e55a8e 348
maclobdell 12:3f30c0e55a8e 349 1. The manifest tool can both sign the update - using the private key generated earlier - and upload it to Mbed Cloud in a single command. Run:
maclobdell 12:3f30c0e55a8e 350
maclobdell 12:3f30c0e55a8e 351 ```
maclobdell 12:3f30c0e55a8e 352 $ manifest-tool update device -p BUILD/YOUR_BOARD_NAME/GCC_ARM/simple-mbed-cloud-client-example_application.bin -D YOUR_ENDPOINT_NAME
maclobdell 12:3f30c0e55a8e 353 ```
maclobdell 12:3f30c0e55a8e 354
maclobdell 12:3f30c0e55a8e 355 Replace `YOUR_BOARD_NAME` with the name of your development board, and replace `YOUR_ENDPOINT_NAME` with the endpoint name in Mbed Cloud.
maclobdell 12:3f30c0e55a8e 356
maclobdell 12:3f30c0e55a8e 357 1. Inspect the logs on the device to see the update progress. It looks similar to:
maclobdell 12:3f30c0e55a8e 358
maclobdell 12:3f30c0e55a8e 359 ```
maclobdell 12:3f30c0e55a8e 360 Firmware download requested
maclobdell 12:3f30c0e55a8e 361 Authorization granted
maclobdell 12:3f30c0e55a8e 362 Downloading: [+++- ] 6 %
maclobdell 12:3f30c0e55a8e 363 ```
maclobdell 12:3f30c0e55a8e 364
maclobdell 12:3f30c0e55a8e 365 1. When the download completes, the firmware is verified. If everything is OK, the firmware update is applied.
maclobdell 12:3f30c0e55a8e 366
maclobdell 12:3f30c0e55a8e 367 ## Known issues
maclobdell 12:3f30c0e55a8e 368
maclobdell 12:3f30c0e55a8e 369 Please check the issues reported on github.