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

@@ -44,6 +44,8 @@ Nanostack provides a set of C API headers with more functionalities. The [nanost
 - `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,7 +57,7 @@ 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).
 
@@ -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,67 @@ 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 chapter gives some tips on how to make initial configuration for the Thread network.
+The initial static configuration for the Thread device can be done in .json file. Next we go through what is actually needed for the minimum set-up.
+
+Usually the border router is the first device to power-up. 
+For the Thread border router the PSKc needs to be configured so that 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 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 to be input for the PSKc generation in the mbed Thread stack.
+
+The panid can be used 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 some 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.
+Both values can be set by using ThreadInterface.h. Alternatively PSKd can be configured in .json:
+
+`"thread-pskd": "Some random value",`
+
+By default the eui64 is read from the radio driver.
+
+##### Device memory configuration
+
+Thread router devices require more RAM/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:
+- Thread router: 32kb
+- Thread SED: 16kb
+
+Also it is possible to define the number of packets that can be buffered in the parent device. 
+If end nodes are running 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 cloud client requirements.
+Note, that if many end nodes start the cloud client in the same time that may lead to the packet drops. And increasing the buffer size requires more nanostack heap (RAM).
+
+Application 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 will require interface_id that can be read by using MeshInterfaceNanostack interface and the function get_interface_id(). 
+
+##### End node's power mode configuration
+
+The SED device can be configured to use different power modes. The `net_polling_api.h` API and the function `arm_nwk_host_mode_set` can be used 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 300 ms polling interval.
+
 #### The maturity of the Mbed OS Thread implementation
 
 Mbed OS provides a certified Thread 1.1 stack implementation.