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 a fixed received signal strength (in dBm) entry for the messages from a given Extended Address in 792 * MAC Filter. 793 * 794 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 795 * 796 * @param[in] aInstance A pointer to an OpenThread instance. 797 * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. 798 * @param[in] aRss A received signal strength (in dBm). 799 * 800 * @retval OT_ERROR_NONE Successfully added an entry for @p aExtAddress and @p aRss. 801 * @retval OT_ERROR_NO_BUFS No available entry exists. 802 * 803 */ 804 otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddress, int8_t aRss); 805 806 /** 807 * Removes a MAC Filter entry for fixed received signal strength setting for a given Extended Address. 808 * 809 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 810 * 811 * No action is performed if there is no existing entry in Filter matching the given Extended Address. 812 * 813 * @param[in] aInstance A pointer to an OpenThread instance. 814 * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. 815 * 816 */ 817 void otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddress); 818 819 /** 820 * Sets the default received signal strength (in dBm) on MAC Filter. 821 * 822 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 823 * 824 * The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry 825 * in the Filter list (added using `otLinkFilterAddRssIn()`). 826 * 827 * @param[in] aInstance A pointer to an OpenThread instance. 828 * @param[in] aRss The default received signal strength (in dBm) to set. 829 * 830 */ 831 void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss); 832 833 /** 834 * Clears any previously set default received signal strength (in dBm) on MAC Filter. 835 * 836 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 837 * 838 * @param[in] aInstance A pointer to an OpenThread instance. 839 * 840 */ 841 void otLinkFilterClearDefaultRssIn(otInstance *aInstance); 842 843 /** 844 * Clears all the received signal strength entries (including default RSS-in) on MAC Filter. 845 * 846 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 847 * 848 * @param[in] aInstance A pointer to an OpenThread instance. 849 * 850 */ 851 void otLinkFilterClearAllRssIn(otInstance *aInstance); 852 853 /** 854 * Gets an in-use RssIn filter entry. 855 * 856 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 857 * 858 * @param[in] aInstance A pointer to an OpenThread instance. 859 * @param[in,out] aIterator A pointer to the MAC filter iterator context. MUST NOT be NULL. 860 * To get the first entry, it should be set to OT_MAC_FILTER_ITERATOR_INIT. 861 * @param[out] aEntry A pointer to where the information is placed. The last entry would have the extended 862 * address as all 0xff to indicate the default received signal strength if it was set. 863 @p aEntry MUST NOT be NULL. 864 * 865 * @retval OT_ERROR_NONE Successfully retrieved the next entry. 866 * @retval OT_ERROR_NOT_FOUND No subsequent entry exists. 867 * 868 */ 869 otError otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry); 870 871 /** 872 * Enables/disables IEEE 802.15.4 radio filter mode. 873 * 874 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 875 * 876 * The radio filter is mainly intended for testing. It can be used to temporarily block all tx/rx on the 802.15.4 radio. 877 * When radio filter is enabled, radio is put to sleep instead of receive (to ensure device does not receive any frame 878 * and/or potentially send ack). Also the frame transmission requests return immediately without sending the frame over 879 * the air (return "no ack" error if ack is requested, otherwise return success). 880 * 881 * @param[in] aInstance A pointer to an OpenThread instance. 882 * @param[in] aFilterEnabled TRUE to enable radio filter, FALSE to disable 883 * 884 */ 885 void otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled); 886 887 /** 888 * Indicates whether the IEEE 802.15.4 radio filter is enabled or not. 889 * 890 * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. 891 * 892 * @retval TRUE If the radio filter is enabled. 893 * @retval FALSE If the radio filter is disabled. 894 * 895 */ 896 bool otLinkIsRadioFilterEnabled(otInstance *aInstance); 897 898 /** 899 * Converts received signal strength to link quality. 900 * 901 * @param[in] aInstance A pointer to an OpenThread instance. 902 * @param[in] aRss The received signal strength value to be converted. 903 * 904 * @return Link quality value mapping to @p aRss. 905 * 906 */ 907 uint8_t otLinkConvertRssToLinkQuality(otInstance *aInstance, int8_t aRss); 908 909 /** 910 * Converts link quality to typical received signal strength. 911 * 912 * @param[in] aInstance A pointer to an OpenThread instance. 913 * @param[in] aLinkQuality LinkQuality value, should be in range [0,3]. 914 * 915 * @return Typical platform received signal strength mapping to @p aLinkQuality. 916 * 917 */ 918 int8_t otLinkConvertLinkQualityToRss(otInstance *aInstance, uint8_t aLinkQuality); 919 920 /** 921 * Gets histogram of retries for a single direct packet until success. 922 * 923 * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. 924 * 925 * @param[in] aInstance A pointer to an OpenThread instance. 926 * @param[out] aNumberOfEntries A pointer to where the size of returned histogram array is placed. 927 * 928 * @returns A pointer to the histogram of retries (in a form of an array). 929 * The n-th element indicates that the packet has been sent with n-th retry. 930 */ 931 const uint32_t *otLinkGetTxDirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries); 932 933 /** 934 * Gets histogram of retries for a single indirect packet until success. 935 * 936 * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. 937 * 938 * @param[in] aInstance A pointer to an OpenThread instance. 939 * @param[out] aNumberOfEntries A pointer to where the size of returned histogram array is placed. 940 * 941 * @returns A pointer to the histogram of retries (in a form of an array). 942 * The n-th element indicates that the packet has been sent with n-th retry. 943 * 944 */ 945 const uint32_t *otLinkGetTxIndirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries); 946 947 /** 948 * Clears histogram statistics for direct and indirect transmissions. 949 * 950 * Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled. 951 * 952 * @param[in] aInstance A pointer to an OpenThread instance. 953 * 954 */ 955 void otLinkResetTxRetrySuccessHistogram(otInstance *aInstance); 956 957 /** 958 * Get the MAC layer counters. 959 * 960 * @param[in] aInstance A pointer to an OpenThread instance. 961 * 962 * @returns A pointer to the MAC layer counters. 963 * 964 */ 965 const otMacCounters *otLinkGetCounters(otInstance *aInstance); 966 967 /** 968 * Resets the MAC layer counters. 969 * 970 * @param[in] aInstance A pointer to an OpenThread instance. 971 * 972 */ 973 void otLinkResetCounters(otInstance *aInstance); 974 975 /** 976 * Pointer is called when an IEEE 802.15.4 frame is received. 977 * 978 * @note This callback is called after FCS processing and @p aFrame may not contain the actual FCS that was received. 979 * 980 * @note This callback is called before IEEE 802.15.4 security processing. 981 * 982 * @param[in] aFrame A pointer to the received IEEE 802.15.4 frame. 983 * @param[in] aIsTx Whether this frame is transmitted, not received. 984 * @param[in] aContext A pointer to application-specific context. 985 * 986 */ 987 typedef void (*otLinkPcapCallback)(const otRadioFrame *aFrame, bool aIsTx, void *aContext); 988 989 /** 990 * Registers a callback to provide received raw IEEE 802.15.4 frames. 991 * 992 * @param[in] aInstance A pointer to an OpenThread instance. 993 * @param[in] aPcapCallback A pointer to a function that is called when receiving an IEEE 802.15.4 link frame or 994 * NULL to disable the callback. 995 * @param[in] aCallbackContext A pointer to application-specific context. 996 * 997 */ 998 void otLinkSetPcapCallback(otInstance *aInstance, otLinkPcapCallback aPcapCallback, void *aCallbackContext); 999 1000 /** 1001 * Indicates whether or not promiscuous mode is enabled at the link layer. 1002 * 1003 * @param[in] aInstance A pointer to an OpenThread instance. 1004 * 1005 * @retval TRUE Promiscuous mode is enabled. 1006 * @retval FALSE Promiscuous mode is not enabled. 1007 * 1008 */ 1009 bool otLinkIsPromiscuous(otInstance *aInstance); 1010 1011 /** 1012 * Enables or disables the link layer promiscuous mode. 1013 * 1014 * @note Promiscuous mode may only be enabled when the Thread interface is disabled. 1015 * 1016 * @param[in] aInstance A pointer to an OpenThread instance. 1017 * @param[in] aPromiscuous true to enable promiscuous mode, or false otherwise. 1018 * 1019 * @retval OT_ERROR_NONE Successfully enabled promiscuous mode. 1020 * @retval OT_ERROR_INVALID_STATE Could not enable promiscuous mode because 1021 * the Thread interface is enabled. 1022 * 1023 */ 1024 otError otLinkSetPromiscuous(otInstance *aInstance, bool aPromiscuous); 1025 1026 /** 1027 * Gets the CSL channel. 1028 * 1029 * @param[in] aInstance A pointer to an OpenThread instance. 1030 * 1031 * @returns The CSL channel. 1032 * 1033 */ 1034 uint8_t otLinkGetCslChannel(otInstance *aInstance); 1035 1036 /** 1037 * Sets the CSL channel. 1038 * 1039 * @param[in] aInstance A pointer to an OpenThread instance. 1040 * @param[in] aChannel The CSL sample channel. Channel value should be `0` (Set CSL Channel unspecified) or 1041 * within the range [1, 10] (if 915-MHz supported) and [11, 26] (if 2.4 GHz supported). 1042 * 1043 * @retval OT_ERROR_NONE Successfully set the CSL parameters. 1044 * @retval OT_ERROR_INVALID_ARGS Invalid @p aChannel. 1045 * 1046 */ 1047 otError otLinkSetCslChannel(otInstance *aInstance, uint8_t aChannel); 1048 1049 /** 1050 * Represents CSL period ten symbols unit in microseconds. 1051 * 1052 * The CSL period (in micro seconds) MUST be a multiple of this value. 1053 * 1054 */ 1055 #define OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC (160) 1056 1057 /** 1058 * Gets the CSL period in microseconds 1059 * 1060 * @param[in] aInstance A pointer to an OpenThread instance. 1061 * 1062 * @returns The CSL period in microseconds. 1063 * 1064 */ 1065 uint32_t otLinkGetCslPeriod(otInstance *aInstance); 1066 1067 /** 1068 * Sets the CSL period in microseconds. Disable CSL by setting this parameter to `0`. 1069 * 1070 * The CSL period MUST be a multiple of `OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC`, otherwise `OT_ERROR_INVALID_ARGS` 1071 * is returned. 1072 * 1073 * @param[in] aInstance A pointer to an OpenThread instance. 1074 * @param[in] aPeriod The CSL period in microseconds. 1075 * 1076 * @retval OT_ERROR_NONE Successfully set the CSL period. 1077 * @retval OT_ERROR_INVALID_ARGS Invalid CSL period 1078 * 1079 */ 1080 otError otLinkSetCslPeriod(otInstance *aInstance, uint32_t aPeriod); 1081 1082 /** 1083 * Gets the CSL timeout. 1084 * 1085 * @param[in] aInstance A pointer to an OpenThread instance. 1086 * 1087 * @returns The CSL timeout in seconds. 1088 * 1089 */ 1090 uint32_t otLinkGetCslTimeout(otInstance *aInstance); 1091 1092 /** 1093 * Sets the CSL timeout in seconds. 1094 * 1095 * @param[in] aInstance A pointer to an OpenThread instance. 1096 * @param[in] aTimeout The CSL timeout in seconds. 1097 * 1098 * @retval OT_ERROR_NONE Successfully set the CSL timeout. 1099 * @retval OT_ERROR_INVALID_ARGS Invalid CSL timeout. 1100 * 1101 */ 1102 otError otLinkSetCslTimeout(otInstance *aInstance, uint32_t aTimeout); 1103 1104 /** 1105 * Returns the current CCA (Clear Channel Assessment) failure rate. 1106 * 1107 * The rate is maintained over a window of (roughly) last `OPENTHREAD_CONFIG_CCA_FAILURE_RATE_AVERAGING_WINDOW` 1108 * frame transmissions. 1109 * 1110 * @returns The CCA failure rate with maximum value `0xffff` corresponding to 100% failure rate. 1111 * 1112 */ 1113 uint16_t otLinkGetCcaFailureRate(otInstance *aInstance); 1114 1115 /** 1116 * Enables or disables the link layer. 1117 * 1118 * @note The link layer may only be enabled / disabled when the Thread Interface is disabled. 1119 * 1120 * @param[in] aInstance A pointer to an OpenThread instance. 1121 * @param[in] aEnable true to enable the link layer, or false otherwise. 1122 * 1123 * @retval OT_ERROR_NONE Successfully enabled / disabled the link layer. 1124 * @retval OT_ERROR_INVALID_STATE Could not disable the link layer because 1125 * the Thread interface is enabled. 1126 * 1127 */ 1128 otError otLinkSetEnabled(otInstance *aInstance, bool aEnable); 1129 1130 /** 1131 * Indicates whether or not the link layer is enabled. 1132 * 1133 * @param[in] aInstance A pointer to an OpenThread instance. 1134 * 1135 * @retval TRUE Link layer is enabled. 1136 * @retval FALSE Link layer is not enabled. 1137 * 1138 */ 1139 bool otLinkIsEnabled(otInstance *aInstance); 1140 1141 /** 1142 * Indicates whether or not CSL is enabled. 1143 * 1144 * @param[in] aInstance A pointer to an OpenThread instance. 1145 * 1146 * @retval TRUE Link layer is CSL enabled. 1147 * @retval FALSE Link layer is not CSL enabled. 1148 * 1149 */ 1150 bool otLinkIsCslEnabled(otInstance *aInstance); 1151 1152 /** 1153 * Indicates whether the device is connected to a parent which supports CSL. 1154 * 1155 * @retval TRUE If parent supports CSL. 1156 * @retval FALSE If parent does not support CSL. 1157 * 1158 */ 1159 bool otLinkIsCslSupported(otInstance *aInstance); 1160 1161 /** 1162 * Instructs the device to send an empty IEEE 802.15.4 data frame. 1163 * 1164 * Is only supported on an Rx-Off-When-Idle device to send an empty data frame to its parent. 1165 * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 1166 * 1167 * @param[in] aInstance A pointer to an OpenThread instance. 1168 * 1169 * @retval OT_ERROR_NONE Successfully enqueued an empty message. 1170 * @retval OT_ERROR_INVALID_STATE Device is not in Rx-Off-When-Idle mode. 1171 * @retval OT_ERROR_NO_BUFS Insufficient message buffers available. 1172 * 1173 */ 1174 otError otLinkSendEmptyData(otInstance *aInstance); 1175 1176 /** 1177 * @} 1178 * 1179 */ 1180 1181 #ifdef __cplusplus 1182 } // extern "C" 1183 #endif 1184 1185 #endif // OPENTHREAD_LINK_H_ 1186
