# otRadioFrame `#include ` Represents an IEEE 802.15.4 radio frame. ## Summary | ### Public attributes || |---|---| | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a8556cf7a4a308424d22d1f9797e955e6` | `uint32_t` ACK security frame counter (applicable when `mAckedWithSecEnhAck` is set). | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1abbe45e283629477d77248eebeb8d549f` | `uint8_t` ACK security key index (applicable when `mAckedWithSecEnhAck` is set). | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a176fa32018dd74b671d693ed6affefa0` | `bool` This indicates if this frame was acknowledged with frame pending set. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1acef8cb5d7b7cb5cb4c24fccd18b22045` | `bool` This indicates if this frame was acknowledged with secured enhance ACK. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a2e1d93949b02f123bf733b5fee6775cd` | `const https://openthread.io/reference/struct/ot-mac-key-material *` The key material used for AES-CCM frame security. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1aaca1d5593ef0b1b6dd940f6a4251dff9` | `uint8_t` Channel used to transmit/receive the frame. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a3d2c5a282da977aee18db87fb622e264` | `bool` Set to true if CSL header IE is present. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1af60d0c886464ef6b01e449a34c6a937d` | `bool` Set to true to enable CSMA-CA for this packet, false to disable both CSMA backoff and CCA. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ad6994d824d77c981e4c492f2aeff4fd4` | `https://openthread.io/reference/struct/ot-radio-ie-info *` The pointer to the Time IE related information. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ae0ab658552f2c9baf0781752ee65d2be` | `union otRadioFrame::@15` The union of transmit and receive information for a radio frame. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ac1d787f53a2e1fd85082492e0dc7d129` | `bool` Indicates whether the frame is a retransmission or not. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a047842af5e062c68c9fba11e13c0a877` | `bool` Indicates whether frame counter and CSL IEs are properly updated in the header. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a797256de153f8d1192f8582114c8a778` | `bool` True if SubMac should skip the AES processing of this frame. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1aea7090ec6c1974d3201ee0dfab0c925e` | `uint16_t` Length of the PSDU. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ae89beb2d91bf3c23e274f48430ebc4db` | `uint8_t` Link Quality Indicator for received frames. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ad58843a28f1e1a6690827548ced85ed2` | `uint8_t` Maximum number of CSMA backoff attempts before declaring channel access failure. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ac663ec320ab9fe4c076e43e7d4c24c68` | `uint8_t` Maximum number of retries allowed after a transmission failure. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a6fc89e98cc7d4dab04eabdbda239a3de` | `uint8_t *` The PSDU. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a3345015f33ce097d4cba3ee38a16d2a5` | `uint8_t` Radio link type - should be ignored by radio driver. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a5bb7aa8af3467a0c2d845417e42c33e1` | `int8_t` Received signal strength indicator in dBm for received frames. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a0b2bcfe33a70990542d4563c042a635b` | `uint8_t` The RX channel after frame TX is done (after all frame retries - ack received, or timeout, or abort). | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ae9f324afe72a37c9e1038ab0f1abad30` | `struct otRadioFrame::@15::@17` Structure representing radio frame receive information. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1ad7dda44ddf8423630a492022f6cd8f3d` | `https://openthread.io/reference/group/radio-types#group__radio-types_1ga4b1723679c73d4b1cb45146bb29e8402` The time of the local radio clock in microseconds when the end of the SFD was present at the local antenna. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a761d50b08a6edd58cdc5bc7eb8d9dff5` | `uint32_t` The delay time in microseconds for a timed transmission referenced to `mTxDelayBaseTime`. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1aea3b25c765094ccb0ba1607b44fc30b9` | `https://openthread.io/reference/group/radio-types#group__radio-types_1ga44619e1e7b1ec8cdd464312687d4ff68` The base time in microseconds for timed transmissions relative to the local radio clock (see `https://openthread.io/reference/group/radio-config#group__radio-config_1gadd536021d7e30db21d42710879580370` and `mTxDelay`). | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1a1e4be33b3cbc31bcd74d40f15f346237` | `struct otRadioFrame::@15::@16` Structure representing radio frame transmit information. | | `https://openthread.io/reference/struct/ot-radio-frame#structot_radio_frame_1aa2bdc5e86b8f2298da588b494bef42ce` | `int8_t` The transmit power in dBm. | ## Public attributes ### mAckFrameCounter ``` uint32_t otRadioFrame::mAckFrameCounter ``` ACK security frame counter (applicable when `mAckedWithSecEnhAck` is set). ### mAckKeyId ``` uint8_t otRadioFrame::mAckKeyId ``` ACK security key index (applicable when `mAckedWithSecEnhAck` is set). ### mAckedWithFramePending ``` bool otRadioFrame::mAckedWithFramePending ``` This indicates if this frame was acknowledged with frame pending set. ### mAckedWithSecEnhAck ``` bool otRadioFrame::mAckedWithSecEnhAck ``` This indicates if this frame was acknowledged with secured enhance ACK. ### mAesKey ``` const otMacKeyMaterial * otRadioFrame::mAesKey ``` The key material used for AES-CCM frame security. ### mChannel ``` uint8_t otRadioFrame::mChannel ``` Channel used to transmit/receive the frame. ### mCslPresent ``` bool otRadioFrame::mCslPresent ``` Set to true if CSL header IE is present. ### mCsmaCaEnabled ``` bool otRadioFrame::mCsmaCaEnabled ``` Set to true to enable CSMA-CA for this packet, false to disable both CSMA backoff and CCA. When it is set to `false`, the frame MUST be sent without performing CCA. In this case `mMaxCsmaBackoffs` MUST also be ignored. ### mIeInfo ``` otRadioIeInfo * otRadioFrame::mIeInfo ``` The pointer to the Time IE related information. This field is only used when the experimental Time Synchronization feature is enabled via `OPENTHREAD_CONFIG_TIME_SYNC_ENABLE` and is ignored otherwise. When `OPENTHREAD_CONFIG_TIME_SYNC_ENABLE` is enabled, the radio platform MUST provide an `https://openthread.io/reference/struct/ot-radio-ie-info` structure and set this pointer on the transmit `https://openthread.io/reference/struct/ot-radio-frame` buffer returned to the OpenThread stack (e.g., via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1gaaeab4fb61100d446642492d8fbe58dea`). The OpenThread stack populates `*mIeInfo` when preparing a transmit frame, and the radio platform uses it (when `mTimeIeOffset != 0`) to update the Time IE in `mPsdu` before transmission. When this feature is disabled, this pointer will not be used and may be set to `NULL`. ### mInfo ``` union otRadioFrame::@15 otRadioFrame::mInfo ``` The union of transmit and receive information for a radio frame. ### mIsARetx ``` bool otRadioFrame::mIsARetx ``` Indicates whether the frame is a retransmission or not. ### mIsHeaderUpdated ``` bool otRadioFrame::mIsHeaderUpdated ``` Indicates whether frame counter and CSL IEs are properly updated in the header. If the platform layer does not provide `OT_RADIO_CAPS_TRANSMIT_SEC` capability, it can ignore this flag. If the platform provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability, then platform is expected to handle tx security processing and assignment of frame counter. In this case the following behavior is expected: When `mIsHeaderUpdated` is set, it indicates that OpenThread core has already set the frame counter and CSL IEs (if security is enabled) in the prepared frame. The counter is ensured to match the counter value from the previous attempts of the same frame. The platform should not assign or change the frame counter (but may still need to perform security processing depending on `mIsSecurityProcessed` flag). If `mIsHeaderUpdated` is not set, then the frame counter and key CSL IE not set in the frame by OpenThread core and it is the responsibility of the radio platform to assign them. The platform must update the frame header (assign counter and CSL IE values) before sending the frame over the air, however if the transmission gets aborted and the frame is never sent over the air (e.g., channel access error) the platform may choose to not update the header. If the platform updates the header, it must also set this flag in the frame before invoking the `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga3535ea41ed81d32998cce061d6f788fc` or `https://openthread.io/reference/group/radio-operation#group__radio-operation_1gab1c9f285cc97bdbef957c8f1d0bbb4ab` callback. ### mIsSecurityProcessed ``` bool otRadioFrame::mIsSecurityProcessed ``` True if SubMac should skip the AES processing of this frame. ### mLength ``` uint16_t otRadioFrame::mLength ``` Length of the PSDU. ### mLqi ``` uint8_t otRadioFrame::mLqi ``` Link Quality Indicator for received frames. ### mMaxCsmaBackoffs ``` uint8_t otRadioFrame::mMaxCsmaBackoffs ``` Maximum number of CSMA backoff attempts before declaring channel access failure. This is applicable and MUST be used when radio platform provides the `OT_RADIO_CAPS_CSMA_BACKOFF` and/or `OT_RADIO_CAPS_TRANSMIT_RETRIES`. This field MUST be ignored if `mCsmaCaEnabled` is set to `false` (CCA is disabled), if either `mTxDelayBaseTime` or `mTxDelay` is non-zero (frame transmission is expected at a specific time), or when the frame is scheduled for transmission via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga3f5c00536dbb219c1b571a01947a1c64`. It can be set to `0` to skip backoff mechanism (note that CCA MUST still be performed assuming `mCsmaCaEnabled` is `true`). ### mMaxFrameRetries ``` uint8_t otRadioFrame::mMaxFrameRetries ``` Maximum number of retries allowed after a transmission failure. This is applicable when the radio platform provides `OT_RADIO_CAPS_TRANSMIT_RETRIES` and the frame is transmitted via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1gadcd90257ecef86b069b91987c53da694`. It MUST be ignored when the frame is scheduled for transmission via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga3f5c00536dbb219c1b571a01947a1c64`. ### mPsdu ``` uint8_t * otRadioFrame::mPsdu ``` The PSDU. ### mRadioType ``` uint8_t otRadioFrame::mRadioType ``` Radio link type - should be ignored by radio driver. ### mRssi ``` int8_t otRadioFrame::mRssi ``` Received signal strength indicator in dBm for received frames. ### mRxChannelAfterTxDone ``` uint8_t otRadioFrame::mRxChannelAfterTxDone ``` The RX channel after frame TX is done (after all frame retries - ack received, or timeout, or abort). Radio platforms can choose to fully ignore this. OT stack will make sure to call `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga315627b370d8ff89ea101d6529911be7` with the desired RX channel after a frame TX is done and signaled in `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga3535ea41ed81d32998cce061d6f788fc` callback. Radio platforms that don't provide `OT_RADIO_CAPS_TRANSMIT_RETRIES` must always ignore this. This field MUST also be ignored when the frame is scheduled for transmission via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga3f5c00536dbb219c1b571a01947a1c64`. This is intended for situations where there may be delay in interactions between OT stack and radio, as an example this is used in RCP/host architecture to make sure RCP switches to PAN channel more quickly. In particular, this can help with CSL tx to a sleepy child, where the child may use a different channel for CSL than the PAN channel. After frame tx, we want the radio/RCP to go back to the PAN channel quickly to ensure that parent does not miss tx from child afterwards, e.g., child responding to the earlier CSL transmitted frame from parent using PAN channel while radio still staying on CSL channel. The switch to the RX channel MUST happen after the frame TX is fully done, i.e., after all retries and when ack is received (when "Ack Request" flag is set on the TX frame) or ack timeout. Note that ack is expected on the same channel that frame is sent on. ### mRxInfo ``` struct otRadioFrame::@15::@17 otRadioFrame::mRxInfo ``` Structure representing radio frame receive information. ### mTimestamp ``` otRadioTime64 otRadioFrame::mTimestamp ``` The time of the local radio clock in microseconds when the end of the SFD was present at the local antenna. The platform should update this field before `https://openthread.io/reference/group/radio-operation#group__radio-operation_1gae996f7f52b54a4e76c688c97aed770f3` is fired for each transmit attempt, or before `https://openthread.io/reference/group/radio-operation#group__radio-operation_1gab1c9f285cc97bdbef957c8f1d0bbb4ab` is invoked for a scheduled transmission. ### mTxDelay ``` uint32_t otRadioFrame::mTxDelay ``` The delay time in microseconds for a timed transmission referenced to `mTxDelayBaseTime`. This field is only applicable when the radio platform supports the `OT_RADIO_CAPS_TRANSMIT_TIMING` capability and the frame is transmitted via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1gadcd90257ecef86b069b91987c53da694`. It MUST be ignored when `OT_RADIO_CAPS_TRANSMIT_TIMING` is not supported or when the frame is scheduled for transmission via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga3f5c00536dbb219c1b571a01947a1c64`. Note: `mTxDelayBaseTime` + `mTxDelay` SHALL point to the point in time when the end of the SFD will be present at the local antenna, relative to the local radio clock. If this field is non-zero, `mMaxCsmaBackoffs` should be ignored. This field does not affect CCA behavior which is controlled by `mCsmaCaEnabled`. ### mTxDelayBaseTime ``` otRadioTime32 otRadioFrame::mTxDelayBaseTime ``` The base time in microseconds for timed transmissions relative to the local radio clock (see `https://openthread.io/reference/group/radio-config#group__radio-config_1gadd536021d7e30db21d42710879580370` and `mTxDelay`). This field is only applicable when the radio platform supports the `OT_RADIO_CAPS_TRANSMIT_TIMING` capability and the frame is transmitted via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1gadcd90257ecef86b069b91987c53da694`. It MUST be ignored when `OT_RADIO_CAPS_TRANSMIT_TIMING` is not supported or when the frame is scheduled for transmission via `https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga3f5c00536dbb219c1b571a01947a1c64`. If this field is non-zero, `mMaxCsmaBackoffs` should be ignored. This field does not affect CCA behavior which is controlled by `mCsmaCaEnabled`. ### mTxInfo ``` struct otRadioFrame::@15::@16 otRadioFrame::mTxInfo ``` Structure representing radio frame transmit information. ### mTxPower ``` int8_t otRadioFrame::mTxPower ``` The transmit power in dBm. If the platform layer does not provide `OT_RADIO_CAPS_TRANSMIT_FRAME_POWER` capability, it can ignore this value. If the value is OT_RADIO_POWER_INVALID, then the platform should ignore this value and transmit the frame with its default transmit power. Otherwise, the platform should transmit this frame with the maximum power no larger than minimal of the following values: 1. mTxPower, 2. The power limit set by [otPlatRadioSetChannelTargetPower()](https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga9b87f77c66eb512c675e7b61617149f6), 3. The power limit set by [otPlatRadioSetChannelMaxTransmitPower()](https://openthread.io/reference/group/radio-operation#group__radio-operation_1gaf61b533edd275c278263659f93b30b5b), 4. The power limit set by [otPlatRadioSetRegion()](https://openthread.io/reference/group/radio-operation#group__radio-operation_1ga28a3257e77a1ce655f488a9adc2e4927).
## Resources OpenThread API Reference topics originate from the source code, available on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread). For more information, or to contribute to our documentation, refer to [Resources](https://openthread.io/resources).