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 defines the OpenThread Thread API (for both FTD and MTD). 33 */ 34 35 #ifndef OPENTHREAD_THREAD_H_ 36 #define OPENTHREAD_THREAD_H_ 37 38 #include <openthread/dataset.h> 39 #include <openthread/link.h> 40 #include <openthread/message.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-thread-general 48 * 49 * @note 50 * The functions in this module require `OPENTHREAD_FTD=1` or `OPENTHREAD_MTD=1`. 51 * 52 * @{ 53 */ 54 55 #define OT_THREAD_VERSION_INVALID 0 ///< Invalid Thread version 56 #define OT_THREAD_VERSION_1_1 2 ///< Thread Version 1.1 57 #define OT_THREAD_VERSION_1_2 3 ///< Thread Version 1.2 58 #define OT_THREAD_VERSION_1_3 4 ///< Thread Version 1.3 59 #define OT_THREAD_VERSION_1_3_1 5 ///< Thread Version 1.3.1 (alias for 1.4) 60 #define OT_THREAD_VERSION_1_4 5 ///< Thread Version 1.4 61 62 /** 63 * Maximum value length of Thread Base TLV. 64 */ 65 #define OT_NETWORK_BASE_TLV_MAX_LENGTH 254 66 67 #define OT_NETWORK_MAX_ROUTER_ID 62 ///< Maximum Router ID 68 69 /** 70 * Represents a Thread device role. 71 */ 72 typedef enum 73 { 74 OT_DEVICE_ROLE_DISABLED = 0, ///< The Thread stack is disabled. 75 OT_DEVICE_ROLE_DETACHED = 1, ///< Not currently participating in a Thread network/partition. 76 OT_DEVICE_ROLE_CHILD = 2, ///< The Thread Child role. 77 OT_DEVICE_ROLE_ROUTER = 3, ///< The Thread Router role. 78 OT_DEVICE_ROLE_LEADER = 4, ///< The Thread Leader role. 79 } otDeviceRole; 80 81 /** 82 * Represents an MLE Link Mode configuration. 83 */ 84 typedef struct otLinkModeConfig 85 { 86 bool mRxOnWhenIdle : 1; ///< 1, if the sender has its receiver on when not transmitting. 0, otherwise. 87 bool mDeviceType : 1; ///< 1, if the sender is an FTD. 0, otherwise. 88 bool mNetworkData : 1; ///< 1, if the sender requires the full Network Data. 0, otherwise. 89 } otLinkModeConfig; 90 91 /** 92 * Holds diagnostic information for a neighboring Thread node 93 */ 94 typedef struct 95 { 96 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address 97 uint32_t mAge; ///< Seconds since last heard 98 uint32_t mConnectionTime; ///< Seconds since link establishment (requires `CONFIG_UPTIME_ENABLE`) 99 uint16_t mRloc16; ///< RLOC16 100 uint32_t mLinkFrameCounter; ///< Link Frame Counter 101 uint32_t mMleFrameCounter; ///< MLE Frame Counter 102 uint8_t mLinkQualityIn; ///< Link Quality In 103 int8_t mAverageRssi; ///< Average RSSI 104 int8_t mLastRssi; ///< Last observed RSSI 105 uint8_t mLinkMargin; ///< Link Margin 106 uint16_t mFrameErrorRate; ///< Frame error rate (0xffff->100%). Requires error tracking feature. 107 uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0xffff->100%). Requires error tracking feature. 108 uint16_t mVersion; ///< Thread version of the neighbor 109 bool mRxOnWhenIdle : 1; ///< rx-on-when-idle 110 bool mFullThreadDevice : 1; ///< Full Thread Device 111 bool mFullNetworkData : 1; ///< Full Network Data 112 bool mIsChild : 1; ///< Is the neighbor a child 113 } otNeighborInfo; 114 115 #define OT_NEIGHBOR_INFO_ITERATOR_INIT 0 ///< Initializer for otNeighborInfoIterator. 116 117 typedef int16_t otNeighborInfoIterator; ///< Used to iterate through neighbor table. 118 119 /** 120 * Represents the Thread Leader Data. 121 */ 122 typedef struct otLeaderData 123 { 124 uint32_t mPartitionId; ///< Partition ID 125 uint8_t mWeighting; ///< Leader Weight 126 uint8_t mDataVersion; ///< Full Network Data Version 127 uint8_t mStableDataVersion; ///< Stable Network Data Version 128 uint8_t mLeaderRouterId; ///< Leader Router ID 129 } otLeaderData; 130 131 /** 132 * Holds diagnostic information for a Thread Router 133 */ 134 typedef struct 135 { 136 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address 137 uint16_t mRloc16; ///< RLOC16 138 uint8_t mRouterId; ///< Router ID 139 uint8_t mNextHop; ///< Next hop to router 140 uint8_t mPathCost; ///< Path cost to router 141 uint8_t mLinkQualityIn; ///< Link Quality In 142 uint8_t mLinkQualityOut; ///< Link Quality Out 143 uint8_t mAge; ///< Time last heard 144 bool mAllocated : 1; ///< Router ID allocated or not 145 bool mLinkEstablished : 1; ///< Link established with Router ID or not 146 uint8_t mVersion; ///< Thread version 147 148 /** 149 * Parent CSL parameters are only relevant when OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE is enabled. 150 */ 151 uint8_t mCslClockAccuracy; ///< CSL clock accuracy, in ± ppm 152 uint8_t mCslUncertainty; ///< CSL uncertainty, in ±10 us 153 } otRouterInfo; 154 155 /** 156 * Represents the IP level counters. 157 */ 158 typedef struct otIpCounters 159 { 160 uint32_t mTxSuccess; ///< The number of IPv6 packets successfully transmitted. 161 uint32_t mRxSuccess; ///< The number of IPv6 packets successfully received. 162 uint32_t mTxFailure; ///< The number of IPv6 packets failed to transmit. 163 uint32_t mRxFailure; ///< The number of IPv6 packets failed to receive. 164 } otIpCounters; 165 166 /** 167 * Represents the Thread MLE counters. 168 */ 169 typedef struct otMleCounters 170 { 171 uint16_t mDisabledRole; ///< Number of times device entered OT_DEVICE_ROLE_DISABLED role. 172 uint16_t mDetachedRole; ///< Number of times device entered OT_DEVICE_ROLE_DETACHED role. 173 uint16_t mChildRole; ///< Number of times device entered OT_DEVICE_ROLE_CHILD role. 174 uint16_t mRouterRole; ///< Number of times device entered OT_DEVICE_ROLE_ROUTER role. 175 uint16_t mLeaderRole; ///< Number of times device entered OT_DEVICE_ROLE_LEADER role. 176 uint16_t mAttachAttempts; ///< Number of attach attempts while device was detached. 177 uint16_t mPartitionIdChanges; ///< Number of changes to partition ID. 178 uint16_t mBetterPartitionAttachAttempts; ///< Number of attempts to attach to a better partition. 179 uint16_t mBetterParentAttachAttempts; ///< Number of attempts to attach to find a better parent (parent search). 180 181 /** 182 * Role time tracking. 183 * 184 * When uptime feature is enabled (OPENTHREAD_CONFIG_UPTIME_ENABLE = 1) time spent in each MLE role is tracked. 185 */ 186 uint64_t mDisabledTime; ///< Number of milliseconds device has been in OT_DEVICE_ROLE_DISABLED role. 187 uint64_t mDetachedTime; ///< Number of milliseconds device has been in OT_DEVICE_ROLE_DETACHED role. 188 uint64_t mChildTime; ///< Number of milliseconds device has been in OT_DEVICE_ROLE_CHILD role. 189 uint64_t mRouterTime; ///< Number of milliseconds device has been in OT_DEVICE_ROLE_ROUTER role. 190 uint64_t mLeaderTime; ///< Number of milliseconds device has been in OT_DEVICE_ROLE_LEADER role. 191 uint64_t mTrackedTime; ///< Number of milliseconds tracked by previous counters. 192 193 /** 194 * Number of times device changed its parent. 195 * 196 * A parent change can happen if device detaches from its current parent and attaches to a different one, or even 197 * while device is attached when the periodic parent search feature is enabled (please see option 198 * OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE). 199 */ 200 uint16_t mParentChanges; 201 } otMleCounters; 202 203 /** 204 * Represents the MLE Parent Response data. 205 */ 206 typedef struct otThreadParentResponseInfo 207 { 208 otExtAddress mExtAddr; ///< IEEE 802.15.4 Extended Address of the Parent 209 uint16_t mRloc16; ///< Short address of the Parent 210 int8_t mRssi; ///< Rssi of the Parent 211 int8_t mPriority; ///< Parent priority 212 uint8_t mLinkQuality3; ///< Parent Link Quality 3 213 uint8_t mLinkQuality2; ///< Parent Link Quality 2 214 uint8_t mLinkQuality1; ///< Parent Link Quality 1 215 bool mIsAttached; ///< Is the node receiving parent response attached 216 } otThreadParentResponseInfo; 217 218 /** 219 * This callback informs the application that the detaching process has finished. 220 * 221 * @param[in] aContext A pointer to application-specific context. 222 */ 223 typedef void (*otDetachGracefullyCallback)(void *aContext); 224 225 /** 226 * Informs the application about the result of waking a Wake-up End Device. 227 * 228 * @param[in] aError OT_ERROR_NONE Indicates that the Wake-up End Device has been added as a neighbor. 229 * OT_ERROR_FAILED Indicates that the Wake-up End Device has not received a wake-up frame, or it 230 * has failed the MLE procedure. 231 * @param[in] aContext A pointer to application-specific context. 232 */ 233 typedef void (*otWakeupCallback)(otError aError, void *aContext); 234 235 /** 236 * Starts Thread protocol operation. 237 * 238 * The interface must be up when calling this function. 239 * 240 * Calling this function with @p aEnabled set to FALSE stops any ongoing processes of detaching started by 241 * otThreadDetachGracefully(). Its callback will be called. 242 * 243 * @param[in] aInstance A pointer to an OpenThread instance. 244 * @param[in] aEnabled TRUE if Thread is enabled, FALSE otherwise. 245 * 246 * @retval OT_ERROR_NONE Successfully started Thread protocol operation. 247 * @retval OT_ERROR_INVALID_STATE The network interface was not up. 248 */ 249 otError otThreadSetEnabled(otInstance *aInstance, bool aEnabled); 250 251 /** 252 * Gets the Thread protocol version. 253 * 254 * The constants `OT_THREAD_VERSION_*` define the numerical version values. 255 * 256 * @returns the Thread protocol version. 257 */ 258 uint16_t otThreadGetVersion(void); 259 260 /** 261 * Indicates whether a node is the only router on the network. 262 * 263 * @param[in] aInstance A pointer to an OpenThread instance. 264 * 265 * @retval TRUE It is the only router in the network. 266 * @retval FALSE It is a child or is not a single router in the network. 267 */ 268 bool otThreadIsSingleton(otInstance *aInstance); 269 270 /** 271 * Starts a Thread Discovery scan. 272 * 273 * @note A successful call to this function enables the rx-on-when-idle mode for the entire scan procedure. 274 * 275 * @param[in] aInstance A pointer to an OpenThread instance. 276 * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). 277 * @param[in] aPanId The PAN ID filter (set to Broadcast PAN to disable filter). 278 * @param[in] aJoiner Value of the Joiner Flag in the Discovery Request TLV. 279 * @param[in] aEnableEui64Filtering TRUE to filter responses on EUI-64, FALSE otherwise. 280 * @param[in] aCallback A pointer to a function called on receiving an MLE Discovery Response or 281 * scan completes. 282 * @param[in] aCallbackContext A pointer to application-specific context. 283 * 284 * @retval OT_ERROR_NONE Successfully started a Thread Discovery Scan. 285 * @retval OT_ERROR_INVALID_STATE The IPv6 interface is not enabled (netif is not up). 286 * @retval OT_ERROR_NO_BUFS Could not allocate message for Discovery Request. 287 * @retval OT_ERROR_BUSY Thread Discovery Scan is already in progress. 288 */ 289 otError otThreadDiscover(otInstance *aInstance, 290 uint32_t aScanChannels, 291 uint16_t aPanId, 292 bool aJoiner, 293 bool aEnableEui64Filtering, 294 otHandleActiveScanResult aCallback, 295 void *aCallbackContext); 296 297 /** 298 * Determines if an MLE Thread Discovery is currently in progress. 299 * 300 * @param[in] aInstance A pointer to an OpenThread instance. 301 */ 302 bool otThreadIsDiscoverInProgress(otInstance *aInstance); 303 304 /** 305 * Sets the Thread Joiner Advertisement when discovering Thread network. 306 * 307 * Thread Joiner Advertisement is used to allow a Joiner to advertise its own application-specific information 308 * (such as Vendor ID, Product ID, Discriminator, etc.) via a newly-proposed Joiner Advertisement TLV, 309 * and to make this information available to Commissioners or Commissioner Candidates without human interaction. 310 * 311 * @param[in] aInstance A pointer to an OpenThread instance. 312 * @param[in] aOui The Vendor IEEE OUI value that will be included in the Joiner Advertisement. Only the 313 * least significant 3 bytes will be used, and the most significant byte will be ignored. 314 * @param[in] aAdvData A pointer to the AdvData that will be included in the Joiner Advertisement. 315 * @param[in] aAdvDataLength The length of AdvData in bytes. 316 * 317 * @retval OT_ERROR_NONE Successfully set Joiner Advertisement. 318 * @retval OT_ERROR_INVALID_ARGS Invalid AdvData. 319 */ 320 otError otThreadSetJoinerAdvertisement(otInstance *aInstance, 321 uint32_t aOui, 322 const uint8_t *aAdvData, 323 uint8_t aAdvDataLength); 324 325 #define OT_JOINER_ADVDATA_MAX_LENGTH 64 ///< Maximum AdvData Length of Joiner Advertisement 326 327 /** 328 * Gets the Thread Child Timeout (in seconds) used when operating in the Child role. 329 * 330 * @param[in] aInstance A pointer to an OpenThread instance. 331 * 332 * @returns The Thread Child Timeout value in seconds. 333 * 334 * @sa otThreadSetChildTimeout 335 */ 336 uint32_t otThreadGetChildTimeout(otInstance *aInstance); 337 338 /** 339 * Sets the Thread Child Timeout (in seconds) used when operating in the Child role. 340 * 341 * @param[in] aInstance A pointer to an OpenThread instance. 342 * @param[in] aTimeout The timeout value in seconds. 343 * 344 * @sa otThreadGetChildTimeout 345 */ 346 void otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeout); 347 348 /** 349 * Gets the IEEE 802.15.4 Extended PAN ID. 350 * 351 * @param[in] aInstance A pointer to an OpenThread instance. 352 * 353 * @returns A pointer to the IEEE 802.15.4 Extended PAN ID. 354 * 355 * @sa otThreadSetExtendedPanId 356 */ 357 const otExtendedPanId *otThreadGetExtendedPanId(otInstance *aInstance); 358 359 /** 360 * Sets the IEEE 802.15.4 Extended PAN ID. 361 * 362 * @note Can only be called while Thread protocols are disabled. A successful 363 * call to this function invalidates the Active and Pending Operational Datasets in 364 * non-volatile memory. 365 * 366 * @param[in] aInstance A pointer to an OpenThread instance. 367 * @param[in] aExtendedPanId A pointer to the IEEE 802.15.4 Extended PAN ID. 368 * 369 * @retval OT_ERROR_NONE Successfully set the Extended PAN ID. 370 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 371 * 372 * @sa otThreadGetExtendedPanId 373 */ 374 otError otThreadSetExtendedPanId(otInstance *aInstance, const otExtendedPanId *aExtendedPanId); 375 376 /** 377 * Returns a pointer to the Leader's RLOC. 378 * 379 * @param[in] aInstance A pointer to an OpenThread instance. 380 * @param[out] aLeaderRloc A pointer to the Leader's RLOC. 381 * 382 * @retval OT_ERROR_NONE The Leader's RLOC was successfully written to @p aLeaderRloc. 383 * @retval OT_ERROR_INVALID_ARGS @p aLeaderRloc was NULL. 384 * @retval OT_ERROR_DETACHED Not currently attached to a Thread Partition. 385 */ 386 otError otThreadGetLeaderRloc(otInstance *aInstance, otIp6Address *aLeaderRloc); 387 388 /** 389 * Get the MLE Link Mode configuration. 390 * 391 * @param[in] aInstance A pointer to an OpenThread instance. 392 * 393 * @returns The MLE Link Mode configuration. 394 * 395 * @sa otThreadSetLinkMode 396 */ 397 otLinkModeConfig otThreadGetLinkMode(otInstance *aInstance); 398 399 /** 400 * Set the MLE Link Mode configuration. 401 * 402 * @param[in] aInstance A pointer to an OpenThread instance. 403 * @param[in] aConfig A pointer to the Link Mode configuration. 404 * 405 * @retval OT_ERROR_NONE Successfully set the MLE Link Mode configuration. 406 * 407 * @sa otThreadGetLinkMode 408 */ 409 otError otThreadSetLinkMode(otInstance *aInstance, otLinkModeConfig aConfig); 410 411 /** 412 * Get the Thread Network Key. 413 * 414 * @param[in] aInstance A pointer to an OpenThread instance. 415 * @param[out] aNetworkKey A pointer to an `otNetworkKey` to return the Thread Network Key. 416 * 417 * @sa otThreadSetNetworkKey 418 */ 419 void otThreadGetNetworkKey(otInstance *aInstance, otNetworkKey *aNetworkKey); 420 421 /** 422 * Get the `otNetworkKeyRef` for Thread Network Key. 423 * 424 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 425 * 426 * @param[in] aInstance A pointer to an OpenThread instance. 427 * 428 * @returns Reference to the Thread Network Key stored in memory. 429 * 430 * @sa otThreadSetNetworkKeyRef 431 */ 432 otNetworkKeyRef otThreadGetNetworkKeyRef(otInstance *aInstance); 433 434 /** 435 * Set the Thread Network Key. 436 * 437 * Succeeds only when Thread protocols are disabled. A successful 438 * call to this function invalidates the Active and Pending Operational Datasets in 439 * non-volatile memory. 440 * 441 * @param[in] aInstance A pointer to an OpenThread instance. 442 * @param[in] aKey A pointer to a buffer containing the Thread Network Key. 443 * 444 * @retval OT_ERROR_NONE Successfully set the Thread Network Key. 445 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 446 * 447 * @sa otThreadGetNetworkKey 448 */ 449 otError otThreadSetNetworkKey(otInstance *aInstance, const otNetworkKey *aKey); 450 451 /** 452 * Set the Thread Network Key as a `otNetworkKeyRef`. 453 * 454 * Succeeds only when Thread protocols are disabled. A successful 455 * call to this function invalidates the Active and Pending Operational Datasets in 456 * non-volatile memory. 457 * 458 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 459 * 460 * @param[in] aInstance A pointer to an OpenThread instance. 461 * @param[in] aKeyRef Reference to the Thread Network Key. 462 * 463 * @retval OT_ERROR_NONE Successfully set the Thread Network Key. 464 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 465 * 466 * @sa otThreadGetNetworkKeyRef 467 */ 468 otError otThreadSetNetworkKeyRef(otInstance *aInstance, otNetworkKeyRef aKeyRef); 469 470 /** 471 * Gets the Thread Routing Locator (RLOC) address. 472 * 473 * @param[in] aInstance A pointer to an OpenThread instance. 474 * 475 * @returns A pointer to the Thread Routing Locator (RLOC) address. 476 */ 477 const otIp6Address *otThreadGetRloc(otInstance *aInstance); 478 479 /** 480 * Gets the Mesh Local EID address. 481 * 482 * @param[in] aInstance A pointer to an OpenThread instance. 483 * 484 * @returns A pointer to the Mesh Local EID address. 485 */ 486 const otIp6Address *otThreadGetMeshLocalEid(otInstance *aInstance); 487 488 /** 489 * Returns a pointer to the Mesh Local Prefix. 490 * 491 * @param[in] aInstance A pointer to an OpenThread instance. 492 * 493 * @returns A pointer to the Mesh Local Prefix. 494 */ 495 const otMeshLocalPrefix *otThreadGetMeshLocalPrefix(otInstance *aInstance); 496 497 /** 498 * Sets the Mesh Local Prefix. 499 * 500 * Succeeds only when Thread protocols are disabled. A successful 501 * call to this function invalidates the Active and Pending Operational Datasets in 502 * non-volatile memory. 503 * 504 * @param[in] aInstance A pointer to an OpenThread instance. 505 * @param[in] aMeshLocalPrefix A pointer to the Mesh Local Prefix. 506 * 507 * @retval OT_ERROR_NONE Successfully set the Mesh Local Prefix. 508 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 509 */ 510 otError otThreadSetMeshLocalPrefix(otInstance *aInstance, const otMeshLocalPrefix *aMeshLocalPrefix); 511 512 /** 513 * Gets the Thread link-local IPv6 address. 514 * 515 * The Thread link local address is derived using IEEE802.15.4 Extended Address as Interface Identifier. 516 * 517 * @param[in] aInstance A pointer to an OpenThread instance. 518 * 519 * @returns A pointer to Thread link-local IPv6 address. 520 */ 521 const otIp6Address *otThreadGetLinkLocalIp6Address(otInstance *aInstance); 522 523 /** 524 * Gets the Thread Link-Local All Thread Nodes multicast address. 525 * 526 * The address is a link-local Unicast Prefix-Based Multicast Address [RFC 3306], with: 527 * - flgs set to 3 (P = 1 and T = 1) 528 * - scop set to 2 529 * - plen set to 64 530 * - network prefix set to the Mesh Local Prefix 531 * - group ID set to 1 532 * 533 * @param[in] aInstance A pointer to an OpenThread instance. 534 * 535 * @returns A pointer to Thread Link-Local All Thread Nodes multicast address. 536 */ 537 const otIp6Address *otThreadGetLinkLocalAllThreadNodesMulticastAddress(otInstance *aInstance); 538 539 /** 540 * Gets the Thread Realm-Local All Thread Nodes multicast address. 541 * 542 * The address is a realm-local Unicast Prefix-Based Multicast Address [RFC 3306], with: 543 * - flgs set to 3 (P = 1 and T = 1) 544 * - scop set to 3 545 * - plen set to 64 546 * - network prefix set to the Mesh Local Prefix 547 * - group ID set to 1 548 * 549 * @param[in] aInstance A pointer to an OpenThread instance. 550 * 551 * @returns A pointer to Thread Realm-Local All Thread Nodes multicast address. 552 */ 553 const otIp6Address *otThreadGetRealmLocalAllThreadNodesMulticastAddress(otInstance *aInstance); 554 555 /** 556 * Retrieves the Service ALOC for given Service ID. 557 * 558 * @param[in] aInstance A pointer to an OpenThread instance. 559 * @param[in] aServiceId Service ID to get ALOC for. 560 * @param[out] aServiceAloc A pointer to output the Service ALOC. MUST NOT BE NULL. 561 * 562 * @retval OT_ERROR_NONE Successfully retrieved the Service ALOC. 563 * @retval OT_ERROR_DETACHED The Thread interface is not currently attached to a Thread Partition. 564 */ 565 otError otThreadGetServiceAloc(otInstance *aInstance, uint8_t aServiceId, otIp6Address *aServiceAloc); 566 567 /** 568 * Get the Thread Network Name. 569 * 570 * @param[in] aInstance A pointer to an OpenThread instance. 571 * 572 * @returns A pointer to the Thread Network Name. 573 * 574 * @sa otThreadSetNetworkName 575 */ 576 const char *otThreadGetNetworkName(otInstance *aInstance); 577 578 /** 579 * Set the Thread Network Name. 580 * 581 * Succeeds only when Thread protocols are disabled. A successful 582 * call to this function invalidates the Active and Pending Operational Datasets in 583 * non-volatile memory. 584 * 585 * @param[in] aInstance A pointer to an OpenThread instance. 586 * @param[in] aNetworkName A pointer to the Thread Network Name. 587 * 588 * @retval OT_ERROR_NONE Successfully set the Thread Network Name. 589 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 590 * 591 * @sa otThreadGetNetworkName 592 */ 593 otError otThreadSetNetworkName(otInstance *aInstance, const char *aNetworkName); 594 595 /** 596 * Gets the Thread Domain Name. 597 * 598 * @note Available since Thread 1.2. 599 * 600 * @param[in] aInstance A pointer to an OpenThread instance. 601 * 602 * @returns A pointer to the Thread Domain Name. 603 * 604 * @sa otThreadSetDomainName 605 */ 606 const char *otThreadGetDomainName(otInstance *aInstance); 607 608 /** 609 * Sets the Thread Domain Name. Only succeeds when Thread protocols are disabled. 610 * 611 * @note Available since Thread 1.2. 612 * 613 * @param[in] aInstance A pointer to an OpenThread instance. 614 * @param[in] aDomainName A pointer to the Thread Domain Name. 615 * 616 * @retval OT_ERROR_NONE Successfully set the Thread Domain Name. 617 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 618 * 619 * @sa otThreadGetDomainName 620 */ 621 otError otThreadSetDomainName(otInstance *aInstance, const char *aDomainName); 622 623 /** 624 * Sets or clears the Interface Identifier manually specified for the Thread Domain Unicast Address. 625 * 626 * Available when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled. 627 * 628 * @note Only available since Thread 1.2. 629 * 630 * @param[in] aInstance A pointer to an OpenThread instance. 631 * @param[in] aIid A pointer to the Interface Identifier to set or NULL to clear. 632 * 633 * @retval OT_ERROR_NONE Successfully set/cleared the Interface Identifier. 634 * @retval OT_ERROR_INVALID_ARGS The specified Interface Identifier is reserved. 635 * 636 * @sa otThreadGetFixedDuaInterfaceIdentifier 637 */ 638 otError otThreadSetFixedDuaInterfaceIdentifier(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid); 639 640 /** 641 * Gets the Interface Identifier manually specified for the Thread Domain Unicast Address. 642 * 643 * Available when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled. 644 * 645 * @note Only available since Thread 1.2. 646 * 647 * @param[in] aInstance A pointer to an OpenThread instance. 648 * 649 * @returns A pointer to the Interface Identifier which was set manually, or NULL if none was set. 650 * 651 * @sa otThreadSetFixedDuaInterfaceIdentifier 652 */ 653 const otIp6InterfaceIdentifier *otThreadGetFixedDuaInterfaceIdentifier(otInstance *aInstance); 654 655 /** 656 * Gets the thrKeySequenceCounter. 657 * 658 * @param[in] aInstance A pointer to an OpenThread instance. 659 * 660 * @returns The thrKeySequenceCounter value. 661 * 662 * @sa otThreadSetKeySequenceCounter 663 */ 664 uint32_t otThreadGetKeySequenceCounter(otInstance *aInstance); 665 666 /** 667 * Sets the thrKeySequenceCounter. 668 * 669 * @note This API is reserved for testing and demo purposes only. Changing settings with 670 * this API will render a production application non-compliant with the Thread Specification. 671 * 672 * @param[in] aInstance A pointer to an OpenThread instance. 673 * @param[in] aKeySequenceCounter The thrKeySequenceCounter value. 674 * 675 * @sa otThreadGetKeySequenceCounter 676 */ 677 void otThreadSetKeySequenceCounter(otInstance *aInstance, uint32_t aKeySequenceCounter); 678 679 /** 680 * Gets the thrKeySwitchGuardTime (in hours). 681 * 682 * @param[in] aInstance A pointer to an OpenThread instance. 683 * 684 * @returns The thrKeySwitchGuardTime value (in hours). 685 * 686 * @sa otThreadSetKeySwitchGuardTime 687 */ 688 uint16_t otThreadGetKeySwitchGuardTime(otInstance *aInstance); 689 690 /** 691 * Sets the thrKeySwitchGuardTime (in hours). 692 * 693 * @note This API is reserved for testing and demo purposes only. Changing settings with 694 * this API will render a production application non-compliant with the Thread Specification. 695 * 696 * @param[in] aInstance A pointer to an OpenThread instance. 697 * @param[in] aKeySwitchGuardTime The thrKeySwitchGuardTime value (in hours). 698 * 699 * @sa otThreadGetKeySwitchGuardTime 700 */ 701 void otThreadSetKeySwitchGuardTime(otInstance *aInstance, uint16_t aKeySwitchGuardTime); 702 703 /** 704 * Detach from the Thread network. 705 * 706 * @param[in] aInstance A pointer to an OpenThread instance. 707 * 708 * @retval OT_ERROR_NONE Successfully detached from the Thread network. 709 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 710 */ 711 otError otThreadBecomeDetached(otInstance *aInstance); 712 713 /** 714 * Attempt to reattach as a child. 715 * 716 * @note This API is reserved for testing and demo purposes only. Changing settings with 717 * this API will render a production application non-compliant with the Thread Specification. 718 * 719 * @param[in] aInstance A pointer to an OpenThread instance. 720 * 721 * @retval OT_ERROR_NONE Successfully begin attempt to become a child. 722 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 723 */ 724 otError otThreadBecomeChild(otInstance *aInstance); 725 726 /** 727 * Gets the next neighbor information. It is used to go through the entries of 728 * the neighbor table. 729 * 730 * @param[in] aInstance A pointer to an OpenThread instance. 731 * @param[in,out] aIterator A pointer to the iterator context. To get the first neighbor entry 732 it should be set to OT_NEIGHBOR_INFO_ITERATOR_INIT. 733 * @param[out] aInfo A pointer to the neighbor information. 734 * 735 * @retval OT_ERROR_NONE Successfully found the next neighbor entry in table. 736 * @retval OT_ERROR_NOT_FOUND No subsequent neighbor entry exists in the table. 737 * @retval OT_ERROR_INVALID_ARGS @p aIterator or @p aInfo was NULL. 738 */ 739 otError otThreadGetNextNeighborInfo(otInstance *aInstance, otNeighborInfoIterator *aIterator, otNeighborInfo *aInfo); 740 741 /** 742 * Get the device role. 743 * 744 * @param[in] aInstance A pointer to an OpenThread instance. 745 * 746 * @retval OT_DEVICE_ROLE_DISABLED The Thread stack is disabled. 747 * @retval OT_DEVICE_ROLE_DETACHED The device is not currently participating in a Thread network/partition. 748 * @retval OT_DEVICE_ROLE_CHILD The device is currently operating as a Thread Child. 749 * @retval OT_DEVICE_ROLE_ROUTER The device is currently operating as a Thread Router. 750 * @retval OT_DEVICE_ROLE_LEADER The device is currently operating as a Thread Leader. 751 */ 752 otDeviceRole otThreadGetDeviceRole(otInstance *aInstance); 753 754 /** 755 * Convert the device role to human-readable string. 756 * 757 * @param[in] aRole The device role to convert. 758 * 759 * @returns A string representing @p aRole. 760 */ 761 const char *otThreadDeviceRoleToString(otDeviceRole aRole); 762 763 /** 764 * Get the Thread Leader Data. 765 * 766 * @param[in] aInstance A pointer to an OpenThread instance. 767 * @param[out] aLeaderData A pointer to where the leader data is placed. 768 * 769 * @retval OT_ERROR_NONE Successfully retrieved the leader data. 770 * @retval OT_ERROR_DETACHED Not currently attached. 771 */ 772 otError otThreadGetLeaderData(otInstance *aInstance, otLeaderData *aLeaderData); 773 774 /** 775 * Get the Leader's Router ID. 776 * 777 * @param[in] aInstance A pointer to an OpenThread instance. 778 * 779 * @returns The Leader's Router ID. 780 */ 781 uint8_t otThreadGetLeaderRouterId(otInstance *aInstance); 782 783 /** 784 * Get the Leader's Weight. 785 * 786 * @param[in] aInstance A pointer to an OpenThread instance. 787 * 788 * @returns The Leader's Weight. 789 */ 790 uint8_t otThreadGetLeaderWeight(otInstance *aInstance); 791 792 /** 793 * Get the Partition ID. 794 * 795 * @param[in] aInstance A pointer to an OpenThread instance. 796 * 797 * @returns The Partition ID. 798 */ 799 uint32_t otThreadGetPartitionId(otInstance *aInstance); 800 801 /** 802 * Get the RLOC16. 803 * 804 * @param[in] aInstance A pointer to an OpenThread instance. 805 * 806 * @returns The RLOC16. 807 */ 808 uint16_t otThreadGetRloc16(otInstance *aInstance); 809 810 /** 811 * The function retrieves diagnostic information for a Thread Router as parent. 812 * 813 * @param[in] aInstance A pointer to an OpenThread instance. 814 * @param[out] aParentInfo A pointer to where the parent router information is placed. 815 */ 816 otError otThreadGetParentInfo(otInstance *aInstance, otRouterInfo *aParentInfo); 817 818 /** 819 * The function retrieves the average RSSI for the Thread Parent. 820 * 821 * @param[in] aInstance A pointer to an OpenThread instance. 822 * @param[out] aParentRssi A pointer to where the parent RSSI should be placed. 823 */ 824 otError otThreadGetParentAverageRssi(otInstance *aInstance, int8_t *aParentRssi); 825 826 /** 827 * The function retrieves the RSSI of the last packet from the Thread Parent. 828 * 829 * @param[in] aInstance A pointer to an OpenThread instance. 830 * @param[out] aLastRssi A pointer to where the last RSSI should be placed. 831 * 832 * @retval OT_ERROR_NONE Successfully retrieved the RSSI data. 833 * @retval OT_ERROR_FAILED Unable to get RSSI data. 834 * @retval OT_ERROR_INVALID_ARGS @p aLastRssi is NULL. 835 */ 836 otError otThreadGetParentLastRssi(otInstance *aInstance, int8_t *aLastRssi); 837 838 /** 839 * Starts the process for child to search for a better parent while staying attached to its current parent. 840 * 841 * Must be used when device is attached as a child. 842 * 843 * @retval OT_ERROR_NONE Successfully started the process to search for a better parent. 844 * @retval OT_ERROR_INVALID_STATE Device role is not child. 845 */ 846 otError otThreadSearchForBetterParent(otInstance *aInstance); 847 848 /** 849 * Gets the IPv6 counters. 850 * 851 * @param[in] aInstance A pointer to an OpenThread instance. 852 * 853 * @returns A pointer to the IPv6 counters. 854 */ 855 const otIpCounters *otThreadGetIp6Counters(otInstance *aInstance); 856 857 /** 858 * Resets the IPv6 counters. 859 * 860 * @param[in] aInstance A pointer to an OpenThread instance. 861 */ 862 void otThreadResetIp6Counters(otInstance *aInstance); 863 864 /** 865 * Gets the time-in-queue histogram for messages in the TX queue. 866 * 867 * Requires `OPENTHREAD_CONFIG_TX_QUEUE_STATISTICS_ENABLE`. 868 * 869 * Histogram of the time-in-queue of messages in the transmit queue is collected. The time-in-queue is tracked for 870 * direct transmissions only and is measured as the duration from when a message is added to the transmit queue until 871 * it is passed to the MAC layer for transmission or dropped. 872 * 873 * The histogram is returned as an array of `uint32_t` values with `aNumBins` entries. The first entry in the array 874 * (at index 0) represents the number of messages with a time-in-queue less than `aBinInterval`. The second entry 875 * represents the number of messages with a time-in-queue greater than or equal to `aBinInterval`, but less than 876 * `2 * aBinInterval`. And so on. The last entry represents the number of messages with time-in-queue greater than or 877 * equal to `(aNumBins - 1) * aBinInterval`. 878 * 879 * The collected statistics can be reset by calling `otThreadResetTimeInQueueStat()`. The histogram information is 880 * collected since the OpenThread instance was initialized or since the last time statistics collection was reset by 881 * calling the `otThreadResetTimeInQueueStat()`. 882 * 883 * Pointers @p aNumBins and @p aBinInterval MUST NOT be NULL. 884 * 885 * @param[in] aInstance A pointer to an OpenThread instance. 886 * @param[out] aNumBins Pointer to return the number of bins in histogram (array length). 887 * @param[out] aBinInterval Pointer to return the histogram bin interval length in milliseconds. 888 * 889 * @returns A pointer to an array of @p aNumBins entries representing the collected histogram info. 890 */ 891 const uint32_t *otThreadGetTimeInQueueHistogram(otInstance *aInstance, uint16_t *aNumBins, uint32_t *aBinInterval); 892 893 /** 894 * Gets the maximum time-in-queue for messages in the TX queue. 895 * 896 * Requires `OPENTHREAD_CONFIG_TX_QUEUE_STATISTICS_ENABLE`. 897 * 898 * The time-in-queue is tracked for direct transmissions only and is measured as the duration from when a message is 899 * added to the transmit queue until it is passed to the MAC layer for transmission or dropped. 900 * 901 * The collected statistics can be reset by calling `otThreadResetTimeInQueueStat()`. 902 * 903 * @param[in] aInstance A pointer to an OpenThread instance. 904 * 905 * @returns The maximum time-in-queue in milliseconds for all messages in the TX queue (so far). 906 */ 907 uint32_t otThreadGetMaxTimeInQueue(otInstance *aInstance); 908 909 /** 910 * Resets the TX queue time-in-queue statistics. 911 * 912 * Requires `OPENTHREAD_CONFIG_TX_QUEUE_STATISTICS_ENABLE`. 913 * 914 * @param[in] aInstance A pointer to an OpenThread instance. 915 */ 916 void otThreadResetTimeInQueueStat(otInstance *aInstance); 917 918 /** 919 * Gets the Thread MLE counters. 920 * 921 * @param[in] aInstance A pointer to an OpenThread instance. 922 * 923 * @returns A pointer to the Thread MLE counters. 924 */ 925 const otMleCounters *otThreadGetMleCounters(otInstance *aInstance); 926 927 /** 928 * Resets the Thread MLE counters. 929 * 930 * @param[in] aInstance A pointer to an OpenThread instance. 931 */ 932 void otThreadResetMleCounters(otInstance *aInstance); 933 934 /** 935 * Gets the current attach duration (number of seconds since the device last attached). 936 * 937 * Requires the `OPENTHREAD_CONFIG_UPTIME_ENABLE` feature. 938 * 939 * If the device is not currently attached, zero will be returned. 940 * 941 * Unlike the role-tracking variables in `otMleCounters`, which track the cumulative time the device is in each role, 942 * this function tracks the time since the last successful attachment, indicating how long the device has been 943 * connected to the Thread mesh (regardless of its role, whether acting as a child, router, or leader). 944 * 945 * @param[in] aInstance A pointer to an OpenThread instance. 946 * 947 * @returns The number of seconds since last attached. 948 */ 949 uint32_t otThreadGetCurrentAttachDuration(otInstance *aInstance); 950 951 /** 952 * Pointer is called every time an MLE Parent Response message is received. 953 * 954 * This is used in `otThreadRegisterParentResponseCallback()`. 955 * 956 * @param[in] aInfo A pointer to a location on stack holding the stats data. 957 * @param[in] aContext A pointer to callback client-specific context. 958 */ 959 typedef void (*otThreadParentResponseCallback)(otThreadParentResponseInfo *aInfo, void *aContext); 960 961 /** 962 * Registers a callback to receive MLE Parent Response data. 963 * 964 * Requires `OPENTHREAD_CONFIG_MLE_PARENT_RESPONSE_CALLBACK_API_ENABLE`. 965 * 966 * @param[in] aInstance A pointer to an OpenThread instance. 967 * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Parent Response message. 968 * @param[in] aContext A pointer to callback client-specific context. 969 */ 970 void otThreadRegisterParentResponseCallback(otInstance *aInstance, 971 otThreadParentResponseCallback aCallback, 972 void *aContext); 973 974 /** 975 * Represents the Thread Discovery Request data. 976 */ 977 typedef struct otThreadDiscoveryRequestInfo 978 { 979 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address of the requester 980 uint8_t mVersion : 4; ///< Thread version. 981 bool mIsJoiner : 1; ///< Whether is from joiner. 982 } otThreadDiscoveryRequestInfo; 983 984 /** 985 * Pointer is called every time an MLE Discovery Request message is received. 986 * 987 * @param[in] aInfo A pointer to the Discovery Request info data. 988 * @param[in] aContext A pointer to callback application-specific context. 989 */ 990 typedef void (*otThreadDiscoveryRequestCallback)(const otThreadDiscoveryRequestInfo *aInfo, void *aContext); 991 992 /** 993 * Sets a callback to receive MLE Discovery Request data. 994 * 995 * @param[in] aInstance A pointer to an OpenThread instance. 996 * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Discovery Request message. 997 * @param[in] aContext A pointer to callback application-specific context. 998 */ 999 void otThreadSetDiscoveryRequestCallback(otInstance *aInstance, 1000 otThreadDiscoveryRequestCallback aCallback, 1001 void *aContext); 1002 1003 /** 1004 * Pointer type defines the callback to notify the outcome of a `otThreadLocateAnycastDestination()` 1005 * request. 1006 * 1007 * @param[in] aContext A pointer to an arbitrary context (provided when callback is registered). 1008 * @param[in] aError The error when handling the request. OT_ERROR_NONE indicates success. 1009 * OT_ERROR_RESPONSE_TIMEOUT indicates a destination could not be found. 1010 * OT_ERROR_ABORT indicates the request was aborted. 1011 * @param[in] aMeshLocalAddress A pointer to the mesh-local EID of the closest destination of the anycast address 1012 * when @p aError is OT_ERROR_NONE, NULL otherwise. 1013 * @param[in] aRloc16 The RLOC16 of the destination if found, otherwise invalid RLOC16 (0xfffe). 1014 */ 1015 typedef void (*otThreadAnycastLocatorCallback)(void *aContext, 1016 otError aError, 1017 const otIp6Address *aMeshLocalAddress, 1018 uint16_t aRloc16); 1019 1020 /** 1021 * Requests the closest destination of a given anycast address to be located. 1022 * 1023 * Is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. 1024 * 1025 * If a previous request is ongoing, a subsequent call to this function will cancel and replace the earlier request. 1026 * 1027 * @param[in] aInstance A pointer to an OpenThread instance. 1028 * @param[in] aAnycastAddress The anycast address to locate. MUST NOT be NULL. 1029 * @param[in] aCallback The callback function to report the result. 1030 * @param[in] aContext An arbitrary context used with @p aCallback. 1031 * 1032 * @retval OT_ERROR_NONE The request started successfully. @p aCallback will be invoked to report the result. 1033 * @retval OT_ERROR_INVALID_ARGS The @p aAnycastAddress is not a valid anycast address or @p aCallback is NULL. 1034 * @retval OT_ERROR_NO_BUFS Out of buffer to prepare and send the request message. 1035 */ 1036 otError otThreadLocateAnycastDestination(otInstance *aInstance, 1037 const otIp6Address *aAnycastAddress, 1038 otThreadAnycastLocatorCallback aCallback, 1039 void *aContext); 1040 1041 /** 1042 * Indicates whether an anycast locate request is currently in progress. 1043 * 1044 * Is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. 1045 * 1046 * @param[in] aInstance A pointer to an OpenThread instance. 1047 * 1048 * @returns TRUE if an anycast locate request is currently in progress, FALSE otherwise. 1049 */ 1050 bool otThreadIsAnycastLocateInProgress(otInstance *aInstance); 1051 1052 /** 1053 * Sends a Proactive Address Notification (ADDR_NTF.ntf) message. 1054 * 1055 * Is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 1056 * 1057 * @param[in] aInstance A pointer to an OpenThread instance. 1058 * @param[in] aDestination The destination to send the ADDR_NTF.ntf message. 1059 * @param[in] aTarget The target address of the ADDR_NTF.ntf message. 1060 * @param[in] aMlIid The ML-IID of the ADDR_NTF.ntf message. 1061 */ 1062 void otThreadSendAddressNotification(otInstance *aInstance, 1063 otIp6Address *aDestination, 1064 otIp6Address *aTarget, 1065 otIp6InterfaceIdentifier *aMlIid); 1066 1067 /** 1068 * Sends a Proactive Backbone Notification (PRO_BB.ntf) message on the Backbone link. 1069 * 1070 * Is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 1071 * 1072 * @param[in] aInstance A pointer to an OpenThread instance. 1073 * @param[in] aTarget The target address of the PRO_BB.ntf message. 1074 * @param[in] aMlIid The ML-IID of the PRO_BB.ntf message. 1075 * @param[in] aTimeSinceLastTransaction Time since last transaction (in seconds). 1076 * 1077 * @retval OT_ERROR_NONE Successfully sent PRO_BB.ntf on backbone link. 1078 * @retval OT_ERROR_NO_BUFS If insufficient message buffers available. 1079 */ 1080 otError otThreadSendProactiveBackboneNotification(otInstance *aInstance, 1081 otIp6Address *aTarget, 1082 otIp6InterfaceIdentifier *aMlIid, 1083 uint32_t aTimeSinceLastTransaction); 1084 1085 /** 1086 * Notifies other nodes in the network (if any) and then stops Thread protocol operation. 1087 * 1088 * It sends an Address Release if it's a router, or sets its child timeout to 0 if it's a child. 1089 * 1090 * @param[in] aInstance A pointer to an OpenThread instance. 1091 * @param[in] aCallback A pointer to a function that is called upon finishing detaching. 1092 * @param[in] aContext A pointer to callback application-specific context. 1093 * 1094 * @retval OT_ERROR_NONE Successfully started detaching. 1095 * @retval OT_ERROR_BUSY Detaching is already in progress. 1096 */ 1097 otError otThreadDetachGracefully(otInstance *aInstance, otDetachGracefullyCallback aCallback, void *aContext); 1098 1099 #define OT_DURATION_STRING_SIZE 21 ///< Recommended size for string representation of `uint32_t` duration in seconds. 1100 1101 /** 1102 * Converts an `uint32_t` duration (in seconds) to a human-readable string. 1103 * 1104 * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. 1105 * 1106 * The string follows the format "<hh>:<mm>:<ss>" for hours, minutes, seconds (if duration is shorter than one day) or 1107 * "<dd>d.<hh>:<mm>:<ss>" (if longer than a day). 1108 * 1109 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 1110 * but the outputted string is always null-terminated. 1111 * 1112 * Is intended for use with `mAge` or `mConnectionTime` in `otNeighborInfo` or `otChildInfo` structures. 1113 * 1114 * @param[in] aDuration A duration interval in seconds. 1115 * @param[out] aBuffer A pointer to a char array to output the string. 1116 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_DURATION_STRING_SIZE`. 1117 */ 1118 void otConvertDurationInSecondsToString(uint32_t aDuration, char *aBuffer, uint16_t aSize); 1119 1120 /** 1121 * Sets the store frame counter ahead. 1122 * 1123 * Requires `OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE` to be enabled. 1124 * 1125 * The OpenThread stack stores the MLE and MAC security frame counter values in non-volatile storage, 1126 * ensuring they persist across device resets. These saved values are set to be ahead of their current 1127 * values by the "frame counter ahead" value. 1128 * 1129 * @param[in] aInstance A pointer to an OpenThread instance. 1130 * @param[in] aStoreFrameCounterAhead The store frame counter ahead to set. 1131 */ 1132 void otThreadSetStoreFrameCounterAhead(otInstance *aInstance, uint32_t aStoreFrameCounterAhead); 1133 1134 /** 1135 * Gets the store frame counter ahead. 1136 * 1137 * Requires `OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE` to be enabled. 1138 * 1139 * @param[in] aInstance A pointer to an OpenThread instance. 1140 * 1141 * @returns The current store frame counter ahead. 1142 */ 1143 uint32_t otThreadGetStoreFrameCounterAhead(otInstance *aInstance); 1144 1145 /** 1146 * Attempts to wake a Wake-up End Device. 1147 * 1148 * Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` to be enabled. 1149 * 1150 * The wake-up starts with transmitting a wake-up frame sequence to the Wake-up End Device. 1151 * During the wake-up sequence, and for a short time after the last wake-up frame is sent, the Wake-up Coordinator keeps 1152 * its receiver on to be able to receive an initial mesh link establishment message from the WED. 1153 * 1154 * @warning The functionality implemented by this function is still in the design phase. 1155 * Consequently, the prototype and semantics of this function are subject to change. 1156 * 1157 * @param[in] aInstance A pointer to an OpenThread instance. 1158 * @param[in] aWedAddress The extended address of the Wake-up End Device. 1159 * @param[in] aWakeupIntervalUs An interval between consecutive wake-up frames (in microseconds). 1160 * @param[in] aWakeupDurationMs Duration of the wake-up sequence (in milliseconds). 1161 * @param[in] aCallback A pointer to function that is called when the wake-up succeeds or fails. 1162 * @param[in] aCallbackContext A pointer to callback application-specific context. 1163 * 1164 * @retval OT_ERROR_NONE Successfully started the wake-up. 1165 * @retval OT_ERROR_INVALID_STATE Another attachment request is still in progress. 1166 * @retval OT_ERROR_INVALID_ARGS The wake-up interval or duration are invalid. 1167 */ 1168 otError otThreadWakeup(otInstance *aInstance, 1169 const otExtAddress *aWedAddress, 1170 uint16_t aWakeupIntervalUs, 1171 uint16_t aWakeupDurationMs, 1172 otWakeupCallback aCallback, 1173 void *aCallbackContext); 1174 1175 /** 1176 * @} 1177 */ 1178 1179 #ifdef __cplusplus 1180 } // extern "C" 1181 #endif 1182 1183 #endif // OPENTHREAD_THREAD_H_ 1184