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@87:a6a7b64f4f48, 2018-06-18 (annotated)

Committer:
mbed_official
Date:
Mon Jun 18 09:15:17 2018 +0100
Revision:
87:a6a7b64f4f48
Parent:
85:7c874d127eff
Child:
91:6effd7785401
Merge remote-tracking branch 'origin/mbed-os-5.9.0-oob'



* origin/mbed-os-5.9.0-oob:

  Update SD Card usage instructions to README (#194)

  Updating mbed-os to mbed-os-5.9.0-rc3

  Ensure Nanostack is initialised before using it (#192)

  Added known issue re: NVM. Added links to issues in known issues list

  Fixed broken links and added known issue for Mbed OS 5.9

  Updating mbed-os to mbed-os-5.9.0-rc2

  Updating mbed-os to mbed-os-5.9.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 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
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 87:a6a7b64f4f48 37 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 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 87:a6a7b64f4f48 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/mbed-mesh-api/mbed_lib.json).
mbed_official 85:7c874d127eff 93 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 94
mbed_official 78:fc7a81fd524c 95 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 96
mbed_official 78:fc7a81fd524c 97 - Change `storage-device` to `MESH_SD_CARD` in the `./configs/mesh_thread.json` file.
mbed_official 78:fc7a81fd524c 98 - Enable commissioning as descibed in the referred instructions.
mbed_official 78:fc7a81fd524c 99 - Compile and program the application.
mbed_official 87:a6a7b64f4f48 100 - 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 101 - Commission the device to the Thread network.
mbed_official 78:fc7a81fd524c 102 - 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 103
mbed_official 19:f55c7983f8ab 104 ### Requirements for hardware
mbed_official 19:f55c7983f8ab 105
mbed_official 68:2330fbeb4926 106 The networking stack used in this example requires TLS functionality to be enabled on Mbed TLS.
mbed_official 68:2330fbeb4926 107 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 108
mbed_official 85:7c874d127eff 109 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 110
mbed_official 49:425a1889434d 111 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 112
mbed_official 52:27692043e962 113 You also need to check how LEDs and buttons are configured for your hardware, and update .json accordingly.
mbed_official 52:27692043e962 114
mbed_official 68:2330fbeb4926 115 ### Changing the radio driver
mbed_official 68:2330fbeb4926 116
mbed_official 68:2330fbeb4926 117 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 118
mbed_official 68:2330fbeb4926 119 To change the RF driver modify the `mbed_app.json` file. For example,
mbed_official 68:2330fbeb4926 120
mbed_official 68:2330fbeb4926 121 ```json
mbed_official 68:2330fbeb4926 122 "radio-type":{
mbed_official 68:2330fbeb4926 123 "help": "options are ATMEL, MCR20, NCS36510, KW24D",
mbed_official 68:2330fbeb4926 124 "value": "ATMEL"
mbed_official 68:2330fbeb4926 125 },
mbed_official 68:2330fbeb4926 126 ```
mbed_official 68:2330fbeb4926 127
Seppo Takalo 0:bde1843b9885 128 ### Compile the application
Seppo Takalo 0:bde1843b9885 129
Seppo Takalo 0:bde1843b9885 130 ```
mbed_official 68:2330fbeb4926 131 mbed compile -m K64F -t GCC_ARM
Seppo Takalo 0:bde1843b9885 132 ```
Seppo Takalo 0:bde1843b9885 133
mbed_official 52:27692043e962 134 A binary is generated in the end of the build process.
Seppo Takalo 0:bde1843b9885 135
Seppo Takalo 0:bde1843b9885 136 ### Connect the RF shield to the board
Seppo Takalo 0:bde1843b9885 137
mbed_official 68:2330fbeb4926 138 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 139
Seppo Takalo 0:bde1843b9885 140 ### Program the target
Seppo Takalo 0:bde1843b9885 141
Seppo Takalo 0:bde1843b9885 142 Drag and drop the binary to the target to program the application.
Seppo Takalo 0:bde1843b9885 143
Seppo Takalo 0:bde1843b9885 144 ### Update the firmware of the border router
Seppo Takalo 0:bde1843b9885 145
mbed_official 55:63aa128e8a80 146 This example supports the following border router:
Seppo Takalo 0:bde1843b9885 147
mbed_official 68:2330fbeb4926 148 - [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router).
mbed_official 52:27692043e962 149
mbed_official 68:2330fbeb4926 150 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 151
mbed_official 68:2330fbeb4926 152 Remember to connect the Ethernet cable between the border router and your home/office router. Then power on the board.
Seppo Takalo 0:bde1843b9885 153
Seppo Takalo 0:bde1843b9885 154 ## Testing
Seppo Takalo 0:bde1843b9885 155
mbed_official 52:27692043e962 156 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 157
Seppo Takalo 0:bde1843b9885 158 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 159
mbed_official 13:4a0466077538 160 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
Seppo Takalo 0:bde1843b9885 161
Seppo Takalo 0:bde1843b9885 162 ```
Seppo Takalo 0:bde1843b9885 163 connected. IP = 2001:db8:a0b:12f0::1
Seppo Takalo 0:bde1843b9885 164 ```
Seppo Takalo 0:bde1843b9885 165
Seppo Takalo 0:bde1843b9885 166 You can use this IP address to `ping` from your PC and verify that the connection is working correctly.
Seppo Takalo 0:bde1843b9885 167
mbed_official 52:27692043e962 168
mbed_official 52:27692043e962 169 ## Memory optimizations
mbed_official 52:27692043e962 170
mbed_official 52:27692043e962 171 On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
mbed_official 52:27692043e962 172 In those cases, you might try following these instructions to optimize the memory usage.
mbed_official 52:27692043e962 173
mbed_official 68:2330fbeb4926 174 ### Mbed TLS configuration
mbed_official 52:27692043e962 175
mbed_official 68:2330fbeb4926 176 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 177
mbed_official 52:27692043e962 178 This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
mbed_official 52:27692043e962 179
mbed_official 68:2330fbeb4926 180 ### Disabling the LED control example
mbed_official 52:27692043e962 181
mbed_official 68:2330fbeb4926 182 You can disable the LED control example by specifying `enable-led-control-example": false` in the `mbed_app.json`
mbed_official 52:27692043e962 183
mbed_official 68:2330fbeb4926 184 This saves you about 2.5 kB of flash.
mbed_official 52:27692043e962 185
mbed_official 52:27692043e962 186 ### Change network stack's event loop stack size
mbed_official 52:27692043e962 187
mbed_official 68:2330fbeb4926 188 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 189 In case client functionality is not used, you can define the following to use 2kB of stack
mbed_official 52:27692043e962 190
mbed_official 52:27692043e962 191 `"nanostack-hal.event_loop_thread_stack_size": 2048`
mbed_official 52:27692043e962 192
mbed_official 68:2330fbeb4926 193 This saves you 4kB of RAM.
mbed_official 52:27692043e962 194
mbed_official 52:27692043e962 195 ### Change Nanostack's heap size
mbed_official 52:27692043e962 196
mbed_official 68:2330fbeb4926 197 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 198
mbed_official 68:2330fbeb4926 199 In `mbed_app.json`, you find the following line:
mbed_official 68:2330fbeb4926 200
mbed_official 52:27692043e962 201 ```
mbed_official 53:82a191e2c133 202 "mbed-mesh-api.heap-size": 15000,
mbed_official 52:27692043e962 203 ```
mbed_official 68:2330fbeb4926 204
mbed_official 68:2330fbeb4926 205 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 206
mbed_official 52:27692043e962 207 ### Move Nanostack's heap inside the system heap
mbed_official 52:27692043e962 208
mbed_official 52:27692043e962 209 Nanostack's internal heap can be moved within the system heap.
mbed_official 68:2330fbeb4926 210 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 211
mbed_official 68:2330fbeb4926 212 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 213
mbed_official 68:2330fbeb4926 214 Add the following line to `mbed_app.json` to test:
mbed_official 68:2330fbeb4926 215
mbed_official 52:27692043e962 216 ```
mbed_official 52:27692043e962 217 "mbed-mesh-api.use-malloc-for-heap": true,
mbed_official 52:27692043e962 218 ```
mbed_official 52:27692043e962 219
mbed_official 52:27692043e962 220 ### Use release profile
mbed_official 52:27692043e962 221
mbed_official 68:2330fbeb4926 222 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 223
mbed_official 52:27692043e962 224 Examples:
mbed_official 68:2330fbeb4926 225
mbed_official 52:27692043e962 226 ```
mbed_official 52:27692043e962 227 $ mbed export -m KW24D -i make_iar --profile release
mbed_official 52:27692043e962 228 OR
mbed_official 52:27692043e962 229 $ mbed compile -m KW24D -t IAR --profile release
mbed_official 52:27692043e962 230 ```
mbed_official 68:2330fbeb4926 231
mbed_official 68:2330fbeb4926 232 ## Troubleshooting
mbed_official 68:2330fbeb4926 233
mbed_official 68:2330fbeb4926 234 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 235
mbed_official 87:a6a7b64f4f48 236 ## Known issues
mbed_official 87:a6a7b64f4f48 237
mbed_official 87:a6a7b64f4f48 238 1. https://github.com/ARMmbed/mbed-os-example-mesh-minimal/issues/188
mbed_official 87:a6a7b64f4f48 239
mbed_official 87:a6a7b64f4f48 240 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 241 ```
mbed_official 87:a6a7b64f4f48 242 uint8_t eui64[8] = {0,0,0,0,0,0,0,0};
mbed_official 87:a6a7b64f4f48 243 mesh.device_eui64_get(eui64);
mbed_official 87:a6a7b64f4f48 244 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 245 ```
mbed_official 87:a6a7b64f4f48 246 The issue will be fixed in Mbed OS 5.9.1 and printing the EUI64 separately will become unnecessary.
mbed_official 87:a6a7b64f4f48 247
mbed_official 87:a6a7b64f4f48 248 1. https://github.com/ARMmbed/mbed-os-example-mesh-minimal/issues/190
mbed_official 87:a6a7b64f4f48 249
mbed_official 87:a6a7b64f4f48 250 Thread is not able to use filesystem at the moment. Saving configuration to NVM is unavailable.