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