Nanostack 6.0.1

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

@@ -82,16 +82,17 @@ Member|Description
 Event type|Description
 ----------|-----------
 `SOCKET_DATA`|Data received.
-`SOCKET_BIND_DONE`|TCP connection ready.
-`SOCKET_BIND_FAIL`|TCP connection failed.
-`SOCKET_BIND_AUTH_FAIL`|TCP connection authentication failed.
+`SOCKET_CONNECT_DONE`|TCP connection ready.
+`SOCKET_CONNECT_FAIL`|TCP connection failed.
+`SOCKET_CONNECT_AUTH_FAIL`|TCP connection authentication failed.
 `SOCKET_INCOMING_CONNECTION`|TCP connection state change from listen to establishment.
 `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_TX_DONE`|Last socket TX process done, in TCP case whole TCP process is ready.
+`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).
 
 An example parsing socket event:
 
@@ -102,7 +103,7 @@ An example parsing socket event:
 static uint8_t rx_buffer[APP_SOCK_RX_SIZE];
 
 void main_receive
-(
+(SOCKET_NO_ROUTER
 	void *cb
 )
 {
@@ -248,6 +249,31 @@ Parameter|Description
 <dd>-6 bind2addrsel is not supported on this type of socket.</dd>
 </dl>
 
+### How to connect a socket
+
+To connect a socket to a remote host:
+
+```
+int8_t socket_connect
+(
+	int8_t			socket,
+	ns_address_t	*address,
+	uint8_t			randomly_take_src_numbers
+)
+```
+
+Parameter|Description
+---------|-----------
+`socket`|The socket ID, which is used to connect to the remote host.
+`address`|A pointer to an <code>address_t</code> structure that contains the address of the remote host.
+`randomly_take_src_numbers`|Value 1 indicates that a randomly selected source port number is used.
+
+<dl>
+<dt>Return value</dt>
+<dd>0 Valid request.</dd>
+<dd>-1 Fail.</dd>
+</dl>
+
 ### How to read data from a socket
 
 To read received data from a socket:
@@ -300,9 +326,9 @@ _Table 3-24_ describes the possible response events when the outcome of the func
 
 Response Event|Socket Type|Description
 --------------|-----------|-----------
-`SOCKET_TX_DONE`|TCP/UDP|UDP link layer TX ready/TCP TX process ready by TCP _Acknowledgement_ (ACK).
-`SOCKET_TX_FAIL`|UDP|UDP link layer TX fails.
-`SOCKET_CONNECTION_RESET`|TCP|TX process fails and connection closed.
+`SOCKET_TX_DONE`|TCP/UDP|UDP: link layer TX ready (d_len = length of datagram). TCP: some data acknowledged (d_len = unacknowledged data remaining in send queue).
+`SOCKET_TX_FAIL`|TCP/UDP|UDP: link layer TX fails. TCP: transmit timeout (no ACKs) and connection closed.
+`SOCKET_CONNECTION_RESET`|TCP|Either the peer reset the connection or there was a protocol error. Connection closed.
 
 To transmit data on an unconnected socket:
 
@@ -364,7 +390,7 @@ The TCP socket configuration API offers three function calls, as shown in _Table
 Function|Description
 --------|-----------
 `socket_listen()`|Set socket to the listen state.
-`socket_connect()`|Connect socket to a host.
+`socket_accept()`|Accepts an incoming TCP connection.
 `socket_shutdown()`|Shut down socket connection.
 
 To set a TCP socket into the listen state:
@@ -380,47 +406,50 @@ int8_t socket_listen
 Parameter|Description
 ---------|-----------
 `socket`|The socket ID that is to be set to the listen state.
-`backlog`|The pending connections queue size. (Not yet implemented).
+`backlog`|The pending connections queue size.
 
 <dl>
 <dt>Return value</dt>
 <dd>0 Valid request.</dd>
-<dd><b>Note:</b> This does not imply that the state of the socket has been successfully changed.</dd>
 <dd>-1 Fail.</dd>
 </dl>
 
-To connect a socket to a remote host:
+For connecting a socket, please refer to the section  above [How to connect a socket](#how-to-connect-a-socket). 
+
+There are three possible responses from the stack for `socket_connect( )`:
+
+- `SOCKET_CONNECT_DONE`
+	- TCP handshake ready.
+
+- `SOCKET_CONNECT_FAIL`
+	- TCP handshake fail - connection actively refused or protocol error.
+
+- `SOCKET_TX_FAIL`
+	- TCP handshake fail - timed out.
+
+For accepting an incoming TCP connection, use `socket_accept()` function.
 
 ```
