thread_management_if.h

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