Nanostack configuration options added

docs/tutorials/using_apis/mesh/quick_start_build.md

@@ -1,9 +1,11 @@
-### Build time configuration of the stack
+### Build time configuration of the Nanostack
 
-To minimize the size of the produced stack, Nanostack defines a set of build options.
+The build time configuration of Nanostack uses the Mbed configuration system. The application needs to create an `mbed_app.json` configuration file if you want to use settings other than default settings. You can also minimize the size of the produced stack by using different build options.
 
 #### Build options
 
+This table demonstrate the difference in binary size between builds:
+
 Option Name | Features supported | Binary size in Mbed OS 5.5
 ------------| -------------------|------------------------------------
 `ethernet_host` | Only Ethernet host support, no mesh networking. | 108 kB
@@ -33,7 +35,7 @@ Select the device role:
 - Mesh network. A router. (default)
 - Star network. A non-routing device. Also known as a host, or sleepy host.
 
-Modify your `mbed_app.json` file to tell which Nanostack configuration to choose and which configrations to use on [Mbed Mesh API](/docs/v5.6/reference/mesh.html).
+Modify your `mbed_app.json` file to direct which Nanostack configuration to choose. The [Mbed Mesh API](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/mbed_lib.json) lists all configurations (6LoWPAN and Thread).
 
 An example of the `mbed_app.json` file:
 
@@ -74,3 +76,48 @@ Then you may optionally choose to select the non-routing mode for those networks
 |Mesh router (default) | `thread_router` | `MESH_DEVICE_TYPE_THREAD_ROUTER` |
 |Non-routing device | `thread_end_device` | `MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE` |
 
