thread_commissioning_api.h

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