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@52:27692043e962, 2017-09-20 (annotated)

Committer:
mbed_official
Date:
Wed Sep 20 12:17:51 2017 +0100
Revision:
52:27692043e962
Parent:
49:425a1889434d
Child:
53:82a191e2c133
Initial commit.

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

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Seppo Takalo 0:bde1843b9885 1 # Example mesh application for mbed OS
Seppo Takalo 0:bde1843b9885 2
mbed_official 52:27692043e962 3 This application is the simplest one to utilize our mesh networking stack. By default the application demonstrates a simple light control application, where devices can control the LED status of all devices in the network.
mbed_official 52:27692043e962 4 The application can be built for the unsecure 6LoWPAN-ND or Thread network.
Seppo Takalo 0:bde1843b9885 5
Seppo Takalo 0:bde1843b9885 6 ## Setup
Seppo Takalo 0:bde1843b9885 7
Seppo Takalo 0:bde1843b9885 8 ### Download the application
Seppo Takalo 0:bde1843b9885 9
Seppo Takalo 0:bde1843b9885 10 ```
Seppo Takalo 0:bde1843b9885 11 mbed import mbed-os-example-mesh-minimal
Seppo Takalo 0:bde1843b9885 12 cd mbed-os-example-mesh-minimal
Seppo Takalo 0:bde1843b9885 13 ```
Seppo Takalo 0:bde1843b9885 14
Seppo Takalo 0:bde1843b9885 15 ### Change the channel settings (optional)
Seppo Takalo 0:bde1843b9885 16
Seppo Takalo 0:bde1843b9885 17 See the file `mbed_app.json` for an example of defining an IEEE 802.15.4 channel to use.
Seppo Takalo 0:bde1843b9885 18
mbed_official 19:f55c7983f8ab 19 ### Selecting optimal Nanostack configuration
mbed_official 19:f55c7983f8ab 20
mbed_official 19:f55c7983f8ab 21 If you want to optimize the flash usage, you need to select a proper configuration for Nanostack. The configuration depends mostly on the preferred use case.
mbed_official 19:f55c7983f8ab 22
mbed_official 19:f55c7983f8ab 23 See [6LoWPAN overview](https://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/quick_start_intro/index.html) for the definition of star and mesh networks. These same principles apply also to Thread protocol.
mbed_official 19:f55c7983f8ab 24
mbed_official 19:f55c7983f8ab 25 Select the protocol the network is based on:
mbed_official 19:f55c7983f8ab 26
mbed_official 19:f55c7983f8ab 27 - 6LoWPAN-ND
mbed_official 19:f55c7983f8ab 28 - Thread
mbed_official 19:f55c7983f8ab 29
mbed_official 19:f55c7983f8ab 30 Select the device role:
mbed_official 19:f55c7983f8ab 31
mbed_official 19:f55c7983f8ab 32 - Mesh network. A router. (default)
mbed_official 19:f55c7983f8ab 33 - Star network. Non routing device. Also known as a host, or sleepy host.
mbed_official 19:f55c7983f8ab 34
mbed_official 19:f55c7983f8ab 35 Modify your `mbed_app.json` file to tell which Nanostack build to choose and which configrations to use on [mbed Mesh API](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/README.md).
mbed_official 19:f55c7983f8ab 36
mbed_official 19:f55c7983f8ab 37 An example of the `mbed_app.json` file:
mbed_official 19:f55c7983f8ab 38
mbed_official 19:f55c7983f8ab 39 ```
mbed_official 19:f55c7983f8ab 40 ...
mbed_official 19:f55c7983f8ab 41 "mesh-type":{
mbed_official 19:f55c7983f8ab 42 "help": "options are MESH_LOWPAN, MESH_THREAD",
mbed_official 19:f55c7983f8ab 43 "value": "MESH_LOWPAN"
mbed_official 19:f55c7983f8ab 44 }
mbed_official 19:f55c7983f8ab 45 },
mbed_official 19:f55c7983f8ab 46 "target_overrides": {
mbed_official 19:f55c7983f8ab 47 "*": {
mbed_official 19:f55c7983f8ab 48 "target.features_add": ["NANOSTACK", "LOWPAN_ROUTER", "COMMON_PAL"],
mbed_official 19:f55c7983f8ab 49 "mbed-mesh-api.6lowpan-nd-device-type": "NET_6LOWPAN_ROUTER",
mbed_official 19:f55c7983f8ab 50 "mbed-mesh-api.thread-device-type": "MESH_DEVICE_TYPE_THREAD_ROUTER",
mbed_official 19:f55c7983f8ab 51 "mbed-mesh-api.heap-size": 32000,
mbed_official 19:f55c7983f8ab 52 "mbed-trace.enable": false
mbed_official 19:f55c7983f8ab 53 }
mbed_official 19:f55c7983f8ab 54 }
mbed_official 19:f55c7983f8ab 55 ```
mbed_official 19:f55c7983f8ab 56
mbed_official 19:f55c7983f8ab 57 The following tables show the values you should use in the `mbed_app.json` file for your devices in different networks.
mbed_official 19:f55c7983f8ab 58
mbed_official 19:f55c7983f8ab 59 - For 6LoWPAN-ND based network use `mesh-type: MESH_LOWPAN`.
mbed_official 19:f55c7983f8ab 60 - For Thread based network use `mesh-type: MESH_THREAD`.
mbed_official 19:f55c7983f8ab 61
mbed_official 52:27692043e962 62 #### 6LoWPAN-ND
mbed_official 52:27692043e962 63
mbed_official 19:f55c7983f8ab 64 **mesh-type: MESH_LOWPAN**
mbed_official 19:f55c7983f8ab 65
mbed_official 19:f55c7983f8ab 66 |Device role|`target.features_add` value|`mbed-mesh-api.6lowpan-nd-device-type`|
mbed_official 19:f55c7983f8ab 67 |-----------|-------------------------|------------------------------------|
mbed_official 19:f55c7983f8ab 68 |Mesh router (default) | LOWPAN_ROUTER | NET_6LOWPAN_ROUTER |
mbed_official 19:f55c7983f8ab 69 |Non routing device | LOWPAN_HOST | NET_6LOWPAN_HOST |
mbed_official 19:f55c7983f8ab 70
mbed_official 52:27692043e962 71 #### Thread
mbed_official 52:27692043e962 72
mbed_official 19:f55c7983f8ab 73 **mesh-type: MESH_THREAD**
mbed_official 19:f55c7983f8ab 74
mbed_official 19:f55c7983f8ab 75 |Device role|`target.features_add` value|`mbed-mesh-api.thread-device-type`|
mbed_official 19:f55c7983f8ab 76 |-----------|-------------------------|------------------------------------|
mbed_official 19:f55c7983f8ab 77 |Mesh router (default) | THREAD_ROUTER | MESH_DEVICE_TYPE_THREAD_ROUTER |
mbed_official 19:f55c7983f8ab 78 |Non routing device | THREAD_END_DEVICE | MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE |
mbed_official 19:f55c7983f8ab 79
mbed_official 52:27692043e962 80 ##### Thread commissioning
mbed_official 52:27692043e962 81
mbed_official 52:27692043e962 82 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 52:27692043e962 83 If you want to use the Thread commissioning add the following lines to the [thread configuration file](https://github.com/ARMmbed/mbed-os-example-mesh-minimal/blob/master/configs/mesh_thread.json).
mbed_official 52:27692043e962 84
mbed_official 52:27692043e962 85 * `"mbed-mesh-api.thread-use-static-link-config": false`
mbed_official 52:27692043e962 86 * `"macros": ["MBEDTLS_USER_CONFIG_FILE=\"mbedtls_config.h\""]`
mbed_official 19:f55c7983f8ab 87
mbed_official 19:f55c7983f8ab 88 ### Requirements for hardware
mbed_official 19:f55c7983f8ab 89
mbed_official 19:f55c7983f8ab 90 The networking stack used in this example requires TLS functionality to be enabled on mbed TLS.
mbed_official 19:f55c7983f8ab 91 On devices where hardware entropy is not present, TLS is disabled by default. This would result in compile time failures or linking failures.
mbed_official 19:f55c7983f8ab 92
mbed_official 19:f55c7983f8ab 93 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 94
mbed_official 49:425a1889434d 95 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 96
mbed_official 52:27692043e962 97 You also need to check how LEDs and buttons are configured for your hardware, and update .json accordingly.
mbed_official 52:27692043e962 98
Seppo Takalo 0:bde1843b9885 99 ### Compile the application
Seppo Takalo 0:bde1843b9885 100
mbed_official 49:425a1889434d 101 #### For 6LoWPAN
Seppo Takalo 0:bde1843b9885 102 ```
mbed_official 49:425a1889434d 103 mbed compile -m K64F -t GCC_ARM --app-config configs/mesh_6lowpan.json
mbed_official 49:425a1889434d 104 ```
mbed_official 49:425a1889434d 105
mbed_official 49:425a1889434d 106 #### For Thread
mbed_official 49:425a1889434d 107
mbed_official 49:425a1889434d 108 ```
mbed_official 49:425a1889434d 109 mbed compile -m K64F -t GCC_ARM --app-config configs/mesh_thread.json
Seppo Takalo 0:bde1843b9885 110 ```
Seppo Takalo 0:bde1843b9885 111
mbed_official 52:27692043e962 112 A binary is generated in the end of the build process.
Seppo Takalo 0:bde1843b9885 113
Seppo Takalo 0:bde1843b9885 114 ### Connect the RF shield to the board
Seppo Takalo 0:bde1843b9885 115
Seppo Takalo 0:bde1843b9885 116 By default, we are using the Atmel AT86RF233 and it can be purchased [here](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 117
Seppo Takalo 0:bde1843b9885 118 ### Program the target
Seppo Takalo 0:bde1843b9885 119
Seppo Takalo 0:bde1843b9885 120 Drag and drop the binary to the target to program the application.
Seppo Takalo 0:bde1843b9885 121
Seppo Takalo 0:bde1843b9885 122 ### Update the firmware of the border router
Seppo Takalo 0:bde1843b9885 123
mbed_official 19:f55c7983f8ab 124 This example supports the following two border routers:
Seppo Takalo 0:bde1843b9885 125
mbed_official 52:27692043e962 126 - [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router)
mbed_official 19:f55c7983f8ab 127 - [mbed gateway](https://firefly-iot.com/product/firefly-6lowpan-gateway-2-4ghz/)
mbed_official 52:27692043e962 128
mbed_official 19:f55c7983f8ab 129 Read the instructions on updating the firmware of your mbed gateway working as 6LoWPAN [here](https://github.com/ARMmbed/mbed-os-example-client#mbed-gateway).
mbed_official 19:f55c7983f8ab 130
mbed_official 19:f55c7983f8ab 131 Both border routers support 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 132
mbed_official 19:f55c7983f8ab 133 Remember to connect the Ethernet cable between the border router and your home/office router. Then power up the board.
Seppo Takalo 0:bde1843b9885 134
Seppo Takalo 0:bde1843b9885 135 ## Testing
Seppo Takalo 0:bde1843b9885 136
mbed_official 52:27692043e962 137 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 138
Seppo Takalo 0:bde1843b9885 139 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 140
mbed_official 13:4a0466077538 141 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
Seppo Takalo 0:bde1843b9885 142
Seppo Takalo 0:bde1843b9885 143 ```
Seppo Takalo 0:bde1843b9885 144 connected. IP = 2001:db8:a0b:12f0::1
Seppo Takalo 0:bde1843b9885 145 ```
Seppo Takalo 0:bde1843b9885 146
Seppo Takalo 0:bde1843b9885 147 You can use this IP address to `ping` from your PC and verify that the connection is working correctly.
Seppo Takalo 0:bde1843b9885 148
Seppo Takalo 0:bde1843b9885 149 ### Changing the radio driver (optional)
Seppo Takalo 0:bde1843b9885 150
mbed_official 52:27692043e962 151 To run a 6LoWPAN-ND network, you need a working RF driver for Nanostack. This example uses the Atmel AT86RF233 by default.
Seppo Takalo 0:bde1843b9885 152
Seppo Takalo 0:bde1843b9885 153 To change the RF driver:
Seppo Takalo 0:bde1843b9885 154
Seppo Takalo 0:bde1843b9885 155 1. Uninstall the Atmel RF driver.
Seppo Takalo 0:bde1843b9885 156
Seppo Takalo 0:bde1843b9885 157 mbed remove atmel-rf-driver
Seppo Takalo 0:bde1843b9885 158
Seppo Takalo 0:bde1843b9885 159 2. Install the new driver. (For example, for the FRDM-CR20A radio shield based on the MCR20A device.)
Seppo Takalo 0:bde1843b9885 160
Seppo Takalo 0:bde1843b9885 161 mbed add mcr20a-rf-driver
Seppo Takalo 0:bde1843b9885 162
Seppo Takalo 0:bde1843b9885 163 3. Recompile your application.
Seppo Takalo 0:bde1843b9885 164
Seppo Takalo 0:bde1843b9885 165 mbed compile -m K64F -t GCC_ARM
Seppo Takalo 0:bde1843b9885 166
mbed_official 19:f55c7983f8ab 167 **Note:** Make sure that the `mbed_app.json` file is also updated to reflect the usage of a particular RF driver. For example,
mbed_official 17:ee2610e1cb78 168
mbed_official 17:ee2610e1cb78 169 ```json
mbed_official 17:ee2610e1cb78 170 "radio-type":{
mbed_official 17:ee2610e1cb78 171 "help": "options are ATMEL, MCR20",
mbed_official 17:ee2610e1cb78 172 "value": "ATMEL"
mbed_official 17:ee2610e1cb78 173 },
mbed_official 17:ee2610e1cb78 174 ```
mbed_official 52:27692043e962 175
mbed_official 52:27692043e962 176 ## Memory optimizations
mbed_official 52:27692043e962 177
mbed_official 52:27692043e962 178 On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
mbed_official 52:27692043e962 179 In those cases, you might try following these instructions to optimize the memory usage.
mbed_official 52:27692043e962 180
mbed_official 52:27692043e962 181 ### mbed TLS configuration
mbed_official 52:27692043e962 182
mbed_official 52:27692043e962 183 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 hardware.
mbed_official 52:27692043e962 184
mbed_official 52:27692043e962 185 This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
mbed_official 52:27692043e962 186
mbed_official 52:27692043e962 187 ### Disabling the Led control example
mbed_official 52:27692043e962 188
mbed_official 52:27692043e962 189 The led control example can be disabled by specifying `enable-led-control-example": false` in the `mbed_app.json`
mbed_official 52:27692043e962 190
mbed_official 52:27692043e962 191 This will save you about 2.5 kB of flash.
mbed_official 52:27692043e962 192
mbed_official 52:27692043e962 193 ### Change network stack's event loop stack size
mbed_official 52:27692043e962 194
mbed_official 52:27692043e962 195 Nanostack's internal event-loop is shared with mbed Client and is therefore
mbed_official 52:27692043e962 196 requiring lots of stack to complete the security hanshakes using TLS protocols.
mbed_official 52:27692043e962 197 In case client functionality is not used, following can be defined to use 2kB of stack
mbed_official 52:27692043e962 198
mbed_official 52:27692043e962 199 `"nanostack-hal.event_loop_thread_stack_size": 2048`
mbed_official 52:27692043e962 200
mbed_official 52:27692043e962 201 This will save you 4kB of RAM.
mbed_official 52:27692043e962 202
mbed_official 52:27692043e962 203 ### Change Nanostack's heap size
mbed_official 52:27692043e962 204
mbed_official 52:27692043e962 205 Nanostack uses internal heap and requires minimum of 14kB in order to run on Thread network where comissioning is enabled.
mbed_official 52:27692043e962 206 When running on different mesh configurations, it might be able to operate on smaller heap.
mbed_official 52:27692043e962 207
mbed_official 52:27692043e962 208 In `mbed_app.json` you will find following line:
mbed_official 52:27692043e962 209 ```
mbed_official 52:27692043e962 210 "mbed-mesh-api.heap-size": 14000,
mbed_official 52:27692043e962 211 ```
mbed_official 52:27692043e962 212 That specifies that 14kB to be used for Nanostack's heap.
mbed_official 52:27692043e962 213
mbed_official 52:27692043e962 214 For 6LoWPAN, you can try 12kB. For smallest memory usage, you should configure node to be in non-routing mode. See https://github.com/ARMmbed/mbed-os/tree/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api#module-configuration
mbed_official 52:27692043e962 215
mbed_official 52:27692043e962 216 ### Move Nanostack's heap inside the system heap
mbed_official 52:27692043e962 217
mbed_official 52:27692043e962 218 Nanostack's internal heap can be moved within the system heap.
mbed_official 52:27692043e962 219 This helps on devices which have split RAM and compiler fails to fit statically allocated
mbed_official 52:27692043e962 220 symbols into one section. For example NXP KW24D device.
mbed_official 52:27692043e962 221
mbed_official 52:27692043e962 222 Mesh API has [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 223
mbed_official 52:27692043e962 224 Add following line to `mbed_app.json` to test:
mbed_official 52:27692043e962 225 ```
mbed_official 52:27692043e962 226 "mbed-mesh-api.use-malloc-for-heap": true,
mbed_official 52:27692043e962 227 ```
mbed_official 52:27692043e962 228
mbed_official 52:27692043e962 229 ### Use release profile
mbed_official 52:27692043e962 230
mbed_official 52:27692043e962 231 For devices with small memory, we recommend using release profiles for building and exporting. Please see [mbed Handbook: Build profiles](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/dev_tools/build_profiles/)
mbed_official 52:27692043e962 232
mbed_official 52:27692043e962 233 Examples:
mbed_official 52:27692043e962 234 ```
mbed_official 52:27692043e962 235 $ mbed export -m KW24D -i make_iar --profile release
mbed_official 52:27692043e962 236 OR
mbed_official 52:27692043e962 237 $ mbed compile -m KW24D -t IAR --profile release
mbed_official 52:27692043e962 238 ```