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