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