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@66:30f2c1317e6d, 2017-11-30 (annotated)

Committer:
mbed_official
Date:
Thu Nov 30 16:30:07 2017 +0000
Revision:
66:30f2c1317e6d
Parent:
55:63aa128e8a80
Child:
68:2330fbeb4926
Update README for mbed-os 5.7



.

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 66:30f2c1317e6d 23 See [6LoWPAN overview](https://os.mbed.com/docs/v5.6/tutorials/6lowpan-mesh.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 66:30f2c1317e6d 35 Modify your `mbed_app.json` file to tell which Nanostack configuration to use 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 66:30f2c1317e6d 48 "target.features_add": ["NANOSTACK", "COMMON_PAL"],
mbed_official 66:30f2c1317e6d 49 "nanostack.configuration": "lowpan_router",
mbed_official 19:f55c7983f8ab 50 "mbed-mesh-api.6lowpan-nd-device-type": "NET_6LOWPAN_ROUTER",
mbed_official 19:f55c7983f8ab 51 "mbed-mesh-api.thread-device-type": "MESH_DEVICE_TYPE_THREAD_ROUTER",
mbed_official 19:f55c7983f8ab 52 "mbed-mesh-api.heap-size": 32000,
mbed_official 19:f55c7983f8ab 53 "mbed-trace.enable": false
mbed_official 19:f55c7983f8ab 54 }
mbed_official 19:f55c7983f8ab 55 }
mbed_official 19:f55c7983f8ab 56 ```
mbed_official 19:f55c7983f8ab 57
mbed_official 19:f55c7983f8ab 58 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 59
mbed_official 19:f55c7983f8ab 60 - For 6LoWPAN-ND based network use `mesh-type: MESH_LOWPAN`.
mbed_official 19:f55c7983f8ab 61 - For Thread based network use `mesh-type: MESH_THREAD`.
mbed_official 19:f55c7983f8ab 62
mbed_official 52:27692043e962 63 #### 6LoWPAN-ND
mbed_official 52:27692043e962 64
mbed_official 19:f55c7983f8ab 65 **mesh-type: MESH_LOWPAN**
mbed_official 19:f55c7983f8ab 66
mbed_official 66:30f2c1317e6d 67 |Device role|`nanostack.configuration` value|`mbed-mesh-api.6lowpan-nd-device-type`|
mbed_official 19:f55c7983f8ab 68 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 69 |Mesh router (default) | lowpan_router | NET_6LOWPAN_ROUTER |
mbed_official 66:30f2c1317e6d 70 |Non routing device | lowpan_host | NET_6LOWPAN_HOST |
mbed_official 19:f55c7983f8ab 71
mbed_official 52:27692043e962 72 #### Thread
mbed_official 52:27692043e962 73
mbed_official 19:f55c7983f8ab 74 **mesh-type: MESH_THREAD**
mbed_official 19:f55c7983f8ab 75
mbed_official 66:30f2c1317e6d 76 |Device role|`nanostack.configuration` value|`mbed-mesh-api.thread-device-type`|
mbed_official 19:f55c7983f8ab 77 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 78 |Mesh router (default) | thread_router | MESH_DEVICE_TYPE_THREAD_ROUTER |
mbed_official 66:30f2c1317e6d 79 |Non routing device | thread_end_device | MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE |
mbed_official 19:f55c7983f8ab 80
mbed_official 52:27692043e962 81 ##### Thread commissioning
mbed_official 52:27692043e962 82
mbed_official 52:27692043e962 83 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 84 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 85
mbed_official 52:27692043e962 86 * `"mbed-mesh-api.thread-use-static-link-config": false`
mbed_official 52:27692043e962 87 * `"macros": ["MBEDTLS_USER_CONFIG_FILE=\"mbedtls_config.h\""]`
mbed_official 19:f55c7983f8ab 88
mbed_official 19:f55c7983f8ab 89 ### Requirements for hardware
mbed_official 19:f55c7983f8ab 90
mbed_official 19:f55c7983f8ab 91 The networking stack used in this example requires TLS functionality to be enabled on mbed TLS.
mbed_official 19:f55c7983f8ab 92 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 93
mbed_official 19:f55c7983f8ab 94 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 95
mbed_official 49:425a1889434d 96 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 97
mbed_official 52:27692043e962 98 You also need to check how LEDs and buttons are configured for your hardware, and update .json accordingly.
mbed_official 52:27692043e962 99
Seppo Takalo 0:bde1843b9885 100 ### Compile the application
Seppo Takalo 0:bde1843b9885 101
mbed_official 49:425a1889434d 102 #### For 6LoWPAN
Seppo Takalo 0:bde1843b9885 103 ```
mbed_official 49:425a1889434d 104 mbed compile -m K64F -t GCC_ARM --app-config configs/mesh_6lowpan.json
mbed_official 49:425a1889434d 105 ```
mbed_official 49:425a1889434d 106
mbed_official 49:425a1889434d 107 #### For Thread
mbed_official 49:425a1889434d 108
mbed_official 49:425a1889434d 109 ```
mbed_official 49:425a1889434d 110 mbed compile -m K64F -t GCC_ARM --app-config configs/mesh_thread.json
Seppo Takalo 0:bde1843b9885 111 ```
Seppo Takalo 0:bde1843b9885 112
mbed_official 52:27692043e962 113 A binary is generated in the end of the build process.
Seppo Takalo 0:bde1843b9885 114
Seppo Takalo 0:bde1843b9885 115 ### Connect the RF shield to the board
Seppo Takalo 0:bde1843b9885 116
Seppo Takalo 0:bde1843b9885 117 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 118
Seppo Takalo 0:bde1843b9885 119 ### Program the target
Seppo Takalo 0:bde1843b9885 120
Seppo Takalo 0:bde1843b9885 121 Drag and drop the binary to the target to program the application.
Seppo Takalo 0:bde1843b9885 122
Seppo Takalo 0:bde1843b9885 123 ### Update the firmware of the border router
Seppo Takalo 0:bde1843b9885 124
mbed_official 55:63aa128e8a80 125 This example supports the following border router:
Seppo Takalo 0:bde1843b9885 126
mbed_official 52:27692043e962 127 - [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router)
mbed_official 52:27692043e962 128
mbed_official 55:63aa128e8a80 129 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 130
mbed_official 19:f55c7983f8ab 131 Remember to connect the Ethernet cable between the border router and your home/office router. Then power up the board.
Seppo Takalo 0:bde1843b9885 132
Seppo Takalo 0:bde1843b9885 133 ## Testing
Seppo Takalo 0:bde1843b9885 134
mbed_official 52:27692043e962 135 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 136
Seppo Takalo 0:bde1843b9885 137 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 138
mbed_official 13:4a0466077538 139 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
Seppo Takalo 0:bde1843b9885 140
Seppo Takalo 0:bde1843b9885 141 ```
Seppo Takalo 0:bde1843b9885 142 connected. IP = 2001:db8:a0b:12f0::1
Seppo Takalo 0:bde1843b9885 143 ```
Seppo Takalo 0:bde1843b9885 144
Seppo Takalo 0:bde1843b9885 145 You can use this IP address to `ping` from your PC and verify that the connection is working correctly.
Seppo Takalo 0:bde1843b9885 146
Seppo Takalo 0:bde1843b9885 147 ### Changing the radio driver (optional)
Seppo Takalo 0:bde1843b9885 148
mbed_official 52:27692043e962 149 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 150
Seppo Takalo 0:bde1843b9885 151 To change the RF driver:
Seppo Takalo 0:bde1843b9885 152
Seppo Takalo 0:bde1843b9885 153 1. Uninstall the Atmel RF driver.
Seppo Takalo 0:bde1843b9885 154
Seppo Takalo 0:bde1843b9885 155 mbed remove atmel-rf-driver
Seppo Takalo 0:bde1843b9885 156
Seppo Takalo 0:bde1843b9885 157 2. Install the new driver. (For example, for the FRDM-CR20A radio shield based on the MCR20A device.)
Seppo Takalo 0:bde1843b9885 158
Seppo Takalo 0:bde1843b9885 159 mbed add mcr20a-rf-driver
Seppo Takalo 0:bde1843b9885 160
Seppo Takalo 0:bde1843b9885 161 3. Recompile your application.
Seppo Takalo 0:bde1843b9885 162
Seppo Takalo 0:bde1843b9885 163 mbed compile -m K64F -t GCC_ARM
Seppo Takalo 0:bde1843b9885 164
mbed_official 19:f55c7983f8ab 165 **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 166
mbed_official 17:ee2610e1cb78 167 ```json
mbed_official 17:ee2610e1cb78 168 "radio-type":{
mbed_official 17:ee2610e1cb78 169 "help": "options are ATMEL, MCR20",
mbed_official 17:ee2610e1cb78 170 "value": "ATMEL"
mbed_official 17:ee2610e1cb78 171 },
mbed_official 17:ee2610e1cb78 172 ```
mbed_official 52:27692043e962 173
mbed_official 52:27692043e962 174 ## Memory optimizations
mbed_official 52:27692043e962 175
mbed_official 52:27692043e962 176 On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
mbed_official 52:27692043e962 177 In those cases, you might try following these instructions to optimize the memory usage.
mbed_official 52:27692043e962 178
mbed_official 52:27692043e962 179 ### mbed TLS configuration
mbed_official 52:27692043e962 180
mbed_official 52:27692043e962 181 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 182
mbed_official 52:27692043e962 183 This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
mbed_official 52:27692043e962 184
mbed_official 52:27692043e962 185 ### Disabling the Led control example
mbed_official 52:27692043e962 186
mbed_official 52:27692043e962 187 The led control example can be disabled by specifying `enable-led-control-example": false` in the `mbed_app.json`
mbed_official 52:27692043e962 188
mbed_official 52:27692043e962 189 This will save you about 2.5 kB of flash.
mbed_official 52:27692043e962 190
mbed_official 52:27692043e962 191 ### Change network stack's event loop stack size
mbed_official 52:27692043e962 192
mbed_official 52:27692043e962 193 Nanostack's internal event-loop is shared with mbed Client and is therefore
mbed_official 52:27692043e962 194 requiring lots of stack to complete the security hanshakes using TLS protocols.
mbed_official 52:27692043e962 195 In case client functionality is not used, following can be defined to use 2kB of stack
mbed_official 52:27692043e962 196
mbed_official 52:27692043e962 197 `"nanostack-hal.event_loop_thread_stack_size": 2048`
mbed_official 52:27692043e962 198
mbed_official 52:27692043e962 199 This will save you 4kB of RAM.
mbed_official 52:27692043e962 200
mbed_official 52:27692043e962 201 ### Change Nanostack's heap size
mbed_official 52:27692043e962 202
mbed_official 53:82a191e2c133 203 Nanostack uses internal heap, which can be configured .json. A thread end device with comissioning enabled requires atleast 15kB in order to run.
mbed_official 52:27692043e962 204
mbed_official 53:82a191e2c133 205 In `mbed_app.json` you will find the following line:
mbed_official 52:27692043e962 206 ```
mbed_official 53:82a191e2c133 207 "mbed-mesh-api.heap-size": 15000,
mbed_official 52:27692043e962 208 ```
mbed_official 53:82a191e2c133 209 For 6LoWPAN, you can try 12kB. For smallest memory usage, you should configure node to be in non-routing mode. See [module-configuration](https://github.com/ARMmbed/mbed-os/tree/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api#module-configuration)
mbed_official 52:27692043e962 210
mbed_official 52:27692043e962 211 ### Move Nanostack's heap inside the system heap
mbed_official 52:27692043e962 212
mbed_official 52:27692043e962 213 Nanostack's internal heap can be moved within the system heap.
mbed_official 52:27692043e962 214 This helps on devices which have split RAM and compiler fails to fit statically allocated
mbed_official 52:27692043e962 215 symbols into one section. For example NXP KW24D device.
mbed_official 52:27692043e962 216
mbed_official 52:27692043e962 217 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 218
mbed_official 52:27692043e962 219 Add following line to `mbed_app.json` to test:
mbed_official 52:27692043e962 220 ```
mbed_official 52:27692043e962 221 "mbed-mesh-api.use-malloc-for-heap": true,
mbed_official 52:27692043e962 222 ```
mbed_official 52:27692043e962 223
mbed_official 52:27692043e962 224 ### Use release profile
mbed_official 52:27692043e962 225
mbed_official 52:27692043e962 226 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 227
mbed_official 52:27692043e962 228 Examples:
mbed_official 52:27692043e962 229 ```
mbed_official 52:27692043e962 230 $ mbed export -m KW24D -i make_iar --profile release
mbed_official 52:27692043e962 231 OR
mbed_official 52:27692043e962 232 $ mbed compile -m KW24D -t IAR --profile release
mbed_official 52:27692043e962 233 ```