net_interface.h

00001 /*
00002  * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 
00015 #ifndef NET_INTERFACE_H_
00016 #define NET_INTERFACE_H_
00017 
00018 #include "ns_types.h"
00019 #include "platform/arm_hal_phy.h"
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 struct mac_api_s;
00026 struct eth_mac_api_s;
00027 
00028 /**
00029  * \file net_interface.h
00030  * \brief  Network API
00031 */
00032 
00033 /*!
00034  * \enum arm_nwk_interface_status_type_e
00035  * \brief Interface status type definition.
00036  */
00037 /** Network Interface Status */
00038 typedef enum arm_nwk_interface_status_type_e {
00039     ARM_NWK_BOOTSTRAP_READY = 0, /**< Interface configured Bootstrap is ready.*/
00040     ARM_NWK_RPL_INSTANCE_FLOODING_READY, /**< RPL instance has been flooded. */
00041     ARM_NWK_SET_DOWN_COMPLETE, /**< Interface DOWN command completed successfully. */
00042     ARM_NWK_NWK_SCAN_FAIL,  /**< Interface has not detected any valid network. */
00043     ARM_NWK_IP_ADDRESS_ALLOCATION_FAIL, /**< IP address allocation failure (ND, DHCPv4 or DHCPv6). */
00044     ARM_NWK_DUPLICATE_ADDRESS_DETECTED, /**< User-specific GP16 was not valid. */
00045     ARM_NWK_AUHTENTICATION_START_FAIL, /**< No valid authentication server detected behind the access point. */
00046     ARM_NWK_AUHTENTICATION_FAIL,    /**< Network authentication failed by handshake. */
00047     ARM_NWK_NWK_CONNECTION_DOWN, /**< No connection between access point and default router. */
00048     ARM_NWK_NWK_PARENT_POLL_FAIL, /**< Sleepy host poll failed 3 times. Interface is shut down. */
00049     ARM_NWK_PHY_CONNECTION_DOWN, /**< Interface PHY cable off or serial port interface not responding anymore. */
00050 } arm_nwk_interface_status_type_e;
00051 
00052 /*!
00053  * \enum arm_library_event_type_e
00054  * \brief Event library type definition.
00055  */
00056 /** Event library type. */
00057 typedef enum arm_library_event_type_e {
00058     ARM_LIB_TASKLET_INIT_EVENT = 0, /**< Tasklet init occurs always when generating a tasklet. */
00059     ARM_LIB_NWK_INTERFACE_EVENT,    /**< Interface bootstrap or state update event. */
00060     ARM_LIB_SYSTEM_TIMER_EVENT, /*!*< System timer event. */
00061     APPLICATION_EVENT, /**< Application-specific event. */
00062 } arm_library_event_type_e;
00063 
00064 
00065 /**
00066  *  Socket event description:
00067  *
00068  *  8-bit variable where four MSB bits describes the event type and
00069  *  four LSB bits describes the socket that has received the event.
00070  *
00071  *      Type   Socket ID
00072  *      ----   ----
00073  *      xxxx   xxxx
00074  *
00075  */
00076 
00077 
00078 /** Socket type exceptions. */
00079 /** Socket event mask. */
00080 #define SOCKET_EVENT_MASK                   0xF0
00081 /** Data received. */
00082 #define SOCKET_DATA                         (0 << 4)
00083 /** TCP connection ready. */
00084 #define SOCKET_BIND_DONE                    (1 << 4)
00085 /** TCP connection failure. */
00086 #define SOCKET_BIND_FAIL                    (2 << 4)
00087 /** TCP connection authentication failed. */
00088 #define SOCKET_BIND_AUTH_FAIL               (3 << 4)
00089 /** TCP incoming connection attempt to listening socket */
00090 #define SOCKET_INCOMING_CONNECTION          (4 << 4)
00091 /** Socket data send failure. */
00092 #define SOCKET_TX_FAIL                      (5 << 4)
00093 /** TCP connection closed. */
00094 #define SOCKET_CONNECT_CLOSED               (6 << 4)
00095 /** TCP connection reset */
00096 #define SOCKET_CONNECTION_RESET             (7 << 4)
00097 /** No route available to the destination. */
00098 #define SOCKET_NO_ROUTE                     (8 << 4)
00099 /** Socket TX done. */
00100 #define SOCKET_TX_DONE                      (9 << 4)
00101 /** Out of memory failure. */
00102 #define SOCKET_NO_RAM                       (10 << 4)
00103 
00104 /*!
00105  * \enum net_security_t
00106  * Network security levels.
00107  */
00108 /** Network level security type. */
00109 typedef enum net_security_t {
00110     NW_NO_SECURITY = 0,                       /**< No Security. */
00111     NW_SECURITY_LEVEL_MIC32 = 1,              /**< 32-bit MIC verify, no encoding. */
00112     NW_SECURITY_LEVEL_MIC64 = 2,              /**< 64-bit MIC verify, no encoding. */
00113     NW_SECURITY_LEVEL_MIC128 = 3,             /**< 128-bit MIC verify, no encoding. */
00114     NW_SECURITY_LEVEL_ENC = 4,                /**< AES encoding without MIC. */
00115     NW_SECURITY_LEVEL_ENC_MIC32 = 5,          /**< 32-bit MIC verify with encoding. */
00116     NW_SECURITY_LEVEL_ENC_MIC64 = 6,          /**< 64-bit MIC verify with encoding. */
00117     NW_SECURITY_LEVEL_ENC_MIC128 = 7          /**< 128-bit MIC verify with encoding. */
00118 } net_security_t;
00119 
00120 /*!
00121  * \enum net_address_t
00122  * \brief Addresses for arm_net_address_get().
00123  */
00124 /** Ipv6 address type.*/
00125 typedef enum net_address_t {
00126     ADDR_IPV6_GP,             /**< Node default global address. */
00127     ADDR_IPV6_GP_SEC,         /**< Node secondary global address. */
00128     ADDR_IPV6_LL              /**< Node default link local address. */
00129 } net_address_t;
00130 
00131 /*!
00132  * \enum net_mac_address_t
00133  * \brief MAC addresses of nodes.
00134  */
00135 /** MAC address type. */
00136 typedef enum net_mac_address_t {
00137     ADDR_MAC_SHORT16,             /**< Nodes 16-bit short address. */
00138     ADDR_MAC_LONG64,              /**< IP layer EUID64 based on MAC layer 64-bit long address after U/I -bit conversion.  */
00139 } net_mac_address_t;
00140 
00141 /*!
00142  * \enum net_tls_cipher_e
00143  * \brief TLS cipher mode enumeration types.
00144  */
00145 /** TLS cipher type */
00146 typedef enum {
00147     NET_TLS_PSK_CIPHER,         /**< Network authentication support, only PSK. */
00148     NET_TLS_ECC_CIPHER,         /**< Network authentication support, only ECC. */
00149     NET_TLS_PSK_AND_ECC_CIPHER, /**< Network authentication support, PSK & ECC. */
00150 } net_tls_cipher_e;
00151 
00152 /*!
00153  * \enum net_pana_session_mode_e
00154  * \brief PANA session cache support.
00155  */
00156 /** PANA session type. */
00157 typedef enum {
00158     NET_PANA_SINGLE_SESSION,        /**< Client tracks only one PANA session data, default use case. */
00159     NET_PANA_MULTI_SESSION,         /**< Client supports many Start network coordinator session data */
00160 } net_pana_session_mode_e;
00161 
00162 /*!
00163  * \enum net_6lowpan_link_layer_sec_mode_e
00164  * \brief 6LoWPAN network security & authentication modes.
00165  */
00166 /** 6lowpan security mode. */
00167 typedef enum {
00168     NET_SEC_MODE_NO_LINK_SECURITY,      /**< Security disabled at link layer, DEFAULT. */
00169     NET_SEC_MODE_PSK_LINK_SECURITY,     /**< Link security by PSK key. */
00170     NET_SEC_MODE_PANA_LINK_SECURITY, /**< PANA network authentication defined link KEY. */
00171 } net_6lowpan_link_layer_sec_mode_e;
00172 
00173 
00174 /*!
00175  * \enum net_6lowpan_mode_e
00176  * \brief 6LoWPAN bootstrap modes.
00177  */
00178 /** Bootstrap mode types. */
00179 typedef enum {
00180     NET_6LOWPAN_BORDER_ROUTER,  /**< Root device for 6LoWPAN ND. */
00181     NET_6LOWPAN_ROUTER,         /**< Router device. */
00182     NET_6LOWPAN_HOST,           /**< Host device DEFAULT setting. */
00183     NET_6LOWPAN_SLEEPY_HOST,    /**< Sleepy host device. */
00184     NET_6LOWPAN_NETWORK_DRIVER, /**< 6LoWPAN radio host device, no bootstrap. */
00185     NET_6LOWPAN_SNIFFER         /**< Sniffer device, no bootstrap. */
00186 } net_6lowpan_mode_e;
00187 
00188 /*!
00189  * \enum net_6lowpan_mode_extension_e
00190  * \brief 6LoWPAN Extension modes.
00191  */
00192 /** Bootstrap extension mode types.. */
00193 typedef enum {
00194     NET_6LOWPAN_ND_WITHOUT_MLE,         /**< 6LoWPAN ND without MLE. */
00195     NET_6LOWPAN_ND_WITH_MLE,            /**< 6LoWPAN ND with MLE. */
00196     NET_6LOWPAN_THREAD,                 /**< 6LoWPAN Thread with MLE attached. */
00197     NET_6LOWPAN_ZIGBEE_IP               /**< 6LoWPAN ZigBeeIP setup. */
00198 } net_6lowpan_mode_extension_e;
00199 
00200 
00201 /*!
00202  * \enum net_ipv6_mode_e
00203  * \brief IPv6 bootstrap modes.
00204  */
00205 /** IPv6 bootstrap mode type. */
00206 typedef enum {
00207     NET_IPV6_BOOTSTRAP_STATIC,  /**< Application defines the IPv6 prefix. */
00208     NET_IPV6_BOOTSTRAP_AUTONOMOUS /**< Interface gets IPv6 address automatically from network using ICMP and DHCP. */
00209 }
00210 net_ipv6_mode_e;
00211 
00212 /*!
00213  * \struct link_layer_setups_s
00214  * \brief Network coordinator parameter list.
00215  */
00216 /** Structure is used to read network parameter for warm start. */
00217 typedef struct link_layer_setups_s {
00218     uint16_t PANId;            /**< Network PAN-ID. */
00219     uint8_t LogicalChannel;    /**< Network logical channel. */
00220     net_mac_address_t addr_mode;   /**< Coordinator address mode. */
00221     uint8_t address[8];        /**< Coordinator address. */
00222     uint8_t sf;                /**< Network superframe setup. */
00223 } link_layer_setups_s;
00224 
00225 /*!
00226  * \struct link_layer_address_s
00227  * \brief Network MAC address info.
00228  */
00229 /**Structure is used to read link layer address. */
00230 typedef struct link_layer_address_s {
00231     uint16_t PANId;            /**< Network PAN-ID. */
00232     uint16_t mac_short;        /**< MAC short address, if <0xfffe then is valid. */
00233     uint8_t mac_long[8];       /**< MAC long address (EUI-48 for Ethernet; EUI-64 for IEEE 802.15.4). */
00234     uint8_t iid_eui64[8];      /**< IPv6 interface identifier based on EUI-64. */
00235 } link_layer_address_s;
00236 
00237 /*!
00238  * \struct network_layer_address_s
00239  * \brief Network layer parent address info.
00240  */
00241 /**Structure is used to read network layer address of the parent node. */
00242 typedef struct network_layer_address_s {
00243     uint8_t border_router[16]; /**< ND Border Router Address. */
00244     uint8_t prefix[8];        /**< Long 64-bit network ID. */
00245 } network_layer_address_s;
00246 
00247 /*!
00248  * \enum net_6lowpan_gp_address_mode_e
00249  * \brief 6LoWPAN stack address modes.
00250  */
00251 /**Different addressing modes for a network interface. */
00252 typedef enum {
00253     NET_6LOWPAN_GP64_ADDRESS,       /**< Interface registers only GP64 address. */
00254     NET_6LOWPAN_GP16_ADDRESS,       /**< Interface registers only GP16 address. */
00255     NET_6LOWPAN_MULTI_GP_ADDRESS,   /**< Interface registers GP16 & GP64 addresses. */
00256 } net_6lowpan_gp_address_mode_e;
00257 
00258 
00259 /*!
00260  * \struct net_tls_psk_info_s
00261  * \brief TLS PSK info structure.
00262  */
00263 /**Structure is used to set TLS PSK key. */
00264 typedef struct net_tls_psk_info_s {
00265     uint32_t key_id;    /**< PSK Key ID can be 0x01-0xffff, storage size is intentionally 32 bits. */
00266     uint8_t key[16];    /**< 128-bit PSK Key. */
00267 } net_tls_psk_info_s;
00268 
00269 /*!
00270  * \struct net_link_layer_psk_security_info_s
00271  * \brief NETWORK PSK link key structure.
00272  */
00273 /**Structure is used to set link level PSK key. */
00274 typedef struct {
00275     uint8_t key_id;             /**< Link layer PSK Key ID, can be 0x01-0xff. */
00276     uint8_t security_key[16];   /**< Link layer 128-bit PSK Key. */
00277 } net_link_layer_psk_security_info_s;
00278 
00279 
00280 /*!
00281  * \struct arm_certificate_chain_entry_s
00282  * \brief Certificate chain structure.
00283  */
00284 /**Structure is used to define a certificate chain. */
00285 typedef struct {
00286     uint8_t chain_length;           /**< Certificate chain length, indicates the chain length. */
00287     const uint8_t *cert_chain[4];   /**< Certificate chain pointer list. */
00288     uint16_t cert_len[4];           /**< Certificate length. */
00289     const uint8_t *key_chain[4];    /**< Certificate private key. */
00290 } arm_certificate_chain_entry_s;
00291 
00292 /*!
00293 * \struct ns_keys_t
00294 * \brief Structure for the network keys used by net_network_key_get
00295 */
00296 /**Structure is used to hold currently active and previously used network keys. */
00297 typedef struct ns_keys_t
00298 
00299 {
00300     uint8_t previous_active_network_key[16];    /**< The key that is currently active when a new key is generated and activated. */
00301     uint8_t previous_active_key_index;           /**< The index associated to the current_active_network_key. */
00302     uint8_t current_active_network_key[16];     /**< Last generated and activated key. */
00303     uint8_t current_active_key_index;           /**< The index associated to the current_active_network_key. */
00304 } ns_keys_t;
00305 
00306 /*!
00307  * \struct border_router_setup_s
00308  * \brief 6LoWPAN border router information structure.
00309  */
00310 /**Structure is used to set up a border router device. */
00311 typedef struct {
00312     uint16_t mac_panid;             /**< Link layer PAN-ID, accepts only < 0xfffe.  */
00313     uint16_t mac_short_adr;         /**< Defines 802.15.4 short address. If the value is <0xfffe it indicates that GP16 is activated. */
00314     uint8_t beacon_protocol_id;     /**< ZigBeeIP uses always 2. */
00315     uint8_t network_id[16];         /**< Network ID 16-bytes, will be used at beacon payload. */
00316     uint8_t lowpan_nd_prefix[8];    /**< Define ND default prefix, ABRO, DODAG ID, GP address. */
00317     uint16_t ra_life_time;          /**< Define ND router lifetime in seconds, recommend value 180+. */
00318     uint32_t abro_version_num;      /**< ND ABRO version number (0 when starting a new ND setup). */
00319 } border_router_setup_s;
00320 
00321 
00322 typedef struct channel_list_s
00323 {
00324     channel_page_e channel_page;
00325     uint32_t channel_mask[8];
00326 } channel_list_s;
00327 
00328 /*!
00329  * \struct network_driver_setup_s
00330  * \brief 6LoWPAN radio interface setup.
00331  */
00332 /**Structure is used to setup a network interface driver. */
00333 typedef struct {
00334     uint16_t mac_panid;                 /**< Link layer PAN-ID, accepts only < 0xfffe. */
00335     uint16_t mac_short_adr;             /**< Defines 802.15.4 short address. If the value is <0xfffe it indicates that GP16 is activated. */
00336     uint8_t beacon_protocol_id;         /**< ZigBeeIP uses always 2. */
00337     uint8_t network_id[16];             /**< Network ID 16-bytes, will be used at beacon payload. */
00338     uint8_t beacon_payload_tlv_length; /**< Optional steering parameter length. */
00339     uint8_t *beacon_payload_tlv_ptr;  /**< Optional steering parameters. */
00340 } network_driver_setup_s;
00341 
00342 /**
00343   * \brief Init 6LoWPAN library
00344   *
00345   * \return 0, Init OK.
00346   */
00347 extern int8_t net_init_core(void);
00348 
00349 /**
00350  * \brief Create network interface base to IDLE state.
00351  * \param api Generates interface with ethernet MAC.
00352  * \param interface_name_ptr String pointer to interface name. Need to end to '\0' character.
00353  *        Max length 32 characters including NULL at end. Note: the given name is not copied,
00354  *        so it must remain valid as long as the interface is.
00355  *
00356  * \return >=0 Interface ID (0-127). Application needs to save this information.
00357  * \return -1 api was NULL.
00358  * \return -2 Ethernet is not supported at this build.
00359  * \return -3 No memory for the interface.
00360  */
00361 extern int8_t arm_nwk_interface_ethernet_init(struct eth_mac_api_s *api, const char *interface_name_ptr);
00362 
00363 /**
00364  * \brief Create network interface base to IDLE state.
00365  * \param api Generates interface with 802.15.4 MAC.
00366  * \param interface_name_ptr String pointer to interface name. Need to end to '\0' character.
00367  *        Max length 32 characters including NULL at end. Note: the given name is not copied,
00368  *        so it must remain valid as long as the interface is.
00369  *
00370  * \return >=0 Interface ID (0-127). Application needs to save this information.
00371  * \return -1 api was NULL.
00372  * \return -3 No memory for the interface.
00373  */
00374 extern int8_t arm_nwk_interface_lowpan_init(struct mac_api_s *api, char *interface_name_ptr);
00375 
00376 /**
00377  * \brief Set IPv6 interface setup.
00378  *
00379  * \param interface_id Network interface ID.
00380  * \param bootstrap_mode Selected bootstrap mode:
00381  *      * NET_IPV6_BOOTSTRAP_STATIC, Application defines the IPv6 prefix.
00382  * \param ipv6_prefix_pointer Pointer to 64 bit IPv6 prefix. The data is copied, so it can be invalidated after function call.
00383  *
00384  * \return >=0 Bootstrap mode set OK.
00385  * \return -1 Unknown network ID.
00386  */
00387 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);
00388 
00389 /**
00390  * \brief Set network interface bootstrap setup.
00391  *
00392  * \param interface_id Network interface ID.
00393  * \param bootstrap_mode Selected bootstrap mode:
00394  *      * NET_6LOWPAN_BORDER_ROUTER, Initialize border router basic setup.
00395  *      * NET_6LOWPAN_ROUTER, Enable normal 6LoWPAN ND and RPL to bootstrap.
00396  *      * NET_6LOWPAN_HOST, Enable normal 6LoWPAN ND only to bootstrap.
00397  *      * NET_6LOWPAN_SLEEPY_HOST, Enable normal 6LoWPAN ND only to bootstrap.
00398  *      * NET_6LOWPAN_NETWORK_DRIVER, 6LoWPAN radio host device no bootstrap.
00399  *      * NET_6LOWPAN_SNIFFER, 6LoWPAN sniffer device no bootstrap.
00400  *
00401  * \param net_6lowpan_mode_extension Define 6LoWPAN MLE and mode as ZigBeeIP or Thread.
00402  *
00403  * \return >=0 Bootstrap mode set OK.
00404  * \return -1 Unknown network ID.
00405  * \return -2 Unsupported bootstrap type in this library.
00406  * \return -3 No memory for 6LoWPAN stack.
00407  * \return -4 Null pointer parameter.
00408  */
00409 extern int8_t arm_nwk_interface_configure_6lowpan_bootstrap_set(int8_t interface_id, net_6lowpan_mode_e bootstrap_mode, net_6lowpan_mode_extension_e net_6lowpan_mode_extension);
00410 
00411 /**
00412  * \brief Set network interface link layer parameters.
00413  *
00414  * \param interface_id Network interface ID
00415  * \param nwk_channel_list Defines network channel page and channel.
00416  * \param link_setup Link layer parameters for NET_6LOWPAN_NETWORK_DRIVER defines NetworkID, PAN-ID Short Address.
00417  *
00418  * \return >=0 Configuration set OK.
00419  * \return -1 Unknown network ID.
00420  * \return -2 Interface is active, bootsrap mode not selected or is not NET_6LOWPAN_NETWORK_DRIVER or NET_6LOWPAN_SNIFFER.
00421  * \return -3 No memory for 6LoWPAN stack.
00422  * \return -4 Null pointer parameter.
00423  */
00424 extern int8_t arm_nwk_interface_network_driver_set(int8_t interface_id, const channel_list_s *nwk_channel_list, network_driver_setup_s *link_setup);
00425 
00426 /**
00427  * \brief Set configured network interface global address mode (border router bootstrap mode cannot set this).
00428  *
00429  * \param interface_id Network interface ID.
00430  * \param mode Define 6LoWPAN Global Address register mode:
00431  *      * NET_6LOWPAN_GP64_ADDRESS, Interface registers only GP64
00432  *      * NET_6LOWPAN_GP16_ADDRESS, Interface registers only GP16
00433  *      * NET_6LOWPAN_MULTI_GP_ADDRESS, Interface registers GP16 and GP64 addresses. GP16 is primary address and GP64 is secondary.
00434  *
00435  * \param short_address_base Short address base. If the application defines value 0-0xfffd, 6LoWPAN tries to register GP16 address
00436  * using that address. 0xfffe and 0xffff generate random 16-bit short address.
00437  *
00438  * \param define_new_short_address_at_DAD This parameter is only checked when mode is not NET_6LOWPAN_GP64_ADDRESS and
00439  * short_address_base is 0-0xfffd. Recommended value is 1. It enables automatic new address definition at
00440  * Duplicate Address Detection (DAD). Value 0 generates a DAD error for the interface bootstrap.
00441  * Border router device will not check that part.
00442  *
00443  * \return >=0 Bootstrap mode set OK.
00444  * \return -1 Unknown network ID.
00445  * \return -2 Illegal for border router.
00446  * \return -3 No memory for 6LoWPAN stack.
00447  */
00448 extern int8_t arm_nwk_6lowpan_gp_address_mode(int8_t interface_id, net_6lowpan_gp_address_mode_e mode, uint16_t short_address_base, uint8_t define_new_short_address_at_DAD);
00449 
00450 /**
00451  * \brief Set the channel list configuration to be used on the network interface.
00452  *
00453  * \param interface_id Network interface ID.
00454  * \param nwk_channel_list Channel list to be used.
00455  *
00456  * \return >=0 Channel configuration OK.
00457  * \return -1 Unknown network interface ID.
00458  * \return -2 Empty channel list, no channels enabled.
00459  * \return -4 If network interface is already active and cannot be re-configured.
00460  */
00461 extern int8_t arm_nwk_set_channel_list(int8_t interface_id, const channel_list_s *nwk_channel_list);
00462 
00463 /**
00464  * \brief Set the link scan time used on network interface.
00465  *
00466  * \param interface_id Network interface ID.
00467  * \param scan_time Value 0-14, scan duration/channel.
00468  *
00469  * \return >=0 Scan configuration OK.
00470  * \return -1 Unknown network interface ID.
00471  * \return -4 If network interface is already active and cannot be re-configured.
00472  * \return -5 Invalid scan time.
00473  */
00474 extern int8_t arm_nwk_6lowpan_link_scan_parameter_set(int8_t interface_id, uint8_t scan_time);
00475 
00476 /**
00477  * \brief A function to set the PAN ID filter.
00478  *
00479  * \param interface_id Network interface ID.
00480  * \param pan_id_filter Enable filter for specific PAN ID. 0xffff disables the filter.
00481  *
00482  * \return 0 Filter set OK.
00483  * \return -1 Unknown Network interface ID.
00484  * \return -2 Interface is active.
00485  *
00486  */
00487 extern int8_t arm_nwk_6lowpan_link_panid_filter_for_nwk_scan(int8_t interface_id, uint16_t pan_id_filter);
00488 
00489 /**
00490   *  \brief Get current used channel.
00491   *
00492   * \return Active channel.
00493   * \return -1 = Radio is closed.
00494   */
00495 extern int16_t arm_net_get_current_channel(int8_t interface_id);
00496 
00497 /**
00498  * \brief A function to read the PAN ID filter.
00499  * \return 16-bit value indicating a PAN ID filter.
00500  */
00501 extern uint16_t arm_net_get_nwk_pan_id_filter(int8_t interface_id);
00502 /**
00503   * \brief Enable/Disable network ID filter.
00504   *
00505   * \param interface_id Network interface ID.
00506   * \param nwk_id A pointer to a new network ID filter, NULL disable filter.
00507   *
00508   * \return 0 On success.
00509   * \return -1 Unknown network ID.
00510   * \return -2 Interface active.
00511   */
00512 extern int8_t arm_nwk_6lowpan_link_nwk_id_filter_for_nwk_scan(int8_t interface_id, const uint8_t *nwk_id_filter);
00513 /**
00514   * \brief Enable/Disable network protocol ID filter.
00515   *
00516   * \param interface_id Network interface ID.
00517   * \param protocol_ID A value that filters only supported network protocols (0= Zigbee1.x, 2= ZigBeeIP).
00518   *
00519   * \return 0 On success.
00520   * \return -1 Unknown network ID.
00521   * \return -2 Interface active.
00522   */
00523 extern int8_t arm_nwk_6lowpan_link_protocol_id_filter_for_nwk_scan(int8_t interface_id, uint8_t protocol_ID);
00524 
00525 /**
00526   * \brief Beacon join priority transmit callback.
00527   *
00528   * Callback defines join priority that is transmitted in beacon. Join priority is
00529   * 8 bit field in beacon that can be set e.g. based on RPL protocol rank data.
00530   *
00531   * \param interface_id The network interface ID.
00532   *
00533   * \return Join priority to be transmitted in beacon. 0 to 255.
00534   */
00535 typedef uint8_t beacon_join_priority_tx_cb(int8_t interface_id);
00536 
00537 /**
00538   * \brief Compare received beacon callback.
00539   *
00540   * Callback defines how preferred the node that has sent beacon is for connecting
00541   * to the network.
00542   *
00543   * \param interface_id The network interface ID.
00544   * \param join_priority Join priority that has been received in beacon. 0 to 255.
00545   * \param link_quality Link quality. 0 to 255. 255 is best quality.
00546   *
00547   * \return Connect to preference. 0 to 255. 255 is highest connect to preference.
00548   */
00549 typedef uint8_t beacon_compare_rx_cb(int8_t interface_id, uint8_t join_priority, uint8_t link_quality);
00550 
00551 /**
00552   * \brief Set callback for beacon join priority transmit
00553   *
00554   * Sets callback that defines join priority that is transmitted in beacon.
00555   * If callback is not set default functionality is used. On default functionality
00556   * join priority is combined from RPL DAGRank and RPL DODAG preference.
00557   *
00558   * \param interface_id The network interface ID.
00559   * \param beacon_join_priority_tx_cb_ptr Function pointer.
00560   *
00561   * \return 0 on success.
00562   * \return -1 Unknown network ID.
00563   * \return -2 Other error.
00564   */
00565 extern int8_t arm_nwk_6lowpan_beacon_join_priority_tx_callback_set(int8_t interface_id, beacon_join_priority_tx_cb *beacon_join_priority_tx_cb_ptr);
00566 
00567 /**
00568   * \brief Set callback for comparing received beacon
00569   *
00570   * Sets callback that defines how preferred the node that has sent beacon is for
00571   * connecting to the network. If callback is not set default functionality is used.
00572   * On default functionality connecting priority is defined based on join priority
00573   * received in beacon and link quality.
00574   *
00575   * \param interface_id Network interface ID.
00576   * \param beacon_compare_rx_cb_ptr Function pointer.
00577   *
00578   * \return 0 on success.
00579   * \return -1 Unknown network ID.
00580   * \return -2 Other error.
00581   */
00582 extern int8_t arm_nwk_6lowpan_beacon_compare_rx_callback_set(int8_t interface_id, beacon_compare_rx_cb *beacon_compare_rx_cb_ptr);
00583 
00584 /**
00585   * \brief Initialize and configure the interface security mode.
00586   *
00587   * \param interface_id Network interface ID.
00588   * \param mode Defines link layer security mode.
00589   *  NET_SEC_MODE_NO_LINK_SECURITY, No security.
00590   *  NET_SEC_MODE_PSK_LINK_SECURITY, Predefined PSK link layer key and ID.
00591   *  NET_SEC_MODE_PANA_LINK_SECURITY, PANA bootstrap network authentication.
00592   *
00593   * \param sec_level Defined security level is checked only when the mode is not NET_SEC_MODE_NO_LINK_SECURITY.
00594   * \param psk_key_info Pointer for PSK link layer keys. Checked only when the mode is NET_SEC_MODE_PSK_LINK_SECURITY.
00595   *
00596   * \return 0 on success.
00597   */
00598 
00599 extern int8_t arm_nwk_link_layer_security_mode(int8_t interface_id, net_6lowpan_link_layer_sec_mode_e mode, uint8_t sec_level, const net_link_layer_psk_security_info_s *psk_key_info);
00600 
00601 /**
00602   * \brief Initialize and configure interface PANA network client.
00603   *
00604   * \param interface_id Network interface ID.
00605   * \param cipher_mode Defines TLS 1.2 Cipher mode PSK, ECC or both.
00606   * \param psk_key_id PSK KEY id for PSK Setup
00607   *
00608   * \return 0 on success.
00609   * \return -1 Unknown network ID or PANA is not supported at this library.
00610   * \return -2 Interface active.
00611   */
00612 extern int8_t arm_pana_client_library_init(int8_t interface_id, net_tls_cipher_e cipher_mode, uint32_t psk_key_id);
00613 
00614 /**
00615   * \brief Initialize and Configure interface PANA network server.
00616   *
00617   * \param interface_id Network interface ID.
00618   * \param cipher_mode Defines TLS 1.2 Cipher mode PSK, ECC or both.
00619   * \param key_material A pointer to 128-bit key material or NULL when the PANA server generates the random key.
00620   * \param time_period_before_activate_key Guard period after a succesful key delivery phase before the key will be activated by server.
00621   *
00622   * \return 0 On success.
00623   * \return -1 Unknown network ID.
00624   * \return -2 Interface active.
00625   */
00626 extern int8_t arm_pana_server_library_init(int8_t interface_id, net_tls_cipher_e cipher_mode, const uint8_t *key_material, uint32_t time_period_before_activate_key);
00627 
00628 /**
00629   * \brief Manually initiate a PANA client key pull. For test purposes only.
00630   *
00631   * \param interface_id Network interface ID.
00632   *
00633   * \return 0 On success.
00634   * \return -1 Unknown network ID.
00635   */
00636 extern int8_t arm_pana_client_key_pull(int8_t interface_id);
00637 
00638 
00639 /**
00640  * \brief Trigger network key update process
00641  *
00642  * This function delivers a new network key to all ZigBee routers that have registered a GP address to server.
00643  * The function call always trig new key-id. Key delivery is started in 300ms interval between nodes.
00644  * This function does not cause any traffic if the server does not have any router device sessions.
00645  *
00646  * \param interface_id Network interface ID.
00647  * \param network_key_material Pointer to new 128-bit key material, NULL generates a random key.
00648  *
00649  * \return 0 Key Update process OK.
00650  * \return -1 PANA server is not initialized yet.
00651  * \return -2 Old key update still active.
00652  * \return -3 Memory allocation fails.
00653  */
00654 extern int8_t arm_pana_server_key_update(int8_t interface_id, const uint8_t *network_key_material);
00655 
00656 /**
00657  * \brief Activate new key material before standard timeout.
00658  *
00659  * This function is only for testing.
00660  *
00661  * \param interface_id Network interface ID.
00662  *
00663  * \return 0 Key activate process OK.
00664  * \return -1 No Pending key update.
00665  * \return -2 PANA server is not initialized or PANA server API is disabled with this library.
00666  */
00667 extern int8_t arm_pana_activate_new_key(int8_t interface_id);
00668 
00669 
00670 /**
00671  * \brief Read PANA server security key material.
00672  *
00673  * previous_active_network_key Only valid when current_active_key_index is bigger than 1.
00674  *
00675  *\param key Pointer for key material information store.
00676  *
00677  * \return 0 Key read OK.
00678  * \return -1 PANA server key material not available.
00679  */
00680 extern int8_t arm_network_key_get(int8_t interface_id, ns_keys_t *key);
00681 
00682 /**
00683  * \brief Start network interface bootstrap.
00684  *
00685  * \param interface_id Network interface ID.
00686  *
00687  *
00688  * \return >=0 Bootstrap start OK.
00689  * \return -1 Unknown network ID.
00690  * \return -2 Not configured.
00691  * \return -3 Active.
00692  */
00693 extern int8_t arm_nwk_interface_up(int8_t interface_id);
00694 /**
00695  * \brief Stop and set interface to idle.
00696  *
00697  * \param interface_id Network interface ID
00698  *
00699  *
00700  * \return >=0 Process OK.
00701  * \return -1 Unknown network ID.
00702  * \return -3 Not Active.
00703  */
00704 extern int8_t arm_nwk_interface_down(int8_t interface_id);
00705 
00706 /**
00707  * \brief Define border router MAC and 6LoWPAN ND setup for selected interface.
00708  *
00709  * \param interface_id Network interface ID.
00710  * \param border_router_setup_ptr Pointer to MAC and 6LoWPAN ND setup.
00711  *
00712  */
00713 extern int8_t arm_nwk_6lowpan_border_router_init(int8_t interface_id, const border_router_setup_s *border_router_setup_ptr);
00714 /**
00715  * \brief Add context at 6LoWPAN interface configure state.
00716  *
00717  *
00718  * \param interface_id Network interface ID.
00719  * \param c_id_flags Bit 4 indicates compress support and bit 0-3 context ID.
00720  * \param context_len Context length in bits need to be 64-128.
00721  * \param ttl Context time to live, value in minutes.
00722  * \param context_ptr Pointer to full 128-bit memory area.
00723  *
00724  * \return 0 Context update OK.
00725  * \return -1 No memory for new context.
00726  * \return -2 Border router base not allocated.
00727  * \return -3 Given parameter fails (c_id_flags > 0x1f or contex_len < 64).
00728  * \
00729  */
00730 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);
00731 /**
00732  * \brief Update runtime configured context.
00733  *
00734  * This function can change the value of context compress state or time to live.
00735  * It triggers a new ABRO version number, indicating that ND parameters are updated.
00736  *
00737  * \param interface_id Network interface ID.
00738  * \param c_id Context ID stack checks first 4 bits, supported values 0-15.
00739  * \param compress_mode 0 = Compress disabled, otherwise compress enabled.
00740  * \param ttl Context time to live value in minutes.
00741  *
00742  * \return 0 Update OK.
00743  * \return -1 Update fail by router state.
00744  *
00745  */
00746 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);
00747 /**
00748  * \brief Delete allocated context by ID.
00749  *
00750  * \param interface_id Network interface ID.
00751  * \param c_id 4-bit Context ID to be deleted.
00752  *
00753  * \return 0 Context delete OK.
00754  * \return -1 Delete process fails.
00755  */
00756 extern int8_t arm_nwk_6lowpan_border_router_context_remove_by_id(int8_t interface_id, uint8_t c_id);
00757 /**
00758  * \brief Update ND ABRO version number.
00759  *
00760  * \param interface_id Network interface ID
00761  *
00762  * \return 0 ABRO version update OK.
00763  * \return -1 ABRO update fails (Interface is not up yet or the border router base is not allocated).
00764  */
00765 extern int8_t arm_nwk_6lowpan_border_router_configure_push(int8_t interface_id);
00766 
00767 extern int8_t arm_nwk_6lowpan_border_route_nd_default_prefix_timeout_set(int8_t interface_id, uint32_t time);
00768 
00769 /**
00770  * \brief A function to read network layer configurations.
00771  * \param interface_id Network interface ID.
00772  * \param network_params A pointer to the structure where the network layer configs are written.
00773  * \return 0 On success.
00774  * \return Negative value if interface is not known.
00775  */
00776 int8_t arm_nwk_param_read(int8_t interface_id, link_layer_setups_s *network_params);
00777 
00778 
00779 /**
00780  * \brief A function to read MAC PAN-ID, Short address and EUID64.
00781  * \param interface_id Network interface ID.
00782  * \param mac_params A pointer to the structure where the MAC addresses are written.
00783  * \return 0 On success.
00784  * \return Negative value if interface is not known.
00785  */
00786 int8_t arm_nwk_mac_address_read(int8_t interface_id, link_layer_address_s *mac_params);
00787 
00788 
00789 /**
00790  * \brief A function to read 6LoWPAN ND border router address and NWK prefix.
00791  * \param interface_id Network interface ID.
00792  * \param nd_addr_info Pointer to the structure where the address is written.
00793  * \return 0 On success.
00794  * \return Negative value if network interface is not known or if the interface
00795  *          is not in active or ready state.
00796  */
00797 int8_t arm_nwk_nd_address_read(int8_t interface_id, network_layer_address_s *nd_addr_info);
00798 
00799 
00800 /**
00801  * \brief A function to read the networking address information.
00802  * \param interface_id Network interface ID.
00803  * \param addr_id The address information type to be read.
00804  * \param address A pointer to a structure where the address information is written.
00805  * \return 0 On success, -1 on failure.
00806  */
00807 extern int8_t arm_net_address_get(int8_t interface_id, net_address_t addr_id, uint8_t *address);
00808 
00809 /**
00810  * \brief A function to read networking addresses one by one.
00811  * \param interface_id Network interface ID.
00812  * \param addr_id The address information type to be read.
00813  * \param integer A pointer that is incremented every call. Start looping with n=0.
00814  * \param address_buffer[16] A pointer to buffer where address is copied.
00815  * \return 0 On success.
00816  * \return -1 No more addresses available.
00817  */
00818 extern int8_t arm_net_address_list_get_next(int8_t interface_id, int *n, uint8_t address_buffer[16]);
00819 
00820 /**
00821  * \brief A function to read network interface address count.
00822  * \param interface_id Network interface ID.
00823  * \param address_count A pointer to the structure where the address count is saved.
00824  *
00825  * \return 0 On success, -1 on errors.
00826  */
00827 extern int8_t arm_net_interface_address_list_size(int8_t interface_id, uint16_t *address_count);
00828 
00829 /**
00830  * \brief A function to set interface metric.
00831  * \param interface_id Network interface ID.
00832  * \param metric Used to rank otherwise-equivalent routes. Lower is preferred and default is 0. The metric value is added to metric provided by the arm_net_route_add() function.
00833  *
00834  * \return 0 On success, -1 on errors.
00835  */
00836 extern int8_t arm_net_interface_set_metric(int8_t interface_id, uint16_t metric);
00837 
00838 /**
00839  * \brief A function to read the interface metric value on an interface.
00840  * \param interface_id Network interface ID.
00841  * \param metric A pointer to the variable where the interface metric value is saved.
00842  *
00843  * \return 0 On success, -1 on errors.
00844  */
00845 extern int8_t arm_net_interface_get_metric(int8_t interface_id, uint16_t *metric);
00846 
00847 /**
00848  * \brief A function to read the network interface.
00849  * \param interface_id Network interface ID.
00850  * \param address_buf_size Buffer size in bytes, minimum 16 bytes.
00851  * \param address_buffer A pointer to a structure where the addresses are saved one by one.
00852  * \param writed_address_count A pointer to the structure where the number of addresses saved is written.
00853  *
00854  * \return 0 on success, -1 on errors.
00855  */
00856 extern int8_t arm_net_address_list_get(int8_t interface_id, uint8_t address_buf_size, uint8_t *address_buffer, int *writed_address_count);
00857 
00858 /**
00859  * \brief A function to add an address to an interface.
00860  * \param interface_id Network interface ID.
00861  * \param address The address to be added to the interface.
00862  * \param prefix_len The length of the address prefix.
00863  * \param valid_lifetime The time in seconds until the address becomes invalid and is removed from the interface. Value 0xffffffff represents infinity.
00864  * \param preferred_lifetime The time in seconds until the address becomes deprecated. Value 0xffffffff represents infinity. The preferred lifetime should not be longer than a valid lifetime.
00865  * \return 0 on success, -1 on errors.
00866  */
00867 extern int8_t arm_net_address_add_to_interface(int8_t interface_id, const uint8_t address[16], uint8_t prefix_len, uint32_t valid_lifetime, uint32_t preferred_lifetime);
00868 
00869 /**
00870  * \brief A function to remove an address from an interface.
00871  * \param interface_id Network interface ID.
00872  * \param address The address to be removed from the interface.
00873  *
00874  * \return 0 on success, -1 on errors.
00875  */
00876 extern int8_t arm_net_address_delete_from_interface(int8_t interface_id, const uint8_t address[16]);
00877 
00878 /**
00879  * \brief A function to add a route to the routing table.
00880  * \param prefix Destination prefix for the route to be added.
00881  * \param prefix_len The length of the prefix.
00882  * \param next_hop Link-local address of the next hop (e.g. router); if NULL the route is marked as on-link.
00883  * \param lifetime The time in seconds until the route is removed from the routing table. Value 0xffffffff means infinite.
00884  * \param metric Used to rank otherwise-equivalent routes. Lower is preferred. Normally 128.
00885  * \param interface_id Network interface ID.
00886  * \return 0 on success, -1 on add failure, -2 on invalid function parameters.
00887  */
00888 extern int8_t arm_net_route_add(const uint8_t *prefix, uint8_t prefix_len, const uint8_t *next_hop, uint32_t lifetime, uint8_t metric, int8_t interface_id);
00889 
00890 /**
00891  * \brief A function to remove a route from the routing table.
00892  * \param prefix The prefix to be removed.
00893  * \param prefix_len The length of the prefix.
00894  * \param next_hop Link-local address of the next hop.
00895  * \param interface_id Network interface ID.
00896  * \return 0 on success, -1 on delete failure, -2 on invalid function parameters.
00897  */
00898 extern int8_t arm_net_route_delete(const uint8_t *prefix, uint8_t prefix_len, const uint8_t *next_hop, int8_t interface_id);
00899 
00900 /** Border Router ND NVM update types. */
00901 /** ND context update, 20 bytes data behind pointer. */
00902 #define ND_PROXY_CONTEXT_NVM_UPDATE         0
00903 /** ND context update flags update. */
00904 #define ND_PROXY_CONTEXT_FLAGS_NVM_UPDATE   1
00905 /** ND context remove. */
00906 #define ND_PROXY_CONTEXT_NVM_REMOVE         2
00907 /** ND prefix update. */
00908 #define ND_PROXY_PREFIX_NVM_UPDATE          3
00909 /** ND ABRO version update. */
00910 #define ND_PROXY_ABRO_VERSION_NVM_UPDATE    4
00911 /**
00912  * \brief Load context from NVM at ZigBeeIP interface configure state.
00913  *
00914  *
00915  * \param interface_id Network Interface ID
00916  * \param context_data A pointer to properly built 20 bytes update array.
00917  *
00918  * \return 0 Context reload OK.
00919  * \return <0 Load fail.
00920  */
00921 extern int8_t arm_nwk_6lowpan_border_router_nd_context_load(int8_t interface_id, uint8_t *contex_data);  //NVM
00922 
00923 extern int8_t arm_network_certificate_chain_set(const arm_certificate_chain_entry_s *chain_info);
00924 
00925 /**
00926  * \brief Add PSK key to TLS library.
00927  *
00928  * \param key_ptr A pointer to 16 bytes long key array.
00929  * \param key_id PSK key ID.
00930  *
00931  * \return 0 = success
00932  * \return -1 = failure
00933  */
00934 extern int8_t arm_tls_add_psk_key(const uint8_t *key_ptr, uint16_t key_id);
00935 
00936 /**
00937  * \brief Remove PSK key from TLS library.
00938  *
00939  * \param key_id PSK key ID.
00940  *
00941  * \return 0 = success
00942  * \retun -1 = failure
00943  */
00944 extern int8_t arm_tls_remove_psk_key(uint16_t key_id);
00945 
00946 /**
00947  * \brief Check if PSK key ID exists.
00948  *
00949  * \param key_id PSK key ID
00950  *
00951  * \return 0 = success
00952  * \retun -1 = failure
00953  */
00954 extern int8_t arm_tls_check_key(uint16_t key_id);
00955 
00956 /**
00957  * \brief Print routing table
00958  *
00959  * Prints the routing table to the command line
00960  */
00961 void arm_print_routing_table(void);
00962 
00963 /**
00964  * \brief Print routing table
00965  *
00966  * Outputs the routing table using the given printf style function
00967  *
00968  * \param print_fn pointer to a printf style output function
00969  */
00970 void arm_print_routing_table2(void (*print_fn)(const char *fmt, ...));
00971 
00972 /**
00973  * \brief Flush neighbor cache
00974  *
00975  * Flushes the neighbor cache
00976  */
00977 void arm_ncache_flush(void);
00978 
00979 /**
00980  * \brief Print neighbor cache
00981  *
00982  * Prints neighbor cache to the command line
00983  */
00984 void arm_print_neigh_cache(void);
00985 
00986 /**
00987  * \brief Print neighbor cache
00988  *
00989  * Outputs the neighbor cache using the given printf style function
00990  *
00991  * \param print_fn pointer to a printf style output function
00992  */
00993 void arm_print_neigh_cache2(void (*print_fn)(const char *fmt, ...));
00994 
00995 /**
00996   * \brief Get the library version information.
00997   *
00998   * \param *ptr Pointer to data location. Required size is 20 bytes.
00999   *
01000   *
01001   * The array containing the version information has the following structure.
01002   *
01003   *  | Platform type | Version | Build ID |
01004   *  | :-----------: | :----------------: |
01005   *  | 1 byte        |  1 byte | 4 bytes  |
01006   *
01007   */
01008 extern void net_get_version_information(uint8_t *ptr);
01009 #ifdef __cplusplus
01010 }
01011 #endif
01012 #endif /* NET_INTERFACE_H_ */