thread_management_if.h

00001 /*
00002  * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 
00015 /**
00016  * \file thread_management_if.h
00017  * \brief Thread management interface.
00018  *
00019  * This interface is used for configuring Thread devices.
00020  * After creating the Thread interface, you can use this interface to configure the Thread device
00021  * behaviour. When you are done with the configurations, you need to call interface up to enable a Thread node.
00022  *
00023  */
00024 
00025 #ifndef THREAD_MANAGEMENT_IF_H_
00026 #define THREAD_MANAGEMENT_IF_H_
00027 
00028 #include "ns_types.h"
00029 #include "net_interface.h" /* Declaration for channel_list_s. */
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif
00034 
00035 /*
00036  * Current protocol version of the Thread implementation.
00037  */
00038 #define THREAD_BEACON_PROTOCOL_ID       3
00039 #define THREAD_BEACON_PROTOCOL_VERSION  1
00040 /**
00041  * Thread network configuration.
00042  *
00043  * You can use this structure in start-up in case of a static configuration.
00044  * This data can also be read after joining the Thread network.
00045  * If this data is not provided to the stack, the device starts the commissioning process to join the Thread network.
00046  *
00047  * If the data is provided, all fields must be initialised to 0.
00048  *
00049  * If XPANID and MASTER KEY are provided, the device starts out-of-band commissioning. The values must be initialised to other than 0.
00050  * If mesh_local_eid is initialised to 0 it is randomized at start-up.
00051  * If extended_random_mac is initialised to 0 it is randomized at start-up.
00052  *
00053  * If timestamp values are set to 0 it triggers a network configuration update when joining the network.
00054  *
00055  * */
00056 typedef struct link_configuration {
00057     uint8_t name[16]; /**< Name of the Thread network*/
00058     uint8_t master_key[16]; /**< Master key of the thread network*/
00059     uint8_t PSKc[16]; /**< PSKc value that is calculated from commissioning credentials credentials,XPANID and network name*/
00060     uint8_t mesh_local_ula_prefix[8]; /**< Mesh local ula prefix*/
00061     uint8_t mesh_local_eid[8]; /**< Mesh local extented id*/
00062     uint8_t extented_pan_id[8]; /**< Extended pan id*/
00063     uint8_t extended_random_mac[8]; /**< Extended random mac which is generated during commissioning*/
00064     uint8_t channel_mask[8]; /**< channel page and mask only supported is page 0*/
00065     uint8_t channel_page;/**< channel page supported pages 0*/
00066     char *PSKc_ptr; /**< Commissioning credentials @TODO think if we need the actual credentials*/
00067     uint8_t PSKc_len;
00068     uint16_t key_rotation; /**< Key rotation time in hours*/
00069     uint32_t key_sequence; /**< Key sequence counter */
00070     uint16_t panId; /**< network id*/
00071     uint8_t Protocol_id; /**< current protocol id*/
00072     uint8_t version; /**< current protocol version*/
00073     uint16_t rfChannel; /**< current rf channel*/
00074     uint8_t securityPolicy; /**< Commission Security Policy*/
00075     uint64_t timestamp;/**< commissioning data set timestamp. [48 bit timestamp seconds]-[15 bit timestamp ticks]-[U bit] */
00076 } link_configuration_s;
00077 
00078 /**
00079  * Security policy options. Default for all is '1';
00080  */
00081 #define SECURITY_POLICY_ALL_SECURITY                            0xff
00082 #define SECURITY_POLICY_OUT_OF_BAND_COMMISSIONING_ALLOWED       0x80       /**< Obtaining the Master Key for out-of-band commissioning is enabled when this is set. */
00083 #define SECURITY_POLICY_NATIVE_COMMISSIONING_ALLOWED            0x40       /**< Native Commissioning using PSKc is allowed when this is set. */
00084 #define SECURITY_POLICY_ALL_ROUTERS_JOIN_ALLOWED                0x20       /**< Thread 1.x Routers are enabled when this is set. */
00085 #define SECURITY_POLICY_EXTERNAL_COMMISSIONER_ALLOWED           0x10       /**< This indicates that external Commissioner authentication is allowed using PSKc. */
00086 #define SECURITY_POLICY_BEACON_PAYLOAD_ENABLED                  0x08       /**< Thread 1.x Beacons are enabled when this is set. */
00087 
00088 /*
00089  * Mandatory device information
00090  *
00091  * This information is required if commissioning is enabled for this device.
00092  */
00093 typedef struct {
00094     uint8_t eui64[8];/**< eui64 of the device. This field is used to identify device when joining to network Mandatory*/
00095     uint8_t *PSKd_ptr;/**< Device credentials used to authenticate device to commissioner Mandatory  length 6-32*/
00096     uint8_t PSKd_len;
00097     char *provisioning_uri_ptr;/**< Provisioning url max 64 bytes*/
00098     char *vendor_name_ptr;/**< Vendor name optional max 32 bytes*/
00099     char *vendor_model_ptr;/**< Vendor model optional max 32 bytes*/
00100     char *vendor_sw_version_ptr;/**<  Vendor SW version optional max 16 bytes*/
00101     uint8_t vendor_stack_version[6];/**< Vendor stack version optional all 0 indicates not set*/
00102     uint8_t *vendor_data_ptr;/**<  optional Array max 64 bytes*/
00103     uint8_t vendor_data_len;/**<  optional Array length max 64 bytes*/
00104 } device_configuration_s;
00105 
00106 
00107 /**
00108  * Initialize Thread stack to node mode.
00109  *
00110  * \param interface_id Network interface ID.
00111  * \param channel_list A pointer to channel list. Can be NULL if all channels accepted.
00112  * \param device_configuration A pointer to device configuration.
00113  * \param static_configuration A pointer to static configuration. Can be NULL.
00114  *
00115  * \return 0, Init OK.
00116  * \return <0 Init fail.
00117  */
00118 int thread_management_node_init(
00119     int8_t interface_id,
00120     channel_list_s *channel_list,
00121     device_configuration_s *device_configuration,
00122     link_configuration_s *static_configuration);
00123 
00124 /**
00125  * Get Thread network settings.
00126  *
00127  * Configuration is a pointer to the static configuration and only valid in current context.
00128  *
00129  * \param interface_id Network interface ID.
00130  *
00131  * \return Pointer to link configuration.
00132  * \return NULL Failure.
00133  */
00134 link_configuration_s *thread_management_configuration_get(int8_t interface_id);
00135 
00136 /** Store Thread network link configuration settings to NVM.
00137  *
00138  * Storing is asynchronous operation and this method makes a request to store link
00139  * configuration settings. Operation will be completed in the background.
00140  * Once settings has been stored the Thread network will be restarted with new
00141  * configuration settings.
00142  *
00143  * /param interface Id of network interface. -1 if interface_id is not available.
00144  * /param link_config Pointer to a structure containing link configuration parameters
00145  *
00146  * /return 0 if store request has been delivered successfully to lower layer.
00147  * /return -1 if storing failed (request not delivered to lower layer)
00148  * /return -2 if store request delivered to lower layer but given interface_id was not valid.
00149  */
00150 int thread_management_link_configuration_store(int8_t interface_id, link_configuration_s *link_config);
00151 
00152 /** Delete Thread network link configuration settings.
00153  *
00154  * Deletion is asynchronous operation and this method makes a request to delete link
00155  * configuration settings. Operation will be completed in the background.
00156  * Once settings has been deleted the Thread network will be restarted with default settings.
00157  *
00158  * /param interface Id of network interface. -1 can be used if interface_id is not available.
00159  *
00160  * /return 0 if delete request has been delivered successfully to lower layer.
00161  * /return -1 if delete failed (request not delivered to lower layer)
00162  * /return -2 if delete request delivered to lower layer but given interface_id was not valid.
00163  */
00164 int thread_management_link_configuration_delete(int8_t interface_id);
00165 
00166 /**
00167  * Get Thread device settings.
00168  *
00169  * Configuration is a pointer to the static device configuration and only valid in current context.
00170  *
00171  * \param interface_id Network interface ID.
00172  *
00173  * \return Pointer to link configuration.
00174  * \return NULL Failure.
00175  */
00176 device_configuration_s *thread_management_device_configuration_get(int8_t interface_id);
00177 
00178 /**
00179  * Thread router max child count set.
00180  *
00181  * This function is used to limit the number of children allowed for parent.
00182  *
00183  * \param interface_id Network interface ID.
00184  * \param maxChildCount Min accepted value is 0 and max 32.
00185  *
00186  * \return 0, Set OK.
00187  * \return <0 Set Fail.
00188  */
00189 int thread_management_max_child_count(
00190     int8_t interface_id,
00191     uint8_t maxChildCount);
00192 
00193 /**
00194  * Get Thread device link timeout.
00195  *
00196  * \param interface_id Network interface ID.
00197  * \link_timeout New timeout value in seconds.
00198  *
00199  * \return 0, Set OK.
00200  * \return <0 Set Fail.
00201  */
00202 int8_t thread_management_set_link_timeout(int8_t interface_id, uint32_t link_timeout);
00203 
00204 /**
00205  * Set link timeout for Thread device.
00206  *
00207  * \param interface_id Network interface ID.
00208  * \link_timeout[out] A pointer to the location for writing the timeout.
00209  *
00210  * \return 0, Get OK
00211  * \return <0 Get Fail
00212  */
00213 int8_t thread_management_get_link_timeout(int8_t interface_id, uint32_t *link_timeout);
00214 
00215 /**
00216  * Set Thread request full network data.
00217  *
00218  * \param interface_id Network interface ID.
00219  * \param full_nwk_data Whether or not to request full network data.
00220  *
00221  * \return 0, Set OK.
00222  * \return <0 Set Fail.
00223  */
00224 int8_t thread_management_set_request_full_nwk_data(int8_t interface_id, bool full_nwk_data);
00225 
00226 /**
00227  * Get Thread request full network data.
00228  *
00229  * \param interface_id Network interface ID.
00230  * \link_timeout[out] A pointer to the location for writing the flag value.
00231  *
00232  * \return 0, Get OK.
00233  * \return <0 Get Fail.
00234  */
00235 int8_t thread_management_get_request_full_nwk_data(int8_t interface_id, bool *full_nwk_data);
00236 
00237 /**
00238  * Additional Thread device settings. Changing these can cause non-compliance with Thread.
00239  *
00240  */
00241 
00242 /**
00243  * Diagnostics functions.
00244  */
00245 
00246 /**
00247  * Get leader mesh local 16 address.
00248  *
00249  * \param interface_id Network interface ID.
00250  * \param address_ptr A pointer to the location of address after copying.
00251  *
00252  * \return 0, Read OK.
00253  * \return <0 Read fail.
00254  */
00255 int thread_management_get_leader_address(int8_t interface_id, uint8_t *address_ptr);
00256 
00257 /**
00258  * Get parent link local 16 address.
00259  *
00260  * \param interface_id Network interface ID.
00261  * \param address_ptr A pointer to the location of address after copying.
00262  *
00263  * \return 0, Read OK.
00264  * \return <0 Read fail.
00265  */
00266 int thread_management_get_parent_address(int8_t interface_id, uint8_t *address_ptr);
00267 
00268 /**
00269  * Get own mesh local 64 address.
00270  *
00271  * \param interface_id Network interface ID.
00272  * \param address_ptr A pointer to the location of address after copying.
00273  *
00274  * \return 0, Read OK.
00275  * \return <0 Read fail.
00276  */
00277 int thread_management_get_ml64_address(int8_t interface_id, uint8_t *address_ptr);
00278 
00279 /**
00280  * Get own mesh local 16 address.
00281  *
00282  * \param interface_id Network interface ID.
00283  * \param address_ptr A pointer to the location of address after copying.
00284  *
00285  * \return 0, Read OK.
00286  * \return <0 Read fail.
00287  */
00288 int thread_management_get_ml16_address(int8_t interface_id, uint8_t *address_ptr);
00289 
00290 /**
00291  * Get commissioner address.
00292  *
00293  * This function returns the commissioner address where you can continue provisioning traffic.
00294  * If the commissioner is not present this function returns a failure.
00295  *
00296  * \param interface_id Network interface ID.
00297  * \param address_ptr A pointer to the location of address after copying.
00298  * \param port_ptr A pointer to the location of port after copying.
00299  *
00300  * \return 0, Read OK.
00301  * \return <0 Read fail.
00302  */
00303 int thread_management_get_commissioner_address(int8_t interface_id, uint8_t *address_ptr, uint16_t *port_ptr);
00304 
00305 
00306 #ifdef __cplusplus
00307 }
00308 #endif
00309 
00310 #endif /* THREAD_MANAGEMENT_IF_H_ */