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.
thread_management_if.h
00001 /* 00002 * Copyright (c) 2014-2017, Arm Limited and affiliates. 00003 * SPDX-License-Identifier: BSD-3-Clause 00004 * 00005 * Redistribution and use in source and binary forms, with or without 00006 * modification, are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright 00009 * notice, this list of conditions and the following disclaimer. 00010 * 2. Redistributions in binary form must reproduce the above copyright 00011 * notice, this list of conditions and the following disclaimer in the 00012 * documentation and/or other materials provided with the distribution. 00013 * 3. Neither the name of the copyright holder nor the 00014 * names of its contributors may be used to endorse or promote products 00015 * derived from this software without specific prior written permission. 00016 * 00017 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00018 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00019 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 00020 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 00021 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 00022 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 00023 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 00024 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 00025 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 00026 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 00027 * POSSIBILITY OF SUCH DAMAGE. 00028 */ 00029 00030 /** 00031 * \file thread_management_if.h 00032 * \brief Thread management interface. 00033 * 00034 * This interface is used for configuring Thread devices. 00035 * After creating the Thread interface, you can use this interface to configure the Thread device 00036 * behaviour. When you are done with the configurations, you need to call interface up to enable a Thread node. 00037 * 00038 */ 00039 00040 #ifndef THREAD_MANAGEMENT_IF_H_ 00041 #define THREAD_MANAGEMENT_IF_H_ 00042 00043 #include "ns_types.h" 00044 #include "net_interface.h" /* Declaration for channel_list_s. */ 00045 00046 #ifdef __cplusplus 00047 extern "C" { 00048 #endif 00049 00050 /* 00051 * Current protocol version of the Thread implementation. 00052 */ 00053 #define THREAD_BEACON_PROTOCOL_ID 3 /**< Beacon Protocol ID */ 00054 #define THREAD_BEACON_PROTOCOL_VERSION 1 /**< Beacon Protocol version */ 00055 00056 /** 00057 * Thread network configuration. 00058 * 00059 * You can use this structure in start-up in case of a static configuration. 00060 * This data can also be read after joining the Thread network. 00061 * If this data is not provided to the stack, the device starts the commissioning process to join the Thread network. 00062 * 00063 * If the data is provided, all fields must be initialised to 0. 00064 * 00065 * If XPANID and MASTER KEY are provided, the device starts out-of-band commissioning. The values must be initialised to other than 0. 00066 * If mesh_local_eid is initialised to 0 it is randomized at start-up. 00067 * If extended_random_mac is initialised to 0 it is randomized at start-up. 00068 * 00069 * If timestamp values are set to 0 it triggers a network configuration update when joining the network. 00070 * 00071 * */ 00072 typedef struct link_configuration { 00073 uint8_t name[16]; /**< Name of the Thread network*/ 00074 uint8_t master_key[16]; /**< Master key of the thread network*/ 00075 uint8_t PSKc[16]; /**< PSKc value that is calculated from commissioning credentials credentials,XPANID and network name*/ 00076 uint8_t mesh_local_ula_prefix[8]; /**< Mesh local ula prefix*/ 00077 uint8_t extented_pan_id[8]; /**< Extended pan id*/ 00078 uint8_t channel_mask[8]; /**< channel page and mask only supported is page 0*/ 00079 uint8_t channel_page;/**< channel page supported pages 0*/ 00080 uint16_t key_rotation; /**< Key rotation time in hours*/ 00081 uint32_t key_sequence; /**< Key sequence counter */ 00082 uint16_t panId; /**< network id*/ 00083 uint8_t version; /**< current protocol version*/ 00084 uint16_t rfChannel; /**< current rf channel*/ 00085 uint8_t securityPolicy; /**< Commission Security Policy*/ 00086 uint64_t timestamp;/**< commissioning data set timestamp. [48 bit timestamp seconds]-[15 bit timestamp ticks]-[U bit] */ 00087 } link_configuration_s; 00088 00089 /** 00090 * Security policy options. Default for all is '1'; 00091 */ 00092 #define SECURITY_POLICY_ALL_SECURITY 0xff 00093 #define SECURITY_POLICY_OUT_OF_BAND_COMMISSIONING_ALLOWED 0x80 /**< Obtaining the Master Key for out-of-band commissioning is enabled when this is set. */ 00094 #define SECURITY_POLICY_NATIVE_COMMISSIONING_ALLOWED 0x40 /**< Native Commissioning using PSKc is allowed when this is set. */ 00095 #define SECURITY_POLICY_ALL_ROUTERS_JOIN_ALLOWED 0x20 /**< Thread 1.x Routers are enabled when this is set. */ 00096 #define SECURITY_POLICY_EXTERNAL_COMMISSIONER_ALLOWED 0x10 /**< This indicates that external Commissioner authentication is allowed using PSKc. */ 00097 #define SECURITY_POLICY_BEACON_PAYLOAD_ENABLED 0x08 /**< Thread 1.x Beacons are enabled when this is set. */ 00098 00099 /* 00100 * Mandatory device information 00101 * 00102 * This information is required if commissioning is enabled for this device. 00103 */ 00104 typedef struct { 00105 uint8_t eui64[8];/**< eui64 of the device. This field is used to identify device when joining to network Mandatory*/ 00106 uint8_t mesh_local_eid[8]; /**< Mesh local extented id*/ 00107 uint8_t extended_random_mac[8]; /**< Extended random mac which is generated during commissioning*/ 00108 uint8_t *PSKd_ptr;/**< Device credentials used to authenticate device to commissioner Mandatory length 6-32*/ 00109 uint8_t PSKd_len;/**< Length of PSKd_ptr*/ 00110 char *provisioning_uri_ptr;/**< Provisioning url max 64 bytes*/ 00111 char *vendor_name_ptr;/**< Vendor name optional max 32 bytes*/ 00112 char *vendor_model_ptr;/**< Vendor model optional max 32 bytes*/ 00113 char *vendor_sw_version_ptr;/**< Vendor SW version optional max 16 bytes*/ 00114 uint8_t vendor_stack_version[6];/**< Vendor stack version optional all 0 indicates not set*/ 00115 uint8_t *vendor_data_ptr;/**< optional Array max 64 bytes*/ 00116 uint8_t vendor_data_len;/**< optional Array length max 64 bytes*/ 00117 } device_configuration_s; 00118 00119 00120 /** 00121 * Initialize Thread stack to node mode. 00122 * 00123 * If static configuration is given and new one is updated by commissioner 00124 * it will override current setup. it is safe to always give this as 00125 * default configuration. 00126 * 00127 * \param interface_id Network interface ID. 00128 * \param channel_list A pointer to channel list. Can be NULL if all channels accepted. 00129 * \param device_configuration A pointer to device configuration. 00130 * \param static_configuration A pointer to static configuration. Can be NULL. 00131 * 00132 * \return 0, Init OK. 00133 * \return <0 Init fail. 00134 */ 00135 int thread_management_node_init( 00136 int8_t interface_id, 00137 channel_list_s *channel_list, 00138 device_configuration_s *device_configuration, 00139 link_configuration_s *static_configuration); 00140 00141 /** 00142 * Thread device type. 00143 * 00144 * REED - Router enabled End device. Device can become router or end device depending on network conditions. 00145 * FED - Full End Device. Device creates links and makes address queries but does not become router. 00146 * MED - Minimal End Device. Device communicates through parent. With radio on 00147 * SED - Sleepy End Device. Device communicates through parent. Uses data poll to sleep. 00148 */ 00149 typedef enum { 00150 THREAD_DEVICE_REED = 1, 00151 THREAD_DEVICE_FED, 00152 THREAD_DEVICE_MED, 00153 THREAD_DEVICE_SED, 00154 } thread_device_type_e; 00155 00156 /** 00157 * Change thread device type. 00158 * 00159 * This function modifies the thread device mode. Default values are given in 00160 * function arm_nwk_interface_configure_6lowpan_bootstrap_set(). 00161 * 00162 * If this function is called when interface is up re-attach is made. 00163 * 00164 * \param interface_id Network interface ID. 00165 * \param device_type Device type of current bootstrap. 00166 * 00167 * \return 0, Set OK. 00168 * \return <0 Set fail. 00169 */ 00170 int thread_management_device_type_set(int8_t interface_id, thread_device_type_e device_type); 00171 00172 /** 00173 * Get Thread network settings. 00174 * 00175 * Configuration is a pointer to the static configuration and only valid in current context. 00176 * 00177 * \param interface_id Network interface ID. 00178 * 00179 * \return Pointer to link configuration. 00180 * \return NULL Failure. 00181 */ 00182 link_configuration_s *thread_management_configuration_get(int8_t interface_id); 00183 00184 /** Store Thread network link configuration settings to NVM. 00185 * 00186 * Storing is asynchronous operation and this method makes a request to store link 00187 * configuration settings. Operation will be completed in the background. 00188 * Once settings has been stored the Thread network will be restarted with new 00189 * configuration settings. 00190 * 00191 * /param interface Id of network interface. -1 if interface_id is not available. 00192 * /param link_config Pointer to a structure containing link configuration parameters 00193 * 00194 * /return 0 if store request has been delivered successfully to lower layer. 00195 * /return -1 if storing failed (request not delivered to lower layer) 00196 * /return -2 if store request delivered to lower layer but given interface_id was not valid. 00197 */ 00198 int thread_management_link_configuration_store(int8_t interface_id, link_configuration_s *link_config); 00199 00200 /** Configure extra TLVs in nanostack . 00201 * 00202 * Storing is asynchronous operation and this method makes a request to store link 00203 * configuration settings. Operation will be completed in the background. 00204 * Once settings has been stored the Thread network will be restarted with new 00205 * configuration settings. 00206 * 00207 * /param interface Id of network interface. -1 if interface_id is not available. 00208 * /param additional_ptr Pointer to the extra TLV that is to be configured in nanostack 00209 * /param additional_len Length of the additional TLV 00210 * 00211 * /return 0 if store request is successful. 00212 * /return < 0 if request is failed. 00213 */ 00214 int thread_management_link_configuration_add(int8_t interface_id, uint8_t *additional_ptr, uint8_t additional_len); 00215 00216 /** Delete Thread network link configuration settings. 00217 * 00218 * Deletion is asynchronous operation and this method makes a request to delete link 00219 * configuration settings. Operation will be completed in the background. 00220 * Once settings has been deleted the Thread network will be restarted with default settings. 00221 * 00222 * /param interface Id of network interface. -1 can be used if interface_id is not available. 00223 * 00224 * /return 0 if delete request has been delivered successfully to lower layer. 00225 * /return -1 if delete failed (request not delivered to lower layer) 00226 * /return -2 if delete request delivered to lower layer but given interface_id was not valid. 00227 */ 00228 int thread_management_link_configuration_delete(int8_t interface_id); 00229 00230 /** 00231 * Get Thread device settings. 00232 * 00233 * Configuration is a pointer to the static device configuration and only valid in current context. 00234 * 00235 * \param interface_id Network interface ID. 00236 * 00237 * \return Pointer to Device configuration. 00238 * \return NULL Failure. 00239 */ 00240 device_configuration_s *thread_management_device_configuration_get(int8_t interface_id); 00241 00242 /** 00243 * Thread router max child count set. 00244 * 00245 * This function is used to limit the number of children allowed for parent. 00246 * 00247 * \param interface_id Network interface ID. 00248 * \param maxChildCount Min accepted value is 0 and max 32. 00249 * 00250 * \return 0, Set OK. 00251 * \return <0 Set Fail. 00252 */ 00253 int thread_management_max_child_count( 00254 int8_t interface_id, 00255 uint8_t maxChildCount); 00256 00257 /** 00258 * Set Thread device link timeout. 00259 * 00260 * \param interface_id Network interface ID. 00261 * \param link_timeout New timeout value in seconds. 00262 * 00263 * \return 0, Set OK. 00264 * \return <0 Set Fail. 00265 */ 00266 int8_t thread_management_set_link_timeout(int8_t interface_id, uint32_t link_timeout); 00267 00268 /** 00269 * Get link timeout from Thread device. 00270 * 00271 * \param interface_id Network interface ID. 00272 * \param link_timeout [out] A pointer to the location for writing the timeout. 00273 * 00274 * \return 0, Get OK 00275 * \return <0 Get Fail 00276 */ 00277 int8_t thread_management_get_link_timeout(int8_t interface_id, uint32_t *link_timeout); 00278 00279 /** 00280 * Set Thread request full network data. 00281 * 00282 * \param interface_id Network interface ID. 00283 * \param full_nwk_data Whether or not to request full network data. 00284 * 00285 * \return 0, Set OK. 00286 * \return <0 Set Fail. 00287 */ 00288 int8_t thread_management_set_request_full_nwk_data(int8_t interface_id, bool full_nwk_data); 00289 00290 /** 00291 * Get Thread request full network data. 00292 * 00293 * \param interface_id Network interface ID. 00294 * \param full_nwk_data [out] Request full network data 00295 * 00296 * \return 0, Get OK. 00297 * \return <0 Get Fail. 00298 */ 00299 int8_t thread_management_get_request_full_nwk_data(int8_t interface_id, bool *full_nwk_data); 00300 00301 /** 00302 * Additional Thread device settings. Changing these can cause non-compliance with Thread. 00303 * 00304 */ 00305 00306 /** 00307 * Diagnostics functions. 00308 */ 00309 00310 /** 00311 * Get leader mesh local 16 address. 00312 * 00313 * \param interface_id Network interface ID. 00314 * \param address_ptr A pointer to the location of address after copying. 00315 * 00316 * \return 0, Read OK. 00317 * \return <0 Read fail. 00318 */ 00319 int thread_management_get_leader_address(int8_t interface_id, uint8_t *address_ptr); 00320 00321 /** 00322 * Get leader anycast address. 00323 * 00324 * Address should be used when contacting Leader without need to know the actual routing details. 00325 * This address will remain valid even after leader changes. 00326 * 00327 * \param interface_id Network interface ID. 00328 * \param address_ptr A pointer to the location of address after copying. 00329 * 00330 * \return 0, Read OK. 00331 * \return <0 Read fail. Not connected to Thread network. 00332 */ 00333 int thread_management_get_leader_aloc(int8_t interface_id, uint8_t *address_ptr); 00334 00335 /** 00336 * Get parent link local 16 address. 00337 * 00338 * \param interface_id Network interface ID. 00339 * \param address_ptr A pointer to the location of address after copying. 00340 * 00341 * \return 0, Read OK. 00342 * \return <0 Read fail. 00343 */ 00344 int thread_management_get_parent_address(int8_t interface_id, uint8_t *address_ptr); 00345 00346 /** 00347 * Get own mesh local 64 address. 00348 * 00349 * \param interface_id Network interface ID. 00350 * \param address_ptr A pointer to the location of address after copying. 00351 * 00352 * \return 0, Read OK. 00353 * \return <0 Read fail. 00354 */ 00355 int thread_management_get_ml64_address(int8_t interface_id, uint8_t *address_ptr); 00356 00357 /** 00358 * Get own mesh local 16 address. 00359 * 00360 * \param interface_id Network interface ID. 00361 * \param address_ptr A pointer to the location of address after copying. 00362 * 00363 * \return 0, Read OK. 00364 * \return <0 Read fail. 00365 */ 00366 int thread_management_get_ml16_address(int8_t interface_id, uint8_t *address_ptr); 00367 00368 /** 00369 * Get commissioner address. 00370 * 00371 * This function returns the commissioner address where you can continue provisioning traffic. 00372 * If the commissioner is not present this function returns a failure. 00373 * 00374 * \param interface_id Network interface ID. 00375 * \param address_ptr A pointer to the location of address after copying. 00376 * \param port_ptr A pointer to the location of port after copying. 00377 * 00378 * \return 0, Read OK. 00379 * \return <0 Read fail. 00380 */ 00381 int thread_management_get_commissioner_address(int8_t interface_id, uint8_t *address_ptr, uint16_t *port_ptr); 00382 00383 /** 00384 * Set device certificate. 00385 * 00386 * This function sets device certificate 00387 * 00388 * \param interface_id Network interface ID. 00389 * \param device_certificate_ptr A pointer to the device certificate. 00390 * \param device_certificate_len Length of device certificate. 00391 * \param priv_key_ptr A private key 00392 * \param priv_key_len Length of a private key 00393 * 00394 * \return 0, OK. 00395 * \return <0 fail. 00396 */ 00397 int thread_management_device_certificate_set(int8_t interface_id, const unsigned char *device_certificate_ptr, uint16_t device_certificate_len, const unsigned char *priv_key_ptr, uint16_t priv_key_len); 00398 00399 /** 00400 * Set network certificate. 00401 * 00402 * This function sets network certificate 00403 * 00404 * \param interface_id Network interface ID. 00405 * \param network_certificate_ptr A pointer array to the network certificate chain. 00406 * \param network_certificate_len An array of lengths of network certificates in chain. 00407 * \param priv_key_ptr A private key 00408 * \param priv_key_len Length of a private key 00409 * 00410 * \return 0, OK. 00411 * \return <0 fail. 00412 */ 00413 int thread_management_network_certificate_set(int8_t interface_id, const unsigned char *network_certificate_ptr, uint16_t network_certificate_len, const unsigned char *priv_key_ptr, uint16_t priv_key_len); 00414 00415 /** 00416 * Set Thread partition weighting. 00417 * 00418 * This function sets weighting value for Thread network partition. Interface will be restarted if interface is active and 00419 * new weighting value is different than previous weighting value. 00420 * 00421 * \param interface_id Network interface ID. 00422 * \param partition_weighting New weighting value for Thread partition 00423 * 00424 * \return 0, OK. 00425 * \return <0 fail. 00426 */ 00427 int thread_management_partition_weighting_set(int8_t interface_id, uint8_t partition_weighting); 00428 00429 /** 00430 * Set Thread Sleepy End Device parent packet buffer size. 00431 * 00432 * This function can be used to adjust count of packets SED parent is storing. 00433 * 00434 * \param interface_id Network interface ID. 00435 * \param small_packets_per_child_count Number of small packets parent is storing for each SED. 00436 * \param big_packets_total_count Number of big packets parent can store for all SEDs. 00437 * 00438 * \return 0, OK. 00439 * \return <0 fail. 00440 */ 00441 int thread_management_sed_parent_buffer_size_set(int8_t interface_id, uint16_t small_packets_per_child_count, uint16_t big_packets_total_count); 00442 00443 #ifdef __cplusplus 00444 } 00445 #endif 00446 00447 #endif /* THREAD_MANAGEMENT_IF_H_ */
Generated on Tue Jul 12 2022 18:18:53 by
