George Djabarov / Mbed OS mbed-os-example-mesh-minimal

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

README.md@102:77951b775883, 2018-09-03 (annotated)

Committer:
mbed_official
Date:
Mon Sep 03 08:45:15 2018 +0100
Revision:
102:77951b775883
Parent:
101:eaeb5760ee04
Child:
103:9982165eb577
Remove sd-driver and update README (#213)



Also SD driver needs to be removed.

.

Commit copied from https://github.com/ARMmbed/mbed-os-example-mesh-minimal

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 68:2330fbeb4926 1 # Example mesh application for Mbed OS
mbed_official 68:2330fbeb4926 2
mbed_official 85:7c874d127eff 3 With this application, you can use the [mesh networking API](https://os.mbed.com/docs/latest/reference/mesh-api.html) that [Mbed OS](https://github.com/ARMmbed/mbed-os) provides.
Seppo Takalo 0:bde1843b9885 4
mbed_official 68:2330fbeb4926 5 The application demonstrates a light control application, where devices can control the LED status of all devices in the network.
mbed_official 52:27692043e962 6 The application can be built for the unsecure 6LoWPAN-ND or Thread network.
Seppo Takalo 0:bde1843b9885 7
mbed_official 85:7c874d127eff 8 See the [6LoWPAN overview](https://os.mbed.com/docs/latest/reference/mesh-tech.html) for the definition of star and mesh networks. These same principles apply also to Thread protocol.
mbed_official 68:2330fbeb4926 9
Seppo Takalo 0:bde1843b9885 10 ## Setup
Seppo Takalo 0:bde1843b9885 11
Seppo Takalo 0:bde1843b9885 12 ### Download the application
Seppo Takalo 0:bde1843b9885 13
Seppo Takalo 0:bde1843b9885 14 ```
Seppo Takalo 0:bde1843b9885 15 mbed import mbed-os-example-mesh-minimal
Seppo Takalo 0:bde1843b9885 16 cd mbed-os-example-mesh-minimal
Seppo Takalo 0:bde1843b9885 17 ```
Seppo Takalo 0:bde1843b9885 18
mbed_official 101:eaeb5760ee04 19 ### Adding connectivity driver
mbed_official 101:eaeb5760ee04 20
mbed_official 101:eaeb5760ee04 21 This application requires 802.15.4 RF driver to be provided for the networking stack. Driver can be either external, or provided by the Mbed OS.
mbed_official 101:eaeb5760ee04 22
mbed_official 101:eaeb5760ee04 23 External driver can be added by calling
mbed_official 101:eaeb5760ee04 24
mbed_official 101:eaeb5760ee04 25 ```
mbed_official 101:eaeb5760ee04 26 mbed add <driver>
mbed_official 101:eaeb5760ee04 27 ```
mbed_official 101:eaeb5760ee04 28
mbed_official 101:eaeb5760ee04 29 For example MCR20A RF driver is added by calling `mbed add mcr20a-rf-driver`
mbed_official 101:eaeb5760ee04 30
mbed_official 101:eaeb5760ee04 31 Atmel AT86RF driver is added by calling `mbed add atmel-rf-driver`
mbed_official 101:eaeb5760ee04 32
mbed_official 102:77951b775883 33 SD driver is added by calling `mbed add sd-driver`
mbed_official 102:77951b775883 34
Seppo Takalo 0:bde1843b9885 35 ### Change the channel settings (optional)
Seppo Takalo 0:bde1843b9885 36
Seppo Takalo 0:bde1843b9885 37 See the file `mbed_app.json` for an example of defining an IEEE 802.15.4 channel to use.
Seppo Takalo 0:bde1843b9885 38
mbed_official 19:f55c7983f8ab 39 ### Selecting optimal Nanostack configuration
mbed_official 19:f55c7983f8ab 40
mbed_official 68:2330fbeb4926 41 To optimize the flash usage, select a proper configuration for Nanostack. The configuration depends mostly on the preferred use case.
mbed_official 19:f55c7983f8ab 42
mbed_official 19:f55c7983f8ab 43 Select the protocol the network is based on:
mbed_official 19:f55c7983f8ab 44
mbed_official 68:2330fbeb4926 45 - 6LoWPAN-ND.
mbed_official 68:2330fbeb4926 46 - Thread.
mbed_official 19:f55c7983f8ab 47
mbed_official 19:f55c7983f8ab 48 Select the device role:
mbed_official 19:f55c7983f8ab 49
mbed_official 19:f55c7983f8ab 50 - Mesh network. A router. (default)
mbed_official 68:2330fbeb4926 51 - Star network. Nonrouting device. Also known as a host or sleepy host.
mbed_official 68:2330fbeb4926 52
mbed_official 87:a6a7b64f4f48 53 Modify your `mbed_app.json` file to see which Nanostack and [Mbed Mesh API](https://os.mbed.com/docs/latest/reference/mesh-api.html) configuration to use.
mbed_official 19:f55c7983f8ab 54
mbed_official 68:2330fbeb4926 55 Example configuration files are provide under `configs/` directory. You may override the `mbed_app.json` with either of these.
mbed_official 68:2330fbeb4926 56
mbed_official 68:2330fbeb4926 57 |configuration file|Use for|
mbed_official 68:2330fbeb4926 58 |------------------|-------|
mbed_official 68:2330fbeb4926 59 |`configs/mesh_6lowpan.json` | 6LoWPAN-ND based mesh network. |
mbed_official 68:2330fbeb4926 60 |`configs/mesh_thread.json` | Thread based mesh network. |
mbed_official 19:f55c7983f8ab 61
mbed_official 19:f55c7983f8ab 62 An example of the `mbed_app.json` file:
mbed_official 19:f55c7983f8ab 63
mbed_official 19:f55c7983f8ab 64 ```
mbed_official 19:f55c7983f8ab 65 ...
mbed_official 19:f55c7983f8ab 66 "mesh-type":{
mbed_official 19:f55c7983f8ab 67 "help": "options are MESH_LOWPAN, MESH_THREAD",
mbed_official 19:f55c7983f8ab 68 "value": "MESH_LOWPAN"
mbed_official 19:f55c7983f8ab 69 }
mbed_official 19:f55c7983f8ab 70 },
mbed_official 19:f55c7983f8ab 71 "target_overrides": {
mbed_official 19:f55c7983f8ab 72 "*": {
mbed_official 66:30f2c1317e6d 73 "target.features_add": ["NANOSTACK", "COMMON_PAL"],
mbed_official 68:2330fbeb4926 74 "nanostack.configuration": "lowpan_router",
mbed_official 19:f55c7983f8ab 75 "mbed-mesh-api.6lowpan-nd-device-type": "NET_6LOWPAN_ROUTER",
mbed_official 19:f55c7983f8ab 76 "mbed-mesh-api.thread-device-type": "MESH_DEVICE_TYPE_THREAD_ROUTER",
mbed_official 19:f55c7983f8ab 77 "mbed-mesh-api.heap-size": 32000,
mbed_official 19:f55c7983f8ab 78 "mbed-trace.enable": false
mbed_official 19:f55c7983f8ab 79 }
mbed_official 19:f55c7983f8ab 80 }
mbed_official 19:f55c7983f8ab 81 ```
mbed_official 19:f55c7983f8ab 82
mbed_official 68:2330fbeb4926 83 The following tables show the values to use in the `mbed_app.json` file for your devices in different networks.
mbed_official 19:f55c7983f8ab 84
mbed_official 68:2330fbeb4926 85 - For a 6LoWPAN-ND based network, use `mesh-type: MESH_LOWPAN`.
mbed_official 68:2330fbeb4926 86 - For a Thread-based network, use `mesh-type: MESH_THREAD`.
mbed_official 19:f55c7983f8ab 87
mbed_official 52:27692043e962 88 #### 6LoWPAN-ND
mbed_official 52:27692043e962 89
mbed_official 19:f55c7983f8ab 90 **mesh-type: MESH_LOWPAN**
mbed_official 19:f55c7983f8ab 91
mbed_official 66:30f2c1317e6d 92 |Device role|`nanostack.configuration` value|`mbed-mesh-api.6lowpan-nd-device-type`|
mbed_official 19:f55c7983f8ab 93 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 94 |Mesh router (default) | lowpan_router | NET_6LOWPAN_ROUTER |
mbed_official 68:2330fbeb4926 95 |Nonrouting device | lowpan_host | NET_6LOWPAN_HOST |
mbed_official 19:f55c7983f8ab 96
mbed_official 52:27692043e962 97 #### Thread
mbed_official 52:27692043e962 98
mbed_official 19:f55c7983f8ab 99 **mesh-type: MESH_THREAD**
mbed_official 19:f55c7983f8ab 100
mbed_official 66:30f2c1317e6d 101 |Device role|`nanostack.configuration` value|`mbed-mesh-api.thread-device-type`|
mbed_official 19:f55c7983f8ab 102 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 103 |Mesh router (default) | thread_router | MESH_DEVICE_TYPE_THREAD_ROUTER |
mbed_official 68:2330fbeb4926 104 |Nonrouting device | thread_end_device | MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE |
mbed_official 19:f55c7983f8ab 105
mbed_official 52:27692043e962 106 ##### Thread commissioning
mbed_official 52:27692043e962 107
mbed_official 87:a6a7b64f4f48 108 By default, the Thread application uses the static network link configuration defined in the [mesh API configuration file](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/mbed-mesh-api/mbed_lib.json).
mbed_official 85:7c874d127eff 109 If you want to commission a Thread device, see [how to commission a Thread device in practice](https://os.mbed.com/docs/latest/reference/mesh-tech.html#thread-commissioning).
mbed_official 78:fc7a81fd524c 110
mbed_official 78:fc7a81fd524c 111 The Thread stack learns the network settings from the commissioning process and saves them to RAM memory. Therefore, the learned network settings are lost when you restart the device next time. To prevent re-commissioning, you can save the Thread configuration settings to an SD card as follows (only in `K64F`):
mbed_official 78:fc7a81fd524c 112
mbed_official 78:fc7a81fd524c 113 - Change `storage-device` to `MESH_SD_CARD` in the `./configs/mesh_thread.json` file.
mbed_official 78:fc7a81fd524c 114 - Enable commissioning as descibed in the referred instructions.
mbed_official 78:fc7a81fd524c 115 - Compile and program the application.
mbed_official 87:a6a7b64f4f48 116 - Insert an erased or FAT-formatted SD card to the `K64F` memory card slot. The application will initialize the SD card with the appropriate file system on first use.
mbed_official 78:fc7a81fd524c 117 - Commission the device to the Thread network.
mbed_official 78:fc7a81fd524c 118 - When you restart the device next time, the device reads the Thread configuration settings from the SD card and tries to attach to an existing network.
mbed_official 19:f55c7983f8ab 119
mbed_official 19:f55c7983f8ab 120 ### Requirements for hardware
mbed_official 19:f55c7983f8ab 121
mbed_official 68:2330fbeb4926 122 The networking stack used in this example requires TLS functionality to be enabled on Mbed TLS.
mbed_official 68:2330fbeb4926 123 On devices where hardware entropy is not present, TLS is disabled by default. This results in compile time failures or linking failures.
mbed_official 19:f55c7983f8ab 124
mbed_official 85:7c874d127eff 125 To learn why entropy is required, read the [TLS Porting guide](https://os.mbed.com/docs/latest/reference/mbed-tls-entropy.html).
mbed_official 19:f55c7983f8ab 126
mbed_official 49:425a1889434d 127 See [Notes on different hardware](https://github.com/ARMmbed/mbed-os-example-mesh-minimal/blob/master/Hardware.md) for known combinations of development boards and RF shields that have been tested.
mbed_official 49:425a1889434d 128
mbed_official 52:27692043e962 129 You also need to check how LEDs and buttons are configured for your hardware, and update .json accordingly.
mbed_official 52:27692043e962 130
mbed_official 68:2330fbeb4926 131 ### Changing the radio driver
mbed_official 68:2330fbeb4926 132
mbed_official 68:2330fbeb4926 133 To run a 6LoWPAN-ND network, you need a working RF driver for Nanostack. This example uses the Atmel AT86RF233 by default.
mbed_official 68:2330fbeb4926 134
mbed_official 68:2330fbeb4926 135 To change the RF driver modify the `mbed_app.json` file. For example,
mbed_official 68:2330fbeb4926 136
mbed_official 68:2330fbeb4926 137 ```json
mbed_official 68:2330fbeb4926 138 "radio-type":{
mbed_official 68:2330fbeb4926 139 "help": "options are ATMEL, MCR20, NCS36510, KW24D",
mbed_official 68:2330fbeb4926 140 "value": "ATMEL"
mbed_official 68:2330fbeb4926 141 },
mbed_official 68:2330fbeb4926 142 ```
mbed_official 68:2330fbeb4926 143
Seppo Takalo 0:bde1843b9885 144 ### Compile the application
Seppo Takalo 0:bde1843b9885 145
Seppo Takalo 0:bde1843b9885 146 ```
mbed_official 68:2330fbeb4926 147 mbed compile -m K64F -t GCC_ARM
Seppo Takalo 0:bde1843b9885 148 ```
Seppo Takalo 0:bde1843b9885 149
mbed_official 52:27692043e962 150 A binary is generated in the end of the build process.
Seppo Takalo 0:bde1843b9885 151
Seppo Takalo 0:bde1843b9885 152 ### Connect the RF shield to the board
Seppo Takalo 0:bde1843b9885 153
mbed_official 68:2330fbeb4926 154 We are using the Atmel AT86RF233, which you can [purchase](https://firefly-iot.com/product/firefly-arduino-shield-2-4ghz/). Place the shield on top of your board, and power it up.
Seppo Takalo 0:bde1843b9885 155
Seppo Takalo 0:bde1843b9885 156 ### Program the target
Seppo Takalo 0:bde1843b9885 157
Seppo Takalo 0:bde1843b9885 158 Drag and drop the binary to the target to program the application.
Seppo Takalo 0:bde1843b9885 159
Seppo Takalo 0:bde1843b9885 160 ### Update the firmware of the border router
Seppo Takalo 0:bde1843b9885 161
mbed_official 55:63aa128e8a80 162 This example supports the following border router:
Seppo Takalo 0:bde1843b9885 163
mbed_official 68:2330fbeb4926 164 - [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router).
mbed_official 52:27692043e962 165
mbed_official 68:2330fbeb4926 166 The border router supports static and dynamic backhaul configuration. The static configuration is good for testing, but the dynamic one works if your network infrastructure is supplying an IPv6 address. Make sure that you use the appropiate mode.
mbed_official 19:f55c7983f8ab 167
mbed_official 68:2330fbeb4926 168 Remember to connect the Ethernet cable between the border router and your home/office router. Then power on the board.
Seppo Takalo 0:bde1843b9885 169
Seppo Takalo 0:bde1843b9885 170 ## Testing
Seppo Takalo 0:bde1843b9885 171
mbed_official 52:27692043e962 172 By default the application is built for the LED control demo, in which the device sends a multicast message to all devices in the network when the button is pressed. All devices that receive the multicast message will change the LED status (red LED on/off) to the state defined in the message. Note, that the Thread devices can form a network without the existance of the border router. The following applies only to the case when the border router is set-up.
mbed_official 52:27692043e962 173
Seppo Takalo 0:bde1843b9885 174 As soon as both the border router and the target are up and running you can verify the correct behaviour. Open a serial console and see the IP address obtained by the device.
Seppo Takalo 0:bde1843b9885 175
mbed_official 13:4a0466077538 176 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
Seppo Takalo 0:bde1843b9885 177
Seppo Takalo 0:bde1843b9885 178 ```
Seppo Takalo 0:bde1843b9885 179 connected. IP = 2001:db8:a0b:12f0::1
Seppo Takalo 0:bde1843b9885 180 ```
Seppo Takalo 0:bde1843b9885 181
Seppo Takalo 0:bde1843b9885 182 You can use this IP address to `ping` from your PC and verify that the connection is working correctly.
Seppo Takalo 0:bde1843b9885 183
mbed_official 52:27692043e962 184
mbed_official 52:27692043e962 185 ## Memory optimizations
mbed_official 52:27692043e962 186
mbed_official 52:27692043e962 187 On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
mbed_official 52:27692043e962 188 In those cases, you might try following these instructions to optimize the memory usage.
mbed_official 52:27692043e962 189
mbed_official 68:2330fbeb4926 190 ### Mbed TLS configuration
mbed_official 52:27692043e962 191
mbed_official 68:2330fbeb4926 192 The custom Mbed TLS configuration can be set by adding `"macros": ["MBEDTLS_USER_CONFIG_FILE=\"mbedtls_config.h\""]` to the `.json` file. The [example Mbed TLS config](https://github.com/ARMmbed/mbed-os-example-mesh-minimal/blob/master/mbedtls_config.h) minimizes the RAM and ROM usage of the application. The configuration works on K64F, but it is not guaranteed to work on every Mbed Enabled platform.
mbed_official 52:27692043e962 193
mbed_official 52:27692043e962 194 This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
mbed_official 52:27692043e962 195
mbed_official 68:2330fbeb4926 196 ### Disabling the LED control example
mbed_official 52:27692043e962 197
mbed_official 68:2330fbeb4926 198 You can disable the LED control example by specifying `enable-led-control-example": false` in the `mbed_app.json`
mbed_official 52:27692043e962 199
mbed_official 68:2330fbeb4926 200 This saves you about 2.5 kB of flash.
mbed_official 52:27692043e962 201
mbed_official 52:27692043e962 202 ### Change network stack's event loop stack size
mbed_official 52:27692043e962 203
mbed_official 68:2330fbeb4926 204 Nanostack's internal event-loop is shared with Mbed Client and therefore requires lots of stack to complete the security hanshakes using TLS protocols.
mbed_official 68:2330fbeb4926 205 In case client functionality is not used, you can define the following to use 2kB of stack
mbed_official 52:27692043e962 206
mbed_official 52:27692043e962 207 `"nanostack-hal.event_loop_thread_stack_size": 2048`
mbed_official 52:27692043e962 208
mbed_official 68:2330fbeb4926 209 This saves you 4kB of RAM.
mbed_official 52:27692043e962 210
mbed_official 52:27692043e962 211 ### Change Nanostack's heap size
mbed_official 52:27692043e962 212
mbed_official 68:2330fbeb4926 213 Nanostack uses internal heap, which you can configure in the .json. A thread end device with comissioning enabled requires at least 15kB to run.
mbed_official 52:27692043e962 214
mbed_official 68:2330fbeb4926 215 In `mbed_app.json`, you find the following line:
mbed_official 68:2330fbeb4926 216
mbed_official 52:27692043e962 217 ```
mbed_official 53:82a191e2c133 218 "mbed-mesh-api.heap-size": 15000,
mbed_official 52:27692043e962 219 ```
mbed_official 68:2330fbeb4926 220
mbed_official 68:2330fbeb4926 221 For 6LoWPAN, you can try 12kB. For the smallest memory usage, configure the node to be in nonrouting mode. See [module-configuration](https://github.com/ARMmbed/mbed-os/tree/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api#module-configuration) for more detail.
mbed_official 52:27692043e962 222
mbed_official 52:27692043e962 223 ### Move Nanostack's heap inside the system heap
mbed_official 52:27692043e962 224
mbed_official 52:27692043e962 225 Nanostack's internal heap can be moved within the system heap.
mbed_official 68:2330fbeb4926 226 This helps on devices that have split RAM and compiler fails to fit statically allocated symbols into one section, for example, the NXP KW24D device.
mbed_official 52:27692043e962 227
mbed_official 68:2330fbeb4926 228 Mesh API has the [use-malloc-for-heap](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/README.md#configurable-parameters-in-section-mbed-mesh-api) option to help this.
mbed_official 52:27692043e962 229
mbed_official 68:2330fbeb4926 230 Add the following line to `mbed_app.json` to test:
mbed_official 68:2330fbeb4926 231
mbed_official 52:27692043e962 232 ```
mbed_official 52:27692043e962 233 "mbed-mesh-api.use-malloc-for-heap": true,
mbed_official 52:27692043e962 234 ```
mbed_official 52:27692043e962 235
mbed_official 52:27692043e962 236 ### Use release profile
mbed_official 52:27692043e962 237
mbed_official 68:2330fbeb4926 238 For devices with small memory, we recommend using release profiles for building and exporting. Please see the documentation about [Build profiles](https://os.mbed.com/docs/latest/tools/build-profiles.html).
mbed_official 52:27692043e962 239
mbed_official 52:27692043e962 240 Examples:
mbed_official 68:2330fbeb4926 241
mbed_official 52:27692043e962 242 ```
mbed_official 52:27692043e962 243 $ mbed export -m KW24D -i make_iar --profile release
mbed_official 52:27692043e962 244 OR
mbed_official 52:27692043e962 245 $ mbed compile -m KW24D -t IAR --profile release
mbed_official 52:27692043e962 246 ```
mbed_official 68:2330fbeb4926 247
mbed_official 68:2330fbeb4926 248 ## Troubleshooting
mbed_official 68:2330fbeb4926 249
mbed_official 68:2330fbeb4926 250 If you have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html) for suggestions on what could be wrong and how to fix it.
mbed_official 87:a6a7b64f4f48 251