This application is the simplest one to utilize our mesh networking stack. It just joins your device to the unsecure 6LoWPAN-ND network. The canonical source for this example lives at https://github.com/ARMmbed/mbed-os-example-mesh-minimal

Example mesh application for Mbed OS

With this application, you can use our mesh networking stack. This application joins your device to the unsecure 6LoWPAN-ND network.

Setup

Building with Mbed CLI

If you'd like to use Mbed CLI to build this offline, then you should refer to the Mbed CLI documentation. The instructions here relate to using the Mbed Online Compiler

  1. Click `Import this application` button.
  2. Change the channel settings: See the file `mbed_app.json` for an example of defining an IEEE 802.15.4 channel to use.
  3. Compile the application

A binary is generated at the end of the build process.

Connect the RF shield to the board

By default, we are using the Atmel AT86RF233, which you can purchase. Place the shield on top of your board, and power it on.

Program the target

Drag and drop the binary to the target to program the application.

Update the firmware of the border router.

You can read the instructions on updating the firmware of your board working as 6LoWPAN border router here.

Please remember to connect the Ethernet cable between the border router and your router. Then, power up the board.

Testing

As soon as both the border router and the target are up and running, you can verify the correct behavior. Open a serial console, and see the IP address obtained by the device.

Note: This application uses a baud rate of 115200.

Quote:

connected. IP = 2001:db8:a0b:12f0::1

You can use this IP address to ping from your PC and verify that the connection is working correctly.

Changing the radio driver (optional)

To run a 6LoWPAN-ND network, you need a working RF driver for Nanostack. This example uses the Atmel AT86RF233 by default.

To change the RF driver:

  1. Uninstall the Atmel RF driver.
  2. Install the new driver. (For example, for the FRDM-CR20A radio shield based on the MCR20A device.)
  3. Recompile your application.
Committer:
mbed_official
Date:
Mon Aug 19 14:00:33 2019 +0100
Revision:
128:e7faff9c9fd9
Parent:
126:48203bfdf420
Child:
129:efd4642eb943
Merge branch 'mbed-os-5.13'

