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
Copy file name to clipboardExpand all lines: README.md
+48-46Lines changed: 48 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,11 @@
1
1
# Pelion Client Mbed OS Example
2
2
3
-
This is a simplified example with the following features:
4
-
- Mbed OS 5.13 and Pelion Device Management Client 3.3.0
3
+
This is a simplified example for Mbed OS with the following features:
4
+
- Mbed OS 5.14.1 and Pelion Device Management Client 4.0.0
5
5
- Support for FW Update
6
6
- 200 lines of code + credential sources
7
7
8
-
Note this application is considered **alpha** and given early access to Mbed Partners.
8
+
There is an example of the client for multiple operating systems in [mbed-cloud-client-example](https://github.com/ARMmbed/mbed-cloud-client-example) repository. The underlying client library is the same for both. This Mbed OS only example is simpler as it only supports one OS, but if you want to do development in Linux and Mbed OS at the same time - you should use the [mbed-cloud-client-example](https://github.com/ARMmbed/mbed-cloud-client-example).
<spanclass="notes">**(*) Note**: the platforms require further testing</span>
23
23
@@ -28,23 +28,25 @@ This section is intended for developers to get started, import the example appli
28
28
## Requirements
29
29
30
30
- Mbed CLI >= 1.10.0
31
-
31
+
32
32
For instructions on installing and using Mbed CLI, please see our [documentation](https://os.mbed.com/docs/mbed-os/latest/tools/developing-mbed-cli.html).
You should generate your own API key. Pelion Device Management is available for any Mbed developer. Create a [free trial](https://os.mbed.com/pelion-free-tier).
39
39
40
-
For instructions on how to generate your API key, please see our [documentation](https://cloud.mbed.com/docs/current/integrate-web-app/api-keys.html#generating-an-api-key).
40
+
For instructions on how to generate your API key, please see our [documentation](https://cloud.mbed.com/docs/current/integrate-web-app/api-keys.html#generating-an-api-key).
41
41
42
42
## Deploying
43
43
44
44
This repository is in the process of being updated and depends on few enhancements being deployed in mbed-cloud-client. In the meantime, follow these steps to import and apply the patches before compiling.
45
45
46
+
```
46
47
mbed import mbed-os-pelion-example
47
48
cd mbed-os-pelion-example
49
+
```
48
50
49
51
## Compiling
50
52
@@ -61,7 +63,7 @@ This repository is in the process of being updated and depends on few enhancemen
61
63
- Press 'i' to print endpoint name
62
64
- Press Ctrl-C to to unregister
63
65
- Press 'r' to reset storage and reboot (warning: it generates a new device ID!)
64
-
66
+
65
67
## Further information and requirements
66
68
67
69
Check the public tutorial for further information:
@@ -73,13 +75,13 @@ Check the public tutorial for further information:
73
75
- Device initializes but can't register to Pelion
74
76
75
77
Error: `client_error(3) -> Bootstrap server URL is not correctly formed`
76
-
78
+
77
79
Solution: Format the the storage by pressing 'r' in the serial terminal.
78
-
80
+
79
81
# Porting process to add support for an Mbed Enabled board
80
82
81
83
There are many steps involved in this process. We generally recomend the following steps:
82
-
84
+
83
85
1. Configure the application using `mbed_app.json`
84
86
- Configure the default connectivity
85
87
- Configure the KVSTORE area to store credentials (internal or external memory)
@@ -104,19 +106,19 @@ You can extend or override the default configuration using `mbed_app.json` in th
104
106
### a. Connectivity
105
107
106
108
Specify the default IP 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`.
111
-
113
+
112
114
Depending on connectivity type, you might have to specify more configuration options. Review the [documentation](https://os.mbed.com/docs/mbed-os/latest/porting/porting-connectivity.html) for further information.
113
115
114
116
### b. Storage for credentials
115
117
116
118
Start by getting familiar with the multiple [storage options](https://os.mbed.com/docs/mbed-os/latest/reference/storage.html) and configurations supported in Mbed OS.
117
119
118
120
Then start designing the system memory map, the location of components (whether they are on internal or external memory), and the corresponding base addresses and sizes. You may want to create a diagram similar to the one below to help you to make design decisions:
119
-
121
+
120
122
+--------------------------+
121
123
| |
122
124
| |
@@ -151,19 +153,19 @@ You can extend or override the default configuration using `mbed_app.json` in th
151
153
In cases where the MCU has two separate memory banks, it's appropiate to allocate the bootloader and base application in one bank, and KVSTORE storage at the begining of the second bank followed by a firmware candidate storage.
152
154
153
155
-**Option 1:** Allocating credentials in internal memory
154
-
156
+
155
157
**This is the preferred option whenever possible**. Make sure `TDB_INTERNAL` is the type of storage selected in `mbed_app.json`. Specify the base address depending on the available memory in the system. The size of this section should be aligned with the flash erase sector. The value should be multiple of 4 with a minimum of 24KB and upwards depending on the use case (for example the usage of certificate chain will increase the need of storage to hold those certificates). An example of this configuration can be seen for the `NUCLEO_F429ZI` platform in this application.
-**Option 2:** Allocating credentials in external memory:
162
-
164
+
163
165
This is possible when the platform has an storage device wired to the MCU (could be on-board or external component). Make sure `FILESYSTEM` is specified as type of storage. The blockdevice and filesystem should be one of the supported in Mbed OS (see [docs](https://os.mbed.com/docs/mbed-os/latest/porting/blockdevice-port.html)).
164
-
166
+
165
167
An example of this configuration can be seen for the `K64F` platform in the [mbed-cloud-client-example](https://github.com/ARMmbed/mbed-cloud-client-example/blob/master/mbed_app.json#L32)
166
-
168
+
167
169
"storage.storage_type" : "FILESYSTEM",
168
170
"storage_filesystem.blockdevice" : "SD",
169
171
"storage_filesystem.filesystem" : "LITTLE",
@@ -175,15 +177,15 @@ You can extend or override the default configuration using `mbed_app.json` in th
175
177
### c. Storage for firmware updates
176
178
177
179
Before enabling FW updates, it's recomended that the application is able to initialize the network and connect to Pelion DM.
178
-
179
-
Once the connection is successfull, you can follow the steps below to enable the platform to receive FW updates. Note the configuration for the application in this section should match with the one on the bootloader - see section below.
180
-
180
+
181
+
Once the connection is successfull, you can follow the steps below to enable the platform to receive FW updates. Note the configuration for the application in this section should match with the one on the bootloader - see section below.
182
+
181
183
- Common configuration
182
-
184
+
183
185
Regardless of where the firmware candidate is located (internal or external), there is a need to have a bootloader in place. The binary of the booloader can be specified with the `bootloader_img` option. The address and size of the bootloader determines the `application-details` and `bootloader-details` options. The value of `bootloader-details` can be obtained by running the binary on the target and observing the serial output.
184
-
186
+
185
187
Review the [mbed-bootloader](https://github.com/ARMmbed/mbed-bootloader#configurations) guidelines on how these options should be selected. Review the [bootloader configuration](2.-Bootloader-configuration) section below for more information.
186
-
188
+
187
189
Copy the compiled bootloader from `mbed-bootloader/BUILDS/<TARGET>/<TOOLCHAIN>-TINY/mbed-bootloader.bin` to `bootloader/mbed-bootloader-<TARGET>.bin`.
188
190
189
191
Edit `mbed-os-pelion-example/mbed_app.json` and modify the target configuration to match with the one in `bootloader_app.json`.
@@ -195,34 +197,34 @@ You can extend or override the default configuration using `mbed_app.json` in th
195
197
-`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.
196
198
197
199
-`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>
198
-
200
+
199
201
An example of this configuration can be seen for the `NUCLEO_F429ZI` platform.
-**Option 1:** Allocating the firmware update candidate in internal memory
208
210
209
211
**This is the preferred option whenever possible**. Make sure `ARM_UCP_FLASHIAP` is selected in `update-storage` in `mbed_app.json`. This area should be located at the end of the flash after the KVSTORE area. Specify the `storage-address`, `storage-size` and `storage-page` as required. The `application-details` option should point at the end of the bootloader area. An example of this configuration can be seen for the `NUCLEO_F429ZI` platform.
-**Option 2:** Allocating the firmware update candidate in external memory
217
-
219
+
218
220
When using an external device to the MCU to store the firmware candidate, make sure `ARM_UCP_FLASHIAP_BLOCKDEVICE` is specified as type of `update-storage`. Specify the `storage-address`, `storage-size` and `storage-page` as required.
219
-
221
+
220
222
An example of this configuration can be seen for the `K64F` platform in the [mbed-cloud-client-example](https://github.com/ARMmbed/mbed-cloud-client-example/blob/master/mbed_app.json#L32)
The bootloader is required to perform FW Updates. The steps below explain how to create a new configuration and binary for the bootloader.
@@ -231,25 +233,25 @@ The bootloader is required to perform FW Updates. The steps below explain how to
231
233
232
234
1. Edit the bootloader application configuration in this example (`bootloader/bootloader_app.json`) and add a new target entry. An example of this configuration can be seen for the `NUCLEO_F429ZI` platform:
<spanclass="notes">**Note:**`mbed-bootloader` is primarily optimized for `GCC_ARM`, so you may want to compile it with that toolchain.
251
-
Before jumping to the next step, you should compile and flash the bootloader and then connect over the virtual serial port 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>
252
-
254
+
Before jumping to the next step, you should compile and flash the bootloader and then connect over the virtual serial port to ensure the bootloader is running correctly. You can ignore errors related to checksum verification or failure to jump to application - these are expected at this stage.</span>
253
255
254
256
## Validation and testing
255
257
@@ -262,8 +264,8 @@ In addition to having an example application succesfully connected to Pelion DM,
262
264
- Mbed OS integration tests
263
265
264
266
See [mbed-os/TESTS/integration/README.md](https://github.com/ARMmbed/mbed-os/blob/sip-workshop/TESTS/integration/README.md) (sip-workshop branch)
265
-
266
-
`mbed test -t <toolchain> -m <platform> -n *integration-* -DINTEGRATION_TESTS -v`
267
+
268
+
`mbed test -t <toolchain> -m <platform> -n *integration-* -DINTEGRATION_TESTS -v`
0 commit comments