thread_commissioning_api.h

00001 /*
00002  * Copyright (c) 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_commissioning_api.h
00017  * \brief Thread commissioning API.
00018  *
00019  * This is a public API used for creating a commissioning device. You can create an on-mesh commissioner
00020  * and a native commissioner.
00021  */
00022 
00023 #ifndef THREAD_COMMISSIONING_API_H_
00024 #define THREAD_COMMISSIONING_API_H_
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 #include "ns_types.h"
00031 
00032 #define TRACE_GROUP_THREAD_COMMISSIONING_API "TCoA"
00033 
00034 typedef enum {
00035     COMMISSIONING_STATE_ACCEPT,
00036     COMMISSIONING_STATE_PENDING,
00037     COMMISSIONING_STATE_REJECT,
00038     COMMISSIONING_STATE_NO_NETWORK
00039 } commissioning_state_e;
00040 
00041 /** \brief Commissioning petition response callback.
00042  *
00043  * \param interface_id Network interface ID. The request comes from this ID.
00044  * \param state State of the commissioning.
00045  *
00046  * \return 0 success, other values failure.
00047  */
00048 typedef int (thread_commissioning_status_cb)(int8_t interface_id, uint16_t commissioner_session_id, commissioning_state_e state);
00049 
00050 
00051 /** \brief Register the commissioner interface.
00052  *
00053  * If the network interface is up, the commissioner functionality is started within the Thread network.
00054  * If there is no interface, the network needs to be scanned first. When the network is found you can add an insecure commissioner,
00055  * attach to it and start using a different communication method with the border router.
00056  *
00057  * \param interface_id Interface ID where the request was made.
00058  * \param PSKc Pre-shared key between the commissioner and the Thread network.
00059  * \param PSKc_len The length of the PSKc.
00060  *
00061  * \return 0 success, other values failure.
00062  */
00063 int thread_commissioning_register(int8_t interface_id, uint8_t PSKc[16]);
00064 
00065 /** \brief Unregister the commissioner interface.
00066  *
00067  * This cleans up all the commissioner data from the device and disconnects it from the Thread network if an insecure commissioner was used.
00068  *
00069  * \param interface_id Network interface ID. The request comes from this ID.
00070  *
00071  * \return 0 success, other values failure.
00072  */
00073 int thread_commissioning_unregister(int8_t interface_id);
00074 
00075 /** \brief Start the commissioning petition.
00076  *
00077  * If the commissioner is insecure, you need to scan the networks and select the Thread network where you want to be a commissioner.
00078  *
00079  * \param interface_id Network interface ID. The request comes from this ID.
00080  * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
00081  * \return 0 Indicates success.
00082  *
00083  * \return -1 The client needs to scan the network to become an insecure commissioner.
00084  * \return Any other value indicates other failures.
00085  */
00086 int thread_commissioning_petition_start(int8_t interface_id, char *commissioner_id_ptr, thread_commissioning_status_cb *status_cb_ptr);
00087 
00088 /** \brief Send petition keep alive.
00089  *
00090  * This function must be called in 40 second intervals. TODO rethink if this should be automatic
00091  *
00092  * \param interface_id Network interface ID. The request comes from this ID.
00093  * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
00094  *
00095  * \return 0 success, other values failure.
00096  */
00097 int thread_commissioning_petition_keep_alive(int8_t interface_id, commissioning_state_e state);
00098 
00099 /** \brief Callback received when a new device is completing the joining process.
00100  *
00101  * The message may include the following meshcop TLV fields:
00102  * * State TLV
00103  * * Vendor Name TLV
00104  * * Vendor Model TLV
00105  * * Vendor SW Version TLV
00106  * * Vendor Data TLV
00107  * * Vendor Stack
00108  * * Version TLV
00109  * * Provisioning URL TLV
00110  *
00111  * \param interface_id Network interface ID. The request comes from this ID.
00112  * \param EUI64 The client identifier.
00113  * \param message_ptr A message including the meshcop TLV set. This message can be parsed using thread_meshcop_lib.h.
00114  * \param message_len The length of the message.
00115  *
00116  * \return 0 Device accepted.
00117  * \return Any other value, device rejected.
00118  */
00119 typedef int (thread_commissioning_joiner_finalisation_cb)(int8_t interface_id, uint8_t EUI64[8], uint8_t *message_ptr, uint16_t message_len);
00120 
00121 /** \brief Add a device to commission to the Thread network.
00122  *
00123  *
00124  * \param interface_id Network interface ID. The request comes from this ID.
00125  * \param short_eui64 A boolean value indicating that short EUI version is used for bloom filter generation.
00126  * \param EUI64 A pointer to EUI64 buffer.
00127  * \param PSKd_ptr A pointer to PSKd buffer.
00128  * \param PSKd_len PSKd string length, current validity check is 1-32 bytes.
00129  * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
00130  *
00131  * \return 0 success, other values failure
00132  */
00133 int thread_commissioning_device_add(int8_t interface_id, bool short_eui64, uint8_t EUI64[8], uint8_t *PSKd_ptr, uint8_t PSKd_len, thread_commissioning_joiner_finalisation_cb *joining_device_cb_ptr);
00134 
00135 /** \brief Delete a device to commission to the Thread network.
00136  *
00137  *
00138  * \param interface_id Network interface ID. The request comes from this ID.
00139  * \param EUI64 A pointer to EUI64 buffer.
00140  *
00141  * \return 0 success, other values failure.
00142  */
00143 int thread_commissioning_device_delete(int8_t interface_id, uint8_t EUI64[8]);
00144 
00145 /** \brief Get next added device details.
00146  *
00147  * \param ptr A pointer for internal looping. First, use NULL pointer, after that use return pointer.
00148  * \param interface_id Network interface ID. The request comes from this ID.
00149  * \param short_eui64 A boolean value indicating that short EUI version is used for bloom filter generation. Can be NULL when no result wanted.
00150  * \param EUI64 A pointer to EUI64 buffer. Can be NULL when no result wanted.
00151  * \param PSKd_ptr A pointer to PSKd buffer. Can be NULL when no result wanted.
00152  *
00153  * \return >NULL for next iteration.
00154  * \return NULL when end of list.
00155  */
00156 void *thread_commission_device_get_next(void *ptr, int8_t interface_id, bool *short_eui64, uint8_t EUI64[8], uint8_t PSKd[32], uint8_t *PSKd_len);
00157 
00158 /** Interfaces needed for native commissioner.
00159  * current design:
00160  *  - The application configures the interface to scan available Thread networks to join
00161  *      - Time passes and the user wants to start scanning for native commissioner networks.
00162  *  - The application configures the interface to begin native commissioner interface scans.
00163  *  - The application selects a network to connect to.
00164  *  - The stack connects to that network -> interface UP event sent.
00165  *  - The application starts using Commissioning API to send COMM_PET.req message triggering a DTLS handshake.
00166  *      - Commission API queries the leader address and native info and uses the one that works.
00167  *
00168  *
00169  */
00170 
00171 typedef struct thread_commissioning_link_configuration {
00172     uint8_t name[16]; /**< Name of the Thread network. utf8 string nul terminated if shorter than 16. */
00173     uint8_t extented_pan_id[8]; /**< Extended PAN ID. */
00174     uint16_t panId; /**< Network ID. */
00175     uint8_t Protocol_id; /**< Current protocol ID. */
00176     uint8_t version; /**< Current protocol version. */
00177     uint8_t rfChannel; /**< Current RF channel. */
00178 } thread_commissioning_link_configuration_s;
00179 
00180 /** \brief Native commissioner network scan result callback.
00181  *
00182  * This callback is called when networks that allow native commissioner to join are found.
00183  * Pointers are valid during this call.
00184  *
00185  * \param interface Interface ID of this Thread instance.
00186  *
00187  */
00188 typedef void thread_commissioning_native_select_cb(int8_t interface_id, uint8_t count, thread_commissioning_link_configuration_s *link_ptr );
00189 
00190 /** \brief Native commissioner network scan start.
00191  *
00192  * Starts the network scan mode to find networks where the device can become a native commissioner.
00193  * This stops the normal Thread joining process and informs the application of available networks.
00194  *
00195  * \param interface Interface ID of this Thread instance.
00196  *
00197  * \return 0 success, other values failure.
00198  */
00199 int thread_commissioning_native_commissioner_start(int8_t interface_id, thread_commissioning_native_select_cb *cb_ptr);
00200 
00201 /** \brief Native commissioner network scan stop.
00202  *
00203  * Stops the network scan mode and continues the normal joining process.
00204  *
00205  * \param interface Interface ID of this Thread instance.
00206  *
00207  * \return 0 success, other values failure.
00208  */
00209 int thread_commissioning_native_commissioner_stop(int8_t interface_id);
00210 
00211 /** \brief Native commissioner connect.
00212  *
00213  * Connects to a specific Thread network to become an active native commissioner.
00214  *
00215  * This function can be called in any time. When the network scan is completed, the available native commissioner networks are listed
00216  * using the callback.
00217  *
00218  * If the connection fails, network scan keeps looking for a new network. After a successful connection, the interface up event is sent.
00219  * TODO do we need backup timers or blacklist if PSKc fails. who is responsible for triggering new scans?
00220  *
00221  * Matching of thread network is made using Network name, Xpanid, panid, TODO channel?? or not? gives channel flexibility
00222  *
00223  * \param interface Interface ID of this Thread instance.
00224  *
00225  * \return 0 success, other values failure.
00226  */
00227 int thread_commissioning_native_commissioner_connect(int8_t interface_id, thread_commissioning_link_configuration_s *link_ptr);
00228 
00229 /**
00230  *\brief Get the address of the native commissioner parent and the commissioning port for the connection.
00231  *
00232  * \param interface_id Network interface ID.
00233  * \param address_ptr A pointer to address buffer (16 bytes) for the commission messages.
00234  * \param port Return the port for the commissioner.
00235  * \param PSKc_ptr A pointer to return buffer for the PSKc (16 bytes) of this network instance.
00236  *
00237  * \return 0, address OK.
00238  * \return <0 fail.
00239  */
00240 int thread_commissioning_native_commissioner_get_connection_info(int8_t interface_id, uint8_t *address_ptr, uint16_t *port);
00241 
00242 /**
00243  * \brief Get the management instance ID from the commissioner interface.
00244  *
00245  * \param interface_id Network interface ID.
00246  *
00247  * \return > 0 Instance ID.
00248  * \return <= 0 fail.
00249  */
00250 int8_t thread_commissioning_get_management_id(int8_t interface_id);
00251 
00252 #ifdef __cplusplus
00253 }
00254 #endif
00255 
00256 #endif /* THREAD_COMMISSIONING_API_H_ */