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