Pfp Cybersecurity (Aka Power Fingerprinting, Inc.) / Mbed OS pfp-emon-nxp

This program collects raw time series data from the ADC using the NXP board that will later be post processed by PFP Cyber-security cloud base machine learning engine to determine the state of the device.

Dependencies:   FXAS21002 FXOS8700Q

simple-mbed-cloud-client/README.md@0:977e87915078, 2019-08-28 (annotated)

Committer:
vithyat
Date:
Wed Aug 28 19:24:56 2019 +0000
Revision:
0:977e87915078
init

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vithyat 0:977e87915078 1 # Device Management for Mbed OS
vithyat 0:977e87915078 2
vithyat 0:977e87915078 3 (This was previously called Simple Mbed Cloud Client.)
vithyat 0:977e87915078 4
vithyat 0:977e87915078 5 This provides a way to add device management capabilities to Mbed OS devices using the Arm Pelion Device Management IoT platform.
vithyat 0:977e87915078 6
vithyat 0:977e87915078 7 It:
vithyat 0:977e87915078 8
vithyat 0:977e87915078 9 - Enables applications to connect and perform firmware updates in a few lines of code.
vithyat 0:977e87915078 10 - Runs separately from your main application; it does not take over your main loop.
vithyat 0:977e87915078 11 - Provides LWM2M resources, variables that sync automatically through Pelion Device Management.
vithyat 0:977e87915078 12 - Helps users avoid doing blocking network operations in interrupt contexts, by automatically defering actions to a separate thread.
vithyat 0:977e87915078 13 - Provides end-to-end Greentea tests for Pelion Device Management.
vithyat 0:977e87915078 14
vithyat 0:977e87915078 15 This library makes it trivial to expose sensors, actuators and other variables to a cloud service. For a complete Pelion Device Management Client API, please see our [documentation](https://cloud.mbed.com/docs/current/mbed-cloud-client/index.html).
vithyat 0:977e87915078 16
vithyat 0:977e87915078 17 ## Device management for your Mbed OS application
vithyat 0:977e87915078 18
vithyat 0:977e87915078 19 Not every device (microcontroller, module or board) is capable of running device management features. Although you can add or extend some hardware capabilities, such as connectivity, storage and TRNG, others are impossible or inconvenient to extend (for example, RAM or flash).
vithyat 0:977e87915078 20
vithyat 0:977e87915078 21 The minimum requirements to add device management feature to your application are:
vithyat 0:977e87915078 22
vithyat 0:977e87915078 23 - RAM: 128K or more.
vithyat 0:977e87915078 24 - Flash: 512K or more.
vithyat 0:977e87915078 25 - Real Time Clock (RTC).
vithyat 0:977e87915078 26 - (Optional but recommended) True Random Number Generator (TRNG).
vithyat 0:977e87915078 27 - A storage device: SD card, SPI flash, QSPI flash or data flash.
vithyat 0:977e87915078 28 - IP connectivity: Ethernet, Wi-Fi, cellular, 6LoWPAN or Thread.
vithyat 0:977e87915078 29
vithyat 0:977e87915078 30 Additionally, we recommend the latest version of Mbed OS support the device and any additional complementary hardware components, or that they have support for the APIs provided in the latest releases of Mbed OS.
vithyat 0:977e87915078 31
vithyat 0:977e87915078 32 Useful references:
vithyat 0:977e87915078 33
vithyat 0:977e87915078 34 - Check which Mbed OS platforms are supported in the [Pelion Device Management quick start guide](https://cloud.mbed.com/quick-start).
vithyat 0:977e87915078 35 - Check the [storage options available](https://os.mbed.com/docs/latest/reference/storage.html).
vithyat 0:977e87915078 36 - Check the [network options available](https://os.mbed.com/docs/latest/reference/network-socket.html).
vithyat 0:977e87915078 37
vithyat 0:977e87915078 38 ### Adding a device management feature to your application
vithyat 0:977e87915078 39
vithyat 0:977e87915078 40 1. Add this library to your Mbed OS project:
vithyat 0:977e87915078 41
vithyat 0:977e87915078 42 ```
vithyat 0:977e87915078 43 $ mbed add https://github.com/ARMmbed/simple-mbed-cloud-client
vithyat 0:977e87915078 44 ```
vithyat 0:977e87915078 45
vithyat 0:977e87915078 46 If you do not have an Mbed OS project to add, you can create one with `mbed new <your_application_name>` and then the `mbed add` step above.
vithyat 0:977e87915078 47
vithyat 0:977e87915078 48 1. Reference the library from the `main.cpp` file, and add network and storage drivers. Finally, initialize the SimpleMbedCloudClient library. This is the architecture of a device management application with Mbed OS:
vithyat 0:977e87915078 49
vithyat 0:977e87915078 50 ```cpp
vithyat 0:977e87915078 51 #include "simple-mbed-cloud-client.h"
vithyat 0:977e87915078 52 #include <Block device>
vithyat 0:977e87915078 53 #include <Filesystem>
vithyat 0:977e87915078 54 #include <Network>
vithyat 0:977e87915078 55
vithyat 0:977e87915078 56 int main() {
vithyat 0:977e87915078 57
vithyat 0:977e87915078 58 /* Initialize connectivity */
vithyat 0:977e87915078 59 NetworkInterface *net = NetworkInterface::get_default_instance();
vithyat 0:977e87915078 60 net->connect();
vithyat 0:977e87915078 61
vithyat 0:977e87915078 62 /* Initialize storage */
vithyat 0:977e87915078 63 BlockDevice *bd = BlockDevice::get_default_instance();
vithyat 0:977e87915078 64 <Filesystem> fs("fs", &bd);
vithyat 0:977e87915078 65
vithyat 0:977e87915078 66 /* Initialize SimpleMbedCloudClient */
vithyat 0:977e87915078 67 SimpleMbedCloudClient client(net, &bd, &fs);
vithyat 0:977e87915078 68 client.init();
vithyat 0:977e87915078 69
vithyat 0:977e87915078 70 /* Create resource */
vithyat 0:977e87915078 71 MbedCloudClientResource *variable;
vithyat 0:977e87915078 72 variable = client.create_resource("3201/0/5853", "variable");
vithyat 0:977e87915078 73 variable->set_value("assign new value");
vithyat 0:977e87915078 74 variable->methods(M2MMethod::GET | M2MMethod::PUT);
vithyat 0:977e87915078 75
vithyat 0:977e87915078 76 }
vithyat 0:977e87915078 77 ```
vithyat 0:977e87915078 78
vithyat 0:977e87915078 79 1. Configure the API key for your Pelion Portal account.
vithyat 0:977e87915078 80
vithyat 0:977e87915078 81 If you don't have an API key available, then log in to the [Pelion IoT Platform portal](https://portal.mbedcloud.com/), navigate to `Access Management` and `API keys`, and create a new one. Then specify the API key as the global `mbed` configuration:
vithyat 0:977e87915078 82
vithyat 0:977e87915078 83 ```
vithyat 0:977e87915078 84 $ mbed config -G CLOUD_SDK_API_KEY <your-api-key>
vithyat 0:977e87915078 85 ```
vithyat 0:977e87915078 86
vithyat 0:977e87915078 87 1. Install the device management certificate:
vithyat 0:977e87915078 88
vithyat 0:977e87915078 89 ```
vithyat 0:977e87915078 90 $ mbed dm init -d "<your company name.com>" --model-name "<product model identifier>"
vithyat 0:977e87915078 91 ```
vithyat 0:977e87915078 92
vithyat 0:977e87915078 93 This creates your private and public key pair and also initialize various `.c` files with these credentials, so you can use Connect and (firmware) Update device management features.
vithyat 0:977e87915078 94
vithyat 0:977e87915078 95 ### Example applications
vithyat 0:977e87915078 96
vithyat 0:977e87915078 97 To help you start quickly, please refer to the following [application example](https://github.com/ARMmbed/pelion-ready-example). It demonstrates how to connect to the Pelion IoT Platform service, register resources and get ready to receive a firmware update.
vithyat 0:977e87915078 98
vithyat 0:977e87915078 99 Also, there are a number of board-specific applications that focus on providing more elaborate hardware features with Mbed OS and the Pelion IoT Platform. These are available in the Pelion [quick start](https://cloud.mbed.com/quick-start). Please see the reference table below, organized by vendor name, for details:
vithyat 0:977e87915078 100
vithyat 0:977e87915078 101 Platform | Connectivity | Storage | Example URL
vithyat 0:977e87915078 102 --------------------------------| -------------------| --------- | --------------------
vithyat 0:977e87915078 103 Nuvoton NUMAKER-IOT-M487 | Wi-Fi | SD Card | https://os.mbed.com/teams/Nuvoton/code/pelion-example-common/
vithyat 0:977e87915078 104 Nuvoton NUMAKER-PFM-M487 | Ethernet | SD Card | https://os.mbed.com/teams/Nuvoton/code/pelion-example-common/
vithyat 0:977e87915078 105 Nuvoton NUMAKER-PFM-NUC472 | Ethernet | SD Card |https://os.mbed.com/teams/Nuvoton/code/pelion-example-common/
vithyat 0:977e87915078 106 NXP FRDM-K64F | Ethernet | SD Card | https://os.mbed.com/teams/NXP/code/mbed-cloud-connect-example-ethernet
vithyat 0:977e87915078 107 NXP FRDM-K66F | Ethernet | SD Card | https://os.mbed.com/teams/NXP/code/mbed-cloud-connect-example-ethernet
vithyat 0:977e87915078 108 Renesas GR-LCYHEE | Wi-Fi | SD Card | https://os.mbed.com/teams/Renesas/code/pelion-example-common/
vithyat 0:977e87915078 109 Sigma Delta Technologies SDT64B | Ethernet | SD Card | https://os.mbed.com/teams/Sigma-Delta-Technologies/code/pelion-example-common
vithyat 0:977e87915078 110 ST DISCO_L475E_IOT01A | Wi-Fi | QSPI | https://os.mbed.com/teams/ST/code/pelion-example-disco-iot01/
vithyat 0:977e87915078 111 ST DISCO_F413H | Wi-Fi | QSPI | https://os.mbed.com/teams/ST/code/pelion-example-common/
vithyat 0:977e87915078 112 ST DISCO_F746NG | Ethernet | QSPI | https://os.mbed.com/teams/ST/code/pelion-example-common/
vithyat 0:977e87915078 113 ST NUCLEO_F429ZI | Ethernet | SD Card | https://os.mbed.com/teams/ST/code/pelion-example-common/
vithyat 0:977e87915078 114 ST NUCLEO_F767ZI | Ethernet | SD Card | https://os.mbed.com/teams/ST/code/pelion-example-common/
vithyat 0:977e87915078 115 ST NUCLEO_F746ZG | Ethernet | SD Card | https://os.mbed.com/teams/ST/code/pelion-example-common/
vithyat 0:977e87915078 116 ST NUCLEO_F207ZG | Ethernet | SD Card | https://os.mbed.com/teams/ST/code/pelion-example-common/
vithyat 0:977e87915078 117 UBlox EVK ODIN W2 | Wi-Fi | SD Card | https://os.mbed.com/teams/ublox/code/pelion-example-common/
vithyat 0:977e87915078 118 UBlox C030 U201 | Cellular | SD Card | https://os.mbed.com/teams/ublox/code/pelion-example-common/
vithyat 0:977e87915078 119
vithyat 0:977e87915078 120 ## Device management configuration
vithyat 0:977e87915078 121
vithyat 0:977e87915078 122 The device management configuration has five distinct areas:
vithyat 0:977e87915078 123
vithyat 0:977e87915078 124 - Connectivity - the transport type for the device to connect to the device management service.
vithyat 0:977e87915078 125 - Storage - the storage type and writing used for both the credentials and the firmware storage.
vithyat 0:977e87915078 126 - Flash geometry - the device flash "sandbox" for bootloader, application header, application image and two SOTP regions.
vithyat 0:977e87915078 127 - SOTP - the address and size of the SOTP regions in flash used to store the device special key that decrypts the credentials storage.
vithyat 0:977e87915078 128 - Bootloader - the bootloader image, application and header offset.
vithyat 0:977e87915078 129
vithyat 0:977e87915078 130 Except for connectivity, the majority of the configuration is shared between the application and bootloader, which ensures the bootloader can correctly find, verify, authorize and apply an update to the device application.
vithyat 0:977e87915078 131
vithyat 0:977e87915078 132 For full documentation about bootloaders and firmware update, please read the following documents:
vithyat 0:977e87915078 133
vithyat 0:977e87915078 134 - [Introduction to Mbed OS bootloaders](https://os.mbed.com/docs/latest/porting/bootloader.html).
vithyat 0:977e87915078 135 - [Creating and using an Mbed OS bootloader](https://os.mbed.com/docs/latest/tutorials/bootloader.html).
vithyat 0:977e87915078 136 - [Bootloader configuration in Mbed OS](https://os.mbed.com/docs/latest/tools/configuring-tools.html).
vithyat 0:977e87915078 137 - [Mbed Bootloader for Pelion Device Management](https://github.com/ARMmbed/mbed-bootloader).
vithyat 0:977e87915078 138 - [Updating devices with Mbed CLI](https://os.mbed.com/docs/latest/tools/cli-update.html).
vithyat 0:977e87915078 139
vithyat 0:977e87915078 140 To hasten this process, you can copy the configuration from the [application example](https://github.com/ARMmbed/pelion-ready-example/blob/master/mbed_app.json) as the basis for your application configuration.
vithyat 0:977e87915078 141
vithyat 0:977e87915078 142 ### 1. Application configuration
vithyat 0:977e87915078 143
vithyat 0:977e87915078 144 Edit the `mbed_app.json` file, and create a new entry under `target_overrides` with the target name for your device:
vithyat 0:977e87915078 145
vithyat 0:977e87915078 146 - **Connectivity** - Specify the default connectivity type for your target. It's essential with targets that lack default connectivity set in `targets.json` or for targets that support multiple connectivity options. For example:
vithyat 0:977e87915078 147
vithyat 0:977e87915078 148 ```
vithyat 0:977e87915078 149 "target.network-default-interface-type" : "ETHERNET",
vithyat 0:977e87915078 150 ```
vithyat 0:977e87915078 151
vithyat 0:977e87915078 152 The possible options are `ETHERNET`, `WIFI` and `CELLULAR`.
vithyat 0:977e87915078 153
vithyat 0:977e87915078 154 Depending on connectivity type, you might have to specify more config options. For an example, please see the defined `CELLULAR` targets in `mbed_app.json`.
vithyat 0:977e87915078 155
vithyat 0:977e87915078 156 - **Storage** - Specify the storage block device type, which dynamically adds the block device driver you specified at compile time. For example:
vithyat 0:977e87915078 157
vithyat 0:977e87915078 158 ```
vithyat 0:977e87915078 159 "target.components_add" : ["SD"],
vithyat 0:977e87915078 160 ```
vithyat 0:977e87915078 161
vithyat 0:977e87915078 162 Valid options are `SD`, `SPIF`, `QSPIF` and `FLASHIAP` (not recommended). For more available options, please see the [block device components](https://github.com/ARMmbed/mbed-os/tree/master/components/storage/blockdevice).
vithyat 0:977e87915078 163
vithyat 0:977e87915078 164 You also have to specify block device pin configuration, which may vary from one block device type to another. Here's an example for `SD`:
vithyat 0:977e87915078 165
vithyat 0:977e87915078 166 ```
vithyat 0:977e87915078 167 "sd.SPI_MOSI" : "PE_6",
vithyat 0:977e87915078 168 "sd.SPI_MISO" : "PE_5",
vithyat 0:977e87915078 169 "sd.SPI_CLK" : "PE_2",
vithyat 0:977e87915078 170 "sd.SPI_CS" : "PE_4",
vithyat 0:977e87915078 171 ```
vithyat 0:977e87915078 172
vithyat 0:977e87915078 173 If you are using SPI/QSPI flash, please make sure you have specified the correct SPI frequency by configuring `spif-driver.SPI_FREQ`. If it is not configured, 40Mhz will be applied by default.
vithyat 0:977e87915078 174
vithyat 0:977e87915078 175 - **Flash** - Define the basics for the microcontroller flash. For example:
vithyat 0:977e87915078 176
vithyat 0:977e87915078 177 ```
vithyat 0:977e87915078 178 "device-management.flash-start-address" : "0x08000000",
vithyat 0:977e87915078 179 "device-management.flash-size" : "(2048*1024)",
vithyat 0:977e87915078 180 ```
vithyat 0:977e87915078 181
vithyat 0:977e87915078 182 - **SOTP** - Define two SOTP or NVStore regions that Mbed OS Device Management will use to store its special keys, which encrypt the data stored. Use the last two Flash sectors (if possible) to ensure that they don't get overwritten when new firmware is applied. For example:
vithyat 0:977e87915078 183
vithyat 0:977e87915078 184 ```
vithyat 0:977e87915078 185 "device-management.sotp-section-1-address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 2*(128*1024))",
vithyat 0:977e87915078 186 "device-management.sotp-section-1-size" : "(128*1024)",
vithyat 0:977e87915078 187 "device-management.sotp-section-2-address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 1*(128*1024))",
vithyat 0:977e87915078 188 "device-management.sotp-section-2-size" : "(128*1024)",
vithyat 0:977e87915078 189 "device-management.sotp-num-sections" : 2
vithyat 0:977e87915078 190 ```
vithyat 0:977e87915078 191
vithyat 0:977e87915078 192 `*-address` defines the start of the Flash sector, and `*-size` defines the actual sector size. `sotp-num-sections` should always be set to `2`.
vithyat 0:977e87915078 193
vithyat 0:977e87915078 194 At this point, we recommend you run the "connect" test suite, which verifies that the device can successfully bootstrap, register and send and receive data from Pelion Device Management service with the provided configuration.
vithyat 0:977e87915078 195
vithyat 0:977e87915078 196 If you already configured your Pelion API key and initialized your credentials as described in the [previous section](#adding-device-management-feature-to-your-application), you can compile the "Connect" tests using:
vithyat 0:977e87915078 197
vithyat 0:977e87915078 198 ```
vithyat 0:977e87915078 199 $ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple*dev*connect -DMBED_TEST_MODE --compile
vithyat 0:977e87915078 200 ```
vithyat 0:977e87915078 201
vithyat 0:977e87915078 202 To run the tests:
vithyat 0:977e87915078 203
vithyat 0:977e87915078 204 ```
vithyat 0:977e87915078 205 $ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple*dev*connect --run -v
vithyat 0:977e87915078 206 ```
vithyat 0:977e87915078 207
vithyat 0:977e87915078 208 ### 2. Bootloader configuration
vithyat 0:977e87915078 209
vithyat 0:977e87915078 210 After you've successfully passed the "Connect" tests as described above, you can enable firmware update feature by adding a bootloader to your application.
vithyat 0:977e87915078 211
vithyat 0:977e87915078 212 1. Import as a new application the official [mbed-bootloader](https://github.com/ARMmbed/mbed-bootloader/) repository or the [mbed-bootloader-extended](https://github.com/ARMmbed/mbed-bootloader-extended/) repository that builds on top of `mbed-bootloader` and extends the support for file systems and storage drivers. You can do this with `mbed import mbed-bootloader-extended`.
vithyat 0:977e87915078 213
vithyat 0:977e87915078 214 1. Inside the imported bootloader application, and edit the application configuration, for example `mbed-bootloader-extended/mbed_app.json`. Add a new target entry similar to the step above, and specify:
vithyat 0:977e87915078 215
vithyat 0:977e87915078 216 - **Flash** - Define the basics for the microcontroller flash (the same as in `mbed_app.json`). For example:
vithyat 0:977e87915078 217
vithyat 0:977e87915078 218 ```
vithyat 0:977e87915078 219 "flash-start-address" : "0x08000000",
vithyat 0:977e87915078 220 "flash-size" : "(2048*1024)",
vithyat 0:977e87915078 221 ```
vithyat 0:977e87915078 222
vithyat 0:977e87915078 223 - **SOTP** - Similar to the **SOTP** step above, specify the location of the SOTP key storage. In the bootloader, the variables are named differently. Try to use the last two Flash sectors (if possible) to ensure that they don't get overwritten when new firmware is applied. For example:
vithyat 0:977e87915078 224
vithyat 0:977e87915078 225 ```
vithyat 0:977e87915078 226 "nvstore.area_1_address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 2*(128*1024))",
vithyat 0:977e87915078 227 "nvstore.area_1_size" : "(128*1024)",
vithyat 0:977e87915078 228 "nvstore.area_2_address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 1*(128*1024))", "nvstore.area_2_size" : "(128*1024)",
vithyat 0:977e87915078 229 ```
vithyat 0:977e87915078 230
vithyat 0:977e87915078 231 - **Application offset** - Specify start address for the application, and also the update-client meta information. As these are automatically calculated, you can copy the ones below:
vithyat 0:977e87915078 232
vithyat 0:977e87915078 233 ```
vithyat 0:977e87915078 234 "update-client.application-details": "(MBED_CONF_APP_FLASH_START_ADDRESS + 64*1024)",
vithyat 0:977e87915078 235 "application-start-address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + 65*1024)",
vithyat 0:977e87915078 236 "max-application-size" : "DEFAULT_MAX_APPLICATION_SIZE",
vithyat 0:977e87915078 237 ```
vithyat 0:977e87915078 238
vithyat 0:977e87915078 239 - **Storage** - Specify the block device pin configuration, exactly as you defined it in the `mbed_app.json` file. For example:
vithyat 0:977e87915078 240
vithyat 0:977e87915078 241 ```
vithyat 0:977e87915078 242 "target.components_add" : ["SD"],
vithyat 0:977e87915078 243 "sd.SPI_MOSI" : "PE_6",
vithyat 0:977e87915078 244 "sd.SPI_MISO" : "PE_5",
vithyat 0:977e87915078 245 "sd.SPI_CLK" : "PE_2",
vithyat 0:977e87915078 246 "sd.SPI_CS" : "PE_4"
vithyat 0:977e87915078 247 ```
vithyat 0:977e87915078 248
vithyat 0:977e87915078 249 If you are using SPI/QSPI flash, please make sure you have specified the correct SPI frequency by configuring `spif-driver.SPI_FREQ`. If it is not configured, 40Mhz will be applied by default.
vithyat 0:977e87915078 250
vithyat 0:977e87915078 251 1. Compile the bootloader using the `bootloader_app.json` configuration you just edited:
vithyat 0:977e87915078 252
vithyat 0:977e87915078 253 ```
vithyat 0:977e87915078 254 $ mbed compile -t <TOOLCHAIN> -m <TARGET> --profile=tiny.json --app-config=<path to pelion-enablement/bootloader/bootloader_app.json>
vithyat 0:977e87915078 255 ```
vithyat 0:977e87915078 256
vithyat 0:977e87915078 257 <span class="notes">**Note:** `mbed-bootloader` is primarily optimized for `GCC_ARM`, so you may want to compile it with that toolchain.
vithyat 0:977e87915078 258 Before jumping to the next step, you should compile and flash the bootloader and then connect over the virtual comport to ensure the bootloader is running correctly. You can ignore errors related to checksum verification or falure to jump to application - these are expected at this stage.</span>
vithyat 0:977e87915078 259
vithyat 0:977e87915078 260 ### 3. Add the bootloader to your application
vithyat 0:977e87915078 261
vithyat 0:977e87915078 262 1. Copy the compiled bootloader from `mbed-bootloader-extended/BUILDS/<TARGET>/<TOOLCHAIN>-TINY/mbed-bootloader.bin` to `<your_application_name>/bootloader/mbed-bootloader-<TARGET>.bin`.
vithyat 0:977e87915078 263
vithyat 0:977e87915078 264 1. Edit `<your_application_name>/mbed_app.json`, and modify the target entry to include:
vithyat 0:977e87915078 265
vithyat 0:977e87915078 266 ```
vithyat 0:977e87915078 267 "target.features_add" : ["BOOTLOADER"],
vithyat 0:977e87915078 268 "target.bootloader_img" : "bootloader/mbed-bootloader-<TARGET>.bin",
vithyat 0:977e87915078 269 "target.app_offset" : "0x10400",
vithyat 0:977e87915078 270 "target.header_offset" : "0x10000",
vithyat 0:977e87915078 271 "update-client.application-details": "(MBED_CONF_APP_FLASH_START_ADDRESS + 64*1024)",
vithyat 0:977e87915078 272 ```
vithyat 0:977e87915078 273
vithyat 0:977e87915078 274 <span class="notes">**Note:**
vithyat 0:977e87915078 275 - `update-client.application-details` should be identical in both `bootloader_app.json` and `mbed_app.json`.
vithyat 0:977e87915078 276 - `target.app_offset` is relative offset to `flash-start-address` you specified in `mbed_app.json` and `bootloader_app.json`, and is the hex value of the offset specified by `application-start-address` in `bootloader_app.json`. For example, `(MBED_CONF_APP_FLASH_START_ADDRESS+65*1024)` dec equals `0x10400` hex.
vithyat 0:977e87915078 277 - `target.header_offset` is also relative offset to the `flash-start-address` you specified in the `bootloader_app.json`, and is the hex value of the offset specified by `update-client.application-details`. For example, `(MBED_CONF_APP_FLASH_START_ADDRESS+64*1024)` dec equals `0x10000` hex.</span>
vithyat 0:977e87915078 278
vithyat 0:977e87915078 279 1. Finally, compile and rerun all tests, including the firmware update ones with:
vithyat 0:977e87915078 280
vithyat 0:977e87915078 281 ```
vithyat 0:977e87915078 282 $ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple-mbed-cloud-client-tests-* -DMBED_TEST_MODE --compile
vithyat 0:977e87915078 283
vithyat 0:977e87915078 284 $ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple-mbed-cloud-client-tests-* --run -v
vithyat 0:977e87915078 285 ```
vithyat 0:977e87915078 286
vithyat 0:977e87915078 287 Refer to the next section about what tests are being executed.
vithyat 0:977e87915078 288
vithyat 0:977e87915078 289 ## Validation and testing
vithyat 0:977e87915078 290
vithyat 0:977e87915078 291 Mbed Device Management provides built-in tests to help you when define your device management configuration. Before running these tests, we recommend you refer to the [testing setup](#testing-setup) section below.
vithyat 0:977e87915078 292
vithyat 0:977e87915078 293 ### Test suites
vithyat 0:977e87915078 294
vithyat 0:977e87915078 295 | **Test suite** | **Description** |
vithyat 0:977e87915078 296 | ------------- | ------------- |
vithyat 0:977e87915078 297 | `fs-single` | File system single-threaded tests with write buffer sizes - 1 byte, 4b, 16b, 64b, 256b, 1kb, 4kb, 16kb, 64kb. |
vithyat 0:977e87915078 298 | `fs-multi` | File system multithreaded test with write buffer sizes - 1 byte, 4b, 16b, 64b, 256b, 1kb, 4kb, 16kb, 64kb. |
vithyat 0:977e87915078 299 | `net-single` | Network single-threaded test with receive buffer sizes - 128 bytes, 256b, 1kb, 2kb, 4kb. |
vithyat 0:977e87915078 300 | `net-multi` | Network multithreaded test for 1, 2 and 3 download threads with 1kb receive buffer size. |
vithyat 0:977e87915078 301 | `stress-net-fs` | Network and file system single and multithreaded tests:<ul><li>memory allocation - 10k, 20k, 40k, 60k</li><li>1 thread (sequential) - 1 download (1kb buffer), 1 file thread (1kb buffer)</li><li>2 parallel threads - 1 download, 1 file thread (1kb buffer)</li><li>3 parallel threads - 1 download, 2 file (256 bytes, 1 kb buffer)</li><li>4 parallel threads - 1 download, 3 file (1 byte, 256 bytes, 1kb buffer)</li></ul> |
vithyat 0:977e87915078 302
vithyat 0:977e87915078 303 ### Test cases - connect
vithyat 0:977e87915078 304
vithyat 0:977e87915078 305 | **Test case** | **Description** |
vithyat 0:977e87915078 306 | ------------- | ------------- |
vithyat 0:977e87915078 307 | `Connect to <Network type>` | Tests the connection to the network through the network interface. |
vithyat 0:977e87915078 308 | `Initialize <Blockdevice>+<Filesystem>` | Initializes the block device driver and file system on top. Usually, the test will be stuck at this point if there's a problem with the storage device. |
vithyat 0:977e87915078 309 | `Format <Filesystem>` | Tests that you can successfully format the block device for the file system type. |
vithyat 0:977e87915078 310 | `Initialize Simple PDMC ` | Verifies you can initialize Pelion Device Management with the given network, storage and file system configuration. This is where the FCU and KCM configuration is written to storage and the Root of Trust is written to SOTP.
vithyat 0:977e87915078 311 | `Pelion DM Bootstrap & Register` | Bootstraps the device and registers it for first time with Pelion Device Management. |
vithyat 0:977e87915078 312 | `Pelion DM Directory` | Verifies that a registered device appears in the Device Directory in Pelion Device Management. |
vithyat 0:977e87915078 313 | `Pelion DM Re-register` | Resets the device and reregisters with Pelion Device Management with previously bootstrapped credentials. |
vithyat 0:977e87915078 314 | `Post-reset Identity` | Verifies that the device identity is preserved over device reset, confirming that Root of Trust is stored in SOTP correctly. |
vithyat 0:977e87915078 315 | `ResourceLwM2M GET` | Verifies that the device can perform a GET request on an LwM2M resource. |
vithyat 0:977e87915078 316 | `ResourceLwM2M SET Test` | Sets or changes value from the device and verifies the Pelion Device Management API client can observe the value changing. |
vithyat 0:977e87915078 317 | `ResourceLwM2M PUT Test` | Verifies the device can perform a PUT request on an LwM2M resource by setting a new value. |
vithyat 0:977e87915078 318 | `Resource LwM2M POST Test` | Verifies the device can execute a POST on an LwM2M resource and the callback function on the device is called. |
vithyat 0:977e87915078 319
vithyat 0:977e87915078 320 ### Test cases - update
vithyat 0:977e87915078 321
vithyat 0:977e87915078 322 | **Test case** | **Description** |
vithyat 0:977e87915078 323 | ------------- | ------------- |
vithyat 0:977e87915078 324 | `Connect to <Network type>` | Tests the connection to the network using the network interface. |
vithyat 0:977e87915078 325 | `Initialize <Blockdevice>+<Filesystem>` | Initializes block device driver and file system on top. Usually the test will be stuck at this point if there's problem with the storage device. |
vithyat 0:977e87915078 326 | `Format <Filesystem>` | Tests that you can successfully format the block device for the file system type. |
vithyat 0:977e87915078 327 | `Initialize Simple PDMC ` | Verifies you can initialize Pelion Device Management with the given network, storage and file system configuration. This is where the FCU and KCM configuration is written to storage and the Root of Trust is written to SOTP.
vithyat 0:977e87915078 328 | `Pelion DM Bootstrap & Register` | Bootstraps the device and registers it for first time with Pelion Device Management. |
vithyat 0:977e87915078 329 | `Pelion DM Directory` | Verifies a registered device appears in the Device Directory in Pelion Device Management. |
vithyat 0:977e87915078 330 | `Firmware Prepare` | Prepares the firmware on the host side and calls `mbed dm` to initiate the Pelion Device Management update campaign. |
vithyat 0:977e87915078 331 | `Firmware Download` | Downloads the firmware onto the device. |
vithyat 0:977e87915078 332 | `Firmware Update` | Resets the device, verifies that the firmware has correct checksum, applies it and reverifies the applied firmware checksum. |
vithyat 0:977e87915078 333 | `Pelion DM Re-register` | Reregisters the device with Pelion Device Management using the new firmware and previously bootstrapped credentials. |
vithyat 0:977e87915078 334 | `Post-update Identity` | Verifies that the device identity is preserved over firmware update and device reset, confirming that Root of Trust is stored in SOTP correctly. |
vithyat 0:977e87915078 335
vithyat 0:977e87915078 336 ### Requirements
vithyat 0:977e87915078 337
vithyat 0:977e87915078 338 Mbed Device Management tests rely on the Python SDK to test the end-to-end solution. To install the Python SDK:
vithyat 0:977e87915078 339
vithyat 0:977e87915078 340 ```
vithyat 0:977e87915078 341 $ pip install mbed-cloud-sdk
vithyat 0:977e87915078 342 ```
vithyat 0:977e87915078 343
vithyat 0:977e87915078 344 <span class="notes">**Note:** The Python SDK requires Python 2.7.10+ or Python 3.4.3+, built with SSL support.</span>
vithyat 0:977e87915078 345
vithyat 0:977e87915078 346 ### Testing setup
vithyat 0:977e87915078 347
vithyat 0:977e87915078 348 1. Import an example application for Pelion Device Management that contains the corresponding configuration for your target.
vithyat 0:977e87915078 349
vithyat 0:977e87915078 350 Please refer to the following [application example](https://github.com/ARMmbed/pelion-ready-example). It demonstrates how to connect to the Pelion IoT Platform service, register resources and get ready to receive a firmware update.
vithyat 0:977e87915078 351
vithyat 0:977e87915078 352 Also, there are board-specific applications that focus on providing more elaborate hardware features with Mbed OS and the Pelion IoT Platform. These are available in the Pelion [quick start](https://cloud.mbed.com/quick-start).
vithyat 0:977e87915078 353
vithyat 0:977e87915078 354 1. Set a global `mbed config` variable `CLOUD_SDK_API_KEY` on the host machine valid for the account your device will connect to. For example:
vithyat 0:977e87915078 355
vithyat 0:977e87915078 356 ```
vithyat 0:977e87915078 357 $ mbed config -G CLOUD_SDK_API_KEY <API_KEY>
vithyat 0:977e87915078 358 ```
vithyat 0:977e87915078 359
vithyat 0:977e87915078 360 For instructions on how to generate an API key, please [see the documentation](https://cloud.mbed.com/docs/current/integrate-web-app/api-keys.html#generating-an-api-key).
vithyat 0:977e87915078 361
vithyat 0:977e87915078 362 1. Initialize your Pelion DM credentials (once per project):
vithyat 0:977e87915078 363
vithyat 0:977e87915078 364 ```
vithyat 0:977e87915078 365 $ mbed dm init -d "<your company name.com>" --model-name "<product model identifier>"
vithyat 0:977e87915078 366 ```
vithyat 0:977e87915078 367
vithyat 0:977e87915078 368 This creates your private and public key pair and also initializes various `.c` files with these credentials, so you can use Connect and (firmware) Update device management features.
vithyat 0:977e87915078 369
vithyat 0:977e87915078 370 1. Remove the `main.cpp` application from the project, or ensure the content of the file is wrapped with `#ifndef MBED_TEST_MODE`.
vithyat 0:977e87915078 371
vithyat 0:977e87915078 372 1. Compile the tests with the `MBED_TEST_MODE` compilation flag.
vithyat 0:977e87915078 373
vithyat 0:977e87915078 374 ```
vithyat 0:977e87915078 375 $ mbed test -t <toolchain> -m <platform> -n simple-mbed-cloud-client-tests-* -DMBED_TEST_MODE --compile
vithyat 0:977e87915078 376 ```
vithyat 0:977e87915078 377
vithyat 0:977e87915078 378 1. Run the tests from the application directory:
vithyat 0:977e87915078 379
vithyat 0:977e87915078 380 ```
vithyat 0:977e87915078 381 $ mbed test -t <toolchain> -m <platform> -n simple-mbed-cloud-client-tests-* --run -v
vithyat 0:977e87915078 382 ```
vithyat 0:977e87915078 383
vithyat 0:977e87915078 384 ### Troubleshooting
vithyat 0:977e87915078 385
vithyat 0:977e87915078 386 Below are common issues and fixes.
vithyat 0:977e87915078 387
vithyat 0:977e87915078 388 #### Autoformatting failed with error -5005
vithyat 0:977e87915078 389
vithyat 0:977e87915078 390 This is due to an issue with the storage block device. If using an SD card, ensure that the SD card is seated properly.
vithyat 0:977e87915078 391
vithyat 0:977e87915078 392 #### Storage initialization failed with error -4002
vithyat 0:977e87915078 393
vithyat 0:977e87915078 394 This is observed when the device is using legacy serial flash which does not support SFDP, or the SPI frequency is not configured properly.
vithyat 0:977e87915078 395
vithyat 0:977e87915078 396 #### SYNC_FAILED during testing
vithyat 0:977e87915078 397
vithyat 0:977e87915078 398 Occasionally, if the test failed during a previous attempt, the SMCC Greentea tests fail to sync. If this is the case, please replug your device to the host PC. Additionally, you may need to update your DAPLink or ST-Link interface firmware.
vithyat 0:977e87915078 399
vithyat 0:977e87915078 400 If the test fails with SYNC_FAILED all the time, please check if the UART flow control pins (UART_CTS, UART_RTS) are properly defined. If your device supports flow control over UART, fill them with the corresponding pins; if not, please specify NC.
vithyat 0:977e87915078 401
vithyat 0:977e87915078 402 #### Device identity is inconsistent
vithyat 0:977e87915078 403
vithyat 0:977e87915078 404 If your device ID in Pelion Device Management is inconsistent over a device reset, it could be because it is failing to open the credentials on the storage held in the Enhanced Secure File System. Typically, this is because the device cannot access the Root of Trust stored in SOTP.
vithyat 0:977e87915078 405
vithyat 0:977e87915078 406 One way to verify this is to see if the storage is reformatted after a device reset when `format-storage-layer-on-error` is set to `1` in `mbed_app.json`. It would appear on the serial terminal output from the device as:
vithyat 0:977e87915078 407
vithyat 0:977e87915078 408 ```
vithyat 0:977e87915078 409 [SMCC] Initializing storage.
vithyat 0:977e87915078 410 [SMCC] Autoformatting the storage.
vithyat 0:977e87915078 411 [SMCC] Reset storage to an empty state.
vithyat 0:977e87915078 412 [SMCC] Starting developer flow
vithyat 0:977e87915078 413 ```
vithyat 0:977e87915078 414
vithyat 0:977e87915078 415 When this occurs, look at the SOTP sectors defined in `mbed_app.json`:
vithyat 0:977e87915078 416
vithyat 0:977e87915078 417 ```
vithyat 0:977e87915078 418 "sotp-section-1-address" : "0xFE000",
vithyat 0:977e87915078 419 "sotp-section-1-size" : "0x1000",
vithyat 0:977e87915078 420 "sotp-section-2-address" : "0xFF000",
vithyat 0:977e87915078 421 "sotp-section-2-size" : "0x1000",
vithyat 0:977e87915078 422 ```
vithyat 0:977e87915078 423
vithyat 0:977e87915078 424 Ensure that the sectors are correct according to the flash layout of your device, and they are not being overwritten during the programming of the device. ST-Link devices overwrite these sectors when you use drag-and-drop of `.bin` files. Thus, moving the SOTP sectors to the end sectors of flash ensures they are not overwritten.
vithyat 0:977e87915078 425
vithyat 0:977e87915078 426 #### Stack overflow
vithyat 0:977e87915078 427
vithyat 0:977e87915078 428 If you receive a stack overflow error, increase the Mbed OS main stack size to at least 6000. You can do this by modifying the following parameter in `mbed_app.json`:
vithyat 0:977e87915078 429
vithyat 0:977e87915078 430 ```
vithyat 0:977e87915078 431 "MBED_CONF_APP_MAIN_STACK_SIZE=6000",
vithyat 0:977e87915078 432 ```
vithyat 0:977e87915078 433
vithyat 0:977e87915078 434 #### Device failed to register
vithyat 0:977e87915078 435
vithyat 0:977e87915078 436 Check the device allocation on your Pelion account to see if you are allowed additional devices to connect. You can delete development devices. After being deleted, they will not count toward your allocation.
vithyat 0:977e87915078 437
vithyat 0:977e87915078 438 #### In network test cases, tests over larger buffers passed, but tests over small buffers keeps failing
vithyat 0:977e87915078 439 This could be observed with cellular modems driven by AT commands.
vithyat 0:977e87915078 440 Suggestions:
vithyat 0:977e87915078 441 1. Connect the modem to an serial interface which supports hardware flow control, and define MDMRTS and MDMCTS correspondingly.
vithyat 0:977e87915078 442 2. Use the highest possible baud-rate of your modem, e.g. 115200bps
vithyat 0:977e87915078 443 3. For the UART connected to your host PC, choose one which supports hardware flow control
vithyat 0:977e87915078 444 4. Set the STDIO UART baud-rate to 230400bps by configuring `platform.stdio-baud-rate`.
vithyat 0:977e87915078 445
vithyat 0:977e87915078 446 #### With SPI/QSPI Flash, LittleFS got corrupted after firmware update test
vithyat 0:977e87915078 447 If you observe logs such as `mbed assertation failed: block < lfs->cfg->block_count` or `invalid superblock`, etc., please check if partition mode is set to 0:
vithyat 0:977e87915078 448 ```
vithyat 0:977e87915078 449 "device-management.partition_mode" : 0
vithyat 0:977e87915078 450 ```
vithyat 0:977e87915078 451
vithyat 0:977e87915078 452 #### Notification channel failures during LwM2M Resource test cases
vithyat 0:977e87915078 453 This could be observed if a previously registered long-poll or webhook notification channel with the same API key existed.
vithyat 0:977e87915078 454 You may either use another API key, or delete the notification channel with curl command:
vithyat 0:977e87915078 455
vithyat 0:977e87915078 456 to delete Long Poll:
vithyat 0:977e87915078 457 ```
vithyat 0:977e87915078 458 curl -H "Authorization: Bearer ${API_KEY}" -X DELETE ${API_URL}/v2/notification/pull
vithyat 0:977e87915078 459 ```
vithyat 0:977e87915078 460 to delete WebHook:
vithyat 0:977e87915078 461 ```
vithyat 0:977e87915078 462 curl -H "Authorization: Bearer ${API_KEY}" -X DELETE ${API_URL}/v2/notification/callback
vithyat 0:977e87915078 463 ```
vithyat 0:977e87915078 464 Please note that long-polling is now deprecated and will be likely be replace in the future. Use callback notification channel (WebHook) instead.
vithyat 0:977e87915078 465
vithyat 0:977e87915078 466 #### I had built the test suites but somehow I got my Python environment messed up; can I run the test binaries without GreenTea?
vithyat 0:977e87915078 467 The test binaries are built under:
vithyat 0:977e87915078 468 ```
vithyat 0:977e87915078 469 <repo folder>/BUILD/tests/<Target Name>/<Toolchain>/simple-mbed-cloud-client/TESTS/<Test Suites>/<test case>/<test case name>.hex.
vithyat 0:977e87915078 470 ```
vithyat 0:977e87915078 471 You may copy the binary you want to manually test and flash it to the device, then when the device boots, paste the following line to the serial console to trigger the test:
vithyat 0:977e87915078 472 ```
vithyat 0:977e87915078 473 {{__sync;1}}
vithyat 0:977e87915078 474 ```
vithyat 0:977e87915078 475
vithyat 0:977e87915078 476 ### Known issues
vithyat 0:977e87915078 477
vithyat 0:977e87915078 478 Check open issues on [GitHub](https://github.com/ARMmbed/simple-mbed-cloud-client/issues).