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@101:eaeb5760ee04, 2018-08-31 (annotated)

Committer:
mbed_official
Date:
Fri Aug 31 13:30:07 2018 +0100
Revision:
101:eaeb5760ee04
Parent:
92:66d4b2417747
Child:
102:77951b775883
Remove external RF drivers



After 5.10 these drivers will be provided by Mbed OS



.

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
Seppo Takalo 0:bde1843b9885 33 ### Change the channel settings (optional)
Seppo Takalo 0:bde1843b9885 34
Seppo Takalo 0:bde1843b9885 35 See the file `mbed_app.json` for an example of defining an IEEE 802.15.4 channel to use.
Seppo Takalo 0:bde1843b9885 36
mbed_official 19:f55c7983f8ab 37 ### Selecting optimal Nanostack configuration
mbed_official 19:f55c7983f8ab 38
mbed_official 68:2330fbeb4926 39 To optimize the flash usage, select a proper configuration for Nanostack. The configuration depends mostly on the preferred use case.
mbed_official 19:f55c7983f8ab 40
mbed_official 19:f55c7983f8ab 41 Select the protocol the network is based on:
mbed_official 19:f55c7983f8ab 42
mbed_official 68:2330fbeb4926 43 - 6LoWPAN-ND.
mbed_official 68:2330fbeb4926 44 - Thread.
mbed_official 19:f55c7983f8ab 45
mbed_official 19:f55c7983f8ab 46 Select the device role:
mbed_official 19:f55c7983f8ab 47
mbed_official 19:f55c7983f8ab 48 - Mesh network. A router. (default)
mbed_official 68:2330fbeb4926 49 - Star network. Nonrouting device. Also known as a host or sleepy host.
mbed_official 68:2330fbeb4926 50
mbed_official 87:a6a7b64f4f48 51 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 52
mbed_official 68:2330fbeb4926 53 Example configuration files are provide under `configs/` directory. You may override the `mbed_app.json` with either of these.
mbed_official 68:2330fbeb4926 54
mbed_official 68:2330fbeb4926 55 |configuration file|Use for|
mbed_official 68:2330fbeb4926 56 |------------------|-------|
mbed_official 68:2330fbeb4926 57 |`configs/mesh_6lowpan.json` | 6LoWPAN-ND based mesh network. |
mbed_official 68:2330fbeb4926 58 |`configs/mesh_thread.json` | Thread based mesh network. |
mbed_official 19:f55c7983f8ab 59
mbed_official 19:f55c7983f8ab 60 An example of the `mbed_app.json` file:
mbed_official 19:f55c7983f8ab 61
mbed_official 19:f55c7983f8ab 62 ```
mbed_official 19:f55c7983f8ab 63 ...
mbed_official 19:f55c7983f8ab 64 "mesh-type":{
mbed_official 19:f55c7983f8ab 65 "help": "options are MESH_LOWPAN, MESH_THREAD",
mbed_official 19:f55c7983f8ab 66 "value": "MESH_LOWPAN"
mbed_official 19:f55c7983f8ab 67 }
mbed_official 19:f55c7983f8ab 68 },
mbed_official 19:f55c7983f8ab 69 "target_overrides": {
mbed_official 19:f55c7983f8ab 70 "*": {
mbed_official 66:30f2c1317e6d 71 "target.features_add": ["NANOSTACK", "COMMON_PAL"],
mbed_official 68:2330fbeb4926 72 "nanostack.configuration": "lowpan_router",
mbed_official 19:f55c7983f8ab 73 "mbed-mesh-api.6lowpan-nd-device-type": "NET_6LOWPAN_ROUTER",
mbed_official 19:f55c7983f8ab 74 "mbed-mesh-api.thread-device-type": "MESH_DEVICE_TYPE_THREAD_ROUTER",
mbed_official 19:f55c7983f8ab 75 "mbed-mesh-api.heap-size": 32000,
mbed_official 19:f55c7983f8ab 76 "mbed-trace.enable": false
mbed_official 19:f55c7983f8ab 77 }
mbed_official 19:f55c7983f8ab 78 }
mbed_official 19:f55c7983f8ab 79 ```
mbed_official 19:f55c7983f8ab 80
mbed_official 68:2330fbeb4926 81 The following tables show the values to use in the `mbed_app.json` file for your devices in different networks.
mbed_official 19:f55c7983f8ab 82
mbed_official 68:2330fbeb4926 83 - For a 6LoWPAN-ND based network, use `mesh-type: MESH_LOWPAN`.
mbed_official 68:2330fbeb4926 84 - For a Thread-based network, use `mesh-type: MESH_THREAD`.
mbed_official 19:f55c7983f8ab 85
mbed_official 52:27692043e962 86 #### 6LoWPAN-ND
mbed_official 52:27692043e962 87
mbed_official 19:f55c7983f8ab 88 **mesh-type: MESH_LOWPAN**
mbed_official 19:f55c7983f8ab 89
mbed_official 66:30f2c1317e6d 90 |Device role|`nanostack.configuration` value|`mbed-mesh-api.6lowpan-nd-device-type`|
mbed_official 19:f55c7983f8ab 91 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 92 |Mesh router (default) | lowpan_router | NET_6LOWPAN_ROUTER |
mbed_official 68:2330fbeb4926 93 |Nonrouting device | lowpan_host | NET_6LOWPAN_HOST |
mbed_official 19:f55c7983f8ab 94
mbed_official 52:27692043e962 95 #### Thread
mbed_official 52:27692043e962 96
mbed_official 19:f55c7983f8ab 97 **mesh-type: MESH_THREAD**
mbed_official 19:f55c7983f8ab 98
mbed_official 66:30f2c1317e6d 99 |Device role|`nanostack.configuration` value|`mbed-mesh-api.thread-device-type`|
mbed_official 19:f55c7983f8ab 100 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 101 |Mesh router (default) | thread_router | MESH_DEVICE_TYPE_THREAD_ROUTER |
mbed_official 68:2330fbeb4926 102 |Nonrouting device | thread_end_device | MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE |
mbed_official 19:f55c7983f8ab 103
mbed_official 52:27692043e962 104 ##### Thread commissioning
mbed_official 52:27692043e962 105
mbed_official 87:a6a7b64f4f48 106 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 107 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 108
mbed_official 78:fc7a81fd524c 109 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 110
mbed_official 78:fc7a81fd524c 111 - Change `storage-device` to `MESH_SD_CARD` in the `./configs/mesh_thread.json` file.
mbed_official 78:fc7a81fd524c 112 - Enable commissioning as descibed in the referred instructions.
mbed_official 78:fc7a81fd524c 113 - Compile and program the application.
mbed_official 87:a6a7b64f4f48 114 - 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 115 - Commission the device to the Thread network.
mbed_official 78:fc7a81fd524c 116 - 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 117
mbed_official 19:f55c7983f8ab 118 ### Requirements for hardware
mbed_official 19:f55c7983f8ab 119
mbed_official 68:2330fbeb4926 120 The networking stack used in this example requires TLS functionality to be enabled on Mbed TLS.
mbed_official 68:2330fbeb4926 121 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 122
mbed_official 85:7c874d127eff 123 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 124
mbed_official 49:425a1889434d 125 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 126
mbed_official 52:27692043e962 127 You also need to check how LEDs and buttons are configured for your hardware, and update .json accordingly.
mbed_official 52:27692043e962 128
mbed_official 68:2330fbeb4926 129 ### Changing the radio driver
mbed_official 68:2330fbeb4926 130
mbed_official 68:2330fbeb4926 131 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 132
mbed_official 68:2330fbeb4926 133 To change the RF driver modify the `mbed_app.json` file. For example,
mbed_official 68:2330fbeb4926 134
mbed_official 68:2330fbeb4926 135 ```json
mbed_official 68:2330fbeb4926 136 "radio-type":{
mbed_official 68:2330fbeb4926 137 "help": "options are ATMEL, MCR20, NCS36510, KW24D",
mbed_official 68:2330fbeb4926 138 "value": "ATMEL"
mbed_official 68:2330fbeb4926 139 },
mbed_official 68:2330fbeb4926 140 ```
mbed_official 68:2330fbeb4926 141
Seppo Takalo 0:bde1843b9885 142 ### Compile the application
Seppo Takalo 0:bde1843b9885 143
Seppo Takalo 0:bde1843b9885 144 ```
mbed_official 68:2330fbeb4926 145 mbed compile -m K64F -t GCC_ARM
Seppo Takalo 0:bde1843b9885 146 ```
Seppo Takalo 0:bde1843b9885 147
mbed_official 52:27692043e962 148 A binary is generated in the end of the build process.
Seppo Takalo 0:bde1843b9885 149
Seppo Takalo 0:bde1843b9885 150 ### Connect the RF shield to the board
Seppo Takalo 0:bde1843b9885 151
mbed_official 68:2330fbeb4926 152 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 153
Seppo Takalo 0:bde1843b9885 154 ### Program the target
Seppo Takalo 0:bde1843b9885 155
Seppo Takalo 0:bde1843b9885 156 Drag and drop the binary to the target to program the application.
Seppo Takalo 0:bde1843b9885 157
Seppo Takalo 0:bde1843b9885 158 ### Update the firmware of the border router
Seppo Takalo 0:bde1843b9885 159
mbed_official 55:63aa128e8a80 160 This example supports the following border router:
Seppo Takalo 0:bde1843b9885 161
mbed_official 68:2330fbeb4926 162 - [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router).
mbed_official 52:27692043e962 163
mbed_official 68:2330fbeb4926 164 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 165
mbed_official 68:2330fbeb4926 166 Remember to connect the Ethernet cable between the border router and your home/office router. Then power on the board.
Seppo Takalo 0:bde1843b9885 167
Seppo Takalo 0:bde1843b9885 168 ## Testing
Seppo Takalo 0:bde1843b9885 169
mbed_official 52:27692043e962 170 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 171
Seppo Takalo 0:bde1843b9885 172 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 173
mbed_official 13:4a0466077538 174 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
Seppo Takalo 0:bde1843b9885 175
Seppo Takalo 0:bde1843b9885 176 ```
Seppo Takalo 0:bde1843b9885 177 connected. IP = 2001:db8:a0b:12f0::1
Seppo Takalo 0:bde1843b9885 178 ```
Seppo Takalo 0:bde1843b9885 179
Seppo Takalo 0:bde1843b9885 180 You can use this IP address to `ping` from your PC and verify that the connection is working correctly.
Seppo Takalo 0:bde1843b9885 181
mbed_official 52:27692043e962 182
mbed_official 52:27692043e962 183 ## Memory optimizations
mbed_official 52:27692043e962 184
mbed_official 52:27692043e962 185 On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
mbed_official 52:27692043e962 186 In those cases, you might try following these instructions to optimize the memory usage.
mbed_official 52:27692043e962 187
mbed_official 68:2330fbeb4926 188 ### Mbed TLS configuration
mbed_official 52:27692043e962 189
mbed_official 68:2330fbeb4926 190 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 191
mbed_official 52:27692043e962 192 This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
mbed_official 52:27692043e962 193
mbed_official 68:2330fbeb4926 194 ### Disabling the LED control example
mbed_official 52:27692043e962 195
mbed_official 68:2330fbeb4926 196 You can disable the LED control example by specifying `enable-led-control-example": false` in the `mbed_app.json`
mbed_official 52:27692043e962 197
mbed_official 68:2330fbeb4926 198 This saves you about 2.5 kB of flash.
mbed_official 52:27692043e962 199
mbed_official 52:27692043e962 200 ### Change network stack's event loop stack size
mbed_official 52:27692043e962 201
mbed_official 68:2330fbeb4926 202 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 203 In case client functionality is not used, you can define the following to use 2kB of stack
mbed_official 52:27692043e962 204
mbed_official 52:27692043e962 205 `"nanostack-hal.event_loop_thread_stack_size": 2048`
mbed_official 52:27692043e962 206
mbed_official 68:2330fbeb4926 207 This saves you 4kB of RAM.
mbed_official 52:27692043e962 208
mbed_official 52:27692043e962 209 ### Change Nanostack's heap size
mbed_official 52:27692043e962 210
mbed_official 68:2330fbeb4926 211 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 212
mbed_official 68:2330fbeb4926 213 In `mbed_app.json`, you find the following line:
mbed_official 68:2330fbeb4926 214
mbed_official 52:27692043e962 215 ```
mbed_official 53:82a191e2c133 216 "mbed-mesh-api.heap-size": 15000,
mbed_official 52:27692043e962 217 ```
mbed_official 68:2330fbeb4926 218
mbed_official 68:2330fbeb4926 219 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 220
mbed_official 52:27692043e962 221 ### Move Nanostack's heap inside the system heap
mbed_official 52:27692043e962 222
mbed_official 52:27692043e962 223 Nanostack's internal heap can be moved within the system heap.
mbed_official 68:2330fbeb4926 224 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 225
mbed_official 68:2330fbeb4926 226 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 227
mbed_official 68:2330fbeb4926 228 Add the following line to `mbed_app.json` to test:
mbed_official 68:2330fbeb4926 229
mbed_official 52:27692043e962 230 ```
mbed_official 52:27692043e962 231 "mbed-mesh-api.use-malloc-for-heap": true,
mbed_official 52:27692043e962 232 ```
mbed_official 52:27692043e962 233
mbed_official 52:27692043e962 234 ### Use release profile
mbed_official 52:27692043e962 235
mbed_official 68:2330fbeb4926 236 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 237
mbed_official 52:27692043e962 238 Examples:
mbed_official 68:2330fbeb4926 239
mbed_official 52:27692043e962 240 ```
mbed_official 52:27692043e962 241 $ mbed export -m KW24D -i make_iar --profile release
mbed_official 52:27692043e962 242 OR
mbed_official 52:27692043e962 243 $ mbed compile -m KW24D -t IAR --profile release
mbed_official 52:27692043e962 244 ```
mbed_official 68:2330fbeb4926 245
mbed_official 68:2330fbeb4926 246 ## Troubleshooting
mbed_official 68:2330fbeb4926 247
mbed_official 68:2330fbeb4926 248 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 249
mbed_official 87:a6a7b64f4f48 250 ## Known issues
mbed_official 87:a6a7b64f4f48 251
mbed_official 87:a6a7b64f4f48 252 1. https://github.com/ARMmbed/mbed-os-example-mesh-minimal/issues/188
mbed_official 87:a6a7b64f4f48 253
mbed_official 87:a6a7b64f4f48 254 The mesh interface function `mesh.get_mac_address()` has inadvertedly been changed in Mbed OS 5.9 to return the actual MAC address and not the EUI64 address. In order to print the actual EUI64 address for Thread commissioning, use the following code snippet after `printf("connected. IP = %s\n", mesh.get_ip_address());`:
mbed_official 87:a6a7b64f4f48 255 ```
mbed_official 87:a6a7b64f4f48 256 uint8_t eui64[8] = {0,0,0,0,0,0,0,0};
mbed_official 87:a6a7b64f4f48 257 mesh.device_eui64_get(eui64);
mbed_official 87:a6a7b64f4f48 258 printf("EUI64 address = %02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x\n", eui64[0], eui64[1], eui64[2], eui64[3], eui64[4], eui64[5], eui64[6], eui64[7]);
mbed_official 87:a6a7b64f4f48 259 ```
mbed_official 92:66d4b2417747 260 The new API for `device_eui64_get` was introduced in PR [7158](https://github.com/ARMmbed/mbed-os/pull/7158) and it will be available in Mbed OS 5.9.2.
mbed_official 87:a6a7b64f4f48 261