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 IEEE 802.15.4 Link Layer API. 33 */ 34 35 #ifndef OPENTHREAD_LINK_H_ 36 #define OPENTHREAD_LINK_H_ 37 38 #include <openthread/commissioner.h> 39 #include <openthread/dataset.h> 40 #include <openthread/platform/radio.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-link-link 48 * 49 * @brief 50 * This module includes functions that control link-layer configuration. 51 * 52 * @{ 53 */ 54 #define OT_US_PER_TEN_SYMBOLS OT_RADIO_TEN_SYMBOLS_TIME ///< Time for 10 symbols in units of microseconds 55 56 /** 57 * Used to indicate no fixed received signal strength was set 58 */ 59 #define OT_MAC_FILTER_FIXED_RSS_DISABLED 127 60 61 #define OT_MAC_FILTER_ITERATOR_INIT 0 ///< Initializer for otMacFilterIterator. 62 63 typedef uint8_t otMacFilterIterator; ///< Used to iterate through mac filter entries. 64 65 /** 66 * Defines address mode of the mac filter. 67 */ 68 typedef enum otMacFilterAddressMode 69 { 70 OT_MAC_FILTER_ADDRESS_MODE_DISABLED, ///< Address filter is disabled. 71 OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST, ///< Allowlist address filter mode is enabled. 72 OT_MAC_FILTER_ADDRESS_MODE_DENYLIST, ///< Denylist address filter mode is enabled. 73 } otMacFilterAddressMode; 74 75 /** 76 * Represents a Mac Filter entry. 77 */ 78 typedef struct otMacFilterEntry 79 { 80 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address 81 int8_t mRssIn; ///< Received signal strength 82 } otMacFilterEntry; 83 84 /** 85 * Represents the MAC layer counters. 86 */ 87 typedef struct otMacCounters 88 { 89 /** 90 * The total number of unique MAC frame transmission requests. 91 * 92 * Note that this counter is incremented for each MAC transmission request only by one, 93 * regardless of the amount of CCA failures, CSMA-CA attempts, or retransmissions. 94 * 95 * This increment rule applies to the following counters: 96 * - @p mTxUnicast 97 * - @p mTxBroadcast 98 * - @p mTxAckRequested 99 * - @p mTxNoAckRequested 100 * - @p mTxData 101 * - @p mTxDataPoll 102 * - @p mTxBeacon 103 * - @p mTxBeaconRequest 104 * - @p mTxOther 105 * - @p mTxErrAbort 106 * - @p mTxErrBusyChannel 107 * 108 * The following equations are valid: 109 * - @p mTxTotal = @p mTxUnicast + @p mTxBroadcast 110 * - @p mTxTotal = @p mTxAckRequested + @p mTxNoAckRequested 111 * - @p mTxTotal = @p mTxData + @p mTxDataPoll + @p mTxBeacon + @p mTxBeaconRequest + @p mTxOther 112 */ 113 uint32_t mTxTotal; 114 115 /** 116 * The total number of unique unicast MAC frame transmission requests. 117 */ 118 uint32_t mTxUnicast; 119 120 /** 121 * The total number of unique broadcast MAC frame transmission requests. 122 */ 123 uint32_t mTxBroadcast; 124 125 /** 126 * The total number of unique MAC frame transmission requests with requested acknowledgment. 127 */ 128 uint32_t mTxAckRequested; 129 130 /** 131 * The total number of unique MAC frame transmission requests that were acked. 132 */ 133 uint32_t mTxAcked; 134 135 /** 136 * The total number of unique MAC frame transmission requests without requested acknowledgment. 137 */ 138 uint32_t mTxNoAckRequested; 139 140 /** 141 * The total number of unique MAC Data frame transmission requests. 142 */ 143 uint32_t mTxData; 144 145 /** 146 * The total number of unique MAC Data Poll frame transmission requests. 147 */ 148 uint32_t mTxDataPoll; 149 150 /** 151 * The total number of unique MAC Beacon frame transmission requests. 152 */ 153 uint32_t mTxBeacon; 154 155 /** 156 * The total number of unique MAC Beacon Request frame transmission requests. 157 */ 158 uint32_t mTxBeaconRequest; 159 160 /** 161 * The total number of unique other MAC frame transmission requests. 162 * 163 * This counter is currently used for counting out-of-band frames. 164 */ 165 uint32_t mTxOther; 166 167 /** 168 * The total number of MAC retransmission attempts. 169 * 170 * Note that this counter is incremented by one for each retransmission attempt that may be 171 * triggered by lack of acknowledgement, CSMA/CA failure, or other type of transmission error. 172 * The @p mTxRetry counter is incremented both for unicast and broadcast MAC frames. 173 * 174 * Modify the following configuration parameters to control the amount of retransmissions in the system: 175 * 176 * - OPENTHREAD_CONFIG_MAC_DEFAULT_MAX_FRAME_RETRIES_DIRECT 177 * - OPENTHREAD_CONFIG_MAC_DEFAULT_MAX_FRAME_RETRIES_INDIRECT 178 * - OPENTHREAD_CONFIG_MAC_TX_NUM_BCAST 179 * - OPENTHREAD_CONFIG_MAC_MAX_CSMA_BACKOFFS_DIRECT 180 * - OPENTHREAD_CONFIG_MAC_MAX_CSMA_BACKOFFS_INDIRECT 181 * 182 * Currently, this counter is invalid if the platform's radio driver capability includes 183 * @ref OT_RADIO_CAPS_TRANSMIT_RETRIES. 184 */ 185 uint32_t mTxRetry; 186 187 /** 188 * The total number of unique MAC transmission packets that meet maximal retry limit for direct packets. 189 */ 190 uint32_t mTxDirectMaxRetryExpiry; 191 192 /** 193 * The total number of unique MAC transmission packets that meet maximal retry limit for indirect packets. 194 */ 195 uint32_t mTxIndirectMaxRetryExpiry; 196 197 /** 198 * The total number of CCA failures. 199 * 200 * The meaning of this counter can be different and it depends on the platform's radio driver capabilities. 201 * 202 * If @ref OT_RADIO_CAPS_CSMA_BACKOFF is enabled, this counter represents the total number of full CSMA/CA 203 * failed attempts and it is incremented by one also for each retransmission (in case of a CSMA/CA fail). 204 * 205 * If @ref OT_RADIO_CAPS_TRANSMIT_RETRIES is enabled, this counter represents the total number of full CSMA/CA 206 * failed attempts and it is incremented by one for each individual data frame request (regardless of the 207 * amount of retransmissions). 208 */ 209 uint32_t mTxErrCca; 210 211 /** 212 * The total number of unique MAC transmission request failures cause by an abort error. 213 */ 214 uint32_t mTxErrAbort; 215 216 /** 217 * The total number of unique MAC transmission requests failures caused by a busy channel (a CSMA/CA fail). 218 */ 219 uint32_t mTxErrBusyChannel; 220 221 /** 222 * The total number of received frames. 223 * 224 * This counter counts all frames reported by the platform's radio driver, including frames 225 * that were dropped, for example because of an FCS error. 226 */ 227 uint32_t mRxTotal; 228 229 /** 230 * The total number of unicast frames received. 231 */ 232 uint32_t mRxUnicast; 233 234 /** 235 * The total number of broadcast frames received. 236 */ 237 uint32_t mRxBroadcast; 238 239 /** 240 * The total number of MAC Data frames received. 241 */ 242 uint32_t mRxData; 243 244 /** 245 * The total number of MAC Data Poll frames received. 246 */ 247 uint32_t mRxDataPoll; 248 249 /** 250 * The total number of MAC Beacon frames received. 251 */ 252 uint32_t mRxBeacon; 253 254 /** 255 * The total number of MAC Beacon Request frames received. 256 */ 257 uint32_t mRxBeaconRequest; 258 259 /** 260 * The total number of other types of frames received. 261 */ 262 uint32_t mRxOther; 263 264 /** 265 * The total number of frames dropped by MAC Filter module, for example received from denylisted node. 266 */ 267 uint32_t mRxAddressFiltered; 268 269 /** 270 * The total number of frames dropped by destination address check, for example received frame for other node. 271 */ 272 uint32_t mRxDestAddrFiltered; 273 274 /** 275 * The total number of frames dropped due to duplication, that is when the frame has been already received. 276 * 277 * This counter may be incremented, for example when ACK frame generated by the receiver hasn't reached 278 * transmitter node which performed retransmission. 279 */ 280 uint32_t mRxDuplicated; 281 282 /** 283 * The total number of frames dropped because of missing or malformed content. 284 */ 285 uint32_t mRxErrNoFrame; 286 287 /** 288 * The total number of frames dropped due to unknown neighbor. 289 */ 290 uint32_t mRxErrUnknownNeighbor; 291 292 /** 293 * The total number of frames dropped due to invalid source address. 294 */ 295 uint32_t mRxErrInvalidSrcAddr; 296 297 /** 298 * The total number of frames dropped due to security error. 299 * 300 * This counter may be incremented, for example when lower than expected Frame Counter is used 301 * to encrypt the frame. 302 */ 303 uint32_t mRxErrSec; 304 305 /** 306 * The total number of frames dropped due to invalid FCS. 307 */ 308 uint32_t mRxErrFcs; 309 310 /** 311 * The total number of frames dropped due to other error. 312 */ 313 uint32_t mRxErrOther; 314 } otMacCounters; 315 316 /** 317 * Represents a received IEEE 802.15.4 Beacon. 318 */ 319 typedef struct otActiveScanResult 320 { 321 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address 322 otNetworkName mNetworkName; ///< Thread Network Name 323 otExtendedPanId mExtendedPanId; ///< Thread Extended PAN ID 324 otSteeringData mSteeringData; ///< Steering Data 325 uint16_t mPanId; ///< IEEE 802.15.4 PAN ID 326 uint16_t mJoinerUdpPort; ///< Joiner UDP Port 327 uint8_t mChannel; ///< IEEE 802.15.4 Channel 328 int8_t mRssi; ///< RSSI (dBm) 329 uint8_t mLqi; ///< LQI 330 unsigned int mVersion : 4; ///< Version 331 bool mIsNative : 1; ///< Native Commissioner flag 332 bool mDiscover : 1; ///< Result from MLE Discovery 333 334 // Applicable/Required only when beacon payload parsing feature 335 // (`OPENTHREAD_CONFIG_MAC_BEACON_PAYLOAD_PARSING_ENABLE`) is enabled. 336 bool mIsJoinable : 1; ///< Joining Permitted flag 337 } otActiveScanResult; 338 339 /** 340 * Represents an energy scan result. 341 */ 342 typedef struct otEnergyScanResult 343 { 344 uint8_t mChannel; ///< IEEE 802.15.4 Channel 345 int8_t mMaxRssi; ///< The max RSSI (dBm) 346 } otEnergyScanResult; 347 348 /** 349 * Pointer is called during an IEEE 802.15.4 Active Scan when an IEEE 802.15.4 Beacon is received or 350 * the scan completes. 351 * 352 * @param[in] aResult A valid pointer to the beacon information or NULL when the active scan completes. 353 * @param[in] aContext A pointer to application-specific context. 354 */ 355 typedef void (*otHandleActiveScanResult)(otActiveScanResult *aResult, void *aContext); 356 357 /** 358 * Starts an IEEE 802.15.4 Active Scan 359 * 360 * @param[in] aInstance A pointer to an OpenThread instance. 361 * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). 362 * @param[in] aScanDuration The time in milliseconds to spend scanning each channel. 363 * @param[in] aCallback A pointer to a function called on receiving a beacon or scan completes. 364 * @param[in] aCallbackContext A pointer to application-specific context. 365 * 366 * @retval OT_ERROR_NONE Accepted the Active Scan request. 367 * @retval OT_ERROR_BUSY Already performing an Active Scan. 368 */ 369 otError otLinkActiveScan(otInstance *aInstance, 370 uint32_t aScanChannels, 371 uint16_t aScanDuration, 372 otHandleActiveScanResult aCallback, 373 void *aCallbackContext); 374 375 /** 376 * Indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress. 377 * 378 * @param[in] aInstance A pointer to an OpenThread instance. 379 * 380 * @returns true if an IEEE 802.15.4 Active Scan is in progress, false otherwise. 381 */ 382 bool otLinkIsActiveScanInProgress(otInstance *aInstance); 383 384 /** 385 * Pointer is called during an IEEE 802.15.4 Energy Scan when the result for a channel is ready or the 386 * scan completes. 387 * 388 * @param[in] aResult A valid pointer to the energy scan result information or NULL when the energy scan completes. 389 * @param[in] aContext A pointer to application-specific context. 390 */ 391 typedef void (*otHandleEnergyScanResult)(otEnergyScanResult *aResult, void *aContext); 392 393 /** 394 * Starts an IEEE 802.15.4 Energy Scan 395 * 396 * @param[in] aInstance A pointer to an OpenThread instance. 397 * @param[in] aScanChannels A bit vector indicating on which channels to perform energy scan. 398 * @param[in] aScanDuration The time in milliseconds to spend scanning each channel. 399 * @param[in] aCallback A pointer to a function called to pass on scan result on indicate scan completion. 400 * @param[in] aCallbackContext A pointer to application-specific context. 401 * 402 * @retval OT_ERROR_NONE Accepted the Energy Scan request. 403 * @retval OT_ERROR_BUSY Could not start the energy scan. 404 */ 405 otError otLinkEnergyScan(otInstance *aInstance, 406 uint32_t aScanChannels, 407 uint16_t aScanDuration, 408 otHandleEnergyScanResult aCallback, 409 void *aCallbackContext); 410 411 /** 412 * Indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress. 413 * 414 * @param[in] aInstance A pointer to an OpenThread instance. 415 * 416 * @returns true if an IEEE 802.15.4 Energy Scan is in progress, false otherwise. 417 */ 418 bool otLinkIsEnergyScanInProgress(otInstance *aInstance); 419 420 /** 421 * Enqueues an IEEE 802.15.4 Data Request message for transmission. 422 * 423 * @param[in] aInstance A pointer to an OpenThread instance. 424 * 425 * @retval OT_ERROR_NONE Successfully enqueued an IEEE 802.15.4 Data Request message. 426 * @retval OT_ERROR_INVALID_STATE Device is not in rx-off-when-idle mode. 427 * @retval OT_ERROR_NO_BUFS Insufficient message buffers available. 428 */ 429 otError otLinkSendDataRequest(otInstance *aInstance); 430 431 /** 432 * Indicates whether or not an IEEE 802.15.4 MAC is in the transmit state. 433 * 434 * MAC module is in the transmit state during CSMA/CA procedure, CCA, Data, Beacon or Data Request frame transmission 435 * and receiving an ACK of a transmitted frame. MAC module is not in the transmit state during transmission of an ACK 436 * frame or a Beacon Request frame. 437 * 438 * @param[in] aInstance A pointer to an OpenThread instance. 439 * 440 * @returns true if an IEEE 802.15.4 MAC is in the transmit state, false otherwise. 441 */ 442 bool otLinkIsInTransmitState(otInstance *aInstance); 443 444 /** 445 * Get the IEEE 802.15.4 channel. 446 * 447 * @param[in] aInstance A pointer to an OpenThread instance. 448 * 449 * @returns The IEEE 802.15.4 channel. 450 * 451 * @sa otLinkSetChannel 452 */ 453 uint8_t otLinkGetChannel(otInstance *aInstance); 454 455 /** 456 * Set the IEEE 802.15.4 channel 457 * 458 * Succeeds only when Thread protocols are disabled. A successful call to this function invalidates the 459 * Active and Pending Operational Datasets in non-volatile memory. 460 * 461 * @param[in] aInstance A pointer to an OpenThread instance. 462 * @param[in] aChannel The IEEE 802.15.4 channel. 463 * 464 * @retval OT_ERROR_NONE Successfully set the channel. 465 * @retval OT_ERROR_INVALID_ARGS If @p aChannel is not in the range [11, 26] or is not in the supported channel mask. 466 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 467 * 468 * @sa otLinkGetChannel 469 */ 470 otError otLinkSetChannel(otInstance *aInstance, uint8_t aChannel); 471 472 /** 473 * Get the supported channel mask of MAC layer. 474 * 475 * @param[in] aInstance A pointer to an OpenThread instance. 476 * 477 * @returns The supported channel mask as `uint32_t` with bit 0 (lsb) mapping to channel 0, bit 1 to channel 1, so on. 478 */ 479 uint32_t otLinkGetSupportedChannelMask(otInstance *aInstance); 480 481 /** 482 * Set the supported channel mask of MAC layer. 483 * 484 * Succeeds only when Thread protocols are disabled. 485 * 486 * @param[in] aInstance A pointer to an OpenThread instance. 487 * @param[in] aChannelMask The supported channel mask (bit 0 or lsb mapping to channel 0, and so on). 488 * 489 * @retval OT_ERROR_NONE Successfully set the supported channel mask. 490 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 491 */ 492 otError otLinkSetSupportedChannelMask(otInstance *aInstance, uint32_t aChannelMask); 493 494 /** 495 * Gets the IEEE 802.15.4 Extended Address. 496 * 497 * @param[in] aInstance A pointer to an OpenThread instance. 498 * 499 * @returns A pointer to the IEEE 802.15.4 Extended Address. 500 */ 501 const otExtAddress *otLinkGetExtendedAddress(otInstance *aInstance); 502 503 /** 504 * Sets the IEEE 802.15.4 Extended Address. 505 * 506 * @note Only succeeds when Thread protocols are disabled. 507 * 508 * @param[in] aInstance A pointer to an OpenThread instance. 509 * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. 510 * 511 * @retval OT_ERROR_NONE Successfully set the IEEE 802.15.4 Extended Address. 512 * @retval OT_ERROR_INVALID_ARGS @p aExtAddress was NULL. 513 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 514 */ 515 otError otLinkSetExtendedAddress(otInstance *aInstance, const otExtAddress *aExtAddress); 516 517 /** 518 * Get the factory-assigned IEEE EUI-64. 519 * 520 * @param[in] aInstance A pointer to the OpenThread instance. 521 * @param[out] aEui64 A pointer to where the factory-assigned IEEE EUI-64 is placed. 522 */ 523 void otLinkGetFactoryAssignedIeeeEui64(otInstance *aInstance, otExtAddress *aEui64); 524 525 /** 526 * Get the IEEE 802.15.4 PAN ID. 527 * 528 * @param[in] aInstance A pointer to an OpenThread instance. 529 * 530 * @returns The IEEE 802.15.4 PAN ID. 531 * 532 * @sa otLinkSetPanId 533 */ 534 otPanId otLinkGetPanId(otInstance *aInstance); 535 536 /** 537 * Set the IEEE 802.15.4 PAN ID. 538 * 539 * Succeeds only when Thread protocols are disabled. A successful call to this function also invalidates 540 * the Active and Pending Operational Datasets in non-volatile memory. 541 * 542 * @param[in] aInstance A pointer to an OpenThread instance. 543 * @param[in] aPanId The IEEE 802.15.4 PAN ID. 544 * 545 * @retval OT_ERROR_NONE Successfully set the PAN ID. 546 * @retval OT_ERROR_INVALID_ARGS If aPanId is not in the range [0, 65534]. 547 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 548 * 549 * @sa otLinkGetPanId 550 */ 551 otError otLinkSetPanId(otInstance *aInstance, otPanId aPanId); 552 553 /** 554 * Get the data poll period of sleepy end device. 555 * 556 * @param[in] aInstance A pointer to an OpenThread instance. 557 * 558 * @returns The data poll period of sleepy end device in milliseconds. 559 * 560 * @sa otLinkSetPollPeriod 561 */ 562 uint32_t otLinkGetPollPeriod(otInstance *aInstance); 563 564 /** 565 * Set/clear user-specified/external data poll period for sleepy end device. 566 * 567 * @note This function updates only poll period of sleepy end device. To update child timeout the function 568 * `otThreadSetChildTimeout()` shall be called. 569 * 570 * @note Minimal non-zero value should be `OPENTHREAD_CONFIG_MAC_MINIMUM_POLL_PERIOD` (10ms). 571 * Or zero to clear user-specified poll period. 572 * 573 * @note User-specified value should be no more than the maximal value 0x3FFFFFF ((1 << 26) - 1) allowed, 574 * otherwise it would be clipped by the maximal value. 575 * 576 * @param[in] aInstance A pointer to an OpenThread instance. 577 * @param[in] aPollPeriod data poll period in milliseconds. 578 * 579 * @retval OT_ERROR_NONE Successfully set/cleared user-specified poll period. 580 * @retval OT_ERROR_INVALID_ARGS If aPollPeriod is invalid. 581 * 582 * @sa otLinkGetPollPeriod 583 */ 584 otError otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod); 585 586 /** 587 * Get the IEEE 802.15.4 Short Address. 588 * 589 * @param[in] aInstance A pointer to an OpenThread instance. 590 * 591 * @returns The IEEE 802.15.4 Short Address. 592 */ 593 otShortAddress otLinkGetShortAddress(otInstance *aInstance); 594 595 /** 596 * Get the IEEE 802.15.4 alternate short address. 597 * 598 * @param[in] aInstance A pointer to an OpenThread instance. 599 * 600 * @returns The alternate short address, or `OT_RADIO_INVALID_SHORT_ADDR` (0xfffe) if there is no alternate address. 601 */ 602 otShortAddress otLinkGetAlternateShortAddress(otInstance *aInstance); 603 604 /** 605 * Returns the maximum number of frame retries during direct transmission. 606 * 607 * @param[in] aInstance A pointer to an OpenThread instance. 608 * 609 * @returns The maximum number of retries during direct transmission. 610 */ 611 uint8_t otLinkGetMaxFrameRetriesDirect(otInstance *aInstance); 612 613 /** 614 * Sets the maximum number of frame retries during direct transmission. 615 * 616 * @param[in] aInstance A pointer to an OpenThread instance. 617 * @param[in] aMaxFrameRetriesDirect The maximum number of retries during direct transmission. 618 */ 619 void otLinkSetMaxFrameRetriesDirect(otInstance *aInstance, uint8_t aMaxFrameRetriesDirect); 620 621 /** 622 * Returns the maximum number of frame retries during indirect transmission. 623 * 624 * @param[in] aInstance A pointer to an OpenThread instance. 625 * 626 * @returns The maximum number of retries during indirect transmission. 627 */ 628 uint8_t otLinkGetMaxFrameRetriesIndirect(otInstance *aInstance); 629 630 /** 631 * Sets the maximum number of frame retries during indirect transmission. 632 * 633 * @param[in] aInstance A pointer to an OpenThread instance. 634 * @param[in] aMaxFrameRetriesIndirect The maximum number of retries during indirect transmission. 635 */ 636 void otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRetriesIndirect); 637 638 /** 639 * Gets the current MAC frame counter value. 640 * 641 * @param[in] aInstance A pointer to the OpenThread instance. 642 * 643 * @returns The current MAC frame counter value. 644 */ 645 uint32_t otLinkGetFrameCounter(otInstance *aInstance); 646 647 /** 648 * Gets the address mode of MAC filter. 649 * 650 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 651 * 652 * @param[in] aInstance A pointer to an OpenThread instance. 653 * 654 * @returns the address mode. 655 */ 656 otMacFilterAddressMode otLinkFilterGetAddressMode(otInstance *aInstance); 657 658 /** 659 * Sets the address mode of MAC filter. 660 * 661 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 662 * 663 * @param[in] aInstance A pointer to an OpenThread instance. 664 * @param[in] aMode The address mode to set. 665 */ 666 void otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aMode); 667 668 /** 669 * Adds an Extended Address to MAC filter. 670 * 671 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 672 * 673 * @param[in] aInstance A pointer to an OpenThread instance. 674 * @param[in] aExtAddress A pointer to the Extended Address (MUST NOT be NULL). 675 * 676 * @retval OT_ERROR_NONE Successfully added @p aExtAddress to MAC filter. 677 * @retval OT_ERROR_NO_BUFS No available entry exists. 678 */ 679 otError otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAddress); 680 681 /** 682 * Removes an Extended Address from MAC filter. 683 * 684 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 685 * 686 * No action is performed if there is no existing entry in Filter matching the given Extended Address. 687 * 688 * @param[in] aInstance A pointer to an OpenThread instance. 689 * @param[in] aExtAddress A pointer to the Extended Address (MUST NOT be NULL). 690 */ 691 void otLinkFilterRemoveAddress(otInstance *aInstance, const otExtAddress *aExtAddress); 692 693 /** 694 * Clears all the Extended Addresses from MAC filter. 695 * 696 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 697 * 698 * @param[in] aInstance A pointer to an OpenThread instance. 699 */ 700 void otLinkFilterClearAddresses(otInstance *aInstance); 701 702 /** 703 * Gets an in-use address filter entry. 704 * 705 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 706 * 707 * @param[in] aInstance A pointer to an OpenThread instance. 708 * @param[in,out] aIterator A pointer to the MAC filter iterator context. To get the first in-use address filter 709 * entry, it should be set to OT_MAC_FILTER_ITERATOR_INIT. MUST NOT be NULL. 710 * @param[out] aEntry A pointer to where the information is placed. MUST NOT be NULL. 711 * 712 * @retval OT_ERROR_NONE Successfully retrieved an in-use address filter entry. 713 * @retval OT_ERROR_NOT_FOUND No subsequent entry exists. 714 */ 715 otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry); 716 717 /** 718 * Adds the specified Extended Address to the `RssIn` list (or modifies an existing 719 * address in the `RssIn` list) and sets the received signal strength (in dBm) entry 720 * for messages from that address. The Extended Address does not necessarily have 721 * to be in the `address allowlist/denylist` filter to set the `rss`. 722 * @note The `RssIn` list contains Extended Addresses whose `rss` or link quality indicator (`lqi`) 723 * values have been set to be different from the defaults. 724 * 725 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 726 * 727 * @param[in] aInstance A pointer to an OpenThread instance. 728 * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. 729 * @param[in] aRss A received signal strength (in dBm). 730 * 731 * @retval OT_ERROR_NONE Successfully added an entry for @p aExtAddress and @p aRss. 732 * @retval OT_ERROR_NO_BUFS No available entry exists. 733 */ 734 otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddress, int8_t aRss); 735 736 /** 737 * Removes the specified Extended Address from the `RssIn` list. Once removed 738 * from the `RssIn` list, this MAC address will instead use the default `rss` 739 * and `lqi` settings, assuming defaults have been set. 740 * (If no defaults have been set, the over-air signal is used.) 741 * 742 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 743 * 744 * No action is performed if there is no existing entry in the `RssIn` list matching the specified Extended Address. 745 * 746 * @param[in] aInstance A pointer to an OpenThread instance. 747 * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. 748 */ 749 void otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddress); 750 751 /** 752 * Sets the default received signal strength (in dBm) on MAC Filter. 753 * 754 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 755 * 756 * The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry 757 * in the Filter list (added using `otLinkFilterAddRssIn()`). 758 * 759 * @param[in] aInstance A pointer to an OpenThread instance. 760 * @param[in] aRss The default received signal strength (in dBm) to set. 761 */ 762 void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss); 763 764 /** 765 * Clears any previously set default received signal strength (in dBm) on MAC Filter. 766 * 767 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 768 * 769 * @param[in] aInstance A pointer to an OpenThread instance. 770 */ 771 void otLinkFilterClearDefaultRssIn(otInstance *aInstance); 772 773 /** 774 * Clears all the received signal strength (`rss`) and link quality 775 * indicator (`lqi`) entries (including defaults) from the `RssIn` list. 776 * Performing this action means that all Extended Addresses will use the on-air signal. 777 * 778 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 779 * 780 * @param[in] aInstance A pointer to an OpenThread instance. 781 */ 782 void otLinkFilterClearAllRssIn(otInstance *aInstance); 783 784 /** 785 * Gets an in-use RssIn filter entry. 786 * 787 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 788 * 789 * @param[in] aInstance A pointer to an OpenThread instance. 790 * @param[in,out] aIterator A pointer to the MAC filter iterator context. MUST NOT be NULL. 791 * To get the first entry, it should be set to OT_MAC_FILTER_ITERATOR_INIT. 792 * @param[out] aEntry A pointer to where the information is placed. The last entry would have the extended 793 * address as all 0xff to indicate the default received signal strength if it was set. 794 @p aEntry MUST NOT be NULL. 795 * 796 * @retval OT_ERROR_NONE Successfully retrieved the next entry. 797 * @retval OT_ERROR_NOT_FOUND No subsequent entry exists. 798 */ 799 otError otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry); 800 801 /** 802 * Enables/disables IEEE 802.15.4 radio filter mode. 803 * 804 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 805 * 806 * The radio filter is mainly intended for testing. It can be used to temporarily block all tx/rx on the 802.15.4 radio. 807 * When radio filter is enabled, radio is put to sleep instead of receive (to ensure device does not receive any frame 808 * and/or potentially send ack). Also the frame transmission requests return immediately without sending the frame over 809 * the air (return "no ack" error if ack is requested, otherwise return success). 810 * 811 * @param[in] aInstance A pointer to an OpenThread instance. 812 * @param[in] aFilterEnabled TRUE to enable radio filter, FALSE to disable 813 */ 814 void otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled); 815 816 /** 817 * Indicates whether the IEEE 802.15.4 radio filter is enabled or not. 818 * 819 * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. 820 * 821 * @retval TRUE If the radio filter is enabled. 822 * @retval FALSE If the radio filter is disabled. 823 */ 824 bool otLinkIsRadioFilterEnabled(otInstance *aInstance); 825 826 /** 827 * Converts received signal strength to link quality. 828 * 829 * @param[in] aInstance A pointer to an OpenThread instance. 830 * @param[in] aRss The received signal strength value to be converted. 831 * 832 * @return Link quality value mapping to @p aRss. 833 */ 834 uint8_t otLinkConvertRssToLinkQuality(otInstance *aInstance, int8_t aRss); 835 836 /** 837 * Converts link quality to typical received signal strength. 838 * 839 * @param[in] aInstance A pointer to an OpenThread instance. 840 * @param[in] aLinkQuality LinkQuality value, should be in range [0,3]. 841 * 842 * @return Typical platform received signal strength mapping to @p aLinkQuality. 843 */ 844 int8_t otLinkConvertLinkQualityToRss(otInstance *aInstance, uint8_t aLinkQuality); 845 846 /** 847 * Gets histogram of retries for a single direct packet until success. 848 * 849 * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. 850 * 851 * @param[in] aInstance A pointer to an OpenThread instance. 852 * @param[out] aNumberOfEntries A pointer to where the size of returned histogram array is placed. 853 * 854 * @returns A pointer to the histogram of retries (in a form of an array). 855 * The n-th element indicates that the packet has been sent with n-th retry. 856 */ 857 const uint32_t *otLinkGetTxDirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries); 858 859 /** 860 * Gets histogram of retries for a single indirect packet until success. 861 * 862 * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. 863 * 864 * @param[in] aInstance A pointer to an OpenThread instance. 865 * @param[out] aNumberOfEntries A pointer to where the size of returned histogram array is placed. 866 * 867 * @returns A pointer to the histogram of retries (in a form of an array). 868 * The n-th element indicates that the packet has been sent with n-th retry. 869 */ 870 const uint32_t *otLinkGetTxIndirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries); 871 872 /** 873 * Clears histogram statistics for direct and indirect transmissions. 874 * 875 * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. 876 * 877 * @param[in] aInstance A pointer to an OpenThread instance. 878 */ 879 void otLinkResetTxRetrySuccessHistogram(otInstance *aInstance); 880 881 /** 882 * Get the MAC layer counters. 883 * 884 * @param[in] aInstance A pointer to an OpenThread instance. 885 * 886 * @returns A pointer to the MAC layer counters. 887 */ 888 const otMacCounters *otLinkGetCounters(otInstance *aInstance); 889 890 /** 891 * Resets the MAC layer counters. 892 * 893 * @param[in] aInstance A pointer to an OpenThread instance. 894 */ 895 void otLinkResetCounters(otInstance *aInstance); 896 897 /** 898 * Pointer is called when an IEEE 802.15.4 frame is received. 899 * 900 * @note This callback is called after FCS processing and @p aFrame may not contain the actual FCS that was received. 901 * 902 * @note This callback is called before IEEE 802.15.4 security processing. 903 * 904 * @param[in] aFrame A pointer to the received IEEE 802.15.4 frame. 905 * @param[in] aIsTx Whether this frame is transmitted, not received. 906 * @param[in] aContext A pointer to application-specific context. 907 */ 908 typedef void (*otLinkPcapCallback)(const otRadioFrame *aFrame, bool aIsTx, void *aContext); 909 910 /** 911 * Registers a callback to provide received raw IEEE 802.15.4 frames. 912 * 913 * @param[in] aInstance A pointer to an OpenThread instance. 914 * @param[in] aPcapCallback A pointer to a function that is called when receiving an IEEE 802.15.4 link frame or 915 * NULL to disable the callback. 916 * @param[in] aCallbackContext A pointer to application-specific context. 917 */ 918 void otLinkSetPcapCallback(otInstance *aInstance, otLinkPcapCallback aPcapCallback, void *aCallbackContext); 919 920 /** 921 * Indicates whether or not promiscuous mode is enabled at the link layer. 922 * 923 * @param[in] aInstance A pointer to an OpenThread instance. 924 * 925 * @retval TRUE Promiscuous mode is enabled. 926 * @retval FALSE Promiscuous mode is not enabled. 927 */ 928 bool otLinkIsPromiscuous(otInstance *aInstance); 929 930 /** 931 * Enables or disables the link layer promiscuous mode. 932 * 933 * @note Promiscuous mode may only be enabled when the Thread interface is disabled. 934 * 935 * @param[in] aInstance A pointer to an OpenThread instance. 936 * @param[in] aPromiscuous true to enable promiscuous mode, or false otherwise. 937 * 938 * @retval OT_ERROR_NONE Successfully enabled promiscuous mode. 939 * @retval OT_ERROR_INVALID_STATE Could not enable promiscuous mode because 940 * the Thread interface is enabled. 941 */ 942 otError otLinkSetPromiscuous(otInstance *aInstance, bool aPromiscuous); 943 944 /** 945 * Gets the CSL channel. 946 * 947 * @param[in] aInstance A pointer to an OpenThread instance. 948 * 949 * @returns The CSL channel. 950 */ 951 uint8_t otLinkGetCslChannel(otInstance *aInstance); 952 953 /** 954 * Sets the CSL channel. 955 * 956 * @param[in] aInstance A pointer to an OpenThread instance. 957 * @param[in] aChannel The CSL sample channel. Channel value should be `0` (Set CSL Channel unspecified) or 958 * within the range [1, 10] (if 915-MHz supported) and [11, 26] (if 2.4 GHz supported). 959 * 960 * @retval OT_ERROR_NONE Successfully set the CSL parameters. 961 * @retval OT_ERROR_INVALID_ARGS Invalid @p aChannel. 962 */ 963 otError otLinkSetCslChannel(otInstance *aInstance, uint8_t aChannel); 964 965 /** 966 * Represents CSL period ten symbols unit in microseconds. 967 * 968 * The CSL period (in micro seconds) MUST be a multiple of this value. 969 */ 970 #define OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC (160) 971 972 /** 973 * Gets the CSL period in microseconds 974 * 975 * @param[in] aInstance A pointer to an OpenThread instance. 976 * 977 * @returns The CSL period in microseconds. 978 */ 979 uint32_t otLinkGetCslPeriod(otInstance *aInstance); 980 981 /** 982 * Sets the CSL period in microseconds. Disable CSL by setting this parameter to `0`. 983 * 984 * The CSL period MUST be a multiple of `OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC`, otherwise `OT_ERROR_INVALID_ARGS` 985 * is returned. 986 * 987 * @param[in] aInstance A pointer to an OpenThread instance. 988 * @param[in] aPeriod The CSL period in microseconds. 989 * 990 * @retval OT_ERROR_NONE Successfully set the CSL period. 991 * @retval OT_ERROR_INVALID_ARGS Invalid CSL period 992 */ 993 otError otLinkSetCslPeriod(otInstance *aInstance, uint32_t aPeriod); 994 995 /** 996 * Gets the CSL timeout. 997 * 998 * @param[in] aInstance A pointer to an OpenThread instance. 999 * 1000 * @returns The CSL timeout in seconds. 1001 */ 1002 uint32_t otLinkGetCslTimeout(otInstance *aInstance); 1003 1004 /** 1005 * Sets the CSL timeout in seconds. 1006 * 1007 * @param[in] aInstance A pointer to an OpenThread instance. 1008 * @param[in] aTimeout The CSL timeout in seconds. 1009 * 1010 * @retval OT_ERROR_NONE Successfully set the CSL timeout. 1011 * @retval OT_ERROR_INVALID_ARGS Invalid CSL timeout. 1012 */ 1013 otError otLinkSetCslTimeout(otInstance *aInstance, uint32_t aTimeout); 1014 1015 /** 1016 * Returns the current CCA (Clear Channel Assessment) failure rate. 1017 * 1018 * The rate is maintained over a window of (roughly) last `OPENTHREAD_CONFIG_CCA_FAILURE_RATE_AVERAGING_WINDOW` 1019 * frame transmissions. 1020 * 1021 * @returns The CCA failure rate with maximum value `0xffff` corresponding to 100% failure rate. 1022 */ 1023 uint16_t otLinkGetCcaFailureRate(otInstance *aInstance); 1024 1025 /** 1026 * Enables or disables the link layer. 1027 * 1028 * @note The link layer may only be enabled / disabled when the Thread Interface is disabled. 1029 * 1030 * @param[in] aInstance A pointer to an OpenThread instance. 1031 * @param[in] aEnable true to enable the link layer, or false otherwise. 1032 * 1033 * @retval OT_ERROR_NONE Successfully enabled / disabled the link layer. 1034 * @retval OT_ERROR_INVALID_STATE Could not disable the link layer because 1035 * the Thread interface is enabled. 1036 */ 1037 otError otLinkSetEnabled(otInstance *aInstance, bool aEnable); 1038 1039 /** 1040 * Indicates whether or not the link layer is enabled. 1041 * 1042 * @param[in] aInstance A pointer to an OpenThread instance. 1043 * 1044 * @retval TRUE Link layer is enabled. 1045 * @retval FALSE Link layer is not enabled. 1046 */ 1047 bool otLinkIsEnabled(otInstance *aInstance); 1048 1049 /** 1050 * Indicates whether or not CSL is enabled. 1051 * 1052 * @param[in] aInstance A pointer to an OpenThread instance. 1053 * 1054 * @retval TRUE Link layer is CSL enabled. 1055 * @retval FALSE Link layer is not CSL enabled. 1056 */ 1057 bool otLinkIsCslEnabled(otInstance *aInstance); 1058 1059 /** 1060 * Indicates whether the device is connected to a parent which supports CSL. 1061 * 1062 * @retval TRUE If parent supports CSL. 1063 * @retval FALSE If parent does not support CSL. 1064 */ 1065 bool otLinkIsCslSupported(otInstance *aInstance); 1066 1067 /** 1068 * Instructs the device to send an empty IEEE 802.15.4 data frame. 1069 * 1070 * Is only supported on an Rx-Off-When-Idle device to send an empty data frame to its parent. 1071 * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 1072 * 1073 * @param[in] aInstance A pointer to an OpenThread instance. 1074 * 1075 * @retval OT_ERROR_NONE Successfully enqueued an empty message. 1076 * @retval OT_ERROR_INVALID_STATE Device is not in Rx-Off-When-Idle mode. 1077 * @retval OT_ERROR_NO_BUFS Insufficient message buffers available. 1078 */ 1079 otError otLinkSendEmptyData(otInstance *aInstance); 1080 1081 /** 1082 * Sets the region code. 1083 * 1084 * The radio region format is the 2-bytes ascii representation of the ISO 3166 alpha-2 code. 1085 * 1086 * @param[in] aInstance The OpenThread instance structure. 1087 * @param[in] aRegionCode The radio region code. The `aRegionCode >> 8` is first ascii char 1088 * and the `aRegionCode & 0xff` is the second ascii char. 1089 * 1090 * @retval OT_ERROR_FAILED Other platform specific errors. 1091 * @retval OT_ERROR_NONE Successfully set region code. 1092 * @retval OT_ERROR_NOT_IMPLEMENTED The feature is not implemented. 1093 */ 1094 otError otLinkSetRegion(otInstance *aInstance, uint16_t aRegionCode); 1095 1096 /** 1097 * Get the region code. 1098 * 1099 * The radio region format is the 2-bytes ascii representation of the ISO 3166 alpha-2 code. 1100 1101 * @param[in] aInstance The OpenThread instance structure. 1102 * @param[out] aRegionCode The radio region code. The `aRegionCode >> 8` is first ascii char 1103 * and the `aRegionCode & 0xff` is the second ascii char. 1104 * 1105 * @retval OT_ERROR_INVALID_ARGS @p aRegionCode is nullptr. 1106 * @retval OT_ERROR_FAILED Other platform specific errors. 1107 * @retval OT_ERROR_NONE Successfully got region code. 1108 * @retval OT_ERROR_NOT_IMPLEMENTED The feature is not implemented. 1109 */ 1110 otError otLinkGetRegion(otInstance *aInstance, uint16_t *aRegionCode); 1111 1112 /** 1113 * Gets the Wake-up channel. 1114 * 1115 * Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` or `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`. 1116 * 1117 * @param[in] aInstance A pointer to an OpenThread instance. 1118 * 1119 * @returns The Wake-up channel. 1120 */ 1121 uint8_t otLinkGetWakeupChannel(otInstance *aInstance); 1122 1123 /** 1124 * Sets the Wake-up channel. 1125 * 1126 * Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` or `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`. 1127 * 1128 * @param[in] aInstance A pointer to an OpenThread instance. 1129 * @param[in] aChannel The Wake-up sample channel. Channel value should be `0` (Set Wake-up Channel unspecified, 1130 * which means the device will use the PAN channel) or within the range [1, 10] (if 915-MHz 1131 * supported) and [11, 26] (if 2.4 GHz supported). 1132 * 1133 * @retval OT_ERROR_NONE Successfully set the Wake-up channel. 1134 * @retval OT_ERROR_INVALID_ARGS Invalid @p aChannel. 1135 */ 1136 otError otLinkSetWakeupChannel(otInstance *aInstance, uint8_t aChannel); 1137 1138 /** 1139 * Enables or disables listening for wake-up frames. 1140 * 1141 * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`. 1142 * 1143 * @param[in] aInstance A pointer to an OpenThread instance. 1144 * @param[in] aEnable true to enable listening for wake-up frames, or false otherwise. 1145 * 1146 * @retval OT_ERROR_NONE Successfully enabled / disabled the listening for wake-up frames. 1147 * @retval OT_ERROR_INVALID_ARGS The listen duration is greater than the listen interval. 1148 * @retval OT_ERROR_INVALID_STATE Could not enable listening for wake-up frames due to bad configuration. 1149 */ 1150 otError otLinkSetWakeUpListenEnabled(otInstance *aInstance, bool aEnable); 1151 1152 /** 1153 * Returns whether listening for wake-up frames is enabled. 1154 * 1155 * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`. 1156 * 1157 * @param[in] aInstance A pointer to an OpenThread instance. 1158 * 1159 * @retval TRUE If listening for wake-up frames is enabled. 1160 * @retval FALSE If listening for wake-up frames is not enabled. 1161 */ 1162 bool otLinkIsWakeupListenEnabled(otInstance *aInstance); 1163 1164 /** 1165 * Get the wake-up listen parameters. 1166 * 1167 * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`. 1168 * 1169 * @param[in] aInstance A pointer to an OpenThread instance. 1170 * @param[out] aInterval A pointer to return the wake-up listen interval in microseconds. 1171 * @param[out] aDuration A pointer to return the wake-up listen duration in microseconds. 1172 */ 1173 void otLinkGetWakeupListenParameters(otInstance *aInstance, uint32_t *aInterval, uint32_t *aDuration); 1174 1175 /** 1176 * Set the wake-up listen parameters. 1177 * 1178 * The listen interval must be greater than the listen duration. 1179 * The listen duration must be greater or equal than the minimum supported. 1180 * 1181 * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`. 1182 * 1183 * @param[in] aInstance A pointer to an OpenThread instance. 1184 * @param[in] aInterval The wake-up listen interval in microseconds. 1185 * @param[in] aDuration The wake-up listen duration in microseconds. 1186 * 1187 * @retval OT_ERROR_NONE Successfully set the wake-up listen parameters. 1188 * @retval OT_ERROR_INVALID_ARGS Invalid wake-up listen parameters. 1189 */ 1190 otError otLinkSetWakeupListenParameters(otInstance *aInstance, uint32_t aInterval, uint32_t aDuration); 1191 1192 /** 1193 * Sets the rx-on-when-idle state. 1194 * 1195 * @param[in] aInstance A pointer to an OpenThread instance. 1196 * @param[in] aRxOnWhenIdle TRUE to keep radio in Receive state, FALSE to put to Sleep state during idle periods. 1197 * 1198 * @retval OT_ERROR_NONE If successful. 1199 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 1200 */ 1201 otError otLinkSetRxOnWhenIdle(otInstance *aInstance, bool aRxOnWhenIdle); 1202 1203 /** 1204 * @} 1205 */ 1206 1207 #ifdef __cplusplus 1208 } // extern "C" 1209 #endif 1210 1211 #endif // OPENTHREAD_LINK_H_ 1212