+##### Configuration parameters for 6LoWPAN-ND and Thread
+
+All 6LoWPAN and Thread configuration options are described below.
+Make sure that all your devices use the same network configuration (both nodes and border router)
+
+```
+
+**Configurable parameters in the `mbed-mesh-api` section**
+
+| Parameter name  | Value         | Description |
+| --------------- | ------------- | ----------- |
+| `heap-size`       | number [0-0xfffe] | Nanostack's internal heap size |
+
+**Thread related configuration parameters**
+
+| Parameter name  | Value         | Description |
+| --------------- | ------------- | ----------- |
+| `thread-pskd`     | string [6-255 chars] | Human-scaled commissioning credentials. |
+| `thread-use-static-link-config` | boolean | True: Use the below link config, False: Use commissioning, ignore the below link config. |
+| `thread-device-type` | enum from `mesh_device_type_t` | Supported device operating modes:<br> `MESH_DEVICE_TYPE_THREAD_ROUTER`<br> `MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE`<br> `MESH_DEVICE_TYPE_THREAD_MINIMAL_END_DEVICE` |
+| `thread-config-channel-mask` | number [0-0x07fff800] | Channel mask, 0x07fff800 is used for Thread networks (2.4GHz). |
+| `thread-config-channel-page` | number [0]| Channel page, 0 for 2,4 GHz radio. |
+| `thread-config-channel`      | number [11-26] | RF channel to use. |
+| `thread-config-panid`        | number [0-0xFFFF] | Network identifier. |
+| `thread-config-network-name` | string [1-16] |
+| `thread-config-commissioning-dataset-timestamp` | [0-0xFFFFFFFFFFFFFFFF] | [48 bit timestamp seconds]-[15 bit timestamp ticks]-[U bit] |
+| `thread-config-extended-panid` | byte array [8] | Extended PAN ID. |
+| `thread-master-key`      | byte array [16]| Network master key. |
+| `thread-config-ml-prefix` | byte array [8] | Mesh local prefix. Should follow the FD00::/8 prefix format  |
+| `thread-config-pskc`      | byte array [16] | Pre-Shared Key for the Commissioner. |
+| `thread-security-policy` | number [0-0xFF] | Commissioning security policy bits. |
+
+**6LoWPAN related configuration parameters**
+
+| Parameter name  | Type     | Description |
+| --------------- | ---------| ----------- |
+| `6lowpan-nd-channel-mask`    | number [0-0x07fff800] | Channel mask, bit-mask of channels to use. |
+| `6lowpan-nd-channel-page`   | number [0, 2] | 0 for 2,4 GHz and 2 for sub-GHz radios. |
+| `6lowpan-nd-channel`        | number [0-26] | RF channel to use when `channel_mask` is not defined. |
+| `6lowpan-nd-panid-filter` | number [0-0xffff] | Beacon PAN ID filter, 0xffff means no filtering. |
+| `6lowpan-nd-security-mode` | "NONE" or "PSK" | To use either no security, or Pre shared network key. |
+| `6lowpan-nd-psk-key-id` | number | PSK key ID when PSK is enabled. |
+| `6lowpan-nd-psk-key` | byte array [16] | Pre-Shared network key. |
+| `6lowpan-nd-sec-level` | number [1-7] | Network security level. Use default `5`. |
+| `6lowpan-nd-device-type` | "NET_6LOWPAN_ROUTER" or "NET_6LOWPAN_HOST" | Device mode. Router is routing packets from other device, creating a mesh network. |

docs/tutorials/using_apis/mesh/thread_commissioning.md

@@ -44,6 +44,8 @@ To get the MAC address for your end device, connect the node to the Thread netwo
 
 For example, in the **mesh-minimal** application, place this `printf("MAC address = %s\n", mesh.get_mac_address());` after `printf("connected. IP = %s\n", mesh.get_ip_address());`
 
+It is also possible to use the Mesh API (ThreadInterface.h) to set values for these parameters.
+
 There are four additional (optional) query parameters you can put into this field:
 
 - `vn`    Vendor name.
@@ -55,6 +57,8 @@ Once you have completed the details, proceed to generate the QR code for your en
 
 #### Using the Thread commissioning application
 
+When building a Thread example application, do not change any of the PSKc related parameters (network name, extended PAN ID or PSKc). PSKc has been precalculated for the application. `Thread Network` is the network password that is required by the commissioning application to commission the mbed Thread examples.
+
 You can use the [Thread Android application](https://play.google.com/store/apps/details?id=org.threadgroup.commissioner) for commissioning. Download and install this on your Android device, turn on Wi-Fi and start the app. Then follow these steps after ensuring all the requirements listed above are satisfied:
 
 1. Set up a connection to the Wi-Fi access point to which the Thread border router is connected. When connected, the application lists your Thread border router(s).

docs/tutorials/using_apis/mesh/thread_intro.md

@@ -36,14 +36,16 @@ Mbed Thread is implemented in the Nanostack library, which also supports the 6Lo
 - To connect to the Thread network, use the [Thread interface API](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/mbed-mesh-api/ThreadInterface.h).
 - For the socket communication over the Thread network, use the [Mbed sockets API](/docs/v5.7/reference/network-socket.html).
 
-Nanostack provides a set of C API headers with more functionalities. The [nanostack repository](https://github.com/ARMmbed/mbed-os/tree/master/features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack) has the following header files():
+Nanostack provides a set of C API headers with more functionalities. The [Nanostack repository](https://github.com/ARMmbed/mbed-os/tree/master/features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack) has the following header files():
 
 - `thread_management_if.h` for initializing the stack and managing the network data.
 - `thread_commissioning_api.h` for implementing an on-mesh or a native Thread commissioner.
 - `thread_border_router_api.h` for implementing a Thread border router.
 - `thread_diagcop_lib.h` for building and parsing the Thread diagnostics protocol TLV messages.
 - `thread_meshcop_lib.h` for building and parsing the Thread mesh commissioning protocol TLV messages.
 - `thread_net_config_api.h` for making neighbour discovery (ND) data requests.
+- `net_polling_api.h` for configuring the Thread node's sleep mode and polling interval.
+- `net_interface.h` for configuring and controlling the nanostack.
 
 #### Thread devices you can build on Mbed OS
 
@@ -55,9 +57,9 @@ The Mbed OS Mesh API allows you to define 3 types of devices:
 
 In addition the Nanostack API allows you to define the Full end device (FED) device type.
 
-In most cases, the REED, MED and SED configurations are enough to build a network. In a SED device, the radio is switched off during the sleep times. To take the full advantage of the SED configuration, the application developer must implement the sleep procedures in the device.
+In most cases, the REED, MED and SED configurations are enough to build a network.
 
-For an end device or a router example, see [mesh minimal example](https://github.com/ARMmbed/mbed-os-example-mesh-minimal).
+For an end device or a router example, see the [mesh minimal example](https://github.com/ARMmbed/mbed-os-example-mesh-minimal).
 
 #### End devices
 
@@ -122,6 +124,8 @@ The Thread network name and the extended PAN ID are received in the scanning pha
 
 After the authentication phase, the commissioner requests the Thread network leader to petition the commissioner to become an authorized commissioner. Here, the border router works as an arbitrator in the middle.
 
+The Thread specification describes the PSKc generation.
+
 Now, the Thread network is ready to accept new joiner devices.
 
 1. The commissioner application scans the QR code, which is PSKd (Pre-Shared Key for device) + EUI64, from the device's label and informs the Thread network that this device is accepted to the network.
@@ -132,12 +136,72 @@ Now, the Thread network is ready to accept new joiner devices.
 
 <span class="notes">**Note:** Thread uses hashing and elliptic curve algorithms for the secure communication. PSKd(s) and EUI64(s) are never transmitted in plain text over the peer to peer connection.</span>
 
-#### How to start on Mbed OS
+##### How to start on Mbed OS
 
 The Mbed OS Thread stack supports all three types of commissioners. You can create an external commissioner application by using the Thread MeshCoP protocol or use the Mbed OS APIs (`thread_commissioning_api.h`) to implement a native or an on-mesh commissioner. Currently, there is no reference implementation for native or on-mesh commissioners. External commissioning is supported through the [Nanostack border router](https://github.com/ARMmbed/nanostack-border-router). An external [Commissioning application](https://play.google.com/store/apps/details?id=org.threadgroup.commissioner) (Android) is already available. Also an IOS version will be available soon.
 
 See [Thread commissioning guide](/docs/v5.7/tutorials/mesh.html#thread-commissioning) how to commission a Thread device to the network in practice.
 
+#### Setting up Thread network
+
+##### Initial configuration
+
+This section gives some tips on how to initially configure the Thread network.
+
+You can create the initial static configuration for the Thread device can be done in the `.json` file. The following steps are what you need to do for the minimum setup.
+
+Usually, the border router is the first device to power up. 
+
+For the Thread border router, you need to configure the PSKc so that the commissioner can connect to it and start commissioning Thread devices to the network and modify the default network settings.
+
+For example, each border router could use the following practise for the initial settings (using `.json` format):
+
+- `"thread-config-panid": "unique random value",`
+- `"thread-config-network-name: "Some name",`
+- `"thread-config-extended-panid": "{unique random value}",`
+- `"thread-master-key: "{unique random value}",`
+- `"thread-config-pskc": "{generated value}",`
+
+The minimal configuration for the border router is to have input values for the PSKc generation, that is, the network name, extended panid and PSKc and the secret password, which is not stored to the device memory. Note that the only use for the extended panid is input for the PSKc generation in the Mbed Thread stack.
+
+You can use the panid to identify each network, but the only way to ensure that each Thread network stays in its own partition is to have different master key for each network.
+
+The Thread network channel may be different for each network to avoid unnecessary packet processing (if the networks can hear each other).
+
+- `"thread-config-channel": 22,`
+
+For the devices to be commissioned, the only thing needed is PSKd and eui64. You can set both values by using `ThreadInterface.h`: `device_eui64_set(const uint8_t *eui64)` and `mesh_error_t device_pskd_set(const char *pskd)`.
+
+Alternatively, you can configure PSKd in .json:
+
+`"thread-pskd": "Some random value",`
+
+By default, the radio driver reads the eui64.
+
+##### Device memory configuration
+
+Thread router devices require more RAM and ROM memory than end devices. How much RAM memory the device needs depends on the size of the network and how big and many packets need to be buffered.
+
+The recommended heap values to start with:
+
+- Thread router: 30kb (if using Arm Mbed Cloud Client and SEDs, then you might need more 2-5kb).
+- Thread SED/MED: 16kb.
+- Thread FED: 22kb.
+
+Also, it is possible to define the number of packets that can be buffered in the parent device. 
+
+If Thread end nodes are running Mbed Cloud Client, that sets requirements for the parent device to buffer the messages during the handshake. By default, the router device has 10 message buffer size to support the Mbed Cloud Client requirements. Note that if many end nodes start the Mbed Cloud Client at the same time, it may lead to the packet drops in the parent device.
+
+Applications can use the nanostack `net_interface.h` API and the function `arm_nwk_sleepy_device_parent_buffer_size_set` to adjust the buffer size for the router (parent) devices. The API requires an `interface_id` that can be read by using `MeshInterfaceNanostack` interface and the function `get_interface_id`. 
+
+You an trace the Nanostack heap usage by using the `ns_dyn_mem_get_mem_stat` function in `nsdynmemLIB.h`. For more information, please see [libservice](See https://github.com/ARMmbed/nanostack-libservice/tree/master/mbed-client-libservice).
+
+##### End node's power mode configuration
+
+You can configure the SED device o use different power modes. You can use the `net_polling_api.h` API and the function `arm_nwk_host_mode_set` for defining the power mode and the polling interval for the end node.
+
+In the polling mode (`NET_HOST_SLOW_POLL_MODE`, `NET_HOST_FAST_POLL_MODE`), the radio is switched off between the polling times. By default, the SED device uses fast poll pode with a 300 ms polling interval.
+
 #### The maturity of the Mbed OS Thread implementation
 
 Mbed OS provides a certified Thread 1.1 stack implementation.