thread_commissioning_api.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  * \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 extented_pan_id[8]; /**< Extended PAN ID. */
00193     uint16_t panId; /**< Network ID. */
00194     uint8_t Protocol_id; /**< Current protocol ID. */
00195     uint8_t version; /**< Current protocol version. */
00196     uint8_t rfChannel; /**< Current RF channel. */
00197 } thread_commissioning_link_configuration_s;
00198 
00199 /** \brief Native commissioner network scan result callback.
00200  *
00201  * This callback is called when networks that allow native commissioner to join are found.
00202  * Pointers are valid during this call.
00203  *
00204  * \param interface_id Interface ID of this Thread instance.
00205  * \param count Count of link configurations
00206  * \param link_ptr Poiner to Commissioning link configuration
00207  *
00208  */
00209 typedef void thread_commissioning_native_select_cb(int8_t interface_id, uint8_t count, thread_commissioning_link_configuration_s *link_ptr );
00210 
00211 /** \brief Native commissioner network scan start.
00212  *
00213  * Starts the network scan mode to find networks where the device can become a native commissioner.
00214  * This stops the normal Thread joining process and informs the application of available networks.
00215  *
00216  * \param interface_id Interface ID of this Thread instance.
00217  * \param cb_ptr Callback function
00218  *
00219  * \return 0 success, other values failure.
00220  */
00221 int thread_commissioning_native_commissioner_start(int8_t interface_id, thread_commissioning_native_select_cb *cb_ptr);
00222 
00223 /** \brief Native commissioner network scan stop.
00224  *
00225  * Stops the network scan mode and continues the normal joining process.
00226  *
00227  * \param interface_id Interface ID of this Thread instance.
00228  *
00229  * \return 0 success, other values failure.
00230  */
00231 int thread_commissioning_native_commissioner_stop(int8_t interface_id);
00232 
00233 /** \brief Native commissioner connect.
00234  *
00235  * Connects to a specific Thread network to become an active native commissioner.
00236  *
00237  * This function can be called in any time. When the network scan is completed, the available native commissioner networks are listed
00238  * using the callback.
00239  *
00240  * If the connection fails, network scan keeps looking for a new network. After a successful connection, the interface up event is sent.
00241  * TODO do we need backup timers or blacklist if PSKc fails. who is responsible for triggering new scans?
00242  *
00243  * Matching of thread network is made using Network name, Xpanid, panid, TODO channel?? or not? gives channel flexibility
00244  *
00245  * \param interface_id Interface ID of this Thread instance.
00246  * \param link_ptr Pointer to Commissioning link configuration.
00247  *
00248  * \return 0 success, other values failure.
00249  */
00250 int thread_commissioning_native_commissioner_connect(int8_t interface_id, thread_commissioning_link_configuration_s *link_ptr);
00251 
00252 /**
00253  *\brief Get the address of the native commissioner parent and the commissioning port for the connection.
00254  *
00255  * \param interface_id Network interface ID.
00256  * \param address_ptr A pointer to address buffer (16 bytes) for the commission messages.
00257  * \param port Return the port for the commissioner.
00258  *
00259  * \return 0, address OK.
00260  * \return <0 fail.
00261  */
00262 int thread_commissioning_native_commissioner_get_connection_info(int8_t interface_id, uint8_t *address_ptr, uint16_t *port);
00263 
00264 /**
00265  * \brief Get the management instance ID from the commissioner interface.
00266  *
00267  * \param interface_id Network interface ID.
00268  *
00269  * \return > 0 Instance ID.
00270  * \return <= 0 fail.
00271  */
00272 int8_t thread_commissioning_get_management_id(int8_t interface_id);
00273 
00274 #ifdef __cplusplus
00275 }
00276 #endif
00277 
00278 #endif /* THREAD_COMMISSIONING_API_H_ */