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