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