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_ */