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  * Thread device type.
00126  *
00127  * REED - Router enabled End device. Device can become router or end device depending on network conditions.
00128  * FED - Full End Device. Device creates links and makes address queries but does not become router.
00129  * MED - Minimal End Device. Device communicates through parent. With radio on
00130  * SED - Sleepy End Device. Device communicates through parent. Uses data poll to sleep.
00131 */
00132 typedef enum {
00133     THREAD_DEVICE_REED = 1,
00134     THREAD_DEVICE_FED,
00135     THREAD_DEVICE_MED,
00136     THREAD_DEVICE_SED,
00137 } thread_device_type_e;
00138 
00139 /**
00140  * Change thread device type.
00141  *
00142  * This function modifies the thread device mode. Default values are given in
00143  * function arm_nwk_interface_configure_6lowpan_bootstrap_set().
00144  *
00145  * If this function is called when interface is up re-attach is made.
00146  *
00147  * \param interface_id Network interface ID.
00148  * \param device_type Device type of current bootstrap.
00149  *
00150  * \return 0, Set OK.
00151  * \return <0 Set fail.
00152  */
00153 
00154 int thread_management_device_type_set(int8_t interface_id, thread_device_type_e device_type);
00155 
00156 /**
00157  * Get Thread network settings.
00158  *
00159  * Configuration is a pointer to the static configuration and only valid in current context.
00160  *
00161  * \param interface_id Network interface ID.
00162  *
00163  * \return Pointer to link configuration.
00164  * \return NULL Failure.
00165  */
00166 link_configuration_s *thread_management_configuration_get(int8_t interface_id);
00167 
00168 /** Store Thread network link configuration settings to NVM.
00169  *
00170  * Storing is asynchronous operation and this method makes a request to store link
00171  * configuration settings. Operation will be completed in the background.
00172  * Once settings has been stored the Thread network will be restarted with new
00173  * configuration settings.
00174  *
00175  * /param interface Id of network interface. -1 if interface_id is not available.
00176  * /param link_config Pointer to a structure containing link configuration parameters
00177  *
00178  * /return 0 if store request has been delivered successfully to lower layer.
00179  * /return -1 if storing failed (request not delivered to lower layer)
00180  * /return -2 if store request delivered to lower layer but given interface_id was not valid.
00181  */
00182 int thread_management_link_configuration_store(int8_t interface_id, link_configuration_s *link_config);
00183 
00184 /** Delete Thread network link configuration settings.
00185  *
00186  * Deletion is asynchronous operation and this method makes a request to delete link
00187  * configuration settings. Operation will be completed in the background.
00188  * Once settings has been deleted the Thread network will be restarted with default settings.
00189  *
00190  * /param interface Id of network interface. -1 can be used if interface_id is not available.
00191  *
00192  * /return 0 if delete request has been delivered successfully to lower layer.
00193  * /return -1 if delete failed (request not delivered to lower layer)
00194  * /return -2 if delete request delivered to lower layer but given interface_id was not valid.
00195  */
00196 int thread_management_link_configuration_delete(int8_t interface_id);
00197 
00198 /**
00199  * Get Thread device settings.
00200  *
00201  * Configuration is a pointer to the static device configuration and only valid in current context.
00202  *
00203  * \param interface_id Network interface ID.
00204  *
00205  * \return Pointer to link configuration.
00206  * \return NULL Failure.
00207  */
00208 device_configuration_s *thread_management_device_configuration_get(int8_t interface_id);
00209 
00210 /**
00211  * Thread router max child count set.
00212  *
00213  * This function is used to limit the number of children allowed for parent.
00214  *
00215  * \param interface_id Network interface ID.
00216  * \param maxChildCount Min accepted value is 0 and max 32.
00217  *
00218  * \return 0, Set OK.
00219  * \return <0 Set Fail.
00220  */
00221 int thread_management_max_child_count(
00222     int8_t interface_id,
00223     uint8_t maxChildCount);
00224 
00225 /**
00226  * Get Thread device link timeout.
00227  *
00228  * \param interface_id Network interface ID.
00229  * \link_timeout New timeout value in seconds.
00230  *
00231  * \return 0, Set OK.
00232  * \return <0 Set Fail.
00233  */
00234 int8_t thread_management_set_link_timeout(int8_t interface_id, uint32_t link_timeout);
00235 
00236 /**
00237  * Set link timeout for Thread device.
00238  *
00239  * \param interface_id Network interface ID.
00240  * \link_timeout[out] A pointer to the location for writing the timeout.
00241  *
00242  * \return 0, Get OK
00243  * \return <0 Get Fail
00244  */
00245 int8_t thread_management_get_link_timeout(int8_t interface_id, uint32_t *link_timeout);
00246 
00247 /**
00248  * Set Thread request full network data.
00249  *
00250  * \param interface_id Network interface ID.
00251  * \param full_nwk_data Whether or not to request full network data.
00252  *
00253  * \return 0, Set OK.
00254  * \return <0 Set Fail.
00255  */
00256 int8_t thread_management_set_request_full_nwk_data(int8_t interface_id, bool full_nwk_data);
00257 
00258 /**
00259  * Get Thread request full network data.
00260  *
00261  * \param interface_id Network interface ID.
00262  * \link_timeout[out] A pointer to the location for writing the flag value.
00263  *
00264  * \return 0, Get OK.
00265  * \return <0 Get Fail.
00266  */
00267 int8_t thread_management_get_request_full_nwk_data(int8_t interface_id, bool *full_nwk_data);
00268 
00269 /**
00270  * Additional Thread device settings. Changing these can cause non-compliance with Thread.
00271  *
00272  */
00273 
00274 /**
00275  * Diagnostics functions.
00276  */
00277 
00278 /**
00279  * Get leader mesh local 16 address.
00280  *
00281  * \param interface_id Network interface ID.
00282  * \param address_ptr A pointer to the location of address after copying.
00283  *
00284  * \return 0, Read OK.
00285  * \return <0 Read fail.
00286  */
00287 int thread_management_get_leader_address(int8_t interface_id, uint8_t *address_ptr);
00288 
00289 /**
00290  * Get parent link local 16 address.
00291  *
00292  * \param interface_id Network interface ID.
00293  * \param address_ptr A pointer to the location of address after copying.
00294  *
00295  * \return 0, Read OK.
00296  * \return <0 Read fail.
00297  */
00298 int thread_management_get_parent_address(int8_t interface_id, uint8_t *address_ptr);
00299 
00300 /**
00301  * Get own mesh local 64 address.
00302  *
00303  * \param interface_id Network interface ID.
00304  * \param address_ptr A pointer to the location of address after copying.
00305  *
00306  * \return 0, Read OK.
00307  * \return <0 Read fail.
00308  */
00309 int thread_management_get_ml64_address(int8_t interface_id, uint8_t *address_ptr);
00310 
00311 /**
00312  * Get own 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_ml16_address(int8_t interface_id, uint8_t *address_ptr);
00321 
00322 /**
00323  * Get commissioner address.
00324  *
00325  * This function returns the commissioner address where you can continue provisioning traffic.
00326  * If the commissioner is not present this function returns a failure.
00327  *
00328  * \param interface_id Network interface ID.
00329  * \param address_ptr A pointer to the location of address after copying.
00330  * \param port_ptr A pointer to the location of port after copying.
00331  *
00332  * \return 0, Read OK.
00333  * \return <0 Read fail.
00334  */
00335 int thread_management_get_commissioner_address(int8_t interface_id, uint8_t *address_ptr, uint16_t *port_ptr);
00336 
00337 
00338 #ifdef __cplusplus
00339 }
00340 #endif
00341 
00342 #endif /* THREAD_MANAGEMENT_IF_H_ */