You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The device management configuration has five distinct areas:
123
-
124
-
- Connectivity - the transport type for the device to connect to the device management service.
125
-
- Storage - the storage type and writing used for both the credentials and the firmware storage.
126
-
- Flash geometry - the device flash "sandbox" for bootloader, application header, application image and two SOTP regions.
127
-
- SOTP - the address and size of the SOTP regions in flash used to store the device special key that decrypts the credentials storage.
128
-
- Bootloader - the bootloader image, application and header offset.
129
-
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.
131
-
132
-
For full documentation about bootloaders and firmware update, please read the following documents:
133
-
134
-
- [Introduction to Mbed OS bootloaders](../porting/bootloader.html).
135
-
- [Creating and using an Mbed OS bootloader](../tutorials/bootloader.html).
136
-
- [Bootloader configuration in Mbed OS](../tools/configuring-tools.html).
137
-
- [Mbed Bootloader for Pelion Device Management](https://github.com/ARMmbed/mbed-bootloader).
138
-
- [Updating devices with Mbed CLI](../tools/cli-update.html).
139
-
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.
141
-
142
-
#### 1. Application configuration
143
-
144
-
Edit the `mbed_app.json` file, and create a new entry under `target_overrides` with the target name for your device:
145
-
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:
The possible options are `ETHERNET`, `WIFI` and `CELLULAR`.
153
-
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`.
155
-
156
-
- **Storage** - Specify the storage block device type, which dynamically adds the block device driver you specified at compile time. For example:
157
-
158
-
```
159
-
"target.components_add" : ["SD"],
160
-
```
161
-
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).
163
-
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`:
165
-
166
-
```
167
-
"sd.SPI_MOSI" : "PE_6",
168
-
"sd.SPI_MISO" : "PE_5",
169
-
"sd.SPI_CLK" : "PE_2",
170
-
"sd.SPI_CS" : "PE_4",
171
-
```
172
-
173
-
- **Flash** - Define the basics for the microcontroller flash. For example:
- **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:
`*-address` defines the start of the Flash sector, and `*-size` defines the actual sector size. `sotp-num-sections` should always be set to `2`.
191
-
192
-
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.
193
-
194
-
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:
After you've successfully passed the "Connect" tests as described above, you can enable firmware update feature by adding a bootloader to your application.
209
-
210
-
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`.
211
-
212
-
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:
213
-
214
-
- **Flash** - Define the basics for the microcontroller flash (the same as in `mbed_app.json`). For example:
215
-
216
-
```
217
-
"flash-start-address" : "0x08000000",
218
-
"flash-size" : "(2048*1024)",
219
-
```
220
-
221
-
- **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:
- **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:
<span class="notes">**Note:** `mbed-bootloader` is primarily optimized for `GCC_ARM`, so you may want to compile it with that toolchain.
254
-
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>
255
-
256
-
#### 3. Add the bootloader to your application
257
-
258
-
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`.
259
-
260
-
1. Edit `<your_application_name>/mbed_app.json`, and modify the target entry to include:
- `update-client.application-details` should be identical in both `bootloader_app.json` and `mbed_app.json`.
272
-
- `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.
273
-
- `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>
274
-
275
-
1. Finally, compile and rerun all tests, including the firmware update ones with:
Refer to the next section about what tests are being executed.
284
-
285
-
### Validation and testing
286
-
287
-
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.
| `Connect to <Network type>` | Tests the connection to the network through the network interface. |
304
-
| `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. |
305
-
| `Format <Filesystem>` | Tests that you can successfully format the block device for the file system type. |
306
-
| `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.
307
-
| `Pelion DM Bootstrap & Register` | Bootstraps the device and registers it for first time with Pelion Device Management. |
308
-
| `Pelion DM Directory` | Verifies that a registered device appears in the Device Directory in Pelion Device Management. |
309
-
| `Pelion DM Re-register` | Resets the device and reregisters with Pelion Device Management with previously bootstrapped credentials. |
310
-
| `Post-reset Identity` | Verifies that the device identity is preserved over device reset, confirming that Root of Trust is stored in SOTP correctly. |
311
-
| `ResourceLwM2M GET` | Verifies that the device can perform a GET request on an LwM2M resource. |
312
-
| `ResourceLwM2M SET Test` | Sets or changes value from the device and verifies the Pelion Device Management API client can observe the value changing. |
313
-
| `ResourceLwM2M PUT Test` | Verifies the device can perform a PUT request on an LwM2M resource by setting a new value. |
314
-
| `Resource LwM2M POST Test` | Verifies the device can execute a POST on an LwM2M resource and the callback function on the device is called. |
315
-
316
-
#### Test cases - update
317
-
318
-
| **Test case** | **Description** |
319
-
| ------------- | ------------- |
320
-
| `Connect to <Network type>` | Tests the connection to the network using the network interface. |
321
-
| `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. |
322
-
| `Format <Filesystem>` | Tests that you can successfully format the block device for the file system type. |
323
-
| `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.
324
-
| `Pelion DM Bootstrap & Register` | Bootstraps the device and registers it for first time with Pelion Device Management. |
325
-
| `Pelion DM Directory` | Verifies a registered device appears in the Device Directory in Pelion Device Management. |
326
-
| `Firmware Prepare` | Prepares the firmware on the host side and calls `mbed dm` to initiate the Pelion Device Management update campaign. |
327
-
| `Firmware Download` | Downloads the firmware onto the device. |
328
-
| `Firmware Update` | Resets the device, verifies that the firmware has correct checksum, applies it and reverifies the applied firmware checksum. |
329
-
| `Pelion DM Re-register` | Reregisters the device with Pelion Device Management using the new firmware and previously bootstrapped credentials. |
330
-
| `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. |
331
-
332
-
#### Requirements
333
-
334
-
Mbed Device Management tests rely on the Python SDK to test the end-to-end solution. To install the Python SDK:
335
-
336
-
```
337
-
$ pip install mbed-cloud-sdk
338
-
```
339
-
340
-
<span class="notes">**Note:** The Python SDK requires Python 2.7.10+ or Python 3.4.3+, built with SSL support.</span>
341
-
342
-
#### Testing setup
343
-
344
-
1. Import an example application for Pelion Device Management that contains the corresponding configuration for your target.
345
-
346
-
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.
347
-
348
-
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).
349
-
350
-
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:
351
-
352
-
```
353
-
$ mbed config -G CLOUD_SDK_API_KEY <API_KEY>
354
-
```
355
-
356
-
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).
357
-
358
-
1. Initialize your Pelion DM credentials (once per project):
359
-
360
-
```
361
-
$ mbed dm init -d "<your company name.com>" --model-name "<product model identifier>"
362
-
```
363
-
364
-
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.
365
-
366
-
1. Remove the `main.cpp` application from the project, or ensure the content of the file is wrapped with `#ifndef MBED_TEST_MODE`.
367
-
368
-
1. Compile the tests with the `MBED_TEST_MODE` compilation flag.
This is due to an issue with the storage block device. If using an SD card, ensure that the SD card is seated properly.
387
-
388
-
##### SYNC_FAILED during testing
389
-
390
-
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.
391
-
392
-
##### Device identity is inconsistent
393
-
394
-
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.
395
-
396
-
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:
397
-
398
-
```
399
-
[SMCC] Initializing storage.
400
-
[SMCC] Autoformatting the storage.
401
-
[SMCC] Reset storage to an empty state.
402
-
[SMCC] Starting developer flow
403
-
```
404
-
405
-
When this occurs, look at the SOTP sectors defined in `mbed_app.json`:
406
-
407
-
```
408
-
"sotp-section-1-address" : "0xFE000",
409
-
"sotp-section-1-size" : "0x1000",
410
-
"sotp-section-2-address" : "0xFF000",
411
-
"sotp-section-2-size" : "0x1000",
412
-
```
413
-
414
-
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.
415
-
416
-
##### Stack overflow
417
-
418
-
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`:
419
-
420
-
```
421
-
"MBED_CONF_APP_MAIN_STACK_SIZE=6000",
422
-
```
423
-
424
-
##### Device failed to register
425
-
426
-
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.
427
-
428
-
#### Known issues
429
-
430
-
Check open issues on [GitHub](https://github.com/ARMmbed/simple-mbed-cloud-client/issues).
0 commit comments