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  * If static configuration is given and new one is updated by commissioner
00111  * it will override current setup. it is save to always give this as
00112  * default configuration.
00113  *
00114  * \param interface_id Network interface ID.
00115  * \param channel_list A pointer to channel list. Can be NULL if all channels accepted.
00116  * \param device_configuration A pointer to device configuration.
00117  * \param static_configuration A pointer to static configuration. Can be NULL.
00118  *
00119  * \return 0, Init OK.
00120  * \return <0 Init fail.
00121  */
00122 int thread_management_node_init(
00123     int8_t interface_id,
00124     channel_list_s *channel_list,
00125     device_configuration_s *device_configuration,
00126     link_configuration_s *static_configuration);
00127 
00128 /**
00129  * Thread device type.
00130  *
00131  * REED - Router enabled End device. Device can become router or end device depending on network conditions.
00132  * FED - Full End Device. Device creates links and makes address queries but does not become router.
00133  * MED - Minimal End Device. Device communicates through parent. With radio on
00134  * SED - Sleepy End Device. Device communicates through parent. Uses data poll to sleep.
00135 */
00136 typedef enum {
00137     THREAD_DEVICE_REED = 1,
00138     THREAD_DEVICE_FED,
00139     THREAD_DEVICE_MED,
00140     THREAD_DEVICE_SED,
00141 } thread_device_type_e;
00142 
00143 /**
00144  * Change thread device type.
00145  *
00146  * This function modifies the thread device mode. Default values are given in
00147  * function arm_nwk_interface_configure_6lowpan_bootstrap_set().
00148  *
00149  * If this function is called when interface is up re-attach is made.
00150  *
00151  * \param interface_id Network interface ID.
00152  * \param device_type Device type of current bootstrap.
00153  *
00154  * \return 0, Set OK.
00155  * \return <0 Set fail.
00156  */
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 link 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  * Get Thread device link timeout.
00231  *
00232  * \param interface_id Network interface ID.
00233  * \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  * Set link timeout for Thread device.
00242  *
00243  * \param interface_id Network interface ID.
00244  * \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  * \link_timeout[out] A pointer to the location for writing the flag value.
00267  *
00268  * \return 0, Get OK.
00269  * \return <0 Get Fail.
00270  */
00271 int8_t thread_management_get_request_full_nwk_data(int8_t interface_id, bool *full_nwk_data);
00272 
00273 /**
00274  * Additional Thread device settings. Changing these can cause non-compliance with Thread.
00275  *
00276  */
00277 
00278 /**
00279  * Diagnostics functions.
00280  */
00281 
00282 /**
00283  * Get leader mesh local 16 address.
00284  *
00285  * \param interface_id Network interface ID.
00286  * \param address_ptr A pointer to the location of address after copying.
00287  *
00288  * \return 0, Read OK.
00289  * \return <0 Read fail.
00290  */
00291 int thread_management_get_leader_address(int8_t interface_id, uint8_t *address_ptr);
00292 
00293 /**
00294  * Get leader anycast address.
00295  *
00296  * Address should be used when contacting Leader without need to know the actual routing details.
00297  * This address will remain valid even after leader changes.
00298  *
00299  * \param interface_id Network interface ID.
00300  * \param address_ptr A pointer to the location of address after copying.
00301  *
00302  * \return 0, Read OK.
00303  * \return <0 Read fail. Not connected to Thread network.
00304  */
00305 int thread_management_get_leader_aloc(int8_t interface_id, uint8_t *address_ptr);
00306 
00307 /**
00308  * Get parent link local 16 address.
00309  *
00310  * \param interface_id Network interface ID.
00311  * \param address_ptr A pointer to the location of address after copying.
00312  *
00313  * \return 0, Read OK.
00314  * \return <0 Read fail.
00315  */
00316 int thread_management_get_parent_address(int8_t interface_id, uint8_t *address_ptr);
00317 
00318 /**
00319  * Get own mesh local 64 address.
00320  *
00321  * \param interface_id Network interface ID.
00322  * \param address_ptr A pointer to the location of address after copying.
00323  *
00324  * \return 0, Read OK.
00325  * \return <0 Read fail.
00326  */
00327 int thread_management_get_ml64_address(int8_t interface_id, uint8_t *address_ptr);
00328 
00329 /**
00330  * Get own mesh local 16 address.
00331  *
00332  * \param interface_id Network interface ID.
00333  * \param address_ptr A pointer to the location of address after copying.
00334  *
00335  * \return 0, Read OK.
00336  * \return <0 Read fail.
00337  */
00338 int thread_management_get_ml16_address(int8_t interface_id, uint8_t *address_ptr);
00339 
00340 /**
00341  * Get commissioner address.
00342  *
00343  * This function returns the commissioner address where you can continue provisioning traffic.
00344  * If the commissioner is not present this function returns a failure.
00345  *
00346  * \param interface_id Network interface ID.
00347  * \param address_ptr A pointer to the location of address after copying.
00348  * \param port_ptr A pointer to the location of port after copying.
00349  *
00350  * \return 0, Read OK.
00351  * \return <0 Read fail.
00352  */
00353 int thread_management_get_commissioner_address(int8_t interface_id, uint8_t *address_ptr, uint16_t *port_ptr);
00354 
00355 
00356 #ifdef __cplusplus
00357 }
00358 #endif
00359 
00360 #endif /* THREAD_MANAGEMENT_IF_H_ */