Diff: README.md

Revision:

52:27692043e962

Parent:

49:425a1889434d

Child:

53:82a191e2c133

--- a/README.md	Fri Mar 10 19:15:11 2017 +0000
+++ b/README.md	Wed Sep 20 12:17:51 2017 +0100
@@ -1,6 +1,7 @@
 # Example mesh application for mbed OS
 
-This application is the simplest one to utilize our mesh networking stack. It just joins your device to the unsecure *6LoWPAN-ND* network.
+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.
+The application can be built for the unsecure 6LoWPAN-ND or Thread network.
 
 ## Setup
 
@@ -58,6 +59,8 @@
 - For 6LoWPAN-ND based network use `mesh-type: MESH_LOWPAN`.
 - For Thread based network use `mesh-type: MESH_THREAD`.
 
+#### 6LoWPAN-ND
+
 **mesh-type: MESH_LOWPAN**
 
 |Device role|`target.features_add` value|`mbed-mesh-api.6lowpan-nd-device-type`|
@@ -65,6 +68,8 @@
 |Mesh router (default) | LOWPAN_ROUTER | NET_6LOWPAN_ROUTER |
 |Non routing device | LOWPAN_HOST | NET_6LOWPAN_HOST |
 
+#### Thread
+
 **mesh-type: MESH_THREAD**
 
 |Device role|`target.features_add` value|`mbed-mesh-api.thread-device-type`|
@@ -72,7 +77,13 @@
 |Mesh router (default) | THREAD_ROUTER | MESH_DEVICE_TYPE_THREAD_ROUTER |
 |Non routing device | THREAD_END_DEVICE | MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE |
 
-**Note:** You need to recompile your application after modifying the configurations by issuing the command `mbed compile -c`.
+##### Thread commissioning
+
+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).
+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-mesh-api.thread-use-static-link-config": false`
+* `"macros": ["MBEDTLS_USER_CONFIG_FILE=\"mbedtls_config.h\""]`
 
 ### Requirements for hardware
 
@@ -83,6 +94,8 @@
 
 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.
 
+You also need to check how LEDs and buttons are configured for your hardware, and update .json accordingly.
+
 ### Compile the application
 
 #### For 6LoWPAN
@@ -96,7 +109,7 @@
 mbed compile -m K64F -t GCC_ARM --app-config configs/mesh_thread.json
 ```
 
-A binary is generated at the end of the build process.
+A binary is generated in the end of the build process.
 
 ### Connect the RF shield to the board
 
@@ -110,9 +123,9 @@
 
 This example supports the following two border routers:
 
-- [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router-private), 6LoWPAN only
+- [Nanostack-border-router](https://github.com/ARMmbed/nanostack-border-router)
 - [mbed gateway](https://firefly-iot.com/product/firefly-6lowpan-gateway-2-4ghz/)
- 
+
 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).
 
 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.
@@ -121,6 +134,8 @@
 
 ## Testing
 
+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.
+
 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.
 
 <span class="notes">**Note:** This application uses the baud rate of 115200.</span>
@@ -133,7 +148,7 @@
 
 ### 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 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:
 
@@ -157,3 +172,67 @@
             "value": "ATMEL"
         },
 ```
+
+## Memory optimizations
+
+On some limited platforms, for example NCS36510 or KW24D, building this application might run out of RAM or ROM.
+In those cases, you might try following these instructions to optimize the memory usage.
+
+### mbed TLS configuration
+
+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.
+
+This configuration file saves you 8.7 kB of RAM but uses 6.8 kB of more flash.
+
+### Disabling the Led control example
+
+The led control example can be disabled by specifying `enable-led-control-example": false` in the `mbed_app.json`
+
+This will save you about 2.5 kB of flash.
+
+### Change network stack's event loop stack size
+
+Nanostack's internal event-loop is shared with mbed Client and is therefore
+requiring lots of stack to complete the security hanshakes using TLS protocols.
+In case client functionality is not used, following can be defined to use 2kB of stack
+
+`"nanostack-hal.event_loop_thread_stack_size": 2048`
+
+This will save you 4kB of RAM.
+
+### Change Nanostack's heap size
+
+Nanostack uses internal heap and requires minimum of 14kB in order to run on Thread network where comissioning is enabled.
+When running on different mesh configurations, it might be able to operate on smaller heap.
+
+In `mbed_app.json` you will find following line:
+```
+"mbed-mesh-api.heap-size": 14000,
+```
+That specifies that 14kB to be used for Nanostack's heap.
+
+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
+
+### Move Nanostack's heap inside the system heap
+
+Nanostack's internal heap can be moved within the system heap.
+This helps on devices which have split RAM and compiler fails to fit statically allocated
+symbols into one section. For example NXP KW24D device.
+
+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.
+
+Add following line to `mbed_app.json` to test:
+```
+"mbed-mesh-api.use-malloc-for-heap": true,
+```
+
+### Use release profile
+
+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/)
+
+Examples:
+```
+$ mbed export -m KW24D -i make_iar --profile release
+OR
+$ mbed compile -m KW24D -t IAR --profile release
+```