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@68:2330fbeb4926, 2017-12-20 (annotated)

Committer:
mbed_official
Date:
Wed Dec 20 14:30:11 2017 +0000
Revision:
68:2330fbeb4926
Parent:
66:30f2c1317e6d
Child:
78:fc7a81fd524c
Merge branch 'mbed-os-5.7.0-oob'



* mbed-os-5.7.0-oob:

  Updates to thread commissioning documentation

  Updating mbed-os to mbed-os-5.7.0-rc3

  Clarify the README.md

  Copy edit README.md

  Updating mbed-os to mbed-os-5.7.0-rc2

  Update README.md

  Update README.md

  Removed led from nucleo F401RE configuration

  Update mesh configuration files (#151)

  Updating mbed-os to mbed-os-5.7.0-rc1



.

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 68:2330fbeb4926 3 With this application, you can use the [mesh networking API](https://os.mbed.com/docs/latest/reference/mesh.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 68:2330fbeb4926 8 See the [6LoWPAN overview](https://os.mbed.com/docs/latest/tutorials/mesh.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
Seppo Takalo 0:bde1843b9885 19 ### Change the channel settings (optional)
Seppo Takalo 0:bde1843b9885 20
Seppo Takalo 0:bde1843b9885 21 See the file `mbed_app.json` for an example of defining an IEEE 802.15.4 channel to use.
Seppo Takalo 0:bde1843b9885 22
mbed_official 19:f55c7983f8ab 23 ### Selecting optimal Nanostack configuration
mbed_official 19:f55c7983f8ab 24
mbed_official 68:2330fbeb4926 25 To optimize the flash usage, select a proper configuration for Nanostack. The configuration depends mostly on the preferred use case.
mbed_official 19:f55c7983f8ab 26
mbed_official 19:f55c7983f8ab 27 Select the protocol the network is based on:
mbed_official 19:f55c7983f8ab 28
mbed_official 68:2330fbeb4926 29 - 6LoWPAN-ND.
mbed_official 68:2330fbeb4926 30 - Thread.
mbed_official 19:f55c7983f8ab 31
mbed_official 19:f55c7983f8ab 32 Select the device role:
mbed_official 19:f55c7983f8ab 33
mbed_official 19:f55c7983f8ab 34 - Mesh network. A router. (default)
mbed_official 68:2330fbeb4926 35 - Star network. Nonrouting device. Also known as a host or sleepy host.
mbed_official 68:2330fbeb4926 36
mbed_official 68:2330fbeb4926 37 Modify your `mbed_app.json` file to see which Nanostack and [Mbed Mesh API](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/README.md) configuration to use.
mbed_official 19:f55c7983f8ab 38
mbed_official 68:2330fbeb4926 39 Example configuration files are provide under `configs/` directory. You may override the `mbed_app.json` with either of these.
mbed_official 68:2330fbeb4926 40
mbed_official 68:2330fbeb4926 41 |configuration file|Use for|
mbed_official 68:2330fbeb4926 42 |------------------|-------|
mbed_official 68:2330fbeb4926 43 |`configs/mesh_6lowpan.json` | 6LoWPAN-ND based mesh network. |
mbed_official 68:2330fbeb4926 44 |`configs/mesh_thread.json` | Thread based mesh network. |
mbed_official 19:f55c7983f8ab 45
mbed_official 19:f55c7983f8ab 46 An example of the `mbed_app.json` file:
mbed_official 19:f55c7983f8ab 47
mbed_official 19:f55c7983f8ab 48 ```
mbed_official 19:f55c7983f8ab 49 ...
mbed_official 19:f55c7983f8ab 50 "mesh-type":{
mbed_official 19:f55c7983f8ab 51 "help": "options are MESH_LOWPAN, MESH_THREAD",
mbed_official 19:f55c7983f8ab 52 "value": "MESH_LOWPAN"
mbed_official 19:f55c7983f8ab 53 }
mbed_official 19:f55c7983f8ab 54 },
mbed_official 19:f55c7983f8ab 55 "target_overrides": {
mbed_official 19:f55c7983f8ab 56 "*": {
mbed_official 66:30f2c1317e6d 57 "target.features_add": ["NANOSTACK", "COMMON_PAL"],
mbed_official 68:2330fbeb4926 58 "nanostack.configuration": "lowpan_router",
mbed_official 19:f55c7983f8ab 59 "mbed-mesh-api.6lowpan-nd-device-type": "NET_6LOWPAN_ROUTER",
mbed_official 19:f55c7983f8ab 60 "mbed-mesh-api.thread-device-type": "MESH_DEVICE_TYPE_THREAD_ROUTER",
mbed_official 19:f55c7983f8ab 61 "mbed-mesh-api.heap-size": 32000,
mbed_official 19:f55c7983f8ab 62 "mbed-trace.enable": false
mbed_official 19:f55c7983f8ab 63 }
mbed_official 19:f55c7983f8ab 64 }
mbed_official 19:f55c7983f8ab 65 ```
mbed_official 19:f55c7983f8ab 66
mbed_official 68:2330fbeb4926 67 The following tables show the values to use in the `mbed_app.json` file for your devices in different networks.
mbed_official 19:f55c7983f8ab 68
mbed_official 68:2330fbeb4926 69 - For a 6LoWPAN-ND based network, use `mesh-type: MESH_LOWPAN`.
mbed_official 68:2330fbeb4926 70 - For a Thread-based network, use `mesh-type: MESH_THREAD`.
mbed_official 19:f55c7983f8ab 71
mbed_official 52:27692043e962 72 #### 6LoWPAN-ND
mbed_official 52:27692043e962 73
mbed_official 19:f55c7983f8ab 74 **mesh-type: MESH_LOWPAN**
mbed_official 19:f55c7983f8ab 75
mbed_official 66:30f2c1317e6d 76 |Device role|`nanostack.configuration` value|`mbed-mesh-api.6lowpan-nd-device-type`|
mbed_official 19:f55c7983f8ab 77 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 78 |Mesh router (default) | lowpan_router | NET_6LOWPAN_ROUTER |
mbed_official 68:2330fbeb4926 79 |Nonrouting device | lowpan_host | NET_6LOWPAN_HOST |
mbed_official 19:f55c7983f8ab 80
mbed_official 52:27692043e962 81 #### Thread
mbed_official 52:27692043e962 82
mbed_official 19:f55c7983f8ab 83 **mesh-type: MESH_THREAD**
mbed_official 19:f55c7983f8ab 84
mbed_official 66:30f2c1317e6d 85 |Device role|`nanostack.configuration` value|`mbed-mesh-api.thread-device-type`|
mbed_official 19:f55c7983f8ab 86 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 87 |Mesh router (default) | thread_router | MESH_DEVICE_TYPE_THREAD_ROUTER |
mbed_official 68:2330fbeb4926 88 |Nonrouting device | thread_end_device | MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE |
mbed_official 19:f55c7983f8ab 89
mbed_official 52:27692043e962 90 ##### Thread commissioning
mbed_official 52:27692043e962 91
mbed_official 68:2330fbeb4926 92 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/FEATURE_NANOSTACK/mbed-mesh-api/mbed_lib.json).
mbed_official 68:2330fbeb4926 93 If you want to use the Thread commissioning, see [how to commission a Thread device in practice](https://os.mbed.com/docs/latest/tutorials/mesh.html#how-to-commission-a-thread-device-in-practice)
mbed_official 19:f55c7983f8ab 94
mbed_official 19:f55c7983f8ab 95 ### Requirements for hardware
mbed_official 19:f55c7983f8ab 96
mbed_official 68:2330fbeb4926 97 The networking stack used in this example requires TLS functionality to be enabled on Mbed TLS.
mbed_official 68:2330fbeb4926 98 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 99
mbed_official 19:f55c7983f8ab 100 To learn why entropy is required, read the [TLS Porting guide](https://docs.mbed.com/docs/mbed-os-handbook/en/5.2/advanced/tls_porting/).
mbed_official 19:f55c7983f8ab 101
mbed_official 49:425a1889434d 102 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 103
mbed_official 52:27692043e962 104 You also need to check how LEDs and buttons are configured for your hardware, and update .json accordingly.
mbed_official 52:27692043e962 105
mbed_official 68:2330fbeb4926 106 ### Changing the radio driver
mbed_official 68:2330fbeb4926 107
mbed_official 68:2330fbeb4926 108 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 109
mbed_official 68:2330fbeb4926 110 To change the RF driver modify the `mbed_app.json` file. For example,
mbed_official 68:2330fbeb4926 111
mbed_official 68:2330fbeb4926 112 ```json
mbed_official 68:2330fbeb4926 113 "radio-type":{
mbed_official 68:2330fbeb4926 114 "help": "options are ATMEL, MCR20, NCS36510, KW24D",
mbed_official 68:2330fbeb4926 115 "value": "ATMEL"
mbed_official 68:2330fbeb4926 116 },
mbed_official 68:2330fbeb4926 117 ```
mbed_official 68:2330fbeb4926 118
Seppo Takalo 0:bde1843b9885 119 ### Compile the application
Seppo Takalo 0:bde1843b9885 120
Seppo Takalo 0:bde1843b9885 121 ```
mbed_official 68:2330fbeb4926 122 mbed compile -m K64F -t GCC_ARM
Seppo Takalo 0:bde1843b9885 123 ```
Seppo Takalo 0:bde1843b9885 124
mbed_official 52:27692043e962 125 A binary is generated in the end of the build process.
Seppo Takalo 0:bde1843b9885 126
Seppo Takalo 0:bde1843b9885 127 ### Connect the RF shield to the board
Seppo Takalo 0:bde1843b9885 128
mbed_official 68:2330fbeb4926 129 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 130
Seppo Takalo 0:bde1843b9885 131 ### Program the target
Seppo Takalo 0:bde1843b9885 132
Seppo Takalo 0:bde1843b9885 133 Drag and drop the binary to the target to program the application.
Seppo Takalo 0:bde1843b9885 134
Seppo Takalo 0:bde1843b9885 135 ### Update the firmware of the border router
Seppo Takalo 0:bde1843b9885 136
mbed_official 55:63aa128e8a80 137 This example supports the following border router:
Seppo Takalo 0:bde1843b9885 138
mbed_official 68:2330fbeb4926 139 - [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router).
mbed_official 52:27692043e962 140
mbed_official 68:2330fbeb4926 141 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 142
mbed_official 68:2330fbeb4926 143 Remember to connect the Ethernet cable between the border router and your home/office router. Then power on the board.
Seppo Takalo 0:bde1843b9885 144
Seppo Takalo 0:bde1843b9885 145 ## Testing
Seppo Takalo 0:bde1843b9885 146
mbed_official 52:27692043e962 147 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 148
Seppo Takalo 0:bde1843b9885 149 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 150
mbed_official 13:4a0466077538 151 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
Seppo Takalo 0:bde1843b9885 152
Seppo Takalo 0:bde1843b9885 153 ```
Seppo Takalo 0:bde1843b9885 154 connected. IP = 2001:db8:a0b:12f0::1
Seppo Takalo 0:bde1843b9885 155 ```
Seppo Takalo 0:bde1843b9885 156
Seppo Takalo 0:bde1843b9885 157 You can use this IP address to `ping` from your PC and verify that the connection is working correctly.
Seppo Takalo 0:bde1843b9885 158
mbed_official 52:27692043e962 159
mbed_official 52:27692043e962 160 ## Memory optimizations
mbed_official 52:27692043e962 161
mbed_official 52:27692043e962 162 On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
mbed_official 52:27692043e962 163 In those cases, you might try following these instructions to optimize the memory usage.
mbed_official 52:27692043e962 164
mbed_official 68:2330fbeb4926 165 ### Mbed TLS configuration
mbed_official 52:27692043e962 166
mbed_official 68:2330fbeb4926 167 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 168
mbed_official 52:27692043e962 169 This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
mbed_official 52:27692043e962 170
mbed_official 68:2330fbeb4926 171 ### Disabling the LED control example
mbed_official 52:27692043e962 172
mbed_official 68:2330fbeb4926 173 You can disable the LED control example by specifying `enable-led-control-example": false` in the `mbed_app.json`
mbed_official 52:27692043e962 174
mbed_official 68:2330fbeb4926 175 This saves you about 2.5 kB of flash.
mbed_official 52:27692043e962 176
mbed_official 52:27692043e962 177 ### Change network stack's event loop stack size
mbed_official 52:27692043e962 178
mbed_official 68:2330fbeb4926 179 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 180 In case client functionality is not used, you can define the following to use 2kB of stack
mbed_official 52:27692043e962 181
mbed_official 52:27692043e962 182 `"nanostack-hal.event_loop_thread_stack_size": 2048`
mbed_official 52:27692043e962 183
mbed_official 68:2330fbeb4926 184 This saves you 4kB of RAM.
mbed_official 52:27692043e962 185
mbed_official 52:27692043e962 186 ### Change Nanostack's heap size
mbed_official 52:27692043e962 187
mbed_official 68:2330fbeb4926 188 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 189
mbed_official 68:2330fbeb4926 190 In `mbed_app.json`, you find the following line:
mbed_official 68:2330fbeb4926 191
mbed_official 52:27692043e962 192 ```
mbed_official 53:82a191e2c133 193 "mbed-mesh-api.heap-size": 15000,
mbed_official 52:27692043e962 194 ```
mbed_official 68:2330fbeb4926 195
mbed_official 68:2330fbeb4926 196 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 197
mbed_official 52:27692043e962 198 ### Move Nanostack's heap inside the system heap
mbed_official 52:27692043e962 199
mbed_official 52:27692043e962 200 Nanostack's internal heap can be moved within the system heap.
mbed_official 68:2330fbeb4926 201 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 202
mbed_official 68:2330fbeb4926 203 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 204
mbed_official 68:2330fbeb4926 205 Add the following line to `mbed_app.json` to test:
mbed_official 68:2330fbeb4926 206
mbed_official 52:27692043e962 207 ```
mbed_official 52:27692043e962 208 "mbed-mesh-api.use-malloc-for-heap": true,
mbed_official 52:27692043e962 209 ```
mbed_official 52:27692043e962 210
mbed_official 52:27692043e962 211 ### Use release profile
mbed_official 52:27692043e962 212
mbed_official 68:2330fbeb4926 213 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 214
mbed_official 52:27692043e962 215 Examples:
mbed_official 68:2330fbeb4926 216
mbed_official 52:27692043e962 217 ```
mbed_official 52:27692043e962 218 $ mbed export -m KW24D -i make_iar --profile release
mbed_official 52:27692043e962 219 OR
mbed_official 52:27692043e962 220 $ mbed compile -m KW24D -t IAR --profile release
mbed_official 52:27692043e962 221 ```
mbed_official 68:2330fbeb4926 222
mbed_official 68:2330fbeb4926 223 ## Troubleshooting
mbed_official 68:2330fbeb4926 224
mbed_official 68:2330fbeb4926 225 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.