1 /* 2 * Copyright (c) 2016, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file includes functions for the Thread Joiner role. 33 */ 34 35 #ifndef OPENTHREAD_JOINER_H_ 36 #define OPENTHREAD_JOINER_H_ 37 38 #include <openthread/platform/radio.h> 39 #include <openthread/platform/toolchain.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-joiner 47 * 48 * @brief 49 * This module includes functions for the Thread Joiner role. 50 * 51 * @note 52 * The functions in this module require `OPENTHREAD_CONFIG_JOINER_ENABLE=1`. 53 * 54 * @{ 55 * 56 */ 57 58 /** 59 * Defines the Joiner State. 60 * 61 */ 62 typedef enum otJoinerState 63 { 64 OT_JOINER_STATE_IDLE = 0, 65 OT_JOINER_STATE_DISCOVER = 1, 66 OT_JOINER_STATE_CONNECT = 2, 67 OT_JOINER_STATE_CONNECTED = 3, 68 OT_JOINER_STATE_ENTRUST = 4, 69 OT_JOINER_STATE_JOINED = 5, 70 } otJoinerState; 71 72 #define OT_JOINER_MAX_DISCERNER_LENGTH 64 ///< Maximum length of a Joiner Discerner in bits. 73 74 /** 75 * Represents a Joiner Discerner. 76 * 77 */ 78 typedef struct otJoinerDiscerner 79 { 80 uint64_t mValue; ///< Discerner value (the lowest `mLength` bits specify the discerner). 81 uint8_t mLength; ///< Length (number of bits) - must be non-zero and at most `OT_JOINER_MAX_DISCERNER_LENGTH`. 82 } otJoinerDiscerner; 83 84 /** 85 * Pointer is called to notify the completion of a join operation. 86 * 87 * @param[in] aError OT_ERROR_NONE if the join process succeeded. 88 * OT_ERROR_SECURITY if the join process failed due to security credentials. 89 * OT_ERROR_NOT_FOUND if no joinable network was discovered. 90 * OT_ERROR_RESPONSE_TIMEOUT if a response timed out. 91 * @param[in] aContext A pointer to application-specific context. 92 * 93 */ 94 typedef void (*otJoinerCallback)(otError aError, void *aContext); 95 96 /** 97 * Enables the Thread Joiner role. 98 * 99 * @param[in] aInstance A pointer to an OpenThread instance. 100 * @param[in] aPskd A pointer to the PSKd. 101 * @param[in] aProvisioningUrl A pointer to the Provisioning URL (may be NULL). 102 * @param[in] aVendorName A pointer to the Vendor Name (may be NULL). 103 * @param[in] aVendorModel A pointer to the Vendor Model (may be NULL). 104 * @param[in] aVendorSwVersion A pointer to the Vendor SW Version (may be NULL). 105 * @param[in] aVendorData A pointer to the Vendor Data (may be NULL). 106 * @param[in] aCallback A pointer to a function that is called when the join operation completes. 107 * @param[in] aContext A pointer to application-specific context. 108 * 109 * @retval OT_ERROR_NONE Successfully started the Joiner role. 110 * @retval OT_ERROR_BUSY The previous attempt is still on-going. 111 * @retval OT_ERROR_INVALID_ARGS @p aPskd or @p aProvisioningUrl is invalid. 112 * @retval OT_ERROR_INVALID_STATE The IPv6 stack is not enabled or Thread stack is fully enabled. 113 * 114 */ 115 otError otJoinerStart(otInstance *aInstance, 116 const char *aPskd, 117 const char *aProvisioningUrl, 118 const char *aVendorName, 119 const char *aVendorModel, 120 const char *aVendorSwVersion, 121 const char *aVendorData, 122 otJoinerCallback aCallback, 123 void *aContext); 124 125 /** 126 * Disables the Thread Joiner role. 127 * 128 * @param[in] aInstance A pointer to an OpenThread instance. 129 * 130 */ 131 void otJoinerStop(otInstance *aInstance); 132 133 /** 134 * Gets the Joiner State. 135 * 136 * @param[in] aInstance A pointer to an OpenThread instance. 137 * 138 * @retval OT_JOINER_STATE_IDLE 139 * @retval OT_JOINER_STATE_DISCOVER 140 * @retval OT_JOINER_STATE_CONNECT 141 * @retval OT_JOINER_STATE_CONNECTED 142 * @retval OT_JOINER_STATE_ENTRUST 143 * @retval OT_JOINER_STATE_JOINED 144 * 145 */ 146 otJoinerState otJoinerGetState(otInstance *aInstance); 147 148 /** 149 * Gets the Joiner ID. 150 * 151 * If a Joiner Discerner is not set, Joiner ID is the first 64 bits of the result of computing SHA-256 over 152 * factory-assigned IEEE EUI-64. Otherwise the Joiner ID is calculated from the Joiner Discerner value. 153 * 154 * The Joiner ID is also used as the device's IEEE 802.15.4 Extended Address during the commissioning process. 155 * 156 * @param[in] aInstance A pointer to the OpenThread instance. 157 * 158 * @returns A pointer to the Joiner ID. 159 * 160 */ 161 const otExtAddress *otJoinerGetId(otInstance *aInstance); 162 163 /** 164 * Sets the Joiner Discerner. 165 * 166 * The Joiner Discerner is used to calculate the Joiner ID during the Thread Commissioning process. For more 167 * information, refer to #otJoinerGetId. 168 * @note The Joiner Discerner takes the place of the Joiner EUI-64 during the joiner session of Thread Commissioning. 169 * 170 * @param[in] aInstance A pointer to the OpenThread instance. 171 * @param[in] aDiscerner A pointer to a Joiner Discerner. If NULL clears any previously set discerner. 172 * 173 * @retval OT_ERROR_NONE The Joiner Discerner updated successfully. 174 * @retval OT_ERROR_INVALID_ARGS @p aDiscerner is not valid (specified length is not within valid range). 175 * @retval OT_ERROR_INVALID_STATE There is an ongoing Joining process so Joiner Discerner could not be changed. 176 * 177 */ 178 otError otJoinerSetDiscerner(otInstance *aInstance, otJoinerDiscerner *aDiscerner); 179 180 /** 181 * Gets the Joiner Discerner. For more information, refer to #otJoinerSetDiscerner. 182 * 183 * @param[in] aInstance A pointer to the OpenThread instance. 184 * 185 * @returns A pointer to Joiner Discerner or NULL if none is set. 186 * 187 */ 188 const otJoinerDiscerner *otJoinerGetDiscerner(otInstance *aInstance); 189 190 /** 191 * Converts a given joiner state enumeration value to a human-readable string. 192 * 193 * @param[in] aState The joiner state. 194 * 195 * @returns A human-readable string representation of @p aState. 196 * 197 */ 198 const char *otJoinerStateToString(otJoinerState aState); 199 200 /** 201 * @} 202 * 203 */ 204 205 #ifdef __cplusplus 206 } // end of extern "C" 207 #endif 208 209 #endif // OPENTHREAD_JOINER_H_ 210
