thread_joiner_application.h

00001 /*
00002  * Copyright (c) 2015-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  * Joiner application starts the commisioning and saves the Static configuration of thread network
00032  * to nvm to recover from restart.
00033  */
00034 
00035 
00036 #ifndef THREAD_JOINER_APPLICATION_H_
00037 #define THREAD_JOINER_APPLICATION_H_
00038 #include <ns_types.h>
00039 
00040 struct link_configuration;
00041 
00042 #define TRACE_GROUP_THREAD_JOINER_APPLICATION "TjoA"
00043 
00044 /** Initialise thread Joiner application.
00045  *
00046  * This instance needs to bee initialised once for each thread network interface.
00047  * if only one thread instance is supported this is needed to call only once.
00048  *
00049  * /param interface interface id of this thread instance.
00050  * /param device_configuration_ptr Device configuration settings for application provisioning.
00051  * /param default_configuration_ptr Default configuration used if not other configuration available.
00052  *
00053  */
00054 int thread_joiner_application_init(int8_t interface_id, device_configuration_s *device_configuration_ptr, struct link_configuration *default_configuration_ptr);
00055 
00056 /** Delete Joiner application.
00057  *
00058  * /param interface interface id of this thread instance.
00059  */
00060 void thread_joiner_application_deinit(int8_t interface_id);
00061 
00062 /** Get configuration
00063  *
00064  * /param interface interface id of this thread instance.
00065  *
00066  */
00067 struct link_configuration *thread_joiner_application_get_config(int8_t interface_id);
00068 
00069 uint64_t thread_joiner_application_active_timestamp_get(int8_t interface_id);
00070 uint8_t thread_joiner_application_security_policy_get(int8_t interface_id);
00071 void thread_joiner_application_active_timestamp_set(int8_t interface_id, uint64_t timestamp);
00072 uint8_t *thread_joiner_application_network_name_get(int8_t interface_id);
00073 uint8_t *thread_joiner_application_active_config_tlv_list_get(uint8_t interface_id, uint16_t *length);
00074 
00075 uint8_t *thread_joiner_application_active_config_params_get(uint8_t interface_id, uint16_t *length);
00076 
00077 /** Get device configuration
00078  *
00079  * /param interface interface id of this thread instance.
00080  *
00081  */
00082 device_configuration_s *thread_joiner_application_get_device_config(int8_t interface_id);
00083 
00084 /** Store link configuration settings to platform specific NVM.
00085  *
00086  * Note1. All platforms may not have support for NVM.
00087  * Note2. Store is asynchronous operation, this method makes a storing request that
00088  *        will be completed in background.
00089  *
00090  * /param interface interface id of this thread instance. -1 if instance not initialized.
00091  * /param link_config Pointer to structure containing link configuration parameters
00092  *
00093  *\ return 0 if store request has been delivered to lower layers.
00094  *\ return -1 if store failed (store request not made)
00095  */
00096 
00097 uint8_t *thread_joiner_application_random_mac_get(int8_t interface_id);
00098 
00099 uint8_t *thread_joiner_application_ml_eid_get(int8_t interface_id);
00100 
00101 int thread_joiner_application_link_configuration_store(int8_t interface_id, link_configuration_s *link_config);
00102 
00103 /** Delete link configuration from platform NVM
00104  *
00105  * Note1. All platforms may not have support for NVM.
00106  * Note2. Delete is asynchronous operation, this method makes a delete request that
00107  *        will be completed on the background
00108  *
00109  * /param interface interface id of this thread instance. -1 if instance not initialized.
00110  *
00111  *\ return 0 if delete request has been delivered to lower layers.
00112  *\ return -1 if delete failed (delete request not made)
00113  */
00114 int thread_joiner_application_link_configuration_delete(int8_t interface_id);
00115 
00116 /** Check if link configuration settings should be loaded from NVM and make a read
00117  * request if settings needs to be loaded.
00118  *
00119  * /param interface interface id of this thread instance.
00120  *
00121  * /return true if read request is made, false otherwise
00122  */
00123 bool thread_joiner_application_nvm_link_configuration_load(int8_t interface_id);
00124 
00125 
00126 /** Provisioning status of the device.
00127  *
00128  */
00129 typedef enum {
00130     PROVISIONING_STATUS_NOT_DONE,
00131     PROVISIONING_STATUS_ONGOING,
00132     PROVISIONING_STATUS_REJECTED,
00133     PROVISIONING_STATUS_DONE,
00134 } thread_provisioning_status_e;
00135 
00136 /** Set the provisioning status of the device.
00137  *
00138  * not done -> When commissioner attaches to network JOIN_APP.req is sent to commissioner
00139  * ongoing -> Waiting response to JOIN_APP.req message.
00140  * rejected -> Provisioning was attempted, but did not succeed. State will go back to not done after random period
00141  * done -> JOIN_APP.resp was received with accepted status.
00142  *
00143  * /param interface interface id of this thread instance.
00144  * /param status Current status of provisioning
00145  *
00146  */
00147 int thread_joiner_application_provisioning_set(int8_t interface_id, thread_provisioning_status_e status);
00148 /** get the provisioning status of the device.
00149  *
00150  * /param interface interface id of this thread instance.
00151  *
00152  * /return true if application provisioning is done.
00153  */
00154 thread_provisioning_status_e thread_joiner_application_provisioning_get(int8_t interface_id);
00155 
00156 /** form thread network with randomized values.
00157  *
00158  * /param interface interface id of this thread instance.
00159  * /param commissioning_credentials_ptr commissioning credentials used to form the network
00160  * /param name_ptr ascii string for name of the network can be NULL
00161  *
00162  */
00163 int thread_joiner_application_form_network(int8_t interface_id, uint8_t *commissioning_credentials_ptr, char *name_ptr);
00164 
00165 /** Commissioning done callback.
00166  *
00167  * This callback is called when commissioning is made and new attach can be made with new static configuration.
00168  *
00169  * /param interface interface id of this thread instance.
00170  *
00171  */
00172 typedef void thread_joiner_application_commission_done_cb(int8_t interface_id);
00173 
00174 /** Commissioning start.
00175  *
00176  * Start commissioning process to this network
00177  *
00178  * /param interface interface id of this thread instance.
00179  *
00180  */
00181 int thread_joiner_application_pskd_commission_start(int8_t interface_id, uint8_t parent_address[16], uint16_t joiner_port, uint16_t panid, uint8_t xpanid[8], uint8_t channel, thread_joiner_application_commission_done_cb *done_cb);
00182 
00183 /** One second ticker for delayed configurations.
00184  *
00185  * /param interface interface id of this thread instance.
00186  *
00187  */
00188 void thread_joiner_application_seconds_timer(int8_t interface_id, uint32_t seconds);
00189 
00190 /** Create new pending configuration.
00191  *
00192  * Cleans the previous pending configuration if it is present.
00193  *
00194  * /param interface interface id of this thread instance.
00195  * /param data_ptr Pointer to data that is included in the new pending set
00196  * /param data_len length of operational dataset that is used to generate the pending set
00197  *
00198  */
00199 int thread_joiner_application_pending_config_create(int8_t interface_id, uint8_t *data_ptr, uint16_t data_len);
00200 
00201 /** Checks if pending configuration is present.
00202  *
00203  * /param interface interface id of this thread instance.
00204  *
00205  */
00206 bool thread_joiner_application_pending_config_exists(int8_t interface_id);
00207 /** get timestamp value of pending configuration.
00208  *
00209  * /param interface interface id of this thread instance.
00210  *
00211  */
00212 uint64_t thread_joiner_application_pending_config_timestamp_get(int8_t interface_id);
00213 
00214 /** Set pending timestamp value
00215  *
00216  * /param interface interface id of this thread instance.
00217  * /param timestamp timestamp value.
00218  *
00219  */
00220 int thread_joiner_application_pending_config_timestamp_set(int8_t interface_id, uint64_t timestamp);
00221 
00222 /** get pending timeout value.
00223  *
00224  * /param interface interface id of this thread instance.
00225  *
00226  * /return timeout in ms.
00227  *
00228  */
00229 uint32_t thread_joiner_application_pending_config_timeout_get(int8_t interface_id);
00230 
00231 /** Enable pending configuration.
00232  *
00233  * Pending configuration is taken in use after timeout.
00234  *
00235  * /param interface interface id of this thread instance.
00236  * /param timeout_in_ms Timeout value after which pending set is activated.
00237  *
00238  */
00239 int thread_joiner_application_pending_config_enable(int8_t interface_id, uint32_t timeout_in_ms);
00240 
00241 
00242 /** delete pending configuration.
00243  *
00244  * Cleans the previous pending configuration if it is present.
00245  *
00246  * /param interface interface id of this thread instance.
00247  *
00248  */
00249 void thread_joiner_application_pending_config_delete(int8_t interface_id);
00250 uint8_t *thread_joiner_application_pending_config_tlv_list_get(uint8_t interface_id, uint16_t *length);
00251 uint16_t thread_joiner_application_pending_config_length(uint8_t interface_id, uint8_t *req_tlv_ptr, uint8_t req_tlv_len, const uint8_t *ignored_tlv_ptr, uint8_t ignored_tlv_len);
00252 uint8_t *thread_joiner_application_pending_config_build(uint8_t interface_id, uint8_t *ptr, uint8_t *req_tlv_ptr, uint8_t req_tlv_len, const uint8_t *ignored_tlv_ptr, uint8_t ignored_tlv_len);
00253 void thread_joiner_application_pending_config_add_missing_fields(uint8_t interface_id);
00254 
00255 /**
00256  *  TODO still expirimental for Thread 1.1
00257  */
00258 void thread_joiner_application_next_pending_config_save(int8_t interface_id);
00259 bool thread_joiner_application_next_pending_config_exists(int8_t interface_id);
00260 uint16_t thread_joiner_application_next_pending_config_length(int8_t interface_id);
00261 uint8_t *thread_joiner_application_next_pending_config_build(int8_t interface_id, uint8_t *ptr);
00262 void thread_joiner_application_next_pending_config_delete(int8_t interface_id);
00263 bool thread_joiner_application_pending_delay_timer_in_sync(int8_t interface_id);
00264 
00265 
00266 void thread_joiner_application_next_active_config_save(int8_t interface_id);
00267 bool thread_joiner_application_next_active_config_exists(int8_t interface_id);
00268 uint16_t thread_joiner_application_next_active_config_length(int8_t interface_id);
00269 uint8_t *thread_joiner_application_next_active_config_write(int8_t interface_id, uint8_t *ptr);
00270 void thread_joiner_application_next_active_config_delete(int8_t interface_id);
00271 
00272 /**Activate old configuration.
00273  *
00274  * If we have old configuration that we can try to restore connectivity to old configuration is is started
00275  *
00276  * /param interface interface id of this thread instance.
00277  *
00278  */
00279 int thread_joiner_application_old_config_activate(int8_t interface_id);
00280 
00281 /**Delete old configuration.
00282  *
00283  * /param interface interface id of this thread instance.
00284  *
00285  */
00286 void thread_joiner_application_old_config_delete(int8_t interface_id);
00287 
00288 /**Create old configuration.
00289  *
00290  * If we have have an active configuration that we have to come back to then the active configuration can be saved
00291  * temporarily to old configuration
00292  *
00293  * /param interface interface id of this thread instance.
00294  *
00295  */
00296 link_configuration_s *thread_joiner_application_old_config_create(int8_t interface_id);
00297 
00298 /**Get old configuration.
00299  *
00300  * If we have have a saved old configuration then it can be retrieved
00301  *
00302  * /param interface interface id of this thread instance.
00303  *
00304  */
00305 bool thread_joiner_application_old_config_exists(int8_t interface_id);
00306 
00307 /** Saves the current configurations to NVM.
00308  *
00309  * /param interface interface id of this thread instance.
00310  *
00311  * /return 0 OK.
00312  * /return <0 Failure.
00313  *
00314  */
00315 int thread_joiner_application_configuration_nvm_save(int8_t interface_id);
00316 
00317 /** Update configuration from meshcop tlv message.
00318  *
00319  * /param interface interface id of this thread instance.
00320  * /param msg_ptr meshcop TLV message structure.
00321  * /param msg_len Length of message.
00322  *
00323  * /return 0 OK.
00324  * /return <0 Failure.
00325  *
00326  */
00327 int thread_joiner_application_update_configuration(uint8_t interface_id, uint8_t *msg_ptr, uint16_t msg_len, bool include_missing_tlvs);
00328 
00329 /** Calculate length of active/pending configuration dataset TLVs.
00330  *
00331  * /param link_configuration Link configuration used to build the message.
00332  * /param msg_ptr meshcop TLV message structure.
00333  * /param msg_len Length of message.
00334   *
00335  * /return length of the message.
00336  * /return <0 Failure.
00337  */
00338 uint16_t thread_joiner_application_active_config_length(uint8_t interface_id, const uint8_t *req_tlv_ptr, uint8_t req_tlv_len, const uint8_t *ignored_tlv_ptr, uint8_t ignored_tlv_len);
00339 
00340 /** build active/pending configuration dataset TLVs.
00341  *
00342  * /param link_configuration Link configuration used to build the message.
00343  * /param response_ptr meshcop TLV message structure.
00344  * /param tlv_list List of TLVs requested NULL if all wanted.
00345  * /param list_len length of tlv list.
00346   *
00347  * /return length of the message.
00348  * /return <0 Failure.
00349  */
00350 
00351 uint8_t *thread_joiner_application_active_config_write(uint8_t interface_id, uint8_t *ptr, const uint8_t *req_tlv_ptr, uint8_t req_tlv_len, const uint8_t *ignored_tlv_ptr, uint8_t ignored_tlv_len);
00352 
00353 /** Calculate length of device configuration TLVs.
00354  *
00355  * /param device_configuration device configuration used to build the message.
00356  *
00357  * /return length of the message.
00358  * /return <0 Failure.
00359  */
00360 int thread_joiner_application_device_configuration_length(device_configuration_s *device_configuration);
00361 
00362 /** write device configuration TLVs.
00363  *
00364  * /param ptr pointer where to write message.
00365  * /param device_configuration device configuration used to build the message.
00366  *
00367  * /return length of the message.
00368  * /return <0 Failure.
00369  */
00370 uint8_t *thread_joiner_application_device_configuration_build(uint8_t *ptr, device_configuration_s *device_configuration);
00371 
00372 /** function to activate pending configuration if present
00373  */
00374 void thread_joiner_pending_config_activate(int8_t interface_id);
00375 
00376 /* MLE active configuration data set fields
00377  *
00378  */
00379 extern const uint8_t mle_active_configuration_dataset_tlvs[];
00380 
00381 extern const uint8_t mle_pending_configuration_dataset_ignore_tlvs[];
00382 
00383 extern const uint8_t mle_active_configuration_dataset_ignore_tlvs[];
00384 
00385 uint8_t mle_active_configuration_dataset_tlvs_size(void);
00386 
00387 uint8_t mle_active_configuration_dataset_ignore_tlvs_size(void);
00388 
00389 uint8_t mle_pending_configuration_dataset_ignore_tlvs_size(void);
00390 
00391 extern const uint8_t mle_pending_configuration_dataset_tlvs[];
00392 
00393 uint8_t mle_pending_configuration_dataset_tlvs_size(void);
00394 
00395 extern const uint8_t pending_configuration_dataset_tlvs[];
00396 
00397 uint8_t pending_configuration_dataset_tlvs_size(void);
00398 
00399 extern const uint8_t active_configuration_dataset_tlvs[];
00400 
00401 uint8_t active_configuration_dataset_tlvs_size(void);
00402 
00403 extern const uint8_t entrust_dataset_tlvs[];
00404 
00405 uint8_t entrust_dataset_tlvs_size(void);
00406 
00407 int joiner_application_security_done_cb(int8_t service_id, uint8_t address[16], uint8_t keyblock[40]);
00408 
00409 int8_t thread_joiner_application_active_configuration_update(int8_t service_id, uint8_t *data_ptr, uint16_t data_len, const uint8_t *ignore_ptr, uint8_t ingore_len);
00410 
00411 #endif /* THREAD_JOINER_APPLICATION_H_ */