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