-int8_t socket_connect
+int8_t socket_accept()
 (
-	int8_t			socket,
-	ns_address_t	*address,
-	uint8_t			randomly_take_src_numbers
+	int8_t	listen_socket_id,
+	ns_address_t	*addr,
+    void (*passed_fptr)  (void *)
 )
 ```
 
 Parameter|Description
 ---------|-----------
-`socket`|The socket ID, which is used to connect to the remote host.
-`address`|A pointer to an <code>address_t</code> structure that contains the address of the remote host.
-`randomly_take_src_numbers`|Value 1 indicates that a randomly selected source port number is used.
+`listen_socket_id`|The socket ID of the listening socket.
+`addr`|Pointer to the address structure where you wish to save the address
+`passed_fptr`|A function pointer to a function that is called whenever a data frame is received to the new socket
 
 <dl>
 <dt>Return value</dt>
-<dd>0 Valid request.</dd>
-<dd><b>Note:</b>This does not imply that the state of the socket has been successfully changed.</dd>
+<dd>0 or greter than zero, i.e.,  id for the new socket.</dd>
 <dd>-1 Fail.</dd>
 </dl>
 
-There are two possible responses from the stack for `socket_connect( )`:
-
-- `SOCKET_BIND_DONE`
-	- TCP handshake ready.
-
-- `SOCKET_CONNECT_FAIL_CLOSED`
-	- TCP handshake fail.
-
 To shut down a TCP connection:
 
 ```

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/16_API_porting.md

@@ -59,7 +59,9 @@ initializing.
 
 ![NanostackRfPhy](img/NanostackRfPhy.png)
 
-Applications use only `LoWPANNDInterface` or `ThreadInterface` directly to set up the network and provide a driver. Rest of the classes provide an abstration between Nanostack and Socket layers of mbed OS.
+Applications use only `LoWPANNDInterface`, `ThreadInterface` or `NanostackEthernetInterface`
+directly to set up the network and provide a driver. Rest of the classes provide an abstration
+between Nanostack and 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.
 

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/img/NanostackRfPhy.plantuml.txt

@@ -1,28 +1,66 @@
 @startuml
 
