thread_management_if.h

00001 /*
00002  * Copyright (c) 2014-2018, 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     uint8_t securityPolicyExt; /**< Additional Security Policy byte*/
00087     uint64_t timestamp;/**< commissioning data set timestamp. [48 bit timestamp seconds]-[15 bit timestamp ticks]-[U bit] */
00088 } link_configuration_s;
00089 
00090 /**
00091  * Security policy options. Default for all is '1';
00092  */
00093 #define SECURITY_POLICY_ALL_SECURITY                            0xff
00094 #define SECURITY_POLICY_OUT_OF_BAND_COMMISSIONING_ALLOWED       0x80       /**< Obtaining the Master Key for out-of-band commissioning is enabled when this is set. */
00095 #define SECURITY_POLICY_NATIVE_COMMISSIONING_ALLOWED            0x40       /**< Native Commissioning using PSKc is allowed when this is set. */
00096 #define SECURITY_POLICY_ALL_ROUTERS_JOIN_ALLOWED                0x20       /**< Thread 1.x Routers are enabled when this is set. */
00097 #define SECURITY_POLICY_EXTERNAL_COMMISSIONER_ALLOWED           0x10       /**< This indicates that external Commissioner authentication is allowed using PSKc. */
00098 #define SECURITY_POLICY_BEACON_PAYLOAD_ENABLED                  0x08       /**< Thread 1.x Beacons are enabled when this is set. */
00099 
00100 /**
00101  * Mandatory device information
00102  *
00103  * This information is required if commissioning is enabled for this device.
00104  */
00105 typedef struct {
00106     uint8_t eui64[8];/**< eui64 of the device. This field is used to identify device when joining to network Mandatory*/
00107     uint8_t mesh_local_eid[8]; /**< Mesh local extented id*/
00108     uint8_t extended_random_mac[8]; /**< Extended random mac which is generated during commissioning*/
00109     uint8_t *PSKd_ptr;/**< Device credentials used to authenticate device to commissioner Mandatory  length 6-32*/
00110     uint8_t PSKd_len;/**< Length of PSKd_ptr*/
00111     char *provisioning_uri_ptr;/**< Provisioning url max 64 bytes*/
00112     char *vendor_name_ptr;/**< Vendor name optional max 32 bytes*/
00113     char *vendor_model_ptr;/**< Vendor model optional max 32 bytes*/
00114     char *vendor_sw_version_ptr;/**<  Vendor SW version optional max 16 bytes*/
00115     uint8_t vendor_stack_version[6];/**< Vendor stack version optional all 0 indicates not set*/
00116     uint8_t *vendor_data_ptr;/**<  optional Array max 64 bytes*/
00117     uint8_t vendor_data_len;/**<  optional Array length max 64 bytes*/
00118 } device_configuration_s;
00119 
00120 
00121 /**
00122  * Initialize Thread stack to node mode.
00123  *
00124  * If static configuration is given and new one is updated by commissioner
00125  * it will override current setup. it is safe to always give this as
00126  * default configuration.
00127  *
00128  * \param interface_id Network interface ID.
00129  * \param channel_list A pointer to channel list. Can be NULL if all channels accepted.
00130  * \param device_configuration A pointer to device configuration.
00131  * \param static_configuration A pointer to static configuration. Can be NULL.
00132  *
00133  * \return 0, Init OK.
00134  * \return <0 Init fail.
00135  */
00136 int thread_management_node_init(
00137     int8_t interface_id,
00138     channel_list_s *channel_list,
00139     device_configuration_s *device_configuration,
00140     link_configuration_s *static_configuration);
00141 
00142 /**
00143  * Thread device type.
00144  *
00145  * REED - Router enabled End device. Device can become router or end device depending on network conditions.
00146  * FED - Full End Device. Device creates links and makes address queries but does not become router.
00147  * MED - Minimal End Device. Device communicates through parent. With radio on
00148  * SED - Sleepy End Device. Device communicates through parent. Uses data poll to sleep.
00149 */
00150 typedef enum {
00151     THREAD_DEVICE_REED = 1,
00152     THREAD_DEVICE_FED,
00153     THREAD_DEVICE_MED,
00154     THREAD_DEVICE_SED,
00155 } thread_device_type_e;
00156 
00157 /**
00158  * Change thread device type.
00159  *
00160  * This function modifies the thread device mode. Default values are given in
00161  * function arm_nwk_interface_configure_6lowpan_bootstrap_set().
00162  *
00163  * If this function is called when interface is up re-attach is made.
00164  *
00165  * \param interface_id Network interface ID.
00166  * \param device_type Device type of current bootstrap.
00167  *
00168  * \return 0, Set OK.
00169  * \return <0 Set fail.
00170  */
00171 int thread_management_device_type_set(int8_t interface_id, thread_device_type_e device_type);
00172 
00173 /**
00174  * Get Thread network settings.
00175  *
00176  * Configuration is a pointer to the static configuration and only valid in current context.
00177  *
00178  * \param interface_id Network interface ID.
00179  *
00180  * \return Pointer to link configuration.
00181  * \return NULL Failure.
00182  */
00183 link_configuration_s *thread_management_configuration_get(int8_t interface_id);
00184 
00185 /** Store Thread network link configuration settings to NVM.
00186  *
00187  * Storing is asynchronous operation and this method makes a request to store link
00188  * configuration settings. Operation will be completed in the background.
00189  * Once settings has been stored the Thread network will be restarted with new
00190  * configuration settings.
00191  *
00192  * /param interface Id of network interface. -1 if interface_id is not available.
00193  * /param link_config Pointer to a structure containing link configuration parameters
00194  *
00195  * /return 0 if store request has been delivered successfully to lower layer.
00196  * /return -1 if storing failed (request not delivered to lower layer)
00197  * /return -2 if store request delivered to lower layer but given interface_id was not valid.
00198  */
00199 int thread_management_link_configuration_store(int8_t interface_id, link_configuration_s *link_config);
00200 
00201 /** Configure extra TLVs in nanostack .
00202  *
00203  * Storing is asynchronous operation and this method makes a request to store link
00204  * configuration settings. Operation will be completed in the background.
00205  * Once settings has been stored the Thread network will be restarted with new
00206  * configuration settings.
00207  *
00208  * /param interface Id of network interface. -1 if interface_id is not available.
00209  * /param additional_ptr Pointer to the extra TLV that is to be configured in nanostack
00210  * /param additional_len Length of the additional TLV
00211  *
00212  * /return 0 if store request is successful.
00213  * /return < 0 if request is failed.
00214  */
00215 int thread_management_link_configuration_add(int8_t interface_id, uint8_t *additional_ptr, uint8_t additional_len);
00216 
00217 /** Delete Thread network link configuration settings.
00218  *
00219  * Deletion is asynchronous operation and this method makes a request to delete link
00220  * configuration settings. Operation will be completed in the background.
00221  * Once settings has been deleted the Thread network will be restarted with default settings.
00222  *
00223  * /param interface Id of network interface. -1 can be used if interface_id is not available.
00224  *
00225  * /return 0 if delete request has been delivered successfully to lower layer.
00226  * /return -1 if delete failed (request not delivered to lower layer)
00227  * /return -2 if delete request delivered to lower layer but given interface_id was not valid.
00228  */
00229 int thread_management_link_configuration_delete(int8_t interface_id);
00230 
00231 /**
00232  * Get Thread device settings.
00233  *
00234  * Configuration is a pointer to the static device configuration and only valid in current context.
00235  *
00236  * \param interface_id Network interface ID.
00237  *
00238  * \return Pointer to Device configuration.
00239  * \return NULL Failure.
00240  */
00241 device_configuration_s *thread_management_device_configuration_get(int8_t interface_id);
00242 
00243 /**
00244  * Thread router max child count set.
00245  *
00246  * This function is used to limit the number of children allowed for parent.
00247  *
00248  * \param interface_id Network interface ID.
00249  * \param maxChildCount Min accepted value is 0 and max 32.
00250  *
00251  * \return 0, Set OK.
00252  * \return <0 Set Fail.
00253  */
00254 int thread_management_max_child_count(
00255     int8_t interface_id,
00256     uint8_t maxChildCount);
00257 
00258 /**
00259  * Set Thread device link timeout.
00260  *
00261  * \param interface_id Network interface ID.
00262  * \param link_timeout New timeout value in seconds.
00263  *
00264  * \return 0, Set OK.
00265  * \return <0 Set Fail.
00266  */
00267 int8_t thread_management_set_link_timeout(int8_t interface_id, uint32_t link_timeout);
00268 
00269 /**
00270  * Get link timeout from Thread device.
00271  *
00272  * \param interface_id Network interface ID.
00273  * \param link_timeout [out] A pointer to the location for writing the timeout.
00274  *
00275  * \return 0, Get OK
00276  * \return <0 Get Fail
00277  */
00278 int8_t thread_management_get_link_timeout(int8_t interface_id, uint32_t *link_timeout);
00279 
00280 /**
00281  * Set Thread request full network data.
00282  *
00283  * \param interface_id Network interface ID.
00284  * \param full_nwk_data Whether or not to request full network data.
00285  *
00286  * \return 0, Set OK.
00287  * \return <0 Set Fail.
00288  */
00289 int8_t thread_management_set_request_full_nwk_data(int8_t interface_id, bool full_nwk_data);
00290 
00291 /**
00292  * Get Thread request full network data.
00293  *
00294  * \param interface_id Network interface ID.
00295  * \param full_nwk_data [out] Request full network data
00296  *
00297  * \return 0, Get OK.
00298  * \return <0 Get Fail.
00299  */
00300 int8_t thread_management_get_request_full_nwk_data(int8_t interface_id, bool *full_nwk_data);
00301 
00302 /**
00303  * Additional Thread device settings. Changing these can cause non-compliance with Thread.
00304  *
00305  */
00306 
00307 /**
00308  * Diagnostics functions.
00309  */
00310 
00311 /**
00312  * Get leader mesh local 16 address.
00313  *
00314  * \param interface_id Network interface ID.
00315  * \param address_ptr A pointer to the location of address after copying.
00316  *
00317  * \return 0, Read OK.
00318  * \return <0 Read fail.
00319  */
00320 int thread_management_get_leader_address(int8_t interface_id, uint8_t *address_ptr);
00321 
00322 /**
00323  * Get leader anycast address.
00324  *
00325  * Address should be used when contacting Leader without need to know the actual routing details.
00326  * This address will remain valid even after leader changes.
00327  *
00328  * \param interface_id Network interface ID.
00329  * \param address_ptr A pointer to the location of address after copying.
00330  *
00331  * \return 0, Read OK.
00332  * \return <0 Read fail. Not connected to Thread network.
00333  */
00334 int thread_management_get_leader_aloc(int8_t interface_id, uint8_t *address_ptr);
00335 
00336 /**
00337  * Get parent link local 16 address.
00338  *
00339  * \param interface_id Network interface ID.
00340  * \param address_ptr A pointer to the location of address after copying.
00341  *
00342  * \return 0, Read OK.
00343  * \return <0 Read fail.
00344  */
00345 int thread_management_get_parent_address(int8_t interface_id, uint8_t *address_ptr);
00346 
00347 /**
00348  * Get own mesh local 64 address.
00349  *
00350  * \param interface_id Network interface ID.
00351  * \param address_ptr A pointer to the location of address after copying.
00352  *
00353  * \return 0, Read OK.
00354  * \return <0 Read fail.
00355  */
00356 int thread_management_get_ml64_address(int8_t interface_id, uint8_t *address_ptr);
00357 
00358 /**
00359  * Get own mesh local 16 address.
00360  *
00361  * \param interface_id Network interface ID.
00362  * \param address_ptr A pointer to the location of address after copying.
00363  *
00364  * \return 0, Read OK.
00365  * \return <0 Read fail.
00366  */
00367 int thread_management_get_ml16_address(int8_t interface_id, uint8_t *address_ptr);
00368 
00369 /**
00370  * Get commissioner address.
00371  *
00372  * This function returns the commissioner address where you can continue provisioning traffic.
00373  * If the commissioner is not present this function returns a failure.
00374  *
00375  * \param interface_id Network interface ID.
00376  * \param address_ptr A pointer to the location of address after copying.
00377  * \param port_ptr A pointer to the location of port after copying.
00378  *
00379  * \return 0, Read OK.
00380  * \return <0 Read fail.
00381  */
00382 int thread_management_get_commissioner_address(int8_t interface_id, uint8_t *address_ptr, uint16_t *port_ptr);
00383 
00384 /**
00385  * Set device certificate.
00386  *
00387  * This function sets device certificate
00388  *
00389  * \param interface_id Network interface ID.
00390  * \param device_certificate_ptr A pointer to the device certificate.
00391  * \param device_certificate_len Length of device certificate.
00392  * \param priv_key_ptr A private key
00393  * \param priv_key_len Length of a private key
00394  *
00395  * \return 0, OK.
00396  * \return <0 fail.
00397  */
00398 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);
00399 
00400 /**
00401  * Set network certificate.
00402  *
00403  * This function sets network certificate
00404  *
00405  * \param interface_id Network interface ID.
00406  * \param network_certificate_ptr A pointer array to the network certificate chain.
00407  * \param network_certificate_len An array of lengths of network certificates in chain.
00408  * \param priv_key_ptr A private key
00409  * \param priv_key_len Length of a private key
00410  *
00411  * \return 0, OK.
00412  * \return <0 fail.
00413  */
00414 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);
00415 
00416 /**
00417  * Set Thread partition weighting.
00418  *
00419  * This function sets weighting value for Thread network partition. Interface will be restarted if interface is active and
00420  * new weighting value is different than previous weighting value.
00421  *
00422  * \param interface_id Network interface ID.
00423  * \param partition_weighting New weighting value for Thread partition
00424  *
00425  * \return 0, OK.
00426  * \return <0 fail.
00427  */
00428 int thread_management_partition_weighting_set(int8_t interface_id, uint8_t partition_weighting);
00429 
00430 /**
00431  * Set Thread Sleepy End Device parent packet buffer size.
00432  *
00433  * This function can be used to adjust count of packets SED parent is storing.
00434  *
00435  * \param interface_id Network interface ID.
00436  * \param small_packets_per_child_count Number of small packets parent is storing for each SED.
00437  * \param big_packets_total_count Number of big packets parent can store for all SEDs.
00438  *
00439  * \return 0, OK.
00440  * \return <0 fail.
00441  */
00442 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);
00443 
00444 #ifdef __cplusplus
00445 }
00446 #endif
00447 
00448 #endif /* THREAD_MANAGEMENT_IF_H_ */