Skip to content

Commit 313f5a1

Browse files
author
Amanda Butler
authored
Create device-management-config.md
Move content from device management file to a new file for better separation and organization of thoughts.
1 parent 4226ebb commit 313f5a1

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

‎docs/device-management-config.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
## Device management configuration
2+
3+
The device management configuration has five distinct areas:
4+
5+
- Connectivity - the transport type for the device to connect to the device management service.
6+
- Storage - the storage type and writing used for both the credentials and the firmware storage.
7+
- Flash geometry - the device flash "sandbox" for bootloader, application header, application image and two SOTP regions.
8+
- SOTP - the address and size of the SOTP regions in flash used to store the device special key that decrypts the credentials storage.
9+
- Bootloader - the bootloader image, application and header offset.
10+
11+
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.
12+
13+
For full documentation about bootloaders and firmware update, please read the following documents:
14+
15+
- [Introduction to Mbed OS bootloaders](../porting/bootloader.html).
16+
- [Creating and using an Mbed OS bootloader](../tutorials/bootloader.html).
17+
- [Bootloader configuration in Mbed OS](../tools/configuring-tools.html).
18+
- [Mbed Bootloader for Pelion Device Management](https://github.com/ARMmbed/mbed-bootloader).
19+
- [Updating devices with Mbed CLI](../tools/cli-update.html).
20+
21+
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.
22+
23+
### 1. Application configuration
24+
25+
Edit the `mbed_app.json` file, and create a new entry under `target_overrides` with the target name for your device:
26+
27+
- **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:
28+
29+
```
30+
"target.network-default-interface-type" : "ETHERNET",
31+
```
32+
33+
The possible options are `ETHERNET`, `WIFI` and `CELLULAR`.
34+
35+
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`.
36+
37+
- **Storage** - Specify the storage block device type, which dynamically adds the block device driver you specified at compile time. For example:
38+
39+
```
40+
"target.components_add" : ["SD"],
41+
```
42+
43+
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).
44+
45+
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`:
46+
47+
```
48+
"sd.SPI_MOSI" : "PE_6",
49+
"sd.SPI_MISO" : "PE_5",
50+
"sd.SPI_CLK" : "PE_2",
51+
"sd.SPI_CS" : "PE_4",
52+
```
53+
54+
- **Flash** - Define the basics for the microcontroller flash. For example:
55+
56+
```
57+
"device_management.flash-start-address" : "0x08000000",
58+
"device_management.flash-size" : "(2048*1024)",
59+
```
60+
61+
- **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:
62+
63+
```
64+
"device_management.sotp-section-1-address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 2*(128*1024))",
65+
"device_management.sotp-section-1-size" : "(128*1024)",
66+
"device_management.sotp-section-2-address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 1*(128*1024))",
67+
"device_management.sotp-section-2-size" : "(128*1024)",
68+
"device_management.sotp-num-sections" : 2
69+
```
70+
71+
`*-address` defines the start of the Flash sector, and `*-size` defines the actual sector size. `sotp-num-sections` should always be set to `2`.
72+
73+
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.
74+
75+
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:
76+
77+
```
78+
$ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple*dev*connect -DMBED_TEST_MODE --compile
79+
```
80+
81+
To run the tests:
82+
83+
```
84+
$ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple*dev*connect --run -v
85+
```
86+
87+
### 2. Bootloader configuration
88+
89+
After you've successfully passed the "Connect" tests as described above, you can enable firmware update feature by adding a bootloader to your application.
90+
91+
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`.
92+
93+
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:
94+
95+
- **Flash** - Define the basics for the microcontroller flash (the same as in `mbed_app.json`). For example:
96+
97+
```
98+
"flash-start-address" : "0x08000000",
99+
"flash-size" : "(2048*1024)",
100+
```
101+
102+
- **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:
103+
104+
```
105+
"nvstore.area_1_address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 2*(128*1024))",
106+
"nvstore.area_1_size" : "(128*1024)",
107+
"nvstore.area_2_address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + MBED_CONF_APP_FLASH_SIZE - 1*(128*1024))", "nvstore.area_2_size" : "(128*1024)",
108+
```
109+
110+
- **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:
111+
112+
```
113+
"update-client.application-details": "(MBED_CONF_APP_FLASH_START_ADDRESS + 64*1024)",
114+
"application-start-address" : "(MBED_CONF_APP_FLASH_START_ADDRESS + 65*1024)",
115+
"max-application-size" : "DEFAULT_MAX_APPLICATION_SIZE",
116+
```
117+
118+
- **Storage** - Specify the block device pin configuration, exactly as you defined it in the `mbed_app.json` file. For example:
119+
120+
```
121+
"target.components_add" : ["SD"],
122+
"sd.SPI_MOSI" : "PE_6",
123+
"sd.SPI_MISO" : "PE_5",
124+
"sd.SPI_CLK" : "PE_2",
125+
"sd.SPI_CS" : "PE_4"
126+
```
127+
128+
1. Compile the bootloader using the `bootloader_app.json` configuration you just edited:
129+
130+
```
131+
$ mbed compile -t <TOOLCHAIN> -m <TARGET> --profile=tiny.json --app-config=<path to pelion-enablement/bootloader/bootloader_app.json>
132+
```
133+
134+
<span class="notes">**Note:** `mbed-bootloader` is primarily optimized for `GCC_ARM`, so you may want to compile it with that toolchain.
135+
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>
136+
137+
### 3. Add the bootloader to your application
138+
139+
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`.
140+
141+
1. Edit `<your_application_name>/mbed_app.json`, and modify the target entry to include:
142+
143+
```
144+
"target.features_add" : ["BOOTLOADER"],
145+
"target.bootloader_img" : "bootloader/mbed-bootloader-<TARGET>.bin",
146+
"target.app_offset" : "0x10400",
147+
"target.header_offset" : "0x10000",
148+
"update-client.application-details": "(MBED_CONF_APP_FLASH_START_ADDRESS + 64*1024)",
149+
```
150+
151+
<span class="notes">**Note:**
152+
- `update-client.application-details` should be identical in both `bootloader_app.json` and `mbed_app.json`.
153+
- `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.
154+
- `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>
155+
156+
1. Finally, compile and rerun all tests, including the firmware update ones with:
157+
158+
```
159+
$ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple*dev*connect -DMBED_TEST_MODE --compile
160+
161+
$ mbed test -t <TOOLCHAIN> -m <BOARD> -n simple*dev*connect --run -v
162+
```
163+
164+
Refer to the next section about what tests are being executed.

0 commit comments

Comments
 (0)