Add network property API to Nanostack (#2318)

Network property API allows application to read network
characteristics that can be used to optimise the network operation.

Application can give amount of data it wishes to send and the API
returns approximated jitter value for the next transmission. The
jitter is calculated based on estimated network size, available data
rate and some other network properties.

The API returns also estimated latency that can be used to adjust
application waiting times.

Other changes:
 - Rename socket specific error_t as socket_error_t to avoid naming
 clashes in tests.
-Fix Wi-SUN network size constants

Author: Arto Kinnunen

nanostack/socket_api.h

@@ -694,27 +694,29 @@ static inline int8_t socket_read_session_address(int8_t socket, ns_address_t *ad
  *
  * IPv6 socket options summary
  *
- * | opt_name / cmsg_type         | Data type        | set/getsockopt  | sendmsg | recvmsg                           |
- * | :--------------------------: | :--------------: | :-------------: | :-----: | :-------------------------------: |
- * | SOCKET_IPV6_TCLASS           | int16_t          |     Yes         |   Yes   | If enabled with RECVTCLASS        |
- * | SOCKET_IPV6_UNICAST_HOPS     | int16_t          |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_MULTICAST_HOPS   | int16_t          |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_ADDR_PREFERENCES | int              |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_USE_MIN_MTU      | int8_t           |     Yes         |   Yes   | No                                |
- * | SOCKET_IPV6_DONTFRAG         | int8_t           |     Yes         |   Yes   | No                                |
- * | SOCKET_IPV6_FLOW_LABEL       | int32_t          |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_HOPLIMIT         | int16_t          |     No          |   Yes   | If enabled with RECVHOPLIMIT      |
- * | SOCKET_IPV6_PKTINFO          | ns_in6_pktinfo_t |     No          |   Yes   | If enabled with RECVPKTINFO       |
- * | SOCKET_IPV6_RECVPKTINFO      | bool             |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_RECVHOPLIMIT     | bool             |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_RECVTCLASS       | bool             |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_MULTICAST_IF     | int8_t           |     Yes         |   No    | No                                |
- * | SOCKET_IPV6_MULTICAST_LOOP   | bool             |     Yes         |   Yes   | No                                |
- * | SOCKET_IPV6_JOIN_GROUP       | ns_ipv6_mreq_t   |     Set only    |   No    | No                                |
- * | SOCKET_IPV6_LEAVE_GROUP      | ns_ipv6_mreq_t   |     Set only    |   No    | No                                |
- * | SOCKET_BROADCAST_PAN         | int8_t           |     Yes         |   No    | No                                |
- * | SOCKET_LINK_LAYER_SECURITY   | int8_t           |     Yes         |   No    | No                                |
- * | SOCKET_INTERFACE_SELECT      | int8_t           |     Yes         |   No    | No                                |
+ * | opt_name / cmsg_type         | Data type         | set/getsockopt  | sendmsg | recvmsg                           |
+ * | :--------------------------: | :---------- ----: | :-------------: | :-----: | :-------------------------------: |
+ * | SOCKET_IPV6_TCLASS           | int16_t           |     Yes         |   Yes   | If enabled with RECVTCLASS        |
+ * | SOCKET_IPV6_UNICAST_HOPS     | int16_t           |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_MULTICAST_HOPS   | int16_t           |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_ADDR_PREFERENCES | int               |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_USE_MIN_MTU      | int8_t            |     Yes         |   Yes   | No                                |
+ * | SOCKET_IPV6_DONTFRAG         | int8_t            |     Yes         |   Yes   | No                                |
+ * | SOCKET_IPV6_FLOW_LABEL       | int32_t           |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_HOPLIMIT         | int16_t           |     No          |   Yes   | If enabled with RECVHOPLIMIT      |
+ * | SOCKET_IPV6_PKTINFO          | ns_in6_pktinfo_t  |     No          |   Yes   | If enabled with RECVPKTINFO       |
+ * | SOCKET_IPV6_RECVPKTINFO      | bool              |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_RECVHOPLIMIT     | bool              |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_RECVTCLASS       | bool              |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_MULTICAST_IF     | int8_t            |     Yes         |   No    | No                                |
+ * | SOCKET_IPV6_MULTICAST_LOOP   | bool              |     Yes         |   Yes   | No                                |
+ * | SOCKET_IPV6_JOIN_GROUP       | ns_ipv6_mreq_t    |     Set only    |   No    | No                                |
+ * | SOCKET_IPV6_LEAVE_GROUP      | ns_ipv6_mreq_t    |     Set only    |   No    | No                                |
+ * | SOCKET_BROADCAST_PAN         | int8_t            |     Yes         |   No    | No                                |
+ * | SOCKET_LINK_LAYER_SECURITY   | int8_t            |     Yes         |   No    | No                                |
+ * | SOCKET_INTERFACE_SELECT      | int8_t            |     Yes         |   No    | No                                |
+ * | SOCKET_LATENCY               | ns_ipv6_latency_t |     Get only    |   No    | No                                |
+ * | SOCKET_STAGGER               | ns_ipv6_stagger_t |     Get only    |   No    | No                                |
  *
  */
 
@@ -753,6 +755,10 @@ static inline int8_t socket_read_session_address(int8_t socket, ns_address_t *ad
 #define SOCKET_IPV6_JOIN_GROUP              15
 /** Leave a multicast group, using ns_ipv6_mreq_t */
 #define SOCKET_IPV6_LEAVE_GROUP             16
+/** Read estimated latency to reach destination */
+#define SOCKET_LATENCY                      17
+/** Read estimated stagger value that can be used as initial delay after bootstrap or firmware update. */
+#define SOCKET_STAGGER                      18
 
 #define SOCKET_BROADCAST_PAN                0xfc /**< Internal use - transmit with IEEE 802.15.4 broadcast PAN ID */
 #define SOCKET_LINK_LAYER_SECURITY          0xfd /**< Not standard enable or disable socket security at link layer (For 802.15.4). */
@@ -765,6 +771,20 @@ typedef struct ns_ipv6_mreq {
     int8_t ipv6mr_interface;            /**< interface id */
 } ns_ipv6_mreq_t;
 
+/** Latency request used for getsockopt() */
+typedef struct {
+    uint8_t dest_addr[16];      /**< [IN] IPv6 destination address */
+    uint32_t latency;           /**< [OUT] estimated latency value in milliseconds */
+} ns_ipv6_latency_t;
+
+/** Stagger request used for getsockopt() */
+typedef struct {
+    uint8_t dest_addr[16];      /**< [IN] IPv6 destination address */
+    uint16_t data_amount;       /**< [IN] Amount of data in kilobytes */
+    uint16_t stagger_min;       /**< [OUT] Minimum stagger value in seconds */
+    uint16_t stagger_max;       /**< [OUT] Maximum stagger value in seconds */
+    uint16_t stagger_rand;      /**< [OUT] Randomized stagger value in seconds */
+} ns_ipv6_stagger_t;
 /**
  * \brief Set an option for a socket
  *
@@ -804,6 +824,7 @@ int8_t socket_setsockopt(int8_t socket, uint8_t level, uint8_t opt_name, const v
  * \return 0 on success.
  * \return -1 invalid socket ID.
  * \return -2 invalid/unsupported option.
+ * \return -3 data can't be retrieved.
  */
 int8_t socket_getsockopt(int8_t socket, uint8_t level, uint8_t opt_name, void *opt_value, uint16_t *opt_len);
 

nanostack/ws_management_api.h

@@ -75,12 +75,11 @@ extern "C" {
 #define CHANNEL_SPACING_100 0x03 // 100 khz
 #define CHANNEL_SPACING_250 0x04 // 250 khz
 
-#define NETWORK_SIZE_AUTOMATIC 0x00
-#define NETWORK_SIZE_SMALL 0x01
-#define NETWORK_SIZE_MEDIUM 0x08
-#define NETWORK_SIZE_LARGE 0x10
-#define NETWORK_SIZE_CERTIFICATE 0xFF
-
+#define NETWORK_SIZE_CERTIFICATE    0x00
+#define NETWORK_SIZE_SMALL          0x01
+#define NETWORK_SIZE_MEDIUM         0x08
+#define NETWORK_SIZE_LARGE          0x10
+#define NETWORK_SIZE_AUTOMATIC      0xFF
 
 /** Temporary API change flag. this will be removed when new version of API is implemented on applications
  *

source/6LoWPAN/Bootstraps/Generic/protocol_6lowpan.c

@@ -74,6 +74,7 @@
 #include "6LoWPAN/Fragmentation/cipv6_fragmenter.h"
 #include "Service_Libs/etx/etx.h"
 #include "Service_Libs/mac_neighbor_table/mac_neighbor_table.h"
+#include "6LoWPAN/ws/ws_common.h"
 #include "6LoWPAN/ws/ws_bootstrap.h"
 
 
@@ -779,3 +780,83 @@ uint8_t protocol_6lowpan_beacon_compare_rx(int8_t interface_id, uint8_t join_pri
 
     return conn_to_pref;
 }
+
+bool protocol_6lowpan_latency_estimate_get(int8_t interface_id, uint32_t *latency)
+{
+    protocol_interface_info_entry_t *cur_interface = protocol_stack_interface_info_get_by_id(interface_id);
+    uint32_t latency_estimate = 0;
+
+    if (!cur_interface) {
+        return false;
+    }
+
+    if (cur_interface->eth_mac_api) {
+        // either PPP or Ethernet interface.
+        latency_estimate = 100;
+    } else if (thread_info(cur_interface)) {
+        // thread network
+        latency_estimate = 1000;
+    } else if (ws_info(cur_interface)) {
+        latency_estimate = ws_common_latency_estimate_get(cur_interface);
+    } else {
+        // 6LoWPAN ND
+        latency_estimate = 8000;
+    }
+
+    if (latency_estimate != 0) {
+        *latency = latency_estimate;
+        return true;
+    }
+
+    return false;
+}
+
+bool protocol_6lowpan_stagger_estimate_get(int8_t interface_id, uint32_t data_amount, uint16_t *stagger_min, uint16_t *stagger_max, uint16_t *stagger_rand)
+{
+    size_t network_size;
+    uint32_t datarate;
+    protocol_interface_info_entry_t *cur_interface = protocol_stack_interface_info_get_by_id(interface_id);
+
+    if (!cur_interface) {
+        return false;
+    }
+
+    *stagger_min = 1;
+
+    if (cur_interface->eth_mac_api) {
+        // either PPP or Ethernet interface.
+        network_size = 1;
+        datarate = 1000000;
+    } else if (thread_info(cur_interface)) {
+        // thread network
+        network_size = 23;
+        datarate = 250000;
+    } else if (ws_info(cur_interface)) {
+        network_size = ws_common_network_size_estimate_get(cur_interface);
+        datarate = ws_common_datarate_get(cur_interface);
+    } else {
+        // 6LoWPAN ND
+        network_size = 1000;
+        datarate = 250000;
+    }
+
+    if (data_amount == 0) {
+        // If no data amount given, use 1kB
+        data_amount = 1;
+    }
+    /**Example:
+     * Maximum stagger value to send 1kB on 50 devices network using datarate 50000 kb/:
+     * (1 * 1024 * 8 * 50) / (50000/4)) = ~ 32s
+     *
+     * devices: 50,   datarate: 250kbps => stagger ~ 6s
+     * devices: 1000, datarate: 50kbps  => stagger ~ 655s
+     */
+    /* Do not occupy whole bandwidth, halve the theoretical datarate and reserve room for other channel usage */
+    datarate = datarate / 4;
+    *stagger_max = (uint16_t) * stagger_min + ((data_amount * 1024 * 8 * network_size) / datarate);
+
+    // Randomize stagger value
+    *stagger_rand = randLIB_get_random_in_range(*stagger_min, *stagger_max);
+
+    return true;
+}

source/6LoWPAN/Bootstraps/protocol_6lowpan.h

@@ -75,5 +75,7 @@ uint8_t protocol_6lowpan_beacon_join_priority_tx(int8_t interface_id);
 uint8_t protocol_6lowpan_beacon_compare_rx(int8_t interface_id, uint8_t join_priority, uint8_t link_quality);
 bool protocol_6lowpan_bootsrap_start(struct protocol_interface_info_entry *interface);
 bool protocol_6lowpan_bootsrap_link_set(struct protocol_interface_info_entry *interface, struct mlme_pan_descriptor_s *pan_descriptor, const uint8_t *beacon_payload, uint8_t beacon_length);
+bool protocol_6lowpan_latency_estimate_get(int8_t interface_id, uint32_t *latency);
+bool protocol_6lowpan_stagger_estimate_get(int8_t interface_id, uint32_t data_amount, uint16_t *stagger_min, uint16_t *stagger_max, uint16_t *stagger_rand);
 
 #endif /* PROTOCOL_6LOWPAN_H_ */

source/6LoWPAN/ws/ws_common.c

@@ -483,6 +483,57 @@ uint32_t ws_common_version_timeout_get(uint8_t config)
     return lifetime;
 }
 
+uint32_t ws_common_latency_estimate_get(protocol_interface_info_entry_t *cur)
+{
+    uint32_t latency = 0;
+
+    if (cur->ws_info->network_size_config <= NETWORK_SIZE_SMALL) {
+        // handles also NETWORK_SIZE_CERTIFICATE
+        latency = 8000;
+    } else if (cur->ws_info->network_size_config <= NETWORK_SIZE_MEDIUM) {
+        latency = 16000;
+    } else if (cur->ws_info->network_size_config <= NETWORK_SIZE_LARGE) {
+        latency = 32000;
+    } else { /* <= NETWORK_SIZE_AUTOMATIC */
+        // Make assumption based on current pan size
+        if (cur->ws_info->pan_information.pan_size < 50) {
+            latency = 8000;
+        } else {
+            latency = 32000;
+        }
+    }
 
-#endif // HAVE_WS
+    return latency;
+}
+
+uint32_t ws_common_datarate_get(protocol_interface_info_entry_t *cur)
+{
+    return ws_get_datarate_using_operating_mode(cur->ws_info->hopping_schdule.operating_mode);
+}
 
+uint32_t ws_common_network_size_estimate_get(protocol_interface_info_entry_t *cur)
+{
+    uint32_t network_size_estimate = 0;
+
+    if (cur->ws_info->network_size_config <= NETWORK_SIZE_SMALL) {
+        // tens of devices (now 30), handles also NETWORK_SIZE_CERTIFICATE
+        network_size_estimate = 30;
+    } else if (cur->ws_info->network_size_config <= NETWORK_SIZE_MEDIUM) {
+        // hundreds of devices (now 300)
+        network_size_estimate = 300;
+    } else if (cur->ws_info->network_size_config <= NETWORK_SIZE_LARGE) {
+        // huge amount of devices (now 1000)
+        network_size_estimate = 1000;
+    } else { /* <= NETWORK_SIZE_AUTOMATIC */
+        // Make assumption based on current pan size
+        if (cur->ws_info->pan_information.pan_size < 50) {
+            network_size_estimate = 50;
+        } else {
+            network_size_estimate = 1000;
+        }
+    }
+
+    return network_size_estimate;
+}
+
+#endif // HAVE_WS

source/6LoWPAN/ws/ws_common.h

@@ -148,6 +148,12 @@ bool ws_common_negative_aro_mark(protocol_interface_info_entry_t *interface, con
 
 uint32_t ws_common_version_timeout_get(uint8_t config);
 
+uint32_t ws_common_latency_estimate_get(protocol_interface_info_entry_t *cur);
+
+uint32_t ws_common_datarate_get(protocol_interface_info_entry_t *cur);
+
+uint32_t ws_common_network_size_estimate_get(protocol_interface_info_entry_t *cur);
+
 #define ws_info(cur) ((cur)->ws_info)
 #else
 #define ws_info(cur) ((ws_info_t *) NULL)
@@ -158,6 +164,9 @@ uint32_t ws_common_version_timeout_get(uint8_t config);
 #define ws_common_fast_timer(cur, ticks) ((void) 0)
 #define ws_common_allow_child_registration(cur, eui64) (2)
 #define ws_common_negative_aro_mark(interface, eui64)(false)
+#define ws_common_latency_estimate_get(cur) 0
+#define ws_common_datarate_get(cur) 0
+#define ws_common_network_size_estimate_get(cur) 0
 
 #endif //HAVE_WS
 #endif //WS_COMMON_H_

source/Core/include/ns_error_types.h

@@ -22,11 +22,11 @@
  * \enum error_t
  * \brief System generic error.
  */
-typedef enum error_t {
+typedef enum {
     eOK = 0,    /*!< no error */
     eFALSE = 1, /*!< no result */
     eBUSY = 2,  /*!< resource busy */
     eSYSTEM     /*!< error code readable in sys_error */
-} error_t;
+} socket_error_t;
 
 #endif /* NS_ERROR_TYPES_H_ */

source/Core/include/ns_socket.h

@@ -190,7 +190,7 @@ extern void socket_init(void);
 extern int8_t socket_event_handler_id_get(void);
 extern bool socket_data_queued_event_push(socket_t *socket);
 extern void socket_event_push(uint8_t sock_event, socket_t *socket, int8_t interface_id, void *session_ptr, uint16_t length);
-extern error_t socket_create(socket_family_t family, socket_type_t type, uint8_t protocol, int8_t *sid, uint16_t port, void (*passed_fptr)(void *), bool buffer_type);
+extern socket_error_t socket_create(socket_family_t family, socket_type_t type, uint8_t protocol, int8_t *sid, uint16_t port, void (*passed_fptr)(void *), bool buffer_type);
 extern socket_t *socket_new_incoming_connection(socket_t *listen_socket);
 void socket_connection_abandoned(socket_t *socket, int8_t interface_id, uint8_t reason);
 void socket_connection_complete(socket_t *socket, int8_t interface_id);
@@ -201,8 +201,8 @@ extern void socket_id_detach(int8_t sid);
 extern buffer_t *socket_buffer_read(socket_t *socket);
 extern socket_t *socket_lookup(socket_family_t family, uint8_t protocol, const sockaddr_t *local_addr, const sockaddr_t *remote_addr);
 extern socket_t *socket_lookup_ipv6(uint8_t protocol, const sockaddr_t *local_addr, const sockaddr_t *remote_addr, bool allow_wildcards);
-extern error_t socket_port_validate(uint16_t port, uint8_t protocol);
-extern error_t socket_up(buffer_t *buf);
+extern socket_error_t socket_port_validate(uint16_t port, uint8_t protocol);
+extern socket_error_t socket_up(buffer_t *buf);
 extern bool socket_message_validate_iov(const struct ns_msghdr *msg, uint16_t *length_out);
 extern int16_t socket_buffer_sendmsg(int8_t sid, buffer_t *buf, const struct ns_msghdr *msg, int flags);
 extern socket_t *socket_pointer_get(int8_t socket);

source/Core/ns_socket.c

@@ -342,7 +342,7 @@ static void socket_free(socket_t *socket)
     ns_dyn_mem_free(socket);
 }
 
-error_t socket_port_validate(uint16_t port, uint8_t protocol)
+socket_error_t socket_port_validate(uint16_t port, uint8_t protocol)
 {
     ns_list_foreach(socket_t, socket, &socket_list) {
         if (!socket_is_ipv6(socket)) {
@@ -497,7 +497,7 @@ socket_t *socket_dereference(socket_t *socket_ptr)
  * \return eFALSE no free sockets
  * \return eBUSY port reserved
  */
-error_t socket_create(socket_family_t family, socket_type_t type, uint8_t protocol, int8_t *sid, uint16_t port, void (*passed_fptr)(void *), bool buffer_type)
+socket_error_t socket_create(socket_family_t family, socket_type_t type, uint8_t protocol, int8_t *sid, uint16_t port, void (*passed_fptr)(void *), bool buffer_type)
 {
     if (sid) {
         *sid = -1;
@@ -850,7 +850,7 @@ socket_t *socket_lookup(socket_family_t family, uint8_t protocol, const sockaddr
  * \return eFALSE no socket found
  * \return eBUSY socket full
  */
-error_t socket_up(buffer_t *buf)
+socket_error_t socket_up(buffer_t *buf)
 {
     socket_t *socket = buf->socket;