* mbed-os-5.13:
Updating mbed-os to mbed-os-5.13.3 (#275)
Update mesh_minimal_startup.py
Updating mbed-os to mbed-os-5.13.2 (#274)

.
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 106:18f64141d066 3 With this application, you can use the [mesh networking API](https://os.mbed.com/docs/latest/apis/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 121:dd070767f365 6 The application can be built for the unsecure 6LoWPAN-ND, Thread or Wi-SUN network.
Seppo Takalo 0:bde1843b9885 7
mbed_official 121:dd070767f365 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 and Wi-SUN protocols.
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 121:dd070767f365 31 - Wi-SUN
mbed_official 19:f55c7983f8ab 32
mbed_official 19:f55c7983f8ab 33 Select the device role:
mbed_official 19:f55c7983f8ab 34
mbed_official 19:f55c7983f8ab 35 - Mesh network. A router. (default)
mbed_official 68:2330fbeb4926 36 - Star network. Nonrouting device. Also known as a host or sleepy host.
mbed_official 68:2330fbeb4926 37
mbed_official 106:18f64141d066 38 Modify your `mbed_app.json` file to see which Nanostack and [Mbed Mesh API](https://os.mbed.com/docs/latest/apis/mesh-api.html) configuration to use.
mbed_official 19:f55c7983f8ab 39
mbed_official 68:2330fbeb4926 40 Example configuration files are provide under `configs/` directory. You may override the `mbed_app.json` with either of these.
mbed_official 68:2330fbeb4926 41
mbed_official 68:2330fbeb4926 42 |configuration file|Use for|
mbed_official 68:2330fbeb4926 43 |------------------|-------|
mbed_official 68:2330fbeb4926 44 |`configs/mesh_6lowpan.json` | 6LoWPAN-ND based mesh network. |
mbed_official 68:2330fbeb4926 45 |`configs/mesh_thread.json` | Thread based mesh network. |
mbed_official 121:dd070767f365 46 |`configs/mesh_wisun_S2LP.json` | Wi-SUN based mesh network. |
mbed_official 19:f55c7983f8ab 47
mbed_official 19:f55c7983f8ab 48 An example of the `mbed_app.json` file:
mbed_official 19:f55c7983f8ab 49
mbed_official 19:f55c7983f8ab 50 ```
mbed_official 19:f55c7983f8ab 51 ...
mbed_official 19:f55c7983f8ab 52 "target_overrides": {
mbed_official 19:f55c7983f8ab 53 "*": {
mbed_official 68:2330fbeb4926 54 "nanostack.configuration": "lowpan_router",
mbed_official 116:b2f0131722a0 55 "nsapi.default-mesh-type": "LOWPAN",
mbed_official 116:b2f0131722a0 56 "mbed-mesh-api.6lowpan-nd-panid-filter": "0xffff",
mbed_official 116:b2f0131722a0 57 "mbed-mesh-api.6lowpan-nd-channel-page": 0,
mbed_official 116:b2f0131722a0 58 "mbed-mesh-api.6lowpan-nd-channel": 12,
mbed_official 116:b2f0131722a0 59 "mbed-mesh-api.6lowpan-nd-channel-mask": "(1<<12)",
mbed_official 116:b2f0131722a0 60 "mbed-mesh-api.heap-size": 14000,
mbed_official 116:b2f0131722a0 61 "mbed-trace.enable": false,
mbed_official 116:b2f0131722a0 62 "platform.stdio-convert-newlines": true,
mbed_official 116:b2f0131722a0 63 "platform.stdio-baud-rate": 115200,
mbed_official 116:b2f0131722a0 64 "atmel-rf.provide-default": true,
mbed_official 116:b2f0131722a0 65 "mcr20a.provide-default": false,
mbed_official 116:b2f0131722a0 66 "target.device_has_add": ["802_15_4_PHY"],
mbed_official 116:b2f0131722a0 67 "target.network-default-interface-type": "MESH"
mbed_official 116:b2f0131722a0 68 },
mbed_official 19:f55c7983f8ab 69 ```
mbed_official 19:f55c7983f8ab 70
mbed_official 68:2330fbeb4926 71 The following tables show the values to use in the `mbed_app.json` file for your devices in different networks.
mbed_official 19:f55c7983f8ab 72
mbed_official 116:b2f0131722a0 73 - For a 6LoWPAN-ND based network, use `nsapi.default-mesh-type: LOWPAN`.
mbed_official 116:b2f0131722a0 74 - For a Thread-based network, use `nsapi.default-mesh-type: THREAD`.
mbed_official 121:dd070767f365 75 - For a Wi-SUN-based network, use `nsapi.default-mesh-type: WISUN`.
mbed_official 19:f55c7983f8ab 76
mbed_official 52:27692043e962 77 #### 6LoWPAN-ND
mbed_official 52:27692043e962 78
mbed_official 116:b2f0131722a0 79 **nsapi.default-mesh-type: LOWPAN**
mbed_official 19:f55c7983f8ab 80
mbed_official 116:b2f0131722a0 81 |Device role|`nanostack.configuration` value|`mbed-mesh-api.6lowpan-nd-device-type` value|
mbed_official 19:f55c7983f8ab 82 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 83 |Mesh router (default) | lowpan_router | NET_6LOWPAN_ROUTER |
mbed_official 68:2330fbeb4926 84 |Nonrouting device | lowpan_host | NET_6LOWPAN_HOST |
mbed_official 19:f55c7983f8ab 85
mbed_official 52:27692043e962 86 #### Thread
mbed_official 52:27692043e962 87
mbed_official 116:b2f0131722a0 88 **nsapi.default-mesh-type: THREAD**
mbed_official 19:f55c7983f8ab 89
mbed_official 116:b2f0131722a0 90 |Device role|`nanostack.configuration` value|`mbed-mesh-api.thread-device-type` value|
mbed_official 19:f55c7983f8ab 91 |-----------|-------------------------|------------------------------------|
mbed_official 66:30f2c1317e6d 92 |Mesh router (default) | thread_router | MESH_DEVICE_TYPE_THREAD_ROUTER |
mbed_official 68:2330fbeb4926 93 |Nonrouting device | thread_end_device | MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE |
mbed_official 19:f55c7983f8ab 94
mbed_official 52:27692043e962 95 ##### Thread commissioning
mbed_official 52:27692043e962 96
mbed_official 87:a6a7b64f4f48 97 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 126:48203bfdf420 98 If you want to commission a Thread device, see [how to commission a Thread device in practice](https://os.mbed.com/docs/mbed-os/latest/reference/thread-tech.html#thread-commissioning).
mbed_official 78:fc7a81fd524c 99
mbed_official 78:fc7a81fd524c 100 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 101
mbed_official 116:b2f0131722a0 102 - Change `storage-device` to `MESH_NVM_SD_CARD` in the `./configs/mesh_thread.json` file.
mbed_official 78:fc7a81fd524c 103 - Enable commissioning as descibed in the referred instructions.
mbed_official 78:fc7a81fd524c 104 - Compile and program the application.
mbed_official 87:a6a7b64f4f48 105 - 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 106 - Commission the device to the Thread network.
mbed_official 78:fc7a81fd524c 107 - 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 108
mbed_official 121:dd070767f365 109 #### Wi-SUN
mbed_official 121:dd070767f365 110
mbed_official 121:dd070767f365 111 **nsapi.default-mesh-type: WISUN**
mbed_official 121:dd070767f365 112
mbed_official 121:dd070767f365 113 |Device role|`nanostack.configuration` value|
mbed_official 121:dd070767f365 114 |-----------|-------------------------|
mbed_official 121:dd070767f365 115 |Mesh router (default) | ws_router |
mbed_official 121:dd070767f365 116
mbed_official 121:dd070767f365 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 121:dd070767f365 133 To change the RF driver modify the `mbed_app.json` file by setting preferred RF driver `provide_default` value to true, For example, to use MCR20a RF driver:
mbed_official 68:2330fbeb4926 134
mbed_official 68:2330fbeb4926 135 ```json
mbed_official 116:b2f0131722a0 136 "atmel-rf.provide-default": false,
mbed_official 116:b2f0131722a0 137 "mcr20a.provide-default": true,
mbed_official 68:2330fbeb4926 138 ```
mbed_official 68:2330fbeb4926 139
mbed_official 121:dd070767f365 140 To run a Wi-SUN network, there is currently only one supported Radio, STM S2LP.
mbed_official 121:dd070767f365 141
mbed_official 121:dd070767f365 142 To use the S2LP, modify the `mbed_app.json` file by setting:
mbed_official 121:dd070767f365 143
mbed_official 121:dd070767f365 144 ```json
mbed_official 121:dd070767f365 145 "s2lp.provide-default": true,
mbed_official 121:dd070767f365 146 ```
mbed_official 121:dd070767f365 147
mbed_official 121:dd070767f365 148 Note that the provide-default for each radio driver defaults to false, so there is no need to list all the possible drivers in the `mbed_app.json`.
mbed_official 121:dd070767f365 149
Seppo Takalo 0:bde1843b9885 150 ### Compile the application
Seppo Takalo 0:bde1843b9885 151
Seppo Takalo 0:bde1843b9885 152 ```
mbed_official 68:2330fbeb4926 153 mbed compile -m K64F -t GCC_ARM
Seppo Takalo 0:bde1843b9885 154 ```
Seppo Takalo 0:bde1843b9885 155
mbed_official 52:27692043e962 156 A binary is generated in the end of the build process.
Seppo Takalo 0:bde1843b9885 157
Seppo Takalo 0:bde1843b9885 158 ### Connect the RF shield to the board
Seppo Takalo 0:bde1843b9885 159
mbed_official 68:2330fbeb4926 160 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 161
Seppo Takalo 0:bde1843b9885 162 ### Program the target
Seppo Takalo 0:bde1843b9885 163
Seppo Takalo 0:bde1843b9885 164 Drag and drop the binary to the target to program the application.
Seppo Takalo 0:bde1843b9885 165
Seppo Takalo 0:bde1843b9885 166 ### Update the firmware of the border router
Seppo Takalo 0:bde1843b9885 167
mbed_official 55:63aa128e8a80 168 This example supports the following border router:
Seppo Takalo 0:bde1843b9885 169
mbed_official 68:2330fbeb4926 170 - [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router).
mbed_official 52:27692043e962 171
mbed_official 68:2330fbeb4926 172 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 173
mbed_official 68:2330fbeb4926 174 Remember to connect the Ethernet cable between the border router and your home/office router. Then power on the board.
Seppo Takalo 0:bde1843b9885 175
Seppo Takalo 0:bde1843b9885 176 ## Testing
Seppo Takalo 0:bde1843b9885 177
mbed_official 52:27692043e962 178 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 179
Seppo Takalo 0:bde1843b9885 180 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 181
mbed_official 13:4a0466077538 182 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
Seppo Takalo 0:bde1843b9885 183
Seppo Takalo 0:bde1843b9885 184 ```
Seppo Takalo 0:bde1843b9885 185 connected. IP = 2001:db8:a0b:12f0::1
Seppo Takalo 0:bde1843b9885 186 ```
Seppo Takalo 0:bde1843b9885 187
Seppo Takalo 0:bde1843b9885 188 You can use this IP address to `ping` from your PC and verify that the connection is working correctly.
Seppo Takalo 0:bde1843b9885 189
mbed_official 52:27692043e962 190
mbed_official 52:27692043e962 191 ## Memory optimizations
mbed_official 52:27692043e962 192
mbed_official 52:27692043e962 193 On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
mbed_official 52:27692043e962 194 In those cases, you might try following these instructions to optimize the memory usage.
mbed_official 52:27692043e962 195
mbed_official 68:2330fbeb4926 196 ### Mbed TLS configuration
mbed_official 52:27692043e962 197
mbed_official 68:2330fbeb4926 198 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 199
mbed_official 52:27692043e962 200 This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
mbed_official 52:27692043e962 201
mbed_official 68:2330fbeb4926 202 ### Disabling the LED control example
mbed_official 52:27692043e962 203
mbed_official 68:2330fbeb4926 204 You can disable the LED control example by specifying `enable-led-control-example": false` in the `mbed_app.json`
mbed_official 52:27692043e962 205
mbed_official 68:2330fbeb4926 206 This saves you about 2.5 kB of flash.
mbed_official 52:27692043e962 207
mbed_official 52:27692043e962 208 ### Change network stack's event loop stack size
mbed_official 52:27692043e962 209
mbed_official 68:2330fbeb4926 210 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 211 In case client functionality is not used, you can define the following to use 2kB of stack
mbed_official 52:27692043e962 212
mbed_official 52:27692043e962 213 `"nanostack-hal.event_loop_thread_stack_size": 2048`
mbed_official 52:27692043e962 214
mbed_official 68:2330fbeb4926 215 This saves you 4kB of RAM.
mbed_official 52:27692043e962 216
mbed_official 52:27692043e962 217 ### Change Nanostack's heap size
mbed_official 52:27692043e962 218
mbed_official 68:2330fbeb4926 219 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 220
mbed_official 68:2330fbeb4926 221 In `mbed_app.json`, you find the following line:
mbed_official 68:2330fbeb4926 222
mbed_official 52:27692043e962 223 ```
mbed_official 53:82a191e2c133 224 "mbed-mesh-api.heap-size": 15000,
mbed_official 52:27692043e962 225 ```
mbed_official 68:2330fbeb4926 226
mbed_official 68:2330fbeb4926 227 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 228
mbed_official 52:27692043e962 229 ### Move Nanostack's heap inside the system heap
mbed_official 52:27692043e962 230
mbed_official 52:27692043e962 231 Nanostack's internal heap can be moved within the system heap.
mbed_official 68:2330fbeb4926 232 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 233
mbed_official 68:2330fbeb4926 234 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 235
mbed_official 68:2330fbeb4926 236 Add the following line to `mbed_app.json` to test:
mbed_official 68:2330fbeb4926 237
mbed_official 52:27692043e962 238 ```
mbed_official 52:27692043e962 239 "mbed-mesh-api.use-malloc-for-heap": true,
mbed_official 52:27692043e962 240 ```
mbed_official 52:27692043e962 241
mbed_official 52:27692043e962 242 ### Use release profile
mbed_official 52:27692043e962 243
mbed_official 68:2330fbeb4926 244 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 245
mbed_official 52:27692043e962 246 Examples:
mbed_official 68:2330fbeb4926 247
mbed_official 52:27692043e962 248 ```
mbed_official 52:27692043e962 249 $ mbed export -m KW24D -i make_iar --profile release
mbed_official 52:27692043e962 250 OR
mbed_official 52:27692043e962 251 $ mbed compile -m KW24D -t IAR --profile release
mbed_official 52:27692043e962 252 ```
mbed_official 68:2330fbeb4926 253
mbed_official 68:2330fbeb4926 254 ## Troubleshooting
mbed_official 68:2330fbeb4926 255
mbed_official 68:2330fbeb4926 256 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 257