Update Nanostack to v6.2.0

Nanostack v6.2.0 will be used in mbed-os-5.6

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/05_reference.md

@@ -45,4 +45,6 @@ The reference manual contains several chapters; you can read them in sequence, b
 
 14. [**Load balancing API**](17_API_load_balancer.md):Read this to familiarize yourself with the Load balancing API
 
+15. [**Warm restart**](18_warm_restart.md):Read this to familiarize yourself with the Warm restart feature
+
 

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/09_API_network_def.md

@@ -462,3 +462,73 @@ Parameter|Description
 <dd>0 Success.</dd>
 <dd>-1 Failure.</dd>
 </dl>
+
+```
+int8_t net_nvm_data_clean
+(
+	int8_t interface_id
+);
+```
+Parameter|Description
+---------|-----------
+`interface_id`|The 6LoWPAN interface ID.
+
+<dl>
+<dt>Return value:</dt>
+<dd>0 Success.</dd>
+<dd>-1 Failure.</dd>
+</dl>
+
+
+```
+int8_t net_nvm_wpan_params_storage_enable
+(
+	int8_t interface_id, 
+	wpan_params_updated *nvm_update_cb, 
+	wpan_params_get *nvm_get_cb
+);
+```
+Parameter|Description
+---------|-----------
+`interface_id`|The 6LoWPAN interface ID.
+
+<dl>
+<dt>Return value:</dt>
+<dd>0 Success.</dd>
+<dd>-1 Failure.</dd>
+<dd>-2 OOM Failure.</dd>
+</dl>
+
+```
+int8_t net_nvm_wpan_params_storage_reset
+(
+	int8_t interface_id
+);
+```
+Parameter|Description
+---------|-----------
+`interface_id`|The 6LoWPAN interface ID.
+
+<dl>
+<dt>Return value:</dt>
+<dd>0 Success.</dd>
+<dd>-1 Failure.</dd>
+</dl>
+
+```
+int8_t net_nvm_wpan_params_storage_disable
+(
+	int8_t interface_id
+);
+```
+Parameter|Description
+---------|-----------
+`interface_id`|The 6LoWPAN interface ID.
+
+<dl>
+<dt>Return value:</dt>
+<dd>0 Success.</dd>
+<dd>-1 Failure.</dd>
+</dl>
+
+

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/11_API_sockets.md

@@ -89,7 +89,7 @@ Event type|Description
 `SOCKET_TX_FAIL`|Socket data send failed.
 `SOCKET_CONNECT_CLOSED`|TCP connection closed.
 `SOCKET_CONNECTION_RESET`|TCP connection reset.
-`SOCKET_NO_ROUTER`|No route available to destination.
+`SOCKET_NO_ROUTE`|No route available to destination.
 `SOCKET_TX_DONE`|TX process done (one per datagram, or if stream will be called each time some data acknowledged)
 `SOCKET_NO_RAM `|If no RAM is present.
 `SOCKET_CONNECTION_PROBLEM`|If TCP is suffering a connection problem (a soft event, it continues to retry).
@@ -103,7 +103,7 @@ An example parsing socket event:
 static uint8_t rx_buffer[APP_SOCK_RX_SIZE];
 
 void main_receive
