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 Commissioner role. 33 */ 34 35 #ifndef OPENTHREAD_COMMISSIONER_H_ 36 #define OPENTHREAD_COMMISSIONER_H_ 37 38 #include <openthread/dataset.h> 39 #include <openthread/ip6.h> 40 #include <openthread/joiner.h> 41 #include <openthread/platform/radio.h> 42 #include <openthread/platform/toolchain.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @addtogroup api-commissioner 50 * 51 * @brief 52 * This module includes functions for the Thread Commissioner role. 53 * 54 * @{ 55 * 56 */ 57 58 /** 59 * This enumeration defines the Commissioner State. 60 * 61 */ 62 typedef enum otCommissionerState 63 { 64 OT_COMMISSIONER_STATE_DISABLED = 0, ///< Commissioner role is disabled. 65 OT_COMMISSIONER_STATE_PETITION = 1, ///< Currently petitioning to become a Commissioner. 66 OT_COMMISSIONER_STATE_ACTIVE = 2, ///< Commissioner role is active. 67 } otCommissionerState; 68 69 /** 70 * This enumeration defines a Joiner Event on the Commissioner. 71 * 72 */ 73 typedef enum otCommissionerJoinerEvent 74 { 75 OT_COMMISSIONER_JOINER_START = 0, 76 OT_COMMISSIONER_JOINER_CONNECTED = 1, 77 OT_COMMISSIONER_JOINER_FINALIZE = 2, 78 OT_COMMISSIONER_JOINER_END = 3, 79 OT_COMMISSIONER_JOINER_REMOVED = 4, 80 } otCommissionerJoinerEvent; 81 82 #define OT_COMMISSIONING_PASSPHRASE_MIN_SIZE 6 ///< Minimum size of the Commissioning Passphrase 83 #define OT_COMMISSIONING_PASSPHRASE_MAX_SIZE 255 ///< Maximum size of the Commissioning Passphrase 84 85 #define OT_PROVISIONING_URL_MAX_SIZE 64 ///< Max size (number of chars) in Provisioning URL string (excludes null char). 86 87 #define OT_STEERING_DATA_MAX_LENGTH 16 ///< Max steering data length (bytes) 88 89 /** 90 * This structure represents the steering data. 91 * 92 */ 93 typedef struct otSteeringData 94 { 95 uint8_t mLength; ///< Length of steering data (bytes) 96 uint8_t m8[OT_STEERING_DATA_MAX_LENGTH]; ///< Byte values 97 } otSteeringData; 98 99 /** 100 * This structure represents a Commissioning Dataset. 101 * 102 */ 103 typedef struct otCommissioningDataset 104 { 105 uint16_t mLocator; ///< Border Router RLOC16 106 uint16_t mSessionId; ///< Commissioner Session Id 107 otSteeringData mSteeringData; ///< Steering Data 108 uint16_t mJoinerUdpPort; ///< Joiner UDP Port 109 110 bool mIsLocatorSet : 1; ///< TRUE if Border Router RLOC16 is set, FALSE otherwise. 111 bool mIsSessionIdSet : 1; ///< TRUE if Commissioner Session Id is set, FALSE otherwise. 112 bool mIsSteeringDataSet : 1; ///< TRUE if Steering Data is set, FALSE otherwise. 113 bool mIsJoinerUdpPortSet : 1; ///< TRUE if Joiner UDP Port is set, FALSE otherwise. 114 } otCommissioningDataset; 115 116 #define OT_JOINER_MAX_PSKD_LENGTH 32 ///< Maximum string length of a Joiner PSKd (does not include null char). 117 118 /** 119 * This structure represents a Joiner PSKd. 120 * 121 */ 122 typedef struct otJoinerPskd 123 { 124 char m8[OT_JOINER_MAX_PSKD_LENGTH + 1]; ///< Char string array (must be null terminated - +1 is for null char). 125 } otJoinerPskd; 126 127 /** 128 * This enumeration defines a Joiner Info Type. 129 * 130 */ 131 typedef enum otJoinerInfoType 132 { 133 OT_JOINER_INFO_TYPE_ANY = 0, ///< Accept any Joiner (no EUI64 or Discerner is specified). 134 OT_JOINER_INFO_TYPE_EUI64 = 1, ///< Joiner EUI-64 is specified (`mSharedId.mEui64` in `otJoinerInfo`). 135 OT_JOINER_INFO_TYPE_DISCERNER = 2, ///< Joiner Discerner is specified (`mSharedId.mDiscerner` in `otJoinerInfo`). 136 } otJoinerInfoType; 137 138 /** 139 * This structure represents a Joiner Info. 140 * 141 */ 142 typedef struct otJoinerInfo 143 { 144 otJoinerInfoType mType; ///< Joiner type. 145 union 146 { 147 otExtAddress mEui64; ///< Joiner EUI64 (when `mType` is `OT_JOINER_INFO_TYPE_EUI64`) 148 otJoinerDiscerner mDiscerner; ///< Joiner Discerner (when `mType` is `OT_JOINER_INFO_TYPE_DISCERNER`) 149 } mSharedId; ///< Shared fields 150 otJoinerPskd mPskd; ///< Joiner PSKd 151 uint32_t mExpirationTime; ///< Joiner expiration time in msec 152 } otJoinerInfo; 153 154 /** 155 * This function pointer is called whenever the commissioner state changes. 156 * 157 * @param[in] aState The Commissioner state. 158 * @param[in] aContext A pointer to application-specific context. 159 * 160 */ 161 typedef void (*otCommissionerStateCallback)(otCommissionerState aState, void *aContext); 162 163 /** 164 * This function pointer is called whenever the joiner state changes. 165 * 166 * @param[in] aEvent The joiner event type. 167 * @param[in] aJoinerInfo A pointer to the Joiner Info. 168 * @param[in] aJoinerId A pointer to the Joiner ID (if not known, it will be NULL). 169 * @param[in] aContext A pointer to application-specific context. 170 * 171 */ 172 typedef void (*otCommissionerJoinerCallback)(otCommissionerJoinerEvent aEvent, 173 const otJoinerInfo * aJoinerInfo, 174 const otExtAddress * aJoinerId, 175 void * aContext); 176 177 /** 178 * This function enables the Thread Commissioner role. 179 * 180 * @param[in] aInstance A pointer to an OpenThread instance. 181 * @param[in] aStateCallback A pointer to a function that is called when the commissioner state changes. 182 * @param[in] aJoinerCallback A pointer to a function that is called with a joiner event occurs. 183 * @param[in] aCallbackContext A pointer to application-specific context. 184 * 185 * @retval OT_ERROR_NONE Successfully started the Commissioner service. 186 * @retval OT_ERROR_ALREADY Commissioner is already started. 187 * @retval OT_ERROR_INVALID_STATE Device is not currently attached to a network. 188 * 189 */ 190 otError otCommissionerStart(otInstance * aInstance, 191 otCommissionerStateCallback aStateCallback, 192 otCommissionerJoinerCallback aJoinerCallback, 193 void * aCallbackContext); 194 195 /** 196 * This function disables the Thread Commissioner role. 197 * 198 * @param[in] aInstance A pointer to an OpenThread instance. 199 * 200 * @retval OT_ERROR_NONE Successfully stopped the Commissioner service. 201 * @retval OT_ERROR_ALREADY Commissioner is already stopped. 202 * 203 */ 204 otError otCommissionerStop(otInstance *aInstance); 205 206 /** 207 * This function returns the Commissioner Id. 208 * 209 * @param[in] aInstance A pointer to an OpenThread instance. 210 * 211 * @returns The Commissioner Id. 212 * 213 */ 214 const char *otCommissionerGetId(otInstance *aInstance); 215 216 /** 217 * This function sets the Commissioner Id. 218 * 219 * @param[in] aInstance A pointer to an OpenThread instance. 220 * @param[in] aId A pointer to a string character array. Must be null terminated. 221 * 222 * @retval OT_ERROR_NONE Successfully set the Commissioner Id. 223 * @retval OT_ERROR_INVALID_ARGS Given name is too long. 224 * @retval OT_ERROR_INVALID_STATE The commissioner is active and id cannot be changed. 225 * 226 */ 227 otError otCommissionerSetId(otInstance *aInstance, const char *aId); 228 229 /** 230 * This function adds a Joiner entry. 231 * 232 * @param[in] aInstance A pointer to an OpenThread instance. 233 * @param[in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner. 234 * @param[in] aPskd A pointer to the PSKd. 235 * @param[in] aTimeout A time after which a Joiner is automatically removed, in seconds. 236 * 237 * @retval OT_ERROR_NONE Successfully added the Joiner. 238 * @retval OT_ERROR_NO_BUFS No buffers available to add the Joiner. 239 * @retval OT_ERROR_INVALID_ARGS @p aEui64 or @p aPskd is invalid. 240 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 241 * 242 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart(). 243 * 244 */ 245 otError otCommissionerAddJoiner(otInstance * aInstance, 246 const otExtAddress *aEui64, 247 const char * aPskd, 248 uint32_t aTimeout); 249 250 /** 251 * This function adds a Joiner entry with a given Joiner Discerner value. 252 * 253 * @param[in] aInstance A pointer to an OpenThread instance. 254 * @param[in] aDiscerner A pointer to the Joiner Discerner. 255 * @param[in] aPskd A pointer to the PSKd. 256 * @param[in] aTimeout A time after which a Joiner is automatically removed, in seconds. 257 * 258 * @retval OT_ERROR_NONE Successfully added the Joiner. 259 * @retval OT_ERROR_NO_BUFS No buffers available to add the Joiner. 260 * @retval OT_ERROR_INVALID_ARGS @p aDiscerner or @p aPskd is invalid. 261 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 262 * 263 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart(). 264 * 265 */ 266 otError otCommissionerAddJoinerWithDiscerner(otInstance * aInstance, 267 const otJoinerDiscerner *aDiscerner, 268 const char * aPskd, 269 uint32_t aTimeout); 270 271 /** 272 * This method get joiner info at aIterator position. 273 * 274 * @param[in] aInstance A pointer to instance. 275 * @param[in,out] aIterator A pointer to the Joiner Info iterator context. 276 * @param[out] aJoiner A reference to Joiner info. 277 * 278 * @retval OT_ERROR_NONE Successfully get the Joiner info. 279 * @retval OT_ERROR_NOT_FOUND Not found next Joiner. 280 * 281 */ 282 otError otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t *aIterator, otJoinerInfo *aJoiner); 283 284 /** 285 * This function removes a Joiner entry. 286 * 287 * @param[in] aInstance A pointer to an OpenThread instance. 288 * @param[in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner. 289 * 290 * @retval OT_ERROR_NONE Successfully removed the Joiner. 291 * @retval OT_ERROR_NOT_FOUND The Joiner specified by @p aEui64 was not found. 292 * @retval OT_ERROR_INVALID_ARGS @p aEui64 is invalid. 293 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 294 * 295 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart(). 296 * 297 */ 298 otError otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aEui64); 299 300 /** 301 * This function removes a Joiner entry. 302 * 303 * @param[in] aInstance A pointer to an OpenThread instance. 304 * @param[in] aDiscerner A pointer to the Joiner Discerner. 305 * 306 * @retval OT_ERROR_NONE Successfully removed the Joiner. 307 * @retval OT_ERROR_NOT_FOUND The Joiner specified by @p aEui64 was not found. 308 * @retval OT_ERROR_INVALID_ARGS @p aDiscerner is invalid. 309 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 310 * 311 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart(). 312 * 313 */ 314 otError otCommissionerRemoveJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner); 315 316 /** 317 * This function gets the Provisioning URL. 318 * 319 * @param[in] aInstance A pointer to an OpenThread instance. 320 * 321 * @returns A pointer to the URL string. 322 * 323 */ 324 const char *otCommissionerGetProvisioningUrl(otInstance *aInstance); 325 326 /** 327 * This function sets the Provisioning URL. 328 * 329 * @param[in] aInstance A pointer to an OpenThread instance. 330 * @param[in] aProvisioningUrl A pointer to the Provisioning URL (may be NULL to set as empty string). 331 * 332 * @retval OT_ERROR_NONE Successfully set the Provisioning URL. 333 * @retval OT_ERROR_INVALID_ARGS @p aProvisioningUrl is invalid (too long). 334 * 335 */ 336 otError otCommissionerSetProvisioningUrl(otInstance *aInstance, const char *aProvisioningUrl); 337 338 /** 339 * This function sends an Announce Begin message. 340 * 341 * @param[in] aInstance A pointer to an OpenThread instance. 342 * @param[in] aChannelMask The channel mask value. 343 * @param[in] aCount The number of Announcement messages per channel. 344 * @param[in] aPeriod The time between two successive MLE Announce transmissions (in milliseconds). 345 * @param[in] aAddress A pointer to the IPv6 destination. 346 * 347 * @retval OT_ERROR_NONE Successfully enqueued the Announce Begin message. 348 * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate an Announce Begin message. 349 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 350 * 351 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart(). 352 * 353 */ 354 otError otCommissionerAnnounceBegin(otInstance * aInstance, 355 uint32_t aChannelMask, 356 uint8_t aCount, 357 uint16_t aPeriod, 358 const otIp6Address *aAddress); 359 360 /** 361 * This function pointer is called when the Commissioner receives an Energy Report. 362 * 363 * @param[in] aChannelMask The channel mask value. 364 * @param[in] aEnergyList A pointer to the energy measurement list. 365 * @param[in] aEnergyListLength Number of entries in @p aEnergyListLength. 366 * @param[in] aContext A pointer to application-specific context. 367 * 368 */ 369 typedef void (*otCommissionerEnergyReportCallback)(uint32_t aChannelMask, 370 const uint8_t *aEnergyList, 371 uint8_t aEnergyListLength, 372 void * aContext); 373 374 /** 375 * This function sends an Energy Scan Query message. 376 * 377 * @param[in] aInstance A pointer to an OpenThread instance. 378 * @param[in] aChannelMask The channel mask value. 379 * @param[in] aCount The number of energy measurements per channel. 380 * @param[in] aPeriod The time between energy measurements (milliseconds). 381 * @param[in] aScanDuration The scan duration for each energy measurement (milliseconds). 382 * @param[in] aAddress A pointer to the IPv6 destination. 383 * @param[in] aCallback A pointer to a function called on receiving an Energy Report message. 384 * @param[in] aContext A pointer to application-specific context. 385 * 386 * @retval OT_ERROR_NONE Successfully enqueued the Energy Scan Query message. 387 * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate an Energy Scan Query message. 388 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 389 * 390 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart(). 391 * 392 */ 393 otError otCommissionerEnergyScan(otInstance * aInstance, 394 uint32_t aChannelMask, 395 uint8_t aCount, 396 uint16_t aPeriod, 397 uint16_t aScanDuration, 398 const otIp6Address * aAddress, 399 otCommissionerEnergyReportCallback aCallback, 400 void * aContext); 401 402 /** 403 * This function pointer is called when the Commissioner receives a PAN ID Conflict message. 404 * 405 * @param[in] aPanId The PAN ID value. 406 * @param[in] aChannelMask The channel mask value. 407 * @param[in] aContext A pointer to application-specific context. 408 * 409 */ 410 typedef void (*otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint32_t aChannelMask, void *aContext); 411 412 /** 413 * This function sends a PAN ID Query message. 414 * 415 * @param[in] aInstance A pointer to an OpenThread instance. 416 * @param[in] aPanId The PAN ID to query. 417 * @param[in] aChannelMask The channel mask value. 418 * @param[in] aAddress A pointer to the IPv6 destination. 419 * @param[in] aCallback A pointer to a function called on receiving a PAN ID Conflict message. 420 * @param[in] aContext A pointer to application-specific context. 421 * 422 * @retval OT_ERROR_NONE Successfully enqueued the PAN ID Query message. 423 * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate a PAN ID Query message. 424 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 425 * 426 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart(). 427 * 428 */ 429 otError otCommissionerPanIdQuery(otInstance * aInstance, 430 uint16_t aPanId, 431 uint32_t aChannelMask, 432 const otIp6Address * aAddress, 433 otCommissionerPanIdConflictCallback aCallback, 434 void * aContext); 435 436 /** 437 * This function sends MGMT_COMMISSIONER_GET. 438 * 439 * @param[in] aInstance A pointer to an OpenThread instance. 440 * @param[in] aTlvs A pointer to TLVs. 441 * @param[in] aLength The length of TLVs. 442 * 443 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 444 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 445 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 446 * 447 */ 448 otError otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength); 449 450 /** 451 * This function sends MGMT_COMMISSIONER_SET. 452 * 453 * @param[in] aInstance A pointer to an OpenThread instance. 454 * @param[in] aDataset A pointer to commissioning dataset. 455 * @param[in] aTlvs A pointer to TLVs. 456 * @param[in] aLength The length of TLVs. 457 * 458 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 459 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 460 * @retval OT_ERROR_INVALID_STATE The commissioner is not active. 461 * 462 */ 463 otError otCommissionerSendMgmtSet(otInstance * aInstance, 464 const otCommissioningDataset *aDataset, 465 const uint8_t * aTlvs, 466 uint8_t aLength); 467 468 /** 469 * This function returns the Commissioner Session ID. 470 * 471 * @param[in] aInstance A pointer to an OpenThread instance. 472 * 473 * @returns The current commissioner session id. 474 * 475 */ 476 uint16_t otCommissionerGetSessionId(otInstance *aInstance); 477 478 /** 479 * This function returns the Commissioner State. 480 * 481 * @param[in] aInstance A pointer to an OpenThread instance. 482 * 483 * @retval OT_COMMISSIONER_STATE_DISABLED Commissioner disabled. 484 * @retval OT_COMMISSIONER_STATE_PETITION Becoming the commissioner. 485 * @retval OT_COMMISSIONER_STATE_ACTIVE Commissioner enabled. 486 * 487 */ 488 otCommissionerState otCommissionerGetState(otInstance *aInstance); 489 490 /** 491 * @} 492 * 493 */ 494 495 #ifdef __cplusplus 496 } // end of extern "C" 497 #endif 498 499 #endif // OPENTHREAD_COMMISSIONER_H_ 500