-class NanostackRfPhy {
-    +int8_t rf_register()
-    +int8_t rf_register()
-    +void get_mac_address(uint8_t *mac)
-    +void set_mac_address(uint8_t *mac)
+package "mbed OS Socket abstraction" {
+    abstract class MeshInterface -|> NetworkInterface
+
+    interface NetworkInterface {
+        +connect();
+        +disconnect();
+        +NetworkStack *get_stack();
+    }
+
+    interface NetworkStack
 }
 
-class MeshInterfaceNanostack {
+package "Nanostack PHY driver interface" {
+    interface NanostackPhy {
+        +int8_t phy_register()
+        +void get_mac_address(uint8_t *mac)
+        +void set_mac_address(uint8_t *mac)
+    }
+    NanostackPhy <|-- abstract class NanostackRfPhy
+    NanostackPhy <|-- abstract class NanostackEthernetPhy
+}
+
+package "mesh API internals" {
+    class NanostackInterface {
+        {static} +NanostackInterface *get_stack()
+        #socket_open()
+        #socket_close()
+        #socket_bind()
+        #socket_listen()
+        #socket_connect()
+        #socket_accept()
+        #socket_send()
+        #socket_recv()
+        #socket_sendto()
+        #socket_recvfrom()
+        #socket_attach()
+        #setsockopt()
+        #getsockopt()
+    }
+    NetworkStack <|-- NanostackInterface
+
+    abstract class MeshInterfaceNanostack {
+    +initialize(NanostackPhy *phy)
+    +connect()
+    +disconnect()
+    #NetworkStack *get_stack(void)
+    }
+    MeshInterface <|-- MeshInterfaceNanostack
+    NanostackPhy --o MeshInterfaceNanostack
+    MeshInterfaceNanostack -left-> NanostackInterface : get_stack()
 }
-MeshInterfaceNanostack o-- NanostackRfPhy
-MeshInterfaceNanostack o-- AbstractMesh
-MeshInterfaceNanostack o-- NanostackInterface
 
-class MeshInterface {
+package "mbed-mesh-api" {
+    MeshInterfaceNanostack <|-- LoWPANNDInterface
+    MeshInterfaceNanostack <|-- ThreadInterface
+    MeshInterfaceNanostack <|-- NanostackEthernetInterface
 }
-NanostackInterface --|> NetworkStack
-MeshInterfaceNanostack --|> MeshInterface
-MeshInterface --|> NetworkInterface
 
-LoWPANNDInterface --|> MeshInterfaceNanostack
-ThreadInterface --|> MeshInterfaceNanostack
 
-AbstractMesh --|> AbstractNetworkInterface
-class AbstractNetworkInterface
+hide empty members
+hide empty attributes
+hide empty fields
 
-@enduml
+@enduml

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/img/mbedOS_sockets.plantumlt.txt

@@ -0,0 +1,28 @@
+@startuml
+
+package "mbed OS Socket abstraction" {
+    interface NetworkStack
+    NetworkStack -o Socket
+    abstract class Socket
+    Socket <|-- UDPSocket
+    Socket <|-- TCPSocket
+    Socket <|-- TCPServer
+}
+
+interface NetworkInterface
+NetworkInterface --> NetworkStack : get_stack()
+EthernetInterface --|> NetworkInterface
+CellularInterface --|> NetworkInterface
+
+package "mbed-mesh-api" {
+    abstract class MeshInterfaceNanostack <|-- LoWPANNDInterface
+    MeshInterfaceNanostack <|-- ThreadInterface
+    MeshInterfaceNanostack --|> NetworkInterface
+}
+
+
+hide empty members
+hide empty attributes
+hide empty fields
+
+@enduml

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

@@ -380,14 +380,37 @@ Parameter|Description
 
 ### Collecting Thread management information
 
-The function `thread_management_info_get()` is used to collect Thread management related information from the Leader Router.
+#### Fetching Thread Management Information
+
+The function `thread_management_get()` is used to collect Thread management related information from the any device in the Thread network.
+
+Parameter|Description
+-----------|-----------
+`instance_id`|Instance ID of the management session.
+`dst_addr` |Destination address; the address of a remote device from whome it is desirable to fetch management information. If however, the address is not provided, a request is sent to the leader of the network for this purpose. If a native commissioner is used, the request for management information is sent to the border router.
+`uri_ptr` |The ASCII string for the URI. This string identifies the CoAP URI for the desired resource. For example, `/c/mg` identifies the management get information resource.
+`fields_ptr`|A pointer to management fields; a set of TLVs. A list of such TLVs can be found in `thread_meshcop_lib.h`.
+`field_count`|Number of fields in the field pointer array (set of TLVs).
+`cb_ptr`|A pointer to `management_get_response_cb` callback function carrying the result of the operation.
+
+<dl>
+<dt>Response</dt>
+<dd> 0, success.</dd>
+<dd><0, failure.</dd>
+</dl>
+
+#### Setting up Thread Management Information
+
+The function `thread_management_set()` is used to set up Thread management related information to any device in the Thread network.
 
 Parameter|Description
 -----------|-----------
 `instance_id`|Instance ID of the management session.
-`fields_ptr`|A pointer to management fields from which the information is fetched.
-`field_count`|Number of fields in the field pointer array.
-`cb_ptr`|A pointer to `management_get_response_cb` callback function.
+`dst_addr` |Destination address; the address of a remote device where it is desired to set up management information. If however, the address is not provided, a request is sent to the leader of the network for this purpose. If a native commissioner is used, the request for setting up management information is sent to the border router.
+`uri_ptr` |The ASCII string for the URI. This string identifies the CoAP URI for the desired resource. For example, `/c/ms` identifies the management set information resource.
+`data_ptr`|A pointer to the desired set of TLVs. 
+`field_count`|Number of fields in the field pointer array (set of TLVs).
+`cb_ptr`|A pointer to `management_get_response_cb` callback function carrying the result of the operation.
 
 <dl>
 <dt>Response</dt>

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

@@ -79,21 +79,21 @@ extern int8_t ethernet_mac_destroy(eth_mac_api_t *mac_api);
  * @param api API to handle the request
  * @param data Data containing request parameters
  */
-typedef void data_request(const eth_mac_api_t* api, const eth_data_req_t *data);
+typedef void eth_mac_data_request(const eth_mac_api_t* api, const eth_data_req_t *data);
 
 /**
  * @brief data_confirm confirm is called as a response to data_request
  * @param api The API which handled the request
  * @param data Data containing confirm parameters
  */
-typedef void data_confirm(const eth_mac_api_t* api, const eth_data_conf_t *data );
+typedef void eth_mac_data_confirm(const eth_mac_api_t* api, const eth_data_conf_t *data );
 
 /**
  * @brief data_indication Data indication is called when MAC layer has received data
  * @param api The API which handled the response
  * @param data Data containing indication parameters
  */
-typedef void data_indication(const eth_mac_api_t* api, const eth_data_ind_t *data );
+typedef void eth_mac_data_indication(const eth_mac_api_t* api, const eth_data_ind_t *data );
 
 /**
  * @brief Set 48 bit address from MAC
@@ -119,15 +119,15 @@ typedef int8_t eth_mac_mac48_address_get(const eth_mac_api_t* api, uint8_t *mac4
  * @param parent_id Upper layer identifier
  * @return 0 if success; -1 if api is NULL or not found
  */
-typedef int8_t eth_mac_api_initialize(eth_mac_api_t *api, data_confirm *conf_cb,
-                                       data_indication *ind_cb, uint8_t parent_id);
+typedef int8_t eth_mac_api_initialize(eth_mac_api_t *api, eth_mac_data_confirm *conf_cb,
+                                       eth_mac_data_indication *ind_cb, uint8_t parent_id);
 
 struct eth_mac_api_s {
     eth_mac_api_initialize      *mac_initialize;
 
-    data_request                *data_req;
-    data_confirm                *data_conf_cb;
-    data_indication             *data_ind_cb;
+    eth_mac_data_request                *data_req;
+    eth_mac_data_confirm                *data_conf_cb;
+    eth_mac_data_indication             *data_ind_cb;
 
     eth_mac_mac48_address_set   *mac48_set;
     eth_mac_mac48_address_get   *mac48_get;
@@ -141,3 +141,4 @@ struct eth_mac_api_s {
 #endif
 
 #endif // ETHERNET_MAC_API_H
+

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

@@ -249,7 +249,7 @@ typedef enum {
     macAutoRequestKeyIndex = 0x7b,  /*>The index of the key used for automatic data*/
     macDefaultKeySource = 0x7c,      /*>Default key source*/
     //NON standard extension
-    macLoadBalancingBeaconTxPeriod = 0xfd,  /*> Set Beacon periodic Tx interval.Value size uint16_t in seconds, Use 0 to disable */
+    macLoadBalancingBeaconTx = 0xfd,  /*> Trig Beacon from load balance module periodic */
     macLoadBalancingAcceptAnyBeacon = 0xfe, /*>Beacon accept state control from other network. Value size bool, data true=Enable, false=disable .*/
     macThreadForceLongAddressForBeacon = 0xff /*>Thread standard force beacon source address for extended 64-bit*/
 } mlme_attr_t;