-(SOCKET_NO_ROUTER
+(SOCKET_NO_ROUTE
 	void *cb
 )
 {

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/12_API_network.md

@@ -12,6 +12,7 @@ This chapter describes the functions of the network control layer. It contains t
 - [_RPL structures and definitions API_](#rpl-structures-and-definitions-api)
 - [_RPL root configuration API_](#rpl-root-configuration-api)
 - [_NET address retrieval API_](#net-address-retrieval-api)
+- [_IPv6 API_](#ipv6-api)
 - [_MLE router and host lifetime configuration API_](#mle-router-and-host-lifetime-configuration-api)
 - [_MLE neighbor limits configuration API_](#mle-neighbor-limits-configuration-api)
 - [_MLE token bucket configuration API_](#mle-token-bucket-configuration-api)
@@ -223,19 +224,19 @@ typedef enum
 
 ### Channel hopping mode
 
-Two hopping modes:
+There are two hopping modes:
 
-- Single channel (non-hopping)
-	* After the network scan, the node changes to the channel from which it found the best available network.
-- FHSS
+- Single channel (non-hopping).
+	* After the network scan, the node changes to the channel with the best available network.
+- FHSS.
 	* Frequency hopping mode.
 	* After the network scan, the node synchronizes to the best available network and starts continuous channel hopping using a predefined channel list.
 
 By default, the 6LoWPAN stack uses the single channel mode. 
 
-To enable the FHSS mode, FHSS instance must be created, configured and registered to software MAC instance.
+To enable the FHSS mode, you need to create, configure and register a FHSS instance to the software MAC instance.
 
-Create FHSS instance and set basic configuration using:
+To create a FHSS instance and set the basic configuration, use:
 
 ```
 fhss_api_t *ns_fhss_create
@@ -246,34 +247,34 @@ fhss_api_t *ns_fhss_create
 )
 ```
 
-Application developer must implement FHSS platform timer functions as described below. FHSS timer uses 1us resolution if not reduced by resolution divider.
+An application developer must implement the FHSS platform timer functions as described below. The FHSS timer uses 1us resolution if not reduced by the resolution divider.
 
 Member|Description
 ------|-----------
 `fhss_timer_start` | FHSS timer start platform function.
 `fhss_timer_stop` | FHSS timer stop platform function.
 `fhss_get_remaining_slots` | FHSS timer get remaining slots platform function.
-`fhss_get_timestamp` | FHSS timer timestamp (since initialization of driver).
+`fhss_get_timestamp` | FHSS timer timestamp read.
 `fhss_resolution_divider` | FHSS timer resolution divider.
 
-FHSS basic configuration is described below.
+The  basic configuration for FHSS:
 
 Member|Description
 ------|-----------
 `fhss_tuning_parameters` | Tuning parameters to enhance synchronization accuracy.
-`fhss_max_synch_interval` | Maximum used interval for requesting synchronization info from FHSS parent device.
+`fhss_max_synch_interval` | Maximum interval for requesting synchronization info from a FHSS parent device.
 `fhss_number_of_channel_retries` | Number of channel retries.
 `channel_mask` | Channel mask.
 
-Some platform-specific tuning parameters can be provided:
+You can provide platform-specific tuning parameters:
 
 Parameter|Description
 ---------|-----------
-`tx_processing_delay` | Delay between data pushed to PHY TX function and TX started (Contains CSMA-CA maximum random period).
+`tx_processing_delay` | Delay between data pushed to PHY TX function and TX started (contains CSMA-CA maximum random period).
 `rx_processing_delay` | Delay between TX done (by transmitter) and received data pushed to MAC (by receiver).
-`ack_processing_delay` | Delay between TX done (by transmitter) and Ack transmission started (by receiver).
+`ack_processing_delay` | Delay between TX done (by transmitter) and ACK transmission started (by receiver).
 
-FHSS synchronization configuration is always given from the border router using the `ns_fhss_configuration_set` function. The endpoint learns the configuration from the received synchronization message.
+The FHSS synchronization configuration is always given from the border router using the `ns_fhss_configuration_set` function. The endpoint learns the configuration from the received synchronization message.
 
 ```
 int ns_fhss_configuration_set
@@ -282,7 +283,7 @@ int ns_fhss_configuration_set
 	const fhss_synch_configuration_t *fhss_synch_configuration
 )
 ```
-Synchronization configuration is described below:
+Synchronization configuration:
 
 Member|Description
 ------|-----------
@@ -291,7 +292,7 @@ Member|Description
 `fhss_superframe_length` | Superframe dwell time (us).
 `fhss_number_of_superframes` | Number of superframes per channel.
 
-Register created FHSS instance to software MAC instance using `ns_sw_mac_fhss_register` function:
+To register the created FHSS instance to software MAC instance, use the `ns_sw_mac_fhss_register` function:
 ```
 int ns_sw_mac_fhss_register
 (
@@ -300,24 +301,24 @@ int ns_sw_mac_fhss_register
 )
 ```
 
-FHSS implements following API which is used by higher layer (software MAC):
+FHSS implements the following API used by the higher layer (software MAC):
 
 Member|Description
 ------|-----------
-`fhss_is_broadcast_channel` | Checks if current channel is broadcast channel.
-`fhss_use_broadcast_queue` | Checks if broadcast queue must be used instead of unicast queue.
-`fhss_tx_handle` | Set destination channel and write synchronization info.
+`fhss_is_broadcast_channel` | Checks if the current channel is a broadcast channel.
+`fhss_use_broadcast_queue` | Checks if a broadcast queue must be used instead of a unicast queue.
+`fhss_tx_handle` | Set the destination channel and write synchronization info.
 `fhss_check_tx_conditions` | Check TX permission.
 `fhss_receive_frame` | Notification of received FHSS synch or synch request frame.
 `fhss_data_tx_done` | Data TX done callback.
 `fhss_data_tx_fail` | Data TX or CCA failed callback.
-`fhss_synch_state_set` | Change synchronization state.
-`fhss_read_timestamp` | Read timestamp.
-`fhss_get_retry_period` | Get retransmission period.
+`fhss_synch_state_set` | Change the synchronization state.
+`fhss_read_timestamp` | Read the timestamp.
+`fhss_get_retry_period` | Get the retransmission period.
 `fhss_init_callbacks` | Initialize MAC functions.
 
 
-Software MAC implements following callbacks to serve requests from FHSS:
+The software MAC implements the following callbacks to serve requests from FHSS:
 
 Member|Description
 ------|-----------
@@ -326,12 +327,12 @@ Member|Description
 `mac_read_datarate` | Read PHY datarate.
 `mac_change_channel` | Change channel.
 `mac_send_fhss_frame` | Send FHSS frame.
-`mac_synch_lost_notification` | Send notification when FHSS synchronization is lost.
+`mac_synch_lost_notification` | Send a notification when FHSS synchronization is lost.
 `mac_tx_poll` | Poll TX queue.
 `mac_broadcast_notify` | Broadcast channel notification from FHSS.
-`mac_read_coordinator_mac_address` | Read coordinator MAC address.
+`mac_read_coordinator_mac_address` | Read the coordinator MAC address.
 
-To disable FHSS, instance can be deleted using `ns_fhss_delete` function.
+To disable FHSS, you can delete an instance using the `ns_fhss_delete` function.
 ```
 int ns_fhss_delete
 (
@@ -646,6 +647,8 @@ All configuration calls (such as channel selection) must be performed before cal
 
 ### IPv6 bootstrap configure
 
+#### IPv6 bootstrap configuration
+
 To configure the IPv6 bootstrap:
 
 ```
@@ -660,7 +663,7 @@ int8_t arm_nwk_interface_configure_ipv6_bootstrap_set
 Parameter|Description
 ---------|-----------
 `interface_id`|The network interface ID.
-`bootstrap_mode`|Values to start the bootstrap mode:<br>
+`bootstrap_mode`|Values to start the bootstrap mode.
 `NET_IPV6_BOOTSTRAP_STATIC`|The application defines the IPv6 prefix.
 `ipv6_prefix_pointer`|A pointer to a 64-bit IPv6 prefix.
 
@@ -672,9 +675,34 @@ Parameter|Description
 
 The `arm_nwk_interface_up()` function call starts the stack bootstrap process and performs neighbour discovery.
 
+
+#### Accept Router Advertisements 
+
+You can change the setting when an interface is created. If you change the setting you must do it before the bootstrap is started.
+
+```
+int8_t arm_nwk_interface_accept_ipv6_ra
+(
+	int8_t 			interface_id,
+	net_ipv6_accept_ra_e 	accept_ra
+)
+```
+
+Parameter|Description
+---------|-----------
+`interface_id`|The network interface ID.
+`accept_ra`|Router Advertisements handling mode:<br>`NET_IPV6_RA_ACCEPT_IF_AUTONOMOUS` Accept Router Advertisements when using autonomous IPv6 address allocation. Ignore when using a static address. This is the default value for the setting.<br>`NET_IPV6_RA_ACCEPT_ALWAYS` Accept Router Advertisements always, even when using static IPv6 address allocation.
+
+<dl>
+<dt>Return value</dt>
+<dd>>=0 Setting done.</dd>
+<dd><0 Failed (for example an invalid interface ID).</dd>
+</dl>
+
+
 ### Security mode for RF link layer
 
-To set a security mode for the link layer of a configured network interface:
+To set the security mode for the link layer of a configured network interface:
 
 ```
 int8_t arm_nwk_link_layer_security_mode
@@ -689,7 +717,7 @@ int8_t arm_nwk_link_layer_security_mode
 Parameter|Description
 ---------|-----------
 `interface_id`|The network interface ID.
-`mode`|Defines the security mode for the link layer:<br>`NET_SEC_MODE_NO_SECURITY`, security is disabled.<br>`NET_SEC_MODE_PSK_LINK_SECURITY`, security is enabled with selected mode and PSK key info.<br>`NET_SEC_MODE_PANA_LINK_SECURITY`, link layer keys are defined by the PANA authentication server.
+`mode`|Defines the security mode for the link layer:<br>`NET_SEC_MODE_NO_SECURITY`, security is disabled.<br>`NET_SEC_MODE_PSK_LINK_SECURITY`, security is enabled with selected mode and PSK key info.<br>`NET_SEC_MODE_PANA_LINK_SECURITY`, PANA authentication server defines the link layer keys.
 `sec_level`|Supported values are 1 to 7. This parameter is only checked when the mode is `NET_SEC_MODE_PSK_LINK_SECURITY`.
 `psk_key_info`|A pointer to PSK key material: key and key ID. This parameter is only checked when the mode is `NET_SEC_MODE_PSK_LINK_SECURITY`.
 

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/18_warm_restart.md

@@ -0,0 +1,59 @@
+The warm restart feature
+========================
+
+This chapter describes the functionality of the warm restart feature. It contains the following sections:
+
+- [_Application configuration_](#application-configuration)
+- [_mbed TLS configuration_](#mbed-tls-configuration)
+
+## Application configuration
+
+This section describes the functionalities needed to enable load balancing from an application.
+
+### NVM storage
+
+To use the warm restart feature, your device needs to have non-volatile memory (NVM) available. The security parameters are stored into it, so a secure storage should be used when possible. The application must control the data storing intervals. If you are using a flash drive, you should save scarsely to ensure a long lifetime for it.
+
+### WPAN & PANA configuration 
+
+To understand how to configure WPAN & PANA to receive security parameters, refer to [Network Definition APIs](09_API_network_def.md). Basically, you need to register callback functions for both to receive security paramaeters whenever they change. 
+
+<span class="notes">**Note:** WPAN parameters change very often. Make sure to store them regularly.</span>
+
+To register WPAN callbacks, use the following function:
+
+```
+net_nvm_wpan_params_storage_enable
+```
+
+To register PANA callbacks, use one of the following functions (based on the type of device):
+
+```
+pana_client_nvm_callback_set
+pana_server_nvm_callback_set
+```
+
+## mbed TLS configuration
+
+This section describes the needed configuration for mbed TLS to use the warm restart feature.
+
+<span class="notes">**Note:** The server side must support mbed TLS session caching for warm restart to work. There is no extra logic needed even if the server does not support session caching (full handshake is performed every time).</span>
+
+Every device initially "cold starts", meaning that a full handshake is performed with server. After the full handshake, the session parameters can be fetched by calling:
+
+```
+mbedtls_ssl_get_session (See mbedtls/ssl.h for details)
+```
+
+When the SSL session details are known, call the function:
+
+```
+mbedtls_ssl_set_session (See mbedtls/ssl.h for details),
+```
+
+Finally, to enable "session id" based SSL resume, call:
+
+```
+mbedtls_ssl_handshake_step,
+```
+

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/driver_api.md

@@ -1,41 +1,107 @@
 # Device Driver API
 
-
 The 6LoWPAN stack uses Device Driver API to communicate with different physical layer drivers. The 6LoWPAN stack supports different device types for PHY layer and special cases where raw IPv6 datagrams are forwarded to a driver.
 
-The driver must first be registered with the 6LoWPAN stack using the `phy_device_driver_s` structure defined in section [_PHY device driver register_](#phy-device-driver-register). This structure defines all the functions that a stack uses in calling a device driver. When the device driver must call the driver API from the stack, it uses the ID number received in the registration phase to distinct between different devices. The following sections define the contents of the driver structures and API interfaces that the driver can use.
+The driver must first be registered with the 6LoWPAN stack using the `phy_device_driver_s` structure defined in section [_PHY device driver register_](#phy-device-driver-register). This structure defines all the functions that the stack uses when calling a device driver. When the device driver must call the driver API from the stack, it uses the ID number received in the registration phase to distinct between different devices. The following sections define the contents of the driver structures and API interfaces that the driver can use.
 
-See Doxygen documentation for the latest [Device Drive API](https://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/api/arm__hal__phy_8h.html)
+See Doxygen documentation for the latest [Device Drive API](https://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/api/arm__hal__phy_8h.html).
+
+## Providing RF driver for Mbed OS applications
+
+For Mbed OS 5, the RF driver implements the `NanostackRfPhy` API. `MeshInterfaceNanostack` requires the driver object to be provided when initializing.
+
+![NanostackRfPhy](img/NanostackRfPhy.png)
+
+Applications use only `LoWPANNDInterface`, `ThreadInterface` or `NanostackEthernetInterface`
+directly to set up the network and provide a driver. The rest of the classes provide an abstration
+between Nanostack and the socket layers of Mbed OS.
+
+See [NanostackRfPhy.h](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/FEATURE_NANOSTACK/nanostack-interface/NanostackRfPhy.h) for an up-to-date header file and API.
 
 ### How to create a new RF driver
 
-The following steps describe how you can create a new RF driver.
+The following steps describe how you can create a new RF driver:
 
 1. Read through the section [_Example RF driver_](#example-rf-driver). You can use this example code as your starting point.
 
-2. Fill in the actual transceiver-specific parts of the RF driver.
+1. Fill in the actual transceiver-specific parts of the RF driver.
 
-3. Register the driver to the 6LoWPAN stack on your application. You can use the example node applications with your driver.
+1. Register the driver to the 6LoWPAN stack on your application. You can use the example node applications with your driver.
 
-4. Create a MAC that is suitable for your purpose (802.15.4, Ethernet or serial).
+1. Create a MAC that is suitable for your purpose (802.15.4, Ethernet or serial).
 
-5. Configure the interface. See instructions in section _How to configure a network interface_ of the chapter [_6LoWPAN stack Initialisation_](07_API_initialize.md#how-to-configure-a-network-interface).
+1. Configure the interface. See instructions in the chapter [_6LoWPAN stack Initialisation_](07_API_initialize.md#how-to-configure-a-network-interface).
 
-6. Check with a RF sniffer tool that you can see RF packets transmitted when you start your device. The 6LoWPAN bootstrap should start with IEEE 802.15.4 Beacon Request packets.
+1. Implement the `NanostackRfPhy` API.
+
+1. Check with a RF sniffer tool that you can see RF packets transmitted when you start your device. The 6LoWPAN bootstrap should start with IEEE 802.15.4 Beacon Request packets.
+
+#### Worker thread for Mbed OS
+
+Nanostack's interfaces use mutexes for protecting the access from multiple threads. In Mbed OS, the mutex cannot be used
+from an interrupt. The same applies to all APIs that have internal locking and multithread support. Therefore, each driver must implement their own worker thread to handle the interrupt requests.
+
+![Worker Thread](img/worker_thread.png)
+
+Example: Use worked thread and signals from an interrupt
+
+```
+// Signals from interrupt routines
+#define SIG_RADIO       1
+#define SIG_TIMER       2
+
+// Worker thread
+Thread irq_thread;
+
+// Interrupt routines
+static void rf_interrupt(void)
+{
+    irq_thread.signal_set(SIG_RADIO);
+}
+
+static void rf_timer_signal(void)
+{
+    irq_thread.signal_set(SIG_TIMER);
+}
+
+
+// Worker thread
+void rf_worker_thread(void)
+{
+    for (;;) {
+        osEvent event = irq_thread.signal_wait(0);
+        if (event.status != osEventSignal) {
+            continue;
+        }
+
+        if (event.value.signals & SIG_RADIO) {
+            rf_process_irq();
+        }
+        if (event.value.signals & SIG_TIMER) {
+            rf_process_timer();
+        }
+    }
+}
+
+...
+// Somewhere in the initialization code
+irq_thread.start(rf_if_irq_task);
+
+```
 
 ### RF driver states
 
 _Figure 11-1_ below shows the basic states of the RF driver.
 
-The following describes the basic states in more detail:
+The basic states in more detail:
 
 State|Description
 -----|-----------
 `DOWN`|This is the initial state of the driver. The radio is not used in this state.
-`RX ACTIVE`|In this state, the driver has the radio turned on and it can receive a packet or ACK from the radio. The driver can also go from this state to the TX ACTIVE state to transmit a packet.
+`RX ACTIVE`|In this state, the driver has the radio turned on and it can receive a packet or ACK from the radio. The driver can also go from this state to the `TX ACTIVE` state to transmit a packet.
 `TX ACTIVE`|In this state, the driver will try to start a transmission:<br>1. It must first check that it is not currently busy doing something else.<br>2. It must check that the channel is free.<br>3. Finally, it can try to transmit the packet.
 `SNIFFER`|This mode can be implemented to enable using the device as a packet sniffer. In this state, the RX is always on and the received packets are sent to the application layer but nothing is transmitted back.
-`ED SCAN`|This mode can be implemented to enable using energy scan. It enables scanning the energy from channels one by one and nothing else.
+`ED SCAN`|This mode can be implemented to enable energy scan. It enables scanning the energy from channels one by one and nothing else.
 `ANY STATE`|This state represents all the states in the state machine.
 
 <span class="notes">**Note**: The driver [initialization and registration](#phy-device-driver-register) using the function `arm_net_phy_register` must be performed before the driver is functional.</span>
@@ -84,7 +150,7 @@ To register a PHY driver to the stack:
 int8_t arm_net_phy_register(phy_device_driver_s *phy_driver);
 ```
 
-See: [Doxygen](https://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/api/arm__hal__phy_8h.html#aff06eaa736d3784c956dc6eda9f27419) for description.
+See the [Doxygen](https://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/api/arm__hal__phy_8h.html#aff06eaa736d3784c956dc6eda9f27419) for the description.
 
 
 ### PHY data RX API

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/index.md

@@ -22,7 +22,7 @@ This document is divided into following sections:
 
 * [6LoWPAN Quick Start Guide](quick_start_intro.md)
 * [ARM mbed IPv6/6LoWPAN Stack Overview](01_overview.md)
-* [ARM mbed Thread Stack Overview](thread_overview.md)
+* [ARM mbed Thread Stack Overview](thread_intro.md)
 * [API Reference Manual](05_reference.md)
 * [Porting ARM mbed Networking Stack](16_API_porting.md)
 

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/mac_api.md

@@ -0,0 +1,241 @@
+# Introduction
+
+Nanostack has a lower level API for the IEEE 802.15.4-2006 MAC standard. This enables developers to support different MACs, be it SW or HW based solution. Nanostack offers SW MAC that you can use when your board does not have 15.4 MAC available.
+
+## SW MAC
+
+Nanostack includes an IEEE 802.15.4 based SW MAC class. You can use SW MAC when your board does not support MAC. To use the SW MAC service you must have a working RF driver registered to Nanostack. To create SW MAC, call the following function:
+
+```
+ns_sw_mac_create()
+```
+
+This creates a SW MAC class and sets a callback function to be used by Nanostack.
+
+<span class="notes">**Note:** You must not call `ns_sw_mac_create()` more than once!</span>
+
+### Initializing SW MAC
+
+Deploy SW MAC as follows:
+
+1. Call `arm_net_phy_register()` to register the configured [_RF driver_](driver_api.md#how-to-create-a-new-rf-driver) class to Nanostack.
+2. Call `ns_sw_mac_create()` to create SW MAC with needed list sizes.
+	- a sleepy device needs only 1-4 as the size of the `device_decription_table_size`.
+	- the minimum and recommended `key_description_table_size` for the Thread stack is 4. (2 for 6LoWPAN)
+	- the recommended value for `key_lookup_size` is 1 and for `key_usage_size` 3.
+3. Call `arm_nwk_interface_lowpan_init()` to create Nanostack with the created SW MAC class. Nanostack will initialize SW MAC before using it.
+
+### Example
+
+See a simple code snippet for creating SW MAC with 16 as neighbour table size with three key descriptions:
+
+```
+int8_t generate_6lowpan_interface(int8_t rf_phy_device_register_id)
+{
+	mac_description_storage_size_t storage_sizes;
+	storage_sizes.device_decription_table_size = 16;
+	storage_sizes.key_description_table_size = 3;
+	storage_sizes.key_lookup_size = 1;
+	storage_sizes.key_usage_size = 3;
+	mac_api_t *mac_api = ns_sw_mac_create(rf_phy_device_register_id, &storage_sizes);
+	if (!mac_api) {
+		tr_error("Mac create fail!");
+		return -1;
+	}
+	return arm_nwk_interface_lowpan_init(mac_api, "6LoWPAN_ROUTER");
+}
+```
+
+### Enabling [_FHSS_](12_API_network.md#channel-hopping-mode)
+
+SW MAC supports FHSS. To enable it, you need to do the following:
+
+1. Call `arm_net_phy_register()` to register the configured RF driver class to Nanostack. 
+2. Call `ns_sw_mac_create()` to create SW MAC with needed list sizes.
+3. Call `ns_fhss_create()` to configure and define the FHSS class.
+4. Call `ns_sw_mac_fhss_register()` to register FHSS to SW MAC.
+5. Call `arm_nwk_interface_lowpan_init()` to create Nanostack with the created SW MAC class.
+
+## IEEE 802.15.4 MAC sublayer APIs
+
+The stack uses the IEEE 802.15.4 defined MAC management service entity (MLME-SAP) and MAC data service (MCPS-SAP) interfaces. MAC API follows MCPS and MLME primitives defined by the IEEE 802.15.4-2006 standard.
+
+The following primitives are used in MAC layer:
+
+| Primitive | Despription |
+| --------- | ----------- |
+| Request | Request made by service user. |
+| Confirm | MAC layer response to earlier request. |
+| Indication | Indication event from MAC to service user. |
+| Response | Service user's response to received indication. |
+
+MAC API is defined in the following header files:
+
+- `mac_api.h` Main header which defines a transparent MAC API for Nanostack to use.
+- `mlme.h` Definitions for MLME-SAP primitives.
+- `mac_mcps.h` Definitions for MCPS-SAP primitives.
+- `mac_common_defines.h` Definitions for common MAC constants.
+
+### MCPS-SAP interface
+
+MCPS-SAP defines 802.15.4 data flow API with the following primitives:
+
+| Primitive | Despription |
+| --------- | ----------- |
+| MCPS-DATA-REQ | Data request primitive to MAC. |
+| MCPS-DATA-CONF | MAC generated confirmation for ongoing MCPS-DATA-REQ. |
+| MCPS-DATA-IND | MAC generated data indication event. |
+| MCPS-PURGE-REQ | Cancel ongoing MCPS-DATA-REQ from MAC. |
+| MCPS-PURGE-CONF | Confirmation from MAC to MCPS-PURGE-REQ operation. |
+
+### MLME-SAP interface
+
+MLME-SAP defines a set of different management primitives and this chapter introduces both supported and unsupported primitives in Nanostack.
+
+#### Supported MLME APIs
+
+MLME-SAP primitives used by Nanostack:
+
+| Primitive | Despription |
+| --------- | ----------- |
+| MLME-BEACON-NOTIFY | MAC generated event for received beacons.|
+| MLME-GET-REQ | Request information about a specified PAN Information Base (PIB) attribute. |
+| MLME-GET-CONF | MAC generated response to MLME-GET-REQ. |
+| MLME-RESET-REQ | Request to reset MAC to idle state and clean data queues. |
+| MLME-SCAN-REQ | Start MAC scan process. Orphan scan is not supported. |
+| MLME-SCAN-CONF | Result of the scan made by MLME-SCAN-REQ. |
+| MLME-COMM-STATUS-IND | MAC generated indication about the communications status. |
+| MLME-SET-REQ | Request to write data into a specified PIB attribute. |
+| MLME-SET-CONF | MAC generated response to MLME-SET-REQ. |
+| MLME-START-REQ | Starts or enables MAC with specified options. Nanostack uses this also for RFD device. |
+| MLME-SYNCH-LOSS-IND | Indicate syncronization loss from wireless PAN. Only used by SW MAC when [_FHSS_](12_API_network.md#channel-hopping-mode) is in use! |
+| MLME-POLL-REQ | Request MAC to do data poll to parent. |
+
+#### Non-supported MLME APIs
+
+Unsupported MLME-SAP primitives:
+
+| Primitive | Support planned | Despription |
+| --------- | --------------- | ----------- |
+| MLME-ASSOCIATE-REQ | Not yet | Start MAC association process. |
+| MLME-ASSOCIATE-CONF | Not yet | MAC association process confirmation status. |
+| MLME-ASSOCIATE-IND | Not yet | MAC association indication to indicate the reception of assocation request. |
+| MLME-ASSOCIATE-RES | Not yet | MAC association response for indication. |
+| MLME-DISASSOCIATE-REQ | Not yet | MAC disassociation request from service user. |
+| MLME-DISASSOCIATE-IND | Not yet | MAC disassociation indication event to service user. |
+| MLME-DISASSOCIATE-CONF | Not yet | MAC disassociation confirmation when the disassociation request is handled. |
+| MLME-GTS-REQ | Not yet | MAC Guaranteed Time Slot (GTS) request. |
+| MLME-GTS-IND | Not yet | MAC GTS allocate event indication. |
+| MLME-GTS-CONF | Not yet | MAC GTS request confirmation. |
+| MLME-ORPHAN-IND | Not yet | Service user indicated by orphaned device. |
+| MLME-ORPHAN-RES | Not yet | Service user response to orphan indication event. |
+| MLME-RESET-CONF | Yes | MAC reset confirmation. |
+| MLME-RX-ENABLE-REQ | Yes | Enable (or disable) RX receiver for a specified time. |
+| MLME-RX-ENABLE-CONF | Yes | Confirmation for MLME-RX-ENABLE-REQ. |
+| MLME-START-CONF | Yes | Confirmation for MLME start request. |
+| MLME-SYNCH-REQ | Not yet | Request MAC to synchronize with coordinator. |
+
+### MAC API class introduction
+
+This chapter introduces MAC mesh interface `mac_api_s`. It is a structure that defines the function callbacks needed by a service user.
+
+The base class defines the functions for two-way communications between an external MAC and service user. The application creates a `mac_api_s` object by calling the MAC adapter's create function. The newly created object is then passed to Nanostack which initializes its own callback functions by calling `mac_api_initialize()` function. A service user operates MAC by calling MLME or MCPS primitive functions.
+
+The MAC API class structure `mac_api_t` is defined as below:
+
+```
+typedef struct mac_api_s {
+	//Service user defined initialization function which is called when Nanostack takes MAC into use
+    mac_api_initialize 				*mac_initialize;
+    //MAC adapter function callbacks for MLME & MCPS SAP
+    mlme_request 					*mlme_req;
+    mcps_data_request 				*mcps_data_req;
+    mcps_purge_request  				*mcps_purge_req;
+    //Service user defined function callbacks
+    mcps_data_confirm 				*data_conf_cb;
+    mcps_data_indication				*data_ind_cb;
+    mcps_purge_confirm      			*purge_conf_cb;
+    mlme_confirm            			*mlme_conf_cb;
+    mlme_indication         			*mlme_ind_cb;
+    //MAC extension API for service user
+    mac_ext_mac64_address_set   		*mac64_set;
+    mac_ext_mac64_address_get   		*mac64_get;
+    mac_storage_decription_sizes_get *mac_storage_sizes_get;
+    int8_t                      		parent_id;
+    uint16_t                    		phyMTU;
+};
+```
+
+Member|Description
+------|-----------
+`mac_initialize` | MAC initialize function called by Nanostack.
+`mlme_req` | MLME request function to use MLME-SAP commands, MAC defines.
+`mcps_data_req` | MCPS data request function to use, MAC defines.
+`mcps_purge_req` | MCPS purge request function to use, MAC defines.
+`mcps_data_confirm` | MCPS data confirm callback function, service user defines.
+`data_ind_cb` | MCPS data indication callback function, service user defines.
+`purge_conf_cb` | MCPS purge confirm callback function, service user defines.
+`mlme_conf_cb` | MLME confirm callback function, service user defines.
+`mlme_ind_cb` | MLME indication callback function, service user defines.
+`mac64_set` | MAC extension function to set mac64 address.
+`mac64_get` | MAC extension function to get mac64 address.
+`mac_storage_sizes_get` | Getter function to query data storage sizes from MAC.
+`parent_id` | Service user ID used to indentify the MAC service user. Optional.
+`phyMTU` | Maximum Transmission Unit (MTU) used by MAC. Standard 802.15.4 MAC must set 127.
+
+### MAC API standard extensions
+
+This chapter introduces MAC API standard extensions.
+
+#### MAC 64-bit address set and get
+
+NanoStack uses 64-bit address set and get. There are two 64-bit addresses available: 
+
+- NVM EUI64.
+- dynamic 64-bit address used at the link layer. 
+
+Thread generates a random MAC64 after commissioning. Therefore, MAC and the RF driver must support updating of radio's dynamic 64-bit address anytime.
+
+Address set and get support two different 64-bit addresses:
+
+| Address enumeration type | Despription |
+| -------------------------- | ----------- |
+| MAC_EXTENDED_READ_ONLY | A unique EUI64. |
+| MAC_EXTENDED_DYNAMIC | Dynamic 64-bit address. Same as EUI64 after boot. |
+
+#### MAC max storage information get
+
+Usually, HW MAC and SW MAC have static keys and neighbour list sizes. Nanostack always asks the max size to limit its neighbour table size. The service user must define the `mac_storage_sizes_get()` function returning the following values:
+
+- MAC Device description list size (must be > 1).
+- MAC Key description list size (must be > 1).
+
+<span class="notes">**Note:** The Key description list size must at least 4 if using Thread!</span>
+
+#### MLME attribute extension
+
+Nanostack uses MLME attribute extensions which have to be ported to the HW MAC adapter. To configure the extensions, use the `MLME-SET-REQ` command.
+
+| Enumeration type | Value | Despription |
+| ---------------- | ----- | ----------- |
+| `macLoadBalancingBeaconTx` | `0xfd` | Trigger to MAC layer to send a beacon. Called by the [_load balancer_](17_API_load_balancer.md) module periodically. |
+| `macLoadBalancingAcceptAnyBeacon` | `0xfe` | Configure MAC layer to accept beacons from other networks. Enabled by [_load balancer_](17_API_load_balancer.md), default value is `False`. Value size boolean, `true=enable`, `false=disable`. |
+| `macThreadForceLongAddressForBeacon` | `0xff` | The Thread standard forces beacon source address to have an extended 64-bit address. |
+
+#### Thread Sleepy End Device (SED) keepalive extension
+
+Thread 1.1 stack defines that sleepy end device data poll process must enable neighbour table keepalive functionality as well. When SED finishes data polling succesfully, it updates its parents keepalive value in a neighbour table. A service user at a parent device does not have a standard mechanism to indicate the data polling event. Therefore, the MAC layer must generate an `MLME-COMM-STATUS` indication callback with status `MLME_DATA_POLL_NOTIFICATION`.
+
+Enumeration extension for MLME communication status enumeration:
+
+| Enumeration type | Value | Despription |
+| ---------------- | ----- | ----------- |
+| MLME_DATA_POLL_NOTIFICATION | `0xff` | Thread requirement for MLME-COMM-STATUS to start indicating the successful data poll events. |
+
+## HW MAC
+
+To use HW MAC, you need to create an adapter class that links function calls between Nanostack and HW MAC. To create the adapter class, you need to implement the functions defined in the `mac_api_s` structure. When HW MAC generates an event the adapter must handle it and do a parameter adaptation before calling the correct function from the `mac_api_s` structure. You may need the same parameter adaptation for requests from Nanostack to HW MAC.
+
+<span class="notes">**Note:** Function calls from Nanostack to HW MAC must be non-blocking in the adapter layer!</span>
+
+ 

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_APIs.md

@@ -9,7 +9,7 @@ To manage Thread, include the following headers into your application:
 #include thread_management_api.h
 ```
 
-The subsequent sections describe API functionality for Thread. To understand the ideas behind Thread, read [ARM mbed Thread Stack Overview](thread_overview.md).
+The subsequent sections describe API functionality for Thread. To understand the ideas behind Thread, read [Introduction to mbed OS Thread](thread_intro.md).
 
 ## Thread Commissioning API
 

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_comm.md

@@ -1,136 +0,0 @@
- Commissioning process
-============
-
-The commissioning process has two phases:
-
-*  Petitioning
-*  Joining
-
-Petitioning must occur before any joiner can join, that is, there must be one sole authorized commissioner - an authenticator for subsequent joiners.
-
-## Mesh Commissioning Protocol (MeshCoP)
-
-The Mesh Commissioning Protocol (MeshCoP) is based on CoAP [RFC 7252](https://tools.ietf.org/html/rfc7252) and performs petitioning, maintenance, management and relay functions. It uses WLAN as an access technology for non-Thread networks whereas within a Thread network it uses the Thread Management Framework.
-
-## Petitioning
-
-### External commissioner candidate
-
-If a commissioner candidate uses a WLAN network interface for commissioning or exists outside Thread network, it is known as an external commissioner candidate. An external commissioner has to petition the Thread network through a representative (the Border Router) to become the sole authorized commissioner. The commissioner candidate must use an authentication handshake with the Border Router to prove its eligibility to become the sole authorized commissioner and set up a secure commissioning session. The commissioner candidate petitions the Leader via the Border Router. If petitioning succeeds, the commissioner candidate becomes the sole authorized external commissioner. As the secure commissioning session is set up, the representative Border Router will be made known throughout the Thread network and all subsequent communication with other Thread devices will now be done through the Border Router. A periodic keep-alive message is sent on the secure commissioning session to ensure it remains open with the commissioner.
-
-**Figure 2-3 External Commissioner Petitioning**
-
-![nw-arc](img/thread_comm_ext.png)
-
-* The process starts with the Border Router being aware of the commissioner credential. This can be entered directly into the Border Router device itself or into any trusted Thread device and sent to the Border Router.
-
-* After a while, the same commissioner credential will be entered into the commissioner candidate that will initiate the registration process, starting with a DTLS handshake. If the DTLS handshake is successful, the Border Router will authenticate the commissioner candidate based on the information of the shared commissioner credential.
-
-* The Border Router will arbitrate with the Leader on behalf of the commissioner candidate to authorize the commissioner candidate to be the sole commissioner and authenticator for subsequent joiners. If there is already an authorized commissioner, the commissioner candidate will be denied authorization.
-
-* The authorized commissioner will keep a secure commissioning session open with the Border Router. The session uses the DTLS record layer for encryption and authentication, based on keys derived from the master key established between the commissioner (as the commissioner candidate) and the Border Router as a result of the DTLS handshake. This commissioning session will be used for various purposes and it communicates CoAP messages carrying petitioning, management and relay messages between the commissioner and the Border Router.
-
-**Figure 2-4 External Commissioner Petitioning Sequence**
-
-![nw-arc](img/thread_ext_pet_seq.png)
-
-### Native commissioner candidate
-
-If the commissioner candidate uses a Thread Network Interface for commissioning, it is known as a native commissioner. A native commissioner has to petition the Thread network through a representative (the Commissioner Router) to become the sole authorized commissioner. The commissioner candidate must use an authentication handshake with the Commissioner Router to prove it is eligible to become the sole authorized commissioner and set up a secure commissioning session. The candidate petitions the Leader via the Commissioner Router. If petitioning succeeds, the commissioner candidate becomes the sole authorized native commissioner. However, the commissioner subsequently joins the Thread network and becomes an active
-device (on-mesh commissioner) and all communication with other Thread devices takes place directly with the commissioner.
-
-**Figure 2-5 Native Commissioner Petitioning**
-
-![nw-arc](img/thread_native_comm_pet.png)
-
-* The process starts with the Commissioner Router being aware of the commissioner credential. This can be entered directly into the Commissioner Router device itself or into any trusted Thread device and sent to the Commissioner Router.
-
-* After a while, the same commissioner credential will be entered into the commissioner candidate and it will initiate the registration process, starting with a DTLS handshake. If the DTLS handshake is successful, the Commissioner Router will authenticate the commissioner candidate based on the information of the shared commissioner credential.
-
-* The Commissioner Router will arbitrate with the Leader on behalf of the commissioner candidate to authorize the commissioner candidate to be the sole commissioner and authenticator for subsequent joiners. If there is already an authorized commissioner, the commissioner candidate will be denied authorization.
-
-* The authorized commissioner will subsequently join the Thread network and thus be able to communicate directly with all Thread devices.
-
-**Figure 2-6 Native Commissioner Petitioning Sequence**
-
-![nw-arc](img/thread_nat_pet_seq.png)
-
-### Petitioning authorization
-
-When a Border Router or Commissioner Router receives a petitioning request from the commissioner candidate, the Border Router or Commissioner Router relays the petitioning request to the Leader with the ID of the commissioner candidate. The Leader will respond by accepting or rejecting the request and the Border Router will relay the response accordingly. If the commissioner candidate is external, the Leader will also advertise the Border Router acting on behalf of the commissioner to the rest of the Thread network so any potential Joiner Router knows where to relay the DTLS handshake messages originating by the joiner. In addition, the beacon information will be updated through a notification so all Thread Routers alter their beacon, assisting the steering of the joiner.
-
-**Figure 2-7 Petitioning Authorization**
-
-![nw-arc](img/thread_pet_auth_seq.png)
-
-## Joining Process
-
-When there is an authorized commissioner associated with the Thread network, Thread devices are allowed to join the Thread network securely. These devices are known as joiners. The actual joining process depends on the system topology that can be identified as one of the following scenarios:
-
-* External commissioner is connected via WLAN
-	* Border Router is not a Joiner Router
-	* Border Router is a Joiner Router
-
-* Native commissioner is connected via Thread network
-	* Joiner Router is not a commissioner
-	* Joiner Router is a commissioner
-
-
-This implies that the commissioner will be in one of the following states:
-
-### External commissioner
-
-In this case, the petitioning process as described in [External commissioner candidate](#external-commissioner-candidate) must have taken place initially to provide a secure commissioning session from Border Router to commissioner bound to the petitioning process. This secure session is then used in the joining process to relay the joining DTLS handshake through to the commissioner. Once the joiner has received the network parameters it needs to attach to the Thread network. This closes the secure commissioning session.
-
-**Case 1: Border Router is not a Joiner Router**
-
-This is the most complex case out of the four presented scenarios. In this case, there are three separate and distinct paths the authentication traffic (the DTLS handshakes) has to go through:
-
-* Joiner to Joiner Router point-to-point
-* Joiner Router to Border Router through Thread network
-* Border Router to commissioner through WLAN
-
-These paths are effectively connected to each other and the Joiner Router and Border Router's relay agents and client-server bindings manage the authentication traffic accordingly.
-
-**Figure 2-8 External commissioner connected to the WLAN, Border Router is not a Joiner Router**
-
-![nw-arc](img/thread_case1.png)
-
-**Case 2: Border Router is a Joiner Router**
-
-This case is simpler because there is no need to relay from a Joiner Router to a Border Router. However, the Border Router uses its relay agent to police unauthenticated traffic as a Joiner Router. There are two separate and distinct paths the authentication traffic (the DTLS handshakes) have to go through:
-
-* Joiner to Border Router point-to-point.
-* Border Router to commissioner through WLAN.
-
-**Figure 2-9 External commissioner connected to the WLAN, Border Router is a Joiner Router**
-
-![nw-arc](img/thread_case3.png)
-
-### Native commissioner
-
-In this case, either the petitioning process as described in [Native commissioner candidate](#native-commissioner-candidate)
-must have taken place initially, or the commissioner has already joined the Thread network, either by starting it or by using an out-of-band process. Once the joiner has received the network parameters it needs to attach to the Thread network. This closes the secure commissioning session.
-
-**Case 1: Joiner Router Is Not a commissioner**
-
-This case is simpler as there is no need to relay from the Border Router to the commissioner. There are two separate and distinct paths the authentication traffic (the DTLS handshakes) has to go through:
-
-* Joiner to Joiner Router point-to-point.
-* Joiner Router to commissioner through Thread network.
-
-**Figure 2-10 Native commissioner connected to the Thread network, Joiner Router is not a commissioner**
-
-![nw-arc](img/thread_case2.png)
-
-**Case 2: Joiner Router is a commissioner**
-
-This case is the simplest because there is no need to relay from the Border Router to the commissioner and there is not a distinct Joiner Router. There is only one distinct path the DTLS handshake has to go through:
-
-* Joiner to Border Router point-to-point.
-
-**Figure 2-11 Native commissioner connected to Thread network, Joiner Router is a commissioner**
-
-![nw-arc](img/thread_case4.png)
-
-

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_commissioning.md

@@ -0,0 +1,40 @@
+## How to commission a Thread device in practise
+
+### Building the node application
+
+By default, the mbed Thread applications/examples use 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 your `.json` file. You can use the [mesh-minimal](https://github.com/ARMmbed/mbed-os-example-mesh-minimal) application as an example.
+
+* `"mbed-mesh-api.thread-use-static-link-config": false`
+* `"macros": ["MBEDTLS_USER_CONFIG_FILE=\"mbedtls_config.h\""]`
+
+Setting `thread-use-static-link-config` to `false` prevents the usage of the predefined link configuration values and allows the device to start network scanning.
+
+### QR code generation
+
+You can use [a free online tool](http://www.qr-code-generator.com/) to generate a QR code.
+
+In the tool, fill in the URL field: `v=1&eui=000b57fffe07a8be&cc=PV7TUCB0`.
+These are just example values. Fill in the correct values for your device and make sure `v=1` is always there.
+
+* `cc` is the PSKd, which is configured in the `.json` file (see the mesh-api configuration).
+* `eui` is equal to the RF MAC address by default. 
+
+There are four additional query parameters you can put into this field: 
+
+* `vn`    Vendor name
+* `vm`    Vendor model
+* `vv`    Product/Vendor version
+* `vs`    Product/Vendor serial number
+
+To print the MAC address, you need to connect the node to the Thread network with static configuration enabled, unless you have your own configuration for the MAC address. 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());`
+
+### Using the Thread commissioning application
+
+You can use the [Thread Android application](https://play.google.com/store/apps/details?id=org.threadgroup.commissioner) for commissioning:
+
+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 routers(s). 
+2. Select a border router from the list.
+3. Enter the passphrase asked by the application. It is `Thread Network` (when using the default mesh-api Thread configuration). After successful connection, the application is ready to scan the QR code.
+4. Power on your Thread device if it is not already on. 
+5. Scan the QR code. The Thread device should join the network. If you are using the mesh-minimal application you should see the IP address printed: `connected. IP = ...`.

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_dev_typ.md

@@ -1,61 +0,0 @@
-Thread network device types and roles
-============
-
-There are different device types and roles in the Thread network. mbed OS offers own builds or configurations to different Thread device types and roles.
-
-## End devices
-
-Usually, end devices are the most constrained devices in the Thread network. They serve as a last hop in the mesh topology. Devices such as plain sensors, controls and switches can be implemented as end devices only. The different types of end devices are described in the following sections.
-
-### Full end device (FED)
-
-A Thread host device that communicates through the parent device, but has the least constraints to the parent. A FED makes address queries and listens to multicast messages.
-
-### Minimal end device (MED)
-
-A Thread host device type that registers its addresses to the parent leaving all routing and address queries to be done by the parent.
-
-### Sleepy end device (SED)
-
-A Thread host device that is similar to the minimal end device, but does not keep the radio on all the time. It uses the polling mechanism to receive packets from the parent. Requires parents to store the packets.
-
-## Routers
-
-Routers provide routing services to the network devices. Routers also provide joining and security services for devices trying to join the network.
-
-A router always attaches to the Thread network as a Router Eligible End Device (REED). REEDs do not forward messages or provide any joining or security services for other devices in the Thread network. The Thread network manages REEDs becoming routers (or vice versa) if necessary without user interaction.
-
-## Roles
-
-Devices participating in a Thread network can take up various roles depending upon their device type and the Thread network join process configuration. The Thread network join process is called Thread Commissioning. The different roles of Thread devices are described in the subsequent sections.
-
-### Border router
-
-A border router is a specific type of a router that provides connectivity from the Thread network to adjacent networks on other physical layers (for example, WiFi and Ethernet). Border routers provide services for devices within the 802.15.4 network, including routing services for off-network operations. There may be one or more border routers in a Thread network.
-
-### Commissioner 
-
-The currently elected authentication server for new Thread devices and the authority for providing the network credentials required to join the network. A device capable of being elected as a commissioner is called a commissioner candidate. Devices without Thread interfaces may perform this role, but the ones with a Thread interface may combine this role with all other roles except the Joiner. For example, a border router can perform the role of commissioner. This device may be, for example, a cell phone or a server in the cloud, and typically provides the interface by which a human administrator manages the joining of a new device to the Thread network.
-
-### Joiner
-
-A joiner is a device to be added by a human administrator or generally a device needed to be commissioned for the Thread network. This role requires a Thread interface and cannot be combined with any other role in a single device. A joiner does not have network credentials.
-
-### Joiner router
-
-A joiner router is an existing Thread router or a REED on the secure Thread network that is one radio hop away from the joiner. A Joiner router requires a Thread interface to operate, and may be combined in any device with other roles except the joiner role.
-
-### Thread leader
-
-A Thread leader is one of the routers that has formed the network and takes the following additional responsibilities on top of the router responsibilities. The first router on a network becomes a leader. 
-
-* Managing router ID assignment.
-* Thread network data registration and distribution.
-* Commissioner petition.
-* Accepting and distributing Thread configurations to the rest of the network.
-
-Thread leader is a single distinguished device in any Thread network, acting as a central arbiter for the network configuration. 
-
-**Figure 2-2 General Thread Network**
-
-![nw-arc](img/Thread_General.png)

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_faq.md

@@ -0,0 +1,90 @@
+## Questions and answers
+
+### How are devices joined to the networks and what are the options for commissioning modes? 
+
+There are no different commissioning modes for devices joining to the network, there are only different kinds of commissioners (on-mesh, native, external). Thread devices either have the configuration or not. If they don’t have the configuration, they try to find a Thread network that accepts them. Then they do the commissioning using DTLS to authenticate themselves and if successful, they will receive the network credentials and become a part of the network.
+
+### Where are the default configurations of the Nanostack set?
+
+- Thread devices do not have a default configuration. They should always be commissioned to the network and receive the configuration on site. A commissioner can modify the configurations to the entire network and all Thread devices in the network will automatically pick the new configuration and save it to NVM.
+- The border router may have a default configuration set, that provides a starting point for setting up the network. 
+
+### Are the Thread configurations easily exposed to the application and are they runtime configurable?
+
+- The Thread management API can be used to read/store/delete the Thread link configuration and to define the device configuration (`thread_management_if.h`). 
+- The Thread commissioner can change the network configuration of the entire Thread network. By using the `thread_commissioning_api.h` and `thread_management_if.h`, you can build an on-mesh or native commissioner that can update the network configuration.
+- For example, the border router can be set up with the default configuration. The commissioner can then update the whole Thread network configuration (including border router).
+
+### Who selects the channel and PAN ID? Will different manufacturers pick different channels and PAN IDs?
+
+Channel and PAN ID are part of the Thread configuration that is received when a device is commissioned to the Thread network. The commissioner can modify the configuration at any time. The manufacturer does not decide the Thread link configuration.
+
+### How can ad-hoc mesh networks be easily formed with different manufacturers?
+
+Ad-hoc networks with devices from different manufacturers can be easily created by commissioning.
+
+### Does the border router listen on all channels or just one?
+
+- The border router is a Thread router device and uses the same configuration as other devices in the Thread network. So it uses a single channel.
+- Devices that have not yet joined the Thread network scan all channels and PAN IDs to find a Thread network that they want to be part of.
+
+### How to commission with a mobile device? Is there an example app?
+
+An example application is [downloadable from the Android store](https://play.google.com/store/apps/details?id=org.threadgroup.commissioner).
+
+### Are there any application examples? What are the Thread features supported/not supported by them?
+
+- Application examples supporting SED and REED types:
+  - [mbed OS Client example](https://github.com/ARMmbed/mbed-os-example-client) 
+  - [mesh minimal example](https://github.com/ARMmbed/mbed-os-example-mesh-minimal)
+- [Thread border router](https://github.com/ARMmbed/nanostack-border-router)
+
+### How to debug and visualize the network?
+
+- You can download a Wireshark version that supports the Thread protocol from the [Wireshark web page](https://www.wireshark.org/download.html)
+- A commissioner can do network diagnostics and topology images using Thread-specific diagnostics commands. Our software supports this but there is no C/C++ API support.
+
+### How to check for errors or check the link quality?
+
+Link quality and errors are easiest to debug using Wireshark.
+
+### How to send/receive with UDP and TCP sockets. How to use multicast groups?
+
+The mesh minimal uses socket communication and multicasting. See more details in the [mesh minimal example](https://github.com/ARMmbed/mbed-os-example-mesh-minimal).
+
+### What if my ISP does not provide IPv6 service? Why do I need IPv6 internet service? Can I use a tunneling service?
+
+Thread is based on the IPv6 protocol. If the communication must go over IPV4 network, there are two solutions available:
+- NAT64
+- IPv6 tunneling.
+
+### What happens if a packet cannot reach its destination (for example, no internet connection to border router)? What is the responce back to the device?
+
+There are no special Thread codes available, you will have the normal internet error codes. An application must handle the temporary network connection problems with proper retry logic.
+
+### How are network errors sent back to the device? Is there a description of what went wrong or simply no response?
+
+There are no special error codes in Thread. The application can receive ICMPv6 error codes.
+
+### How to message all nodes in the mesh? Can I use a multicast address?
+
+IPv6 multicast messages are supported. link-local and realm-local (mesh-local) multicast scopes work within the Thread network, as well the site-local multicast messages.
+
+### How can I use link-local addresses versus global addresses?
+
+- Usually, global addresses are used to communicate with the remote services. When a device has the destination address, the network stack selects the proper source address and route to that destination. 
+- An application developer may implement a protocol (using multicast) for querying the link-local or mesh-local addresses from other devices in the Thread network. Link-local addresses work only over one radio hop. Mesh-local addresses work over multiple hops in the Thread network.
+- The mbed OS mesh API provides functions to query the device's own addresses (link-local or global).
+
+### What are the configurable parameters in the Thread devices? What do they mean and where are they documented?
+
+- The Thread configurable parameters are the Active Operational Dataset parameters. The parameter explanations can be found in the [mbed Mesh API](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/README.md). 
+More information can be found in the Thread specification. 
+- The Thread device configuration includes PSKd and EUI64 (usually the MAC address of the radio chip), that are used to commission the device.
+
+### What are PSKc and PSKd? Where can find these?
+
+- PSKc is the authentication key for the native or external commissioner. This value is generated from the passphrase of the network combined with the network name and XPANID that are received when scanning the networks. The commissioner application asks for this passphrase after scanning and selecting an available Thread network, exactly the same way as in WiFi.
+- PSKd is the authentication key used to authenticate a device to the Thread network in combination with EUI64. 
+- These values are printed to a sticker on the device or the device packaging in the form of a QR code that is then scanned by the commissioner application. This will allow the device to be commissioned to the Thread network. After the authentication, the Thread configuration is given to the new device. 
+

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_intro.md

@@ -0,0 +1,163 @@
+# Introduction to mbed OS Thread
+
+## Why to use Thread
+
+Thread was designed with one goal in mind; to create the best way to connect and control products in home. The key features of Thread are:
+
+- Designed for home.
+- Built-in security.
+- Optimized for battery-operated devices.
+- Utilizes IPv6 protocols.
+- Robust mesh network.
+- Simple to set up and use.
+
+[Read more here](http://threadgroup.org/What-is-Thread/Connected-Home).
+
+The Thread stack is built on IPv6 over Low power Wireless Personal Area Networks (6LoWPAN), which itself builds on IEEE 802.15.4 to offer IP-based networking. Internet Protocol (IP) provides the core mechanism for relaying datagrams across IP networks, and its routing capabilities enable internetworking.
+
+![Thread_image](img/thread_arch.png)
+ 
+Read more at the [Thread Group site](http://www.threadgroup.org/).
+
+## Why mbed OS with Thread stack
+
+ARM mbed OS is an open source embedded operating system designed specifically to facilitate the creation and deployment of commercial, standards-based IoT solutions at scale. mbed OS features full support for Thread to simplify development of secure IoT applications in home and to ease the Thread product certification. The mbed OS Thread stack is a Thread Group certified component.
+
+### mbed Thread is based on the mbed OS key elements
+
+The key elements of mbed OS are:
+
+- Hardware platform agnostic layer that allows easy adaptation of new hardware components.
+- Modular approach, which allows including the necessary libraries based on the application needs.
+- Multilayer build (SW/HW) in security that helps you to protect your IoT solutions.
+- mbed RTOS (ARM CMSIS-RTOS) providing the real time software execution.
+- Toolchain and IDE support.
+
+mbed Thread is implemented in the Nanostack library, which also supports the 6LoWPAN protocol. In mbed OS, the Thread stack runs in its own RTOS thread using an internal event scheduler. mbed OS provides the [mesh C++ API](https://github.com/ARMmbed/mbed-os/tree/master/features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/mbed-mesh-api) for building Thread applications.
+
+- 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](https://github.com/ARMmbed/mbed-os/tree/master/features/netsocket).
+
+Nanostack provides a set of C API headers with more functionalities. The following header files are located [here](https://github.com/ARMmbed/mbed-os/tree/master/features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack):
+
+- `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. 
+
+### Thread devices you can build on mbed OS
+
+The mbed OS mesh API allows you to define 3 types of devices:
+
+- Router enabled device (REED), which can become an active router.
+- Sleepy end device (SED).
+- Minimal end device (MED).
+
+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.
+
+For an end device or a router example, see [mesh minimal example](https://github.com/ARMmbed/mbed-os-example-mesh-minimal).
+
+#### End devices
+
+mbed OS offers separate configurations for different Thread end device types. Usually, the end devices are the most constrained devices in the Thread network. They serve as last hop in the mesh topology. Devices such as plain sensors, controls and switches can be implemented as end devices only. For the most constrained hardware, the minimal end device (MED) or the sleepy end device (SED) is an optimal selection as the implementation requires the smallest amount of flash and RAM memory due to the limited functionality. Note that a sleepy end device also requires more resources on the parent device. End devices communicate through a parent and can switch to another parent if the current connection is broken.
+
+A Thread network does not work with end devices only. There must be router devices, that can route the traffic between nodes and to 
+the back-end network through the border router.
+
+Minimal end device (MED):
+
+- Registers its address to a single parent.
+- Relies all routing and address queries on the parent.
+- Must start a new scan if the parent is lost; longer disconnect from network.
+
+Sleepy end device (SED) is like MED, but:
+
+- Does not keep the radio on all the time.
+- Uses a polling mechanism to receive packets from the parent (polling time configurable).
+- Requires the parent to store packets when in sleep.
+- Can be temporarily switched to MED to transfer large amounts of data.
+
+Full End Device (FED):
+
+- Does not register addresses to the parent.
+- Makes address queries.
+- Listens to multicast messages from other devices (others than parent).
+- Reduces the parent device's load and memory requirements compared to MED and SED.
+
+
+#### Routers
+
+In Thread networks, devices operate in several specific roles separated by the services they provide. All router devices provide mesh routing and they can switch the state between an active router and a REED device without any user interaction. The first router on a network becomes a leader, that manages:
+
+- Router ID assignment.
+- Thread network data registration.
+- Network data distribution. 
+- Commissioner petition. 
+
+Additionally, a router can act as a border router (must be configured in build time), that provides services for devices within the Thread mesh network and the backbone network.
+
+mbed OS offers a separate build for a Thread border router. The border router routes IPv6 traffic to the external IPv6 networks. Currently, our border router uses an Ethernet connection to the backbone IP network, but also other means of connectivity are available (cellular or WiFi).
+
+See an example of a Thread border router [here](https://github.com/ARMmbed/nanostack-border-router).
+
+#### Commissioning
+
+Commissioning takes place when new devices need to be added to the Thread network. All mbed OS Thread devices (end nodes and routers) can join to any certified Thread network. In Thread, there can be one commissioner, that allows new devices to join the network. There are three types of commissioners:
+
+- A native commissioner uses the 802.15.4 radio interface, but does not belong to the Thread network.
+- An on-mesh commissioner is a Thread device already joined in the Thread network.
+- An external commissioner connects to the Thread network through the border router, that is connected to the backbone.
+
+**Example use case for external commissioning**
+
+An external commissioner uses mDNS-SD service discovery to find a list of available Thread networks. When you select the network to connect to, the application asks for the network passphrase. The passphrase is usually placed on a label on the border router box (like in WiFi).
+
+The commissioner application generates PSKc from:
+
+- The network passphrase.
+- The Thread network name.
+- The extended PAN ID.
+
+The Thread network name and the extended PAN ID are received in the scanning phase. The commissioner application can now start a DTLS session using the generated PSKc.
+
+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.
+
+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. 
+2. The joiner device detects in the scanning response that it can now join the network and starts a DTLS session using PSKd.
+3. The session is created through the Thread network (via the joiner router and the border router) to the commissioner application. 
+4. The commissioner authenticates the device and accepts it to the network. 
+5. The device receives the Thread configuration, which allows it to join.
+
+<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
+
+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 (Android) is already available [here](https://play.google.com/store/apps/details?id=org.threadgroup.commissioner). Also an IOS version will be available soon.
+
+See [Thread commissioning guide](thread_commissioning.md) how to commission a Thread device to the network in practise.
+
+## The maturity of the mbed OS Thread implementation
+
+ARM mbed OS provides a certified Thread 1.1 stack implementation.
+
+In addition to the Thread Group certification, where the focus is to ensure interoperability with different implementations, the ARM mbed team is focused on delivering a high quality implementation of the software components required in the Thread implementation. We have invested in the automated test environment, where we can verify all the change requests as well as the regular releases.
+
+To ensure high quality the ARM mbed OS Thread stack is tested daily including:
+
+- The non-functional test sets (stability, reliability, performance, stress, recovery).
+- The functional test cases using Valgrind memory analysis tool.
+- The code coverage measurement using LCov.
+- Automated certification test cases to ensure the certification validation all the time.
+- The RAM/ROM and performance measurements with trend charts.
+
+To ensure the production ready delivery we also check:
+
+- Security vulnerabilities using Defensics automated testing tool.
+- Static code analysis using the Coverity tool.
+- Interoperability against other vendors using the official Thread certification harness.

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_overview.md

@@ -1,28 +0,0 @@
-Introduction to Thread
-============
-
-The Thread stack is an open standard for reliable, cost-effective, low-power, wireless device-to-device (D2D) communication. It is designed specifically for Connected Home applications where IP-based networking is desired and a variety of application layers can be used on the stack.
-
-These are the general characteristics of the Thread stack and network:
-
-* Simple network installation, start-up and operation: The simple protocols for forming, joining, and maintaining Thread networks allow systems to self-configure and fix routing problems as they occur.
-
-* Secure: Devices do not join the Thread network unless authorized and all communications are encrypted and secure.
-	
-* Small and large networks: Home networks vary from several devices to hundreds of devices communicating seamlessly. The network layer is designed to optimize the network operation based on the expected use.
-
-* Range: Typical devices in conjunction with mesh networking provide sufficient range to cover a normal home. Spread spectrum technology is used at the physical layer to provide good immunity to interference.
-
-* No single point of failure: The stack is designed to provide secure and reliable operations even with the failure or loss of individual devices.
-	
-* Low power: Host devices can typically operate for several years on AA type batteries using suitable duty cycles.
-
-The Thread stack runs on the top of 6LoWPAN stack and hence, compliments the ARM mbed IPv6/6LoWPAN stack functionality providing added security, control, reliability, and robustness. 
-
-**Figure 2-1 Thread network protocol architecture**
-
-![nw-arc](img/Thread_Prot_Arch_Comb.png)
-
-
-
-

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_sec.md

@@ -1,22 +0,0 @@
-Thread security fundamentals
-============
-
-## Authentication and key agreement
-
-The fundamental security used in the Thread network is an elliptic curve variant of J-PAKE (EC-JPAKE), using the NIST P-256 elliptic curve. J-PAKE is a password-authenticated key exchange (PAKE) with _juggling_ (hence the J). It essentially uses elliptic curve Diffie-Hellmann for key agreement and Schnorr signatures as a Non-Interactive Zero-Knowledge (NIZK) proof mechanism to authenticate two peers and to establish a shared secret between them based on the passphrase. The author has published two internet drafts which describe J-PAKE [draft-hao-jpake-01](https://tools.ietf.org/html/draft-hao-jpake-01) and the Schnorr NIZK proof [draft-hao-schnorr-01](https://tools.ietf.org/html/draft-hao-schnorr-01).
-
-A Transport Layer Security (TLS) 1.2 [RFC 5246](https://tools.ietf.org/html/rfc5246) handshake will be developed for EC-JPAKE, and it can potentially be used in both TLS and DTLS. Datagram Transport Layer Security (DTLS) [RFC 6347](https://tools.ietf.org/html/rfc6347) is a variant of TLS with additional fields in the records to make it suitable for use over an unreliable datagram-based transport (for example, User Datagram Protocol (UDP)), whereas TLS assumes a reliable transport such as Transport Control Protocol (TCP).
-
-# Network-wide Key
-
-The Thread Network is protected with a network-wide key, that is used at the Media Access Control (MAC) layer to protect the 802.15.4 MAC data frames. This is an elementary form of security used to prevent casual eavesdropping and targeted disruption of the Thread network from outsiders without knowledge of the network-wide key. As it is a network-wide key, compromise of any Thread device could potentially reveal the key; therefore, it is not typically used as the only form of protection within the Thread network. From the point of view of joining, it is used to discriminate between an authenticated and authorized Thread device and the joiner (in its initial state). The network-wide key, along with other network parameters, is delivered securely to a joiner using a Key Encryption Key (KEK) to secure it.
-
-## Authentication
-
-As a joiner is untrusted at the point of joining, it is common practice to enforce some sort of policing mechanism to ensure the joiner can be verified and at the same time limit the effect of rogue devices attempting to join the Thread network. In a Thread network, this requires the joiner to identify a Joiner Router and to communicate solely in a point-to-point fashion with the Joiner Router. The Joiner Router polices any traffic from the joiner and forwards it to the commissioner in a controlled manner to allow the authentication protocol (DTLS handshake) to execute.
-
-In a case where the commissioner is not in direct communication with the joiner, the Joiner Router must relay the DTLS handshake with the commissioner. The Commissioning Relay Protocol provides encapsulation of the DTLS handshake and relaying of the DTLS handshake from the joiner all the way to the commissioner in a simple manner.
-
-## Maintenance
-
-A commissioner uses the Commissioning Protocol to keep a secure communication session alive and also to change certain parameters of the network, for example, the network name.

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/mkdocs.yml

@@ -11,10 +11,9 @@ pages:
 - ['02_N_arch.md', 'ARM mbed 6LoWPAN Stack Overview', 'Stack architecture']
 - ['03_N_usage.md', 'ARM mbed 6LoWPAN Stack Overview', 'Application usage']
 - ['04_N_networking.md', 'ARM mbed 6LoWPAN Stack Overview','Networking topology and protocols']
-- ['thread_overview.md', 'ARM mbed Thread Stack Overview', 'Thread Stack']
-- ['thread_dev_typ.md', 'ARM mbed Thread Stack Overview', 'Device Types & Roles']
-- ['thread_sec.md', 'ARM mbed Thread Stack Overview', 'Thread Security Fundamentals']
-- ['thread_comm.md', 'ARM mbed Thread Stack Overview', 'Thread Commissioning (Join Process)']
+- ['thread_intro.md', 'ARM mbed Thread Stack Overview', 'mbed OS Thread introduction']
+- ['thread_faq.md', 'ARM mbed Thread Stack Overview', 'Thread FAQ']
+- ['thread_commissioning.md', 'ARM mbed Thread Stack Overview', 'Commissioning in practise']
 - ['05_reference.md','API Reference Manual', 'API Reference - Synopsis']
 - ['api_changes_to_v5_0_0.md', 'API Reference Manual', 'API updates v.5.0.0']
 - ['api_changes_to_v4_0_0.md', 'API Reference Manual', 'API updates v.4.0.0']
@@ -33,5 +32,8 @@ pages:
 - ['15_API_debug.md','API Reference Manual', 'Network Debug Statistics API']
 - ['thread_APIs.md','API Reference Manual', 'Thread Stack APIs']
 - ['16_API_porting.md','Porting a new platform to ARM mbed Networking Stack', 'Porting to the Stack']
+- ['18_warm_restart.md','Join the network fast','Warm restart feature']
+- ['mac_api.md','Stack MAC API','MAC API']
+
 
 copyright: © ARM Ltd. Copyright 2016 – ARM mbed IoT Device Platform

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/ccmLIB.h

@@ -25,7 +25,7 @@
  *  - ccm_sec_init(), A function to init CCM library.
  *  - ccm_process_run(), A function to run configured CCM process.
  *
- *  \section ccm-inctuction CCM process sequence:
+ *  \section ccm-instruction CCM process sequence:
  *  1. Init CCM library by, ccm key, ccm_sec_init()
  *      - security level
  *      - 128-bit CCM key

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/dhcp_service_api.h

@@ -59,6 +59,10 @@
 #define TX_OPT_MULTICAST_HOP_LIMIT_64   0x02    /**< Use multicast hop limit of 64. */
 ///@}
 
+/**
+ * /enum dhcp_instance_type
+ * /brief DHCP instance types.
+ */
 typedef enum dhcp_instance_type
 {
     DHCP_INSTANCE_CLIENT,
@@ -72,6 +76,7 @@ typedef enum dhcp_instance_type
  * until some instance acknowledges that the message belongs to it.
  * \param instance_id An instance of registered server.
  * \param msg_tr_id The message transaction ID.
+ * \param msg_name Message type.
  * \param msg_ptr An allocated message pointer. Should not deallocate unless RET_MSG_ACCEPTED returned (then responsibility of client).
  * \param msg_len The length of the message.
  *
@@ -90,6 +95,7 @@ typedef int (dhcp_service_receive_req_cb)(uint16_t instance_id, uint32_t msg_tr_
  *
  * \param instance_id An instance of a registered server.
  * \param ptr A pointer for the client object.
+ * \param msg_name Message type.
  * \param msg_ptr An allocated message pointer. Should not deallocate unless RET_MSG_ACCEPTED returned (then responsibility of client).
  * \param msg_len The length of the message.
  *
@@ -108,7 +114,7 @@ typedef int (dhcp_service_receive_resp_cb)(uint16_t instance_id, void *ptr, uint
  *
  * \param interface_id Interface for the new DHCP instance.
  * \param instance_type The type of the new DHCP instance.
- * \param A callback function to receive DHCP messages.
+ * \param receive_req_cb A callback function to receive DHCP messages.
  *
  * \return Instance ID that is used to identify the service.
  */

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/mac_filter_api.h

@@ -49,6 +49,10 @@
 
 #include "ns_types.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * \brief Start MAC level filter.
  * This function can be called again if default values are modified.
@@ -191,4 +195,8 @@ int_fast8_t mac_filter_add_short(int8_t interface_id, uint16_t mac16, int16_t lq
  */
 int_fast8_t mac_filter_add_long(int8_t interface_id, uint8_t mac64[8], int16_t lqi_m, int16_t lqi_add, int16_t dbm_m, int16_t dbm_add);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* MAC_FILTER_API_H_ */

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/net_interface.h

@@ -171,8 +171,13 @@ typedef enum {
 typedef enum {
     NET_IPV6_BOOTSTRAP_STATIC,  /**< Application defines the IPv6 prefix. */
     NET_IPV6_BOOTSTRAP_AUTONOMOUS /**< Interface gets IPv6 address automatically from network using ICMP and DHCP. */
-}
-net_ipv6_mode_e;
+} net_ipv6_mode_e;
+
+/** IPv6 accept RA behaviour */
+typedef enum {
+    NET_IPV6_RA_ACCEPT_IF_AUTONOMOUS, /**<Accept Router Advertisements when using autonomous IPv6 address allocation. Ignore when using a static address. This is the default value for the setting. */
+    NET_IPV6_RA_ACCEPT_ALWAYS         /**<Accept Router Advertisements always, even when using static IPv6 address allocation. */
+} net_ipv6_accept_ra_e;
 
 /** Network coordinator parameter list.
  * Structure is used to read network parameter for warm start.
@@ -311,6 +316,19 @@ extern int8_t arm_nwk_interface_lowpan_init(struct mac_api_s *api, char *interfa
  */
 extern int8_t arm_nwk_interface_configure_ipv6_bootstrap_set(int8_t interface_id, net_ipv6_mode_e bootstrap_mode, const uint8_t *ipv6_prefix_pointer);
 
+/**
+ * \brief Accept Router Advertisements setting.
+ *
+ * Accept Router Advertisements setting. Setting can be changed after an interface is created.
+ * If setting is changed it must be done before the bootstrap is started.
+ *
+ * \param interface_id The network interface ID.
+ * \param accept_ra Router Advertisements handling mode.
+ * \return 0 Setting done.
+ * \return <0 Failed (for example an invalid interface ID).
+ */
+extern int8_t arm_nwk_interface_accept_ipv6_ra(int8_t interface_id, net_ipv6_accept_ra_e accept_ra);
+
 /**
  * \brief Set network interface bootstrap setup.
  *
@@ -412,7 +430,9 @@ extern int8_t arm_nwk_6lowpan_link_scan_parameter_set(int8_t interface_id, uint8
 extern int8_t arm_nwk_6lowpan_link_panid_filter_for_nwk_scan(int8_t interface_id, uint16_t pan_id_filter);
 
 /**
-  *  \brief Get current used channel.
+  * \brief Get current used channel.
+  *
+  * \param interface_id Network interface ID.
   *
   * \return Active channel.
   * \return -1 = Radio is closed.
@@ -421,9 +441,13 @@ extern int16_t arm_net_get_current_channel(int8_t interface_id);
 
 /**
  * \brief A function to read the PAN ID filter.
+ *
+ * \param interface_id Network interface ID.
+ *
  * \return 16-bit value indicating a PAN ID filter.
  */
 extern uint16_t arm_net_get_nwk_pan_id_filter(int8_t interface_id);
+
 /**
   * \brief Enable/Disable network ID filter.
   *
@@ -435,6 +459,7 @@ extern uint16_t arm_net_get_nwk_pan_id_filter(int8_t interface_id);
   * \return -2 Interface active.
   */
 extern int8_t arm_nwk_6lowpan_link_nwk_id_filter_for_nwk_scan(int8_t interface_id, const uint8_t *nwk_id_filter);
+
 /**
   * \brief Enable/Disable network protocol ID filter.
   *
@@ -560,7 +585,6 @@ extern int8_t arm_pana_server_library_init(int8_t interface_id, net_tls_cipher_e
   */
 extern int8_t arm_pana_client_key_pull(int8_t interface_id);
 
-
 /**
  * \brief Trigger network key update process
  *
@@ -591,7 +615,6 @@ extern int8_t arm_pana_server_key_update(int8_t interface_id, const uint8_t *net
  */
 extern int8_t arm_pana_activate_new_key(int8_t interface_id);
 
-
 /**
  * \brief Read PANA server security key material.
  *
@@ -617,12 +640,12 @@ extern int8_t arm_network_key_get(int8_t interface_id, ns_keys_t *key);
  * \return -3 Active.
  */
 extern int8_t arm_nwk_interface_up(int8_t interface_id);
+
 /**
  * \brief Stop and set interface to idle.
  *
  * \param interface_id Network interface ID
  *
- *
  * \return >=0 Process OK.
  * \return -1 Unknown network ID.
  * \return -3 Not Active.
@@ -635,12 +658,13 @@ extern int8_t arm_nwk_interface_down(int8_t interface_id);
  * \param interface_id Network interface ID.
  * \param border_router_setup_ptr Pointer to MAC and 6LoWPAN ND setup.
  *
+ * \return 0 on success, negative value on error case.
  */
 extern int8_t arm_nwk_6lowpan_border_router_init(int8_t interface_id, const border_router_setup_s *border_router_setup_ptr);
+
 /**
  * \brief Add context at 6LoWPAN interface configure state.
  *
- *
  * \param interface_id Network interface ID.
  * \param c_id_flags Bit 4 indicates compress support and bit 0-3 context ID.
  * \param context_len Context length in bits need to be 64-128.
@@ -654,6 +678,7 @@ extern int8_t arm_nwk_6lowpan_border_router_init(int8_t interface_id, const bord
  * \
  */
 extern int8_t arm_nwk_6lowpan_border_router_context_update(int8_t interface_id, uint8_t c_id_flags, uint8_t context_len, uint16_t ttl, const uint8_t *context_ptr);
+
 /**
  * \brief Update runtime configured context.
  *
@@ -670,6 +695,7 @@ extern int8_t arm_nwk_6lowpan_border_router_context_update(int8_t interface_id,
  *
  */
 extern int8_t arm_nwk_6lowpan_border_router_context_parameter_update(int8_t interface_id, uint8_t c_id, uint8_t compress_mode, uint16_t ttl);
+
 /**
  * \brief Delete allocated context by ID.
  *
@@ -680,6 +706,7 @@ extern int8_t arm_nwk_6lowpan_border_router_context_parameter_update(int8_t inte
  * \return -1 Delete process fails.
  */
 extern int8_t arm_nwk_6lowpan_border_router_context_remove_by_id(int8_t interface_id, uint8_t c_id);
+
 /**
  * \brief Update ND ABRO version number.
  *
@@ -708,7 +735,6 @@ extern int8_t arm_nwk_6lowpan_border_route_nd_default_prefix_timeout_set(int8_t
  */
 int8_t arm_nwk_param_read(int8_t interface_id, link_layer_setups_s *network_params);
 
-
 /**
  * \brief A function to read MAC PAN-ID, Short address and EUID64.
  * \param interface_id Network interface ID.
@@ -718,7 +744,6 @@ int8_t arm_nwk_param_read(int8_t interface_id, link_layer_setups_s *network_para
  */
 int8_t arm_nwk_mac_address_read(int8_t interface_id, link_layer_address_s *mac_params);
 
-
 /**
  * \brief A function to read 6LoWPAN ND border router address and NWK prefix.
  * \param interface_id Network interface ID.
@@ -729,7 +754,6 @@ int8_t arm_nwk_mac_address_read(int8_t interface_id, link_layer_address_s *mac_p
  */
 int8_t arm_nwk_nd_address_read(int8_t interface_id, network_layer_address_s *nd_addr_info);
 
-
 /**
  * \brief A function to read the networking address information.
  * \param interface_id Network interface ID.
@@ -840,10 +864,10 @@ extern int8_t arm_net_route_delete(const uint8_t *prefix, uint8_t prefix_len, co
 #define ND_PROXY_PREFIX_NVM_UPDATE          3
 /** ND ABRO version update. */
 #define ND_PROXY_ABRO_VERSION_NVM_UPDATE    4
+
 /**
  * \brief Load context from NVM at ZigBeeIP interface configure state.
  *
- *
  * \param interface_id Network Interface ID
  * \param contex_data A pointer to properly built 20 bytes update array.
  *

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/net_thread_test.h

@@ -461,6 +461,17 @@ int8_t thread_test_router_id_request_send(int8_t interface_id, uint8_t status);
  */
 int8_t thread_test_joiner_router_joiner_port_set(uint16_t port);
 
+/**
+ *\brief set a router address to be requested. For a router, this address is sent
+ *\in address solicit request to leader and for leader this is the router address
+ *
+ * \param interface_id               Network Interface
+ * \param router_addr                Address requested
+ * \return 0,                        Command OK
+ * \return <0                        Command Fail
+ */
+int8_t thread_test_router_address_set(int8_t interface_id, uint16_t router_addr);
+
 #ifdef __cplusplus
 }
 #endif

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/ns_mdns_api.h

@@ -10,25 +10,27 @@
  *
  * See the License for the specific language governing permissions and limitations under the License.
  *
- * SPDX-License-Identifier: Apache-2.0
- * Licensed under the Apache License, Version 2.0 (the License); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an AS IS BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
  */
 
 #ifndef _NS_MDNS_API_H_
 #define _NS_MDNS_API_H_
 
-typedef struct ns_mdns_service *ns_mdns_service_t;
-typedef struct ns_mdns *ns_mdns_t;
+/**
+ * \file ns_mdns_api.h
+ * \brief Nanostack mDNS-SD API.
+ */
+
+/*!
+ * \struct ns_mdns_t
+ * \brief Structure for Nanostack mDNS instance
+ */
+typedef struct ns_mdns *ns_mdns_t;  /**< Instance */
+
+/*!
+ * \struct ns_mdns_service_t
+ * \brief Structure for Nanostack mDNS service instance
+ */
+typedef struct ns_mdns_service *ns_mdns_service_t;  /**< Service instance */
 
 /*!
  * \struct ns_mdns_service_param_t
@@ -60,22 +62,22 @@ ns_mdns_t ns_mdns_server_start(const char *server_name, uint32_t ttl, uint32_t t
 /**
  * \brief Stop mDNS server
  *
- * \param ns_mdns Server instance received from ns_mdns_server_start
+ * \param ns_mdns_instance Server instance received from ns_mdns_server_start
  *
  */
-void ns_mdns_server_stop(ns_mdns_t ns_mdns);
+void ns_mdns_server_stop(ns_mdns_t ns_mdns_instance);
 
 /**
  * \brief Register service to mDNS server
  *
- * \param ns_mdns Server instance received from ns_mdns_server_start
+ * \param ns_mdns_instance Server instance received from ns_mdns_server_start
  *
  * \param service Parameters for service
  *
  * \return mDNS Service descriptor or NULL in case of failure.
  *
  */
-ns_mdns_service_t ns_mdns_service_register(ns_mdns_t ns_mdns, ns_mdns_service_param_t *service);
+ns_mdns_service_t ns_mdns_service_register(ns_mdns_t ns_mdns_instance, ns_mdns_service_param_t *service);
 
 /**
  * \brief Unregister service from mDNS server
@@ -89,9 +91,10 @@ void ns_mdns_service_unregister(ns_mdns_service_t service_desc);
  * \brief Send mDNS announcement. Application should call this method once application
  * advertised parameters has changed.
  *
- * \param ns_mdns Server instance received from ns_mdns_server_start
+ * \param ns_mdns_instance Server instance received from ns_mdns_server_start
  */
 
-void ns_mdns_announcement_send(ns_mdns_t ns_mdns);
+void ns_mdns_announcement_send(ns_mdns_t ns_mdns_instance);
 
 #endif /* _NS_MDNS_API_H_ */
+

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/socket_api.h

@@ -107,7 +107,7 @@ extern "C" {
  * | SOCKET_TX_FAIL             | 0x50  | Socket data send failed.                                            |
  * | SOCKET_CONNECT_CLOSED      | 0x60  | TCP connection closed.                                              |
  * | SOCKET_CONNECTION_RESET    | 0x70  | TCP connection reset.                                               |
- * | SOCKET_NO_ROUTER           | 0x80  | No route available to destination.                                  |
+ * | SOCKET_NO_ROUTE            | 0x80  | No route available to destination.                                  |
  * | SOCKET_TX_DONE             | 0x90  | UDP: link layer TX ready (d_len = length of datagram).              |
  * |                            |       | TCP: some data acknowledged (d_len = data remaining in send queue)  |
  * | SOCKET_NO_RAM              | 0xA0  | No RAM available.                                                   |

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_commissioning_api.h

@@ -29,8 +29,12 @@ extern "C" {
 
 #include "ns_types.h"
 
-#define TRACE_GROUP_THREAD_COMMISSIONING_API "TCoA"
+#define TRACE_GROUP_THREAD_COMMISSIONING_API "TCoA"  /**< trace group definition */
 
+/**
+ * /enum commissioning_state_e
+ * /brief Commissioning states.
+ */
 typedef enum {
     COMMISSIONING_STATE_ACCEPT,
     COMMISSIONING_STATE_PENDING,
@@ -41,6 +45,7 @@ typedef enum {
 /** \brief Commissioning petition response callback.
  *
  * \param interface_id Network interface ID. The request comes from this ID.
+ * \param commissioner_session_id Commissioner session ID.
  * \param state State of the commissioning.
  *
  * \return 0 success, other values failure.
@@ -56,7 +61,6 @@ typedef int (thread_commissioning_status_cb)(int8_t interface_id, uint16_t commi
  *
  * \param interface_id Interface ID where the request was made.
  * \param PSKc Pre-shared key between the commissioner and the Thread network.
- * \param PSKc_len The length of the PSKc.
  *
  * \return 0 success, other values failure.
  */
@@ -77,7 +81,8 @@ int thread_commissioning_unregister(int8_t interface_id);
  * If the commissioner is insecure, you need to scan the networks and select the Thread network where you want to be a commissioner.
  *
  * \param interface_id Network interface ID. The request comes from this ID.
- * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
+ * \param commissioner_id_ptr NUL terminated commissioner ID string.
+ * \param status_cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
  * \return 0 Indicates success.
  *
  * \return -1 The client needs to scan the network to become an insecure commissioner.
@@ -87,10 +92,10 @@ int thread_commissioning_petition_start(int8_t interface_id, char *commissioner_
 
 /** \brief Send petition keep alive.
  *
- * This function must be called in 40 second intervals. TODO rethink if this should be automatic
+ * This function must be called in 40 second intervals. TODO rethink if this should be automatic.
  *
  * \param interface_id Network interface ID. The request comes from this ID.
- * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
+ * \param state Commissioning state.
  *
  * \return 0 success, other values failure.
  */
@@ -119,21 +124,19 @@ int thread_commissioning_petition_keep_alive(int8_t interface_id, commissioning_
 typedef int (thread_commissioning_joiner_finalisation_cb)(int8_t interface_id, uint8_t EUI64[8], uint8_t *message_ptr, uint16_t message_len);
 
 /** \brief Add a device to commission to the Thread network.
- *
  *
  * \param interface_id Network interface ID. The request comes from this ID.
  * \param short_eui64 A boolean value indicating that short EUI version is used for bloom filter generation.
  * \param EUI64 A pointer to EUI64 buffer.
  * \param PSKd_ptr A pointer to PSKd buffer.
  * \param PSKd_len PSKd string length, current validity check is 1-32 bytes.
- * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
+ * \param joining_device_cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
  *
  * \return 0 success, other values failure
  */
 int thread_commissioning_device_add(int8_t interface_id, bool short_eui64, uint8_t EUI64[8], uint8_t *PSKd_ptr, uint8_t PSKd_len, thread_commissioning_joiner_finalisation_cb *joining_device_cb_ptr);
 
 /** \brief Delete a device to commission to the Thread network.
- *
  *
  * \param interface_id Network interface ID. The request comes from this ID.
  * \param EUI64 A pointer to EUI64 buffer.
@@ -148,7 +151,8 @@ int thread_commissioning_device_delete(int8_t interface_id, uint8_t EUI64[8]);
  * \param interface_id Network interface ID. The request comes from this ID.
  * \param short_eui64 A boolean value indicating that short EUI version is used for bloom filter generation. Can be NULL when no result wanted.
  * \param EUI64 A pointer to EUI64 buffer. Can be NULL when no result wanted.
- * \param PSKd_ptr A pointer to PSKd buffer. Can be NULL when no result wanted.
+ * \param PSKd A pointer to PSKd buffer. Can be NULL when no result wanted.
+ * \param PSKd_len Length of data in PSKd.
  *
  * \return >NULL for next iteration.
  * \return NULL when end of list.
@@ -182,7 +186,9 @@ typedef struct thread_commissioning_link_configuration {
  * This callback is called when networks that allow native commissioner to join are found.
  * Pointers are valid during this call.
  *
- * \param interface Interface ID of this Thread instance.
+ * \param interface_id Interface ID of this Thread instance.
+ * \param count Count of link configurations
+ * \param link_ptr Poiner to Commissioning link configuration
  *
  */
 typedef void thread_commissioning_native_select_cb(int8_t interface_id, uint8_t count, thread_commissioning_link_configuration_s *link_ptr );
@@ -192,7 +198,8 @@ typedef void thread_commissioning_native_select_cb(int8_t interface_id, uint8_t
  * Starts the network scan mode to find networks where the device can become a native commissioner.
  * This stops the normal Thread joining process and informs the application of available networks.
  *
- * \param interface Interface ID of this Thread instance.
+ * \param interface_id Interface ID of this Thread instance.
+ * \param cb_ptr Callback function
  *
  * \return 0 success, other values failure.
  */
@@ -202,7 +209,7 @@ int thread_commissioning_native_commissioner_start(int8_t interface_id, thread_c
  *
  * Stops the network scan mode and continues the normal joining process.
  *
- * \param interface Interface ID of this Thread instance.
+ * \param interface_id Interface ID of this Thread instance.
  *
  * \return 0 success, other values failure.
  */
@@ -220,7 +227,8 @@ int thread_commissioning_native_commissioner_stop(int8_t interface_id);
  *
  * Matching of thread network is made using Network name, Xpanid, panid, TODO channel?? or not? gives channel flexibility
  *
- * \param interface Interface ID of this Thread instance.
+ * \param interface_id Interface ID of this Thread instance.
+ * \param link_ptr Pointer to Commissioning link configuration.
  *
  * \return 0 success, other values failure.
  */
@@ -232,7 +240,6 @@ int thread_commissioning_native_commissioner_connect(int8_t interface_id, thread
  * \param interface_id Network interface ID.
  * \param address_ptr A pointer to address buffer (16 bytes) for the commission messages.
  * \param port Return the port for the commissioner.
- * \param PSKc_ptr A pointer to return buffer for the PSKc (16 bytes) of this network instance.
  *
  * \return 0, address OK.
  * \return <0 fail.

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_dhcpv6_server.h

@@ -29,6 +29,8 @@
  *
  * \param interface_id Network Interface
  * \param prefix_ptr pointer DHCPv6 Server Given Prefix
+ * \param max_client_cnt Max number of clients
+ * \param stableData True if data is stable
  *
  * \return 0, Set OK
  * \return <0 Set Not OK

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_diagcop_lib.h

@@ -40,7 +40,7 @@
 #define DIAGCOP_TLV_SUPPLY_VOLTAGE                          15  /**< Can not reset*/
 #define DIAGCOP_TLV_CHILD_TABLE                             16  /**< Can not reset*/
 #define DIAGCOP_TLV_CHANNEL_PAGES                           17  /**< Can not reset*/
-#define DIAGCOP_TLV_TYPE_LIST                               18
+#define DIAGCOP_TLV_TYPE_LIST                               18  /**< List type*/
 
 /**
  * \brief Write array TLV.
@@ -99,7 +99,7 @@
  * \param ptr Message buffer.
  * \param length Length of the message buffer to validate message.
  * \param type Type of TLV searched.
- * \param result_ptr Pointer value is given as result if length is positive. Can be NULL which only searches for the length.
+ * \param result Pointer value is given as result if length is positive. Can be NULL which only searches for the length.
  * \return The length of the TLV data found
  * \return 0 if TLV is empty or no TLV found.
  * \return negative value indicates corrupted message.
@@ -112,7 +112,7 @@
  * \param ptr pointer TLV message array.
  * \param length length of TLV message array.
  * \param type Type of TLV.
- * \param data_ptr pointer to variable where the value is read.
+ * \param data pointer to variable where the value is read.
  * \return pointer length of TLV 1 if success. 0 means TLV not found or does not have any data.
  * Any other value indicates that TLV is not as expected.
  */
@@ -124,7 +124,7 @@
  * \param ptr pointer TLV message array.
  * \param length length of TLV message array.
  * \param type Type of TLV.
- * \param data_ptr pointer to variable where the value is read.
+ * \param data pointer to variable where the value is read.
  * \return pointer length of TLV 2 if success. 0 means TLV not found or does not have any data.
  * Any other value indicates that TLV is not as expected.
  */
@@ -136,7 +136,7 @@
  * \param ptr pointer TLV message array.
  * \param length length of TLV message array.
  * \param type Type of TLV.
- * \param data_ptr pointer to variable where the value is read.
+ * \param data pointer to variable where the value is read.
  * \return pointer length of TLV 4 if success. 0 means TLV not found or does not have any data.
  * Any other value indicates that TLV is not as expected.
  */
@@ -148,7 +148,7 @@
  * \param ptr pointer TLV message array.
  * \param length length of TLV message array.
  * \param type Type of TLV.
- * \param data_ptr pointer to variable where the value is read.
+ * \param data pointer to variable where the value is read.
  * \return pointer length of TLV 4 if success. 0 means TLV not found or does not have any data.
  * Any other value indicates that TLV is not as expected.
  */

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_lowpower_api.h

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2017 ARM Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: LicenseRef-PBL
+ *
+ * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.mbed.com/licenses/PBL-1.0
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ *
+ */
+
+/**
+ * \file thread_lowpower_api.h
+ * \brief Nanostack Thread lowpower probe implementation. Responsible for tasks like
+ * request link metrics by sending data requests.
+ */
+
+#ifndef THREAD_LOWPOWER_API_H_
+#define THREAD_LOWPOWER_API_H_
+
+#include <ns_types.h>
+
+/** \brief callback function that returns the received metrics
+ *
+ * \param destination_address address to which the lowpower query is sent
+ * \param interface_id interface_id of destination
+ * \param metrics_ptr Pointer to metrics
+ * \param metrics_len Length of metrics_ptr
+ *
+ * \return metrics_ptr if response received, NULL if no response is received
+ * \return metrics_len length of the response received, 0 if NULL response is received
+ *
+ */
+typedef int (thread_lowpower_resp_cb)(uint8_t *destination_address, int8_t interface_id, uint8_t *metrics_ptr, uint16_t metrics_len);
+
+/** \brief Send lowpower data request for requesting low power metrics
+ *
+ * \param interface_id Interface ID of the Thread network.
+ * \param destination_address destination ll64 address
+ * \param metrics_ptr array of metrics to be measured
+ * \param metrics_len length of the metrics array
+ * \param response_cb callback function called to return values after execution
+ *
+ * \return 0 if data request successfully initiated.
+ *
+ */
+int thread_lowpower_test_probe_send(int8_t interface_id, uint8_t *destination_address, uint8_t *metrics_ptr, uint8_t metrics_len, thread_lowpower_resp_cb response_cb);
+
+#endif /*THREAD_LOWPOWER_API_H_ */

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_management_api.h

@@ -43,7 +43,7 @@ extern "C" {
 
 #include "ns_types.h"
 
-#define TRACE_GROUP_THREAD_MANAGEMENT_API "TMaA"
+#define TRACE_GROUP_THREAD_MANAGEMENT_API "TMaA"  /**< trace group definition */
 
 /** Thread management state
  */
@@ -163,11 +163,14 @@ int thread_management_get(int8_t instance_id, uint8_t dst_addr[static 16], char
  *
  * \param instance_id Instance ID of the management session.
  * \param dst_addr Destination address, the address of a remote device where it is desired to setup management information. If however, the address is not provided, a request is sent to leader of the network for this purpose. If a  native commissioner is being used, the rquest for setting up management information is sent to the Border router.
-  * \param uri_ptr The ASCII string for the URI. This string identifies the CoAP URI for the desired resource, for example, /c/ms identifies the the management set information resource.
+ * \param uri_ptr The ASCII string for the URI. This string identifies the CoAP URI for the desired resource, for example, /c/ms identifies the the management set information resource.
  * \param data_ptr A pointer to the desired set of TLVs. 
  * \param data_len count of the members (no. of TLVs) in the TLV set.
  * \param cb_ptr A callback function carrying the result of the operation.
  *
+ * \return 0, Success
+ * \return <0 Fail.
+ *
  */
 int thread_management_set(int8_t instance_id, uint8_t dst_addr[static 16], char *uri_ptr, uint8_t *data_ptr, uint8_t data_len, management_set_response_cb *cb_ptr);
 

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_management_if.h

@@ -35,8 +35,9 @@ extern "C" {
 /*
  * Current protocol version of the Thread implementation.
  */
-#define THREAD_BEACON_PROTOCOL_ID       3
-#define THREAD_BEACON_PROTOCOL_VERSION  1
+#define THREAD_BEACON_PROTOCOL_ID       3   /**< Beacon Protocol ID */
+#define THREAD_BEACON_PROTOCOL_VERSION  1   /**< Beacon Protocol version */
+
 /**
  * Thread network configuration.
  *
@@ -63,8 +64,8 @@ typedef struct link_configuration {
     uint8_t extended_random_mac[8]; /**< Extended random mac which is generated during commissioning*/
     uint8_t channel_mask[8]; /**< channel page and mask only supported is page 0*/
     uint8_t channel_page;/**< channel page supported pages 0*/
-    char *PSKc_ptr; /**< Commissioning credentials @TODO think if we need the actual credentials*/
-    uint8_t PSKc_len;
+    char *PSKc_ptr; /**< Commissioning credentials.  TODO! think if we need the actual credentials*/
+    uint8_t PSKc_len; /**< Length of PSKc */
     uint16_t key_rotation; /**< Key rotation time in hours*/
     uint32_t key_sequence; /**< Key sequence counter */
     uint16_t panId; /**< network id*/
@@ -93,7 +94,7 @@ typedef struct link_configuration {
 typedef struct {
     uint8_t eui64[8];/**< eui64 of the device. This field is used to identify device when joining to network Mandatory*/
     uint8_t *PSKd_ptr;/**< Device credentials used to authenticate device to commissioner Mandatory  length 6-32*/
-    uint8_t PSKd_len;
+    uint8_t PSKd_len;/**< Length of PSKd_ptr*/
     char *provisioning_uri_ptr;/**< Provisioning url max 64 bytes*/
     char *vendor_name_ptr;/**< Vendor name optional max 32 bytes*/
     char *vendor_model_ptr;/**< Vendor model optional max 32 bytes*/
@@ -108,7 +109,7 @@ typedef struct {
  * Initialize Thread stack to node mode.
  *
  * If static configuration is given and new one is updated by commissioner
- * it will override current setup. it is save to always give this as
+ * it will override current setup. it is safe to always give this as
  * default configuration.
  *
  * \param interface_id Network interface ID.
@@ -154,7 +155,6 @@ typedef enum {
  * \return 0, Set OK.
  * \return <0 Set fail.
  */
-
 int thread_management_device_type_set(int8_t interface_id, thread_device_type_e device_type);
 
 /**
@@ -206,7 +206,7 @@ int thread_management_link_configuration_delete(int8_t interface_id);
  *
  * \param interface_id Network interface ID.
  *
- * \return Pointer to link configuration.
+ * \return Pointer to Device configuration.
  * \return NULL Failure.
  */
 device_configuration_s *thread_management_device_configuration_get(int8_t interface_id);
@@ -227,10 +227,10 @@ int thread_management_max_child_count(
     uint8_t maxChildCount);
 
 /**
- * Get Thread device link timeout.
+ * Set Thread device link timeout.
  *
  * \param interface_id Network interface ID.
- * \link_timeout New timeout value in seconds.
+ * \param link_timeout New timeout value in seconds.
  *
  * \return 0, Set OK.
  * \return <0 Set Fail.
@@ -238,10 +238,10 @@ int thread_management_max_child_count(
 int8_t thread_management_set_link_timeout(int8_t interface_id, uint32_t link_timeout);
 
 /**
- * Set link timeout for Thread device.
+ * Get link timeout from Thread device.
  *
  * \param interface_id Network interface ID.
- * \link_timeout[out] A pointer to the location for writing the timeout.
+ * \param link_timeout [out] A pointer to the location for writing the timeout.
  *
  * \return 0, Get OK
  * \return <0 Get Fail
@@ -263,7 +263,8 @@ int8_t thread_management_set_request_full_nwk_data(int8_t interface_id, bool ful
  * Get Thread request full network data.
  *
  * \param interface_id Network interface ID.
- * \link_timeout[out] A pointer to the location for writing the flag value.
+ * \param link_timeout [out] A pointer to the location for writing the flag value.
+ * \param full_nwk_data Request full network data
  *
  * \return 0, Get OK.
  * \return <0 Get Fail.

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_meshcop_lib.h

@@ -29,27 +29,45 @@
 /**
  * Network configuration TLV
  */
+/** Channel TLV. */
 #define MESHCOP_TLV_CHANNEL                                0
+/** PANID TLV. */
 #define MESHCOP_TLV_PANID                                  1
+/** Extended PANID TLV. */
 #define MESHCOP_TLV_XPANID                                 2
+/** Network Name TLV. */
 #define MESHCOP_TLV_NETWORK_NAME                           3
+/** PSKc TLV. */
 #define MESHCOP_TLV_PSKC                                   4
+/** Network Master key TLV. */
 #define MESHCOP_TLV_NETWORK_MASTER_KEY                     5
+/** Network Key Sequence TLV. */
 #define MESHCOP_TLV_NETWORK_KEY_SEQUENCE                   6
+/** Mesh Local Ula prefix TLV. */
 #define MESHCOP_TLV_NETWORK_MESH_LOCAL_ULA                 7
 
 /**
  * Network management TLV
  */
+/** Steering data TLV. */
 #define MESHCOP_TLV_STEERING_DATA                          8
+/** Border router locator TLV. */
 #define MESHCOP_TLV_BORDER_ROUTER_LOCATOR                  9
+/** Commissioner ID TLV. */
 #define MESHCOP_TLV_COMMISSIONER_ID                        10
+/** Commissioner session ID TLV. */
 #define MESHCOP_TLV_COMMISSIONER_SESSION_ID                11
+/** Security Policy TLV. */
 #define MESHCOP_TLV_SECURITY_POLICY                        12
+/** GET TLV. */
 #define MESHCOP_TLV_GET                                    13
+/** Active Timestamp TLV. */
 #define MESHCOP_TLV_ACTIVE_TIME_STAMP                      14
+/** Commissioner UDP port TLV. */
 #define MESHCOP_TLV_COMMISSIONER_UDP_PORT                  15
+/** state TLV. */
 #define MESHCOP_TLV_STATE                                  16
+/** Joiner UDP port TLV. */
 #define MESHCOP_TLV_JOINER_UDP_PORT                        18
 
 /**
@@ -60,44 +78,74 @@
 /**
  * Relay message TLV
  */
+/** Joiner Encapsulation TLV. */
 #define MESHCOP_TLV_JOINER_ENCAPSULATION                   17
+/** Joiner UDP port TLV. */
 #define MESHCOP_TLV_JOINER_UDP_PORT                        18
+/** Joiner IID TLV. */
 #define MESHCOP_TLV_JOINER_IID                             19
+/** Joiner Router locator TLV. */
 #define MESHCOP_TLV_JOINER_ROUTER_LOCATOR                  20
+/** Key Exchange Key TLV. */
 #define MESHCOP_TLV_JOINER_ROUTER_KEK                      21
 
 /**
- * Application provisioning TLV?
+ * Application provisioning TLVs
  */
+/** Provisioning URL TLV. */
 #define MESHCOP_TLV_PROVISIONING_URL                       32
+/** Vendr Name TLV. */
 #define MESHCOP_TLV_VENDOR_NAME                            33
+/** Vendor Model TLV. */
 #define MESHCOP_TLV_VENDOR_MODEL                           34
+/** Vendor SW version TLV. */
 #define MESHCOP_TLV_VENDOR_SW_VERSION                      35
+/** Vendor Data TLV. */
 #define MESHCOP_TLV_VENDOR_DATA                            36
+/** Vendor Stack Version TLV. */
 #define MESHCOP_TLV_VENDOR_STACK_VERSION                   37
 
 /**
  * Tunneling
  */
+/** UDP encapsulation TLV. */
 #define MESHCOP_TLV_UDP_ENCAPSULATION                      48
+/** IPv6 address TLV. */
 #define MESHCOP_TLV_IPV6_ADDRESS                           49
+/** TMF Forwarding Port TLV. */
 #define MESHCOP_TLV_TMF_FORWARDING_PORT                    50
 
 /**
- * 1.1 new feature TLV
+ * Thread management interface TLVs
  */
+/** Pending Timestamp TLV. */
 #define MESHCOP_TLV_PENDING_TIMESTAMP                      51
+/** Delay timer for pending configuration TLV. */
 #define MESHCOP_TLV_DELAY_TIMER                            52
+/** Channel mask TLV. */
 #define MESHCOP_TLV_CHANNEL_MASK                           53
+/** Count TLV. */
 #define MESHCOP_TLV_COUNT                                  54
+/** Period TLV. */
 #define MESHCOP_TLV_PERIOD                                 55
+/** Duration TLV. */
 #define MESHCOP_TLV_DURATION                               56
+/** Energy List TLV. */
 #define MESHCOP_TLV_ENERGY_LIST                            57
+
+/** Discovery Request TLV. */
 #define MESHCOP_TLV_DISCOVERY_REQUEST                      128
+/** Discovery response TLV. */
 #define MESHCOP_TLV_DISCOVERY_RESPONSE                     129
 
+/** @defgroup Thread 1.2 experimental */
+
+/** Timeout TLV. */
 #define MESHCOP_TLV_TIMEOUT                                58
 
+/** Domain prefix TLV TLV.*/
+#define MESHCOP_TLV_DOMAIN_PREFIX                          60
+
 /**
  * Write array TLV.
  *
@@ -191,6 +239,87 @@ bool thread_meshcop_tlv_exist(const uint8_t *ptr, const uint16_t length, const u
  */
 uint16_t thread_meshcop_tlv_find(const uint8_t *ptr, const uint16_t length, const uint8_t type, uint8_t **result_ptr);
 
+/**
+ * Get length of the TLV.
+ *
+ * \param ptr Message buffer.
+ * \param length Length of the message buffer to validate message.
+ *
+ * \return The length of the TLV data found
+ * \return 0 if TLV is empty.
+ * \return negative value indicates corrupted message or no TLV present.
+ */
+int16_t thread_meshcop_tlv_length(const uint8_t *ptr, uint16_t length);
+
+/**
+ * Get length of the TLV including the type and length field.
+ *
+ * \param ptr Message buffer.
+ * \param length Length of the message buffer to validate message.
+ *
+ * \return The length of the TLV data found
+ * \return 0 if TLV is empty.
+ * \return negative value indicates corrupted message or no TLV present.
+ */
+int16_t thread_meshcop_tlv_length_required(const uint8_t *ptr, uint16_t length);
+
+/**
+ * Go through TLV list in order.
+ *
+ * \param ptr Message buffer.
+ * \param length Length of the message buffer to validate message. Length value modified to remaining value or 0 when no more TLVs present
+ *
+ * \return ptr to the next TLV
+ * \return NULL if no TLV found.
+ */
+const uint8_t *thread_meshcop_tlv_get_next(const uint8_t *ptr, uint16_t *length);
+
+/**
+ * Validate that required TLVs are present in the buffer.
+ *
+ * \param ptr TLV message buffer.
+ * \param length Length of the TLV message buffer.
+ * \param required_tlv_ptr buffer where the IDs of TLVs that are must be present
+ * \param required_tlv_len Amount of TLVs
+ *
+ * \return amount of TLVs present in the buffer.
+ */
+bool thread_meshcop_tlv_list_present(const uint8_t *ptr, uint16_t length, const uint8_t *required_tlv_ptr, uint8_t required_tlv_len);
+
+/**
+ * Get list of TLVS included in the buffer.
+ *
+ * \param ptr TLV message buffer.
+ * \param length Length of the TLV message buffer.
+ * \param result_ptr [OUT] buffer where the IDs of TLVs are written. can be NULL when counting amount of TLVs
+ * \param result_len [OUT] Amount of TLVs written in buffer
+ *
+ * \return amount of TLVs present in the buffer.
+ */
+uint16_t thread_meshcop_tlv_list_generate(const uint8_t *ptr, uint16_t length,uint8_t *result_ptr, uint16_t *result_len);
+
+/**
+ * Remove TLV from list of TLVs.
+ *
+ * \param tlv_ptr pointer to TLV List buffer.
+ * \param tlv_len Length of the TLV list buffer.
+ * \param tlv_type TLV that is removed from the List
+ *
+ * \return amount of TLVs present in the buffer.
+ */
+uint16_t thread_meshcop_tlv_list_remove(uint8_t *tlv_ptr, uint16_t tlv_len, uint8_t tlv_type);
+
+/**
+ * Check if specific type is available in list of TLVs.
+ *
+ * \param list_ptr Pointer to TLV list buffer.
+ * \param list_len Length of the TLV list buffer.
+ * \param tlv_type TLV type to be find from the list
+ *
+ * \return true if type exists, false if type does not exist.
+ */
+bool thread_meshcop_tlv_list_type_available(const uint8_t *list_ptr, uint16_t list_len, uint8_t tlv_type);
+
 /**
  * Find next TLV from message.
  *

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/thread_net_config_api.h

@@ -26,7 +26,7 @@ extern "C" {
 
 #include "ns_types.h"
 
-/*
+/**
   * \brief function callback type for nd_data_request.
   *
   * \param inteface_id Network interface ID where request was made.