> Documentation index: https://openthread.io/reference/llms.txt

# Radio Operation

This module includes the platform abstraction for radio operations.

## Summary

| ### Functions ||
|---|---|
| `otPlatDiagRadioReceiveDone(otInstance *aInstance, otRadioFrame *aFrame, otError aError)` | `void` The radio driver calls this function to notify OpenThread diagnostics module of a received frame. |
| `otPlatDiagRadioTransmitDone(otInstance *aInstance, otRadioFrame *aFrame, otError aError)` | `void` The radio driver calls this function to notify OpenThread diagnostics module that the transmission has completed. |
| `otPlatRadioAddCalibratedPower(otInstance *aInstance, uint8_t aChannel, int16_t aActualPower, const uint8_t *aRawPowerSetting, uint16_t aRawPowerSettingLength)` | `otError` Add a calibrated power of the specified channel to the power calibration table. |
| `otPlatRadioAddSrcMatchExtEntry(otInstance *aInstance, const otExtAddress *aExtAddress)` | `otError` Add an extended address to the source address match table. |
| `otPlatRadioAddSrcMatchShortEntry(otInstance *aInstance, otShortAddress aShortAddress)` | `otError` Add a short address to the source address match table. |
| `otPlatRadioAvailabilityUpdated(otInstance *aInstance)` | `void` The radio driver calls this function to notify OpenThread that the radio availability has changed. |
| `otPlatRadioBusLatencyChanged(otInstance *aInstance)` | `void` The radio driver calls this function to notify OpenThread that the spinel bus latency has been changed. |
| `otPlatRadioCancelScheduledTx(otInstance *aInstance)` | `otError` Cancel a previously scheduled transmission. |
| `otPlatRadioClearCalibratedPowers(otInstance *aInstance)` | `otError` Clear all calibrated powers from the power calibration table. |
| `otPlatRadioClearSrcMatchExtEntries(otInstance *aInstance)` | `void` Clear all the extended/long addresses from source address match table. |
| `otPlatRadioClearSrcMatchExtEntry(otInstance *aInstance, const otExtAddress *aExtAddress)` | `otError` Remove an extended address from the source address match table. |
| `otPlatRadioClearSrcMatchShortEntries(otInstance *aInstance)` | `void` Clear all short addresses from the source address match table. |
| `otPlatRadioClearSrcMatchShortEntry(otInstance *aInstance, otShortAddress aShortAddress)` | `otError` Remove a short address from the source address match table. |
| `otPlatRadioConfigureEnhAckProbing(otInstance *aInstance, otLinkMetrics aLinkMetrics, otShortAddress aShortAddress, const otExtAddress *aExtAddress)` | `otError` Enable/disable or update Enhanced-ACK Based Probing in radio for a specific Initiator. |
| `otPlatRadioDisable(otInstance *aInstance)` | `otError` Disable the radio. |
| `otPlatRadioEnable(otInstance *aInstance)` | `otError` Enable the radio. |
| `otPlatRadioEnableCsl(otInstance *aInstance, uint32_t aCslPeriod, otShortAddress aShortAddr, const otExtAddress *aExtAddr)` | `otError` Enable or disable CSL receiver. |
| `otPlatRadioEnableSrcMatch(otInstance *aInstance, bool aEnable)` | `void` Enable/Disable source address match feature. |
| `otPlatRadioEnergyScan(otInstance *aInstance, uint8_t aScanChannel, uint16_t aScanDuration)` | `otError` Begin the energy scan sequence on the radio. |
| `otPlatRadioEnergyScanDone(otInstance *aInstance, int8_t aEnergyScanMaxRssi)` | `void` The radio driver calls this function to notify OpenThread that the energy scan is complete. |
| `otPlatRadioGetAvailability(otInstance *aInstance, otRadioAvailability *aAvailability)` | `otError` Gets the current radio availability schedule. |
| `otPlatRadioGetCoexMetrics(otInstance *aInstance, otRadioCoexMetrics *aCoexMetrics)` | `otError` Get the radio coexistence metrics. |
| `otPlatRadioGetCslAccuracy(otInstance *aInstance)` | `uint8_t` Get the current estimated worst case accuracy (maximum ± deviation from the nominal frequency) of the local radio clock in units of PPM. |
| `otPlatRadioGetCslUncertainty(otInstance *aInstance)` | `uint8_t` The fixed uncertainty (i.e. |
| `otPlatRadioGetPreferredChannelMask(otInstance *aInstance)` | `uint32_t` Gets the radio preferred channel mask that the device prefers to form on. |
| `otPlatRadioGetRawPowerSetting(otInstance *aInstance, uint8_t aChannel, uint8_t *aRawPowerSetting, uint16_t *aRawPowerSettingLength)` | `otError` Get the raw power setting for the given channel. |
| `otPlatRadioGetRegion(otInstance *aInstance, uint16_t *aRegionCode)` | `otError` Get the region code. |
| `otPlatRadioGetRssi(otInstance *aInstance)` | `int8_t` Return a recent RSSI measurement when the radio is in receive state. |
| `otPlatRadioGetScheduledTxFrame(otInstance *aInstance)` | `otRadioFrame *` Get the radio transmit frame buffer dedicated for scheduled transmissions (`otPlatRadioScheduleTx()`). |
| `otPlatRadioGetState(otInstance *aInstance)` | `otRadioState` Get current state of the radio. |
| `otPlatRadioGetSupportedChannelMask(otInstance *aInstance)` | `uint32_t` Get the radio supported channel mask that the device is allowed to be on. |
| `otPlatRadioGetTransmitBuffer(otInstance *aInstance)` | `otRadioFrame *` Get the radio transmit frame buffer. |
| `otPlatRadioIsCoexEnabled(otInstance *aInstance)` | `bool` Check whether radio coex is enabled or not. |
| `otPlatRadioIsEnabled(otInstance *aInstance)` | `bool` Check whether the radio is enabled or not. |
| `otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel)` | `otError` Transition the radio from Sleep to Receive (turn on the radio), or change the radio's receive channel. |
| `otPlatRadioReceiveAt(otInstance *aInstance, uint8_t aChannel, otRadioTime32 aStart, uint32_t aDuration)` | `otError` Schedules a radio reception window at a specific time and duration. |
| `otPlatRadioReceiveDone(otInstance *aInstance, otRadioFrame *aFrame, otError aError)` | `void` The radio driver calls this function to notify OpenThread of a received frame. |
| `otPlatRadioResetCsl(otInstance *aInstance)` | `otError` Reset CSL receiver in the platform. |
| `otPlatRadioScheduleTx(otInstance *aInstance, otRadioTime64 aTxTime)` | `otError` Schedule a radio frame transmission at a specific target time. |
| `otPlatRadioScheduledTxDone(otInstance *aInstance, otRadioFrame *aAckFrame, otError aError)` | `void` The radio driver calls this function to notify OpenThread that a scheduled transmission (initiated via `otPlatRadioScheduleTx()`) has completed, providing both the transmission outcome and, if applicable, the received acknowledgment frame. |
| `otPlatRadioSetChannelMaxTransmitPower(otInstance *aInstance, uint8_t aChannel, int8_t aMaxPower)` | `otError` Set the max transmit power for a specific channel. |
| `otPlatRadioSetChannelTargetPower(otInstance *aInstance, uint8_t aChannel, int16_t aTargetPower)` | `otError` Set the target power for the given channel. |
| `otPlatRadioSetCoexEnabled(otInstance *aInstance, bool aEnabled)` | `otError` Enable the radio coex. |
| `otPlatRadioSetRegion(otInstance *aInstance, uint16_t aRegionCode)` | `otError` Set the region code. |
| `otPlatRadioSleep(otInstance *aInstance)` | `otError` Transition the radio to the Sleep state (turn off the radio). |
| `otPlatRadioTransmit(otInstance *aInstance, otRadioFrame *aFrame)` | `otError` Begin the transmit sequence on the radio. |
| `otPlatRadioTxDone(otInstance *aInstance, otRadioFrame *aFrame, otRadioFrame *aAckFrame, otError aError)` | `void` The radio driver calls this function to notify OpenThread that the transmit operation has completed, providing both the transmitted frame and, if applicable, the received ack frame. |
| `otPlatRadioTxStarted(otInstance *aInstance, otRadioFrame *aFrame)` | `void` The radio driver calls this function to notify OpenThread that the transmission has started. |
| `otPlatRadioUpdateCslSampleTime(otInstance *aInstance, otRadioTime32 aCslSampleTime)` | `void` Update CSL sample time in radio driver. |

## Functions

### otPlatDiagRadioReceiveDone

```
void otPlatDiagRadioReceiveDone(
  otInstance *aInstance,
  otRadioFrame *aFrame,
  otError aError
)
```
The radio driver calls this function to notify OpenThread diagnostics module of a received frame.

<br />

> [!NOTE]
> **Note:** This function is deprecated and will be removed in the future. It is recommended to use the function `otPlatRadioReceiveDone()`.

Is used when diagnostics is enabled.

<br />


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aFrame` (as documented in `otPlatRadioReceiveDone()`) `[in] aError` (as documented in `otPlatRadioReceiveDone()`)

### otPlatDiagRadioTransmitDone

```
void otPlatDiagRadioTransmitDone(
  otInstance *aInstance,
  otRadioFrame *aFrame,
  otError aError
)
```
The radio driver calls this function to notify OpenThread diagnostics module that the transmission has completed.

<br />

> [!NOTE]
> **Note:** This function is deprecated and will be removed in the future. It is recommended to use the function `otPlatRadioTxDone()`.

Is used when diagnostics is enabled.

<br />


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aFrame` A pointer to the frame that was transmitted. `[in] aError` OT_ERROR_NONE when the frame was transmitted, OT_ERROR_CHANNEL_ACCESS_FAILURE tx could not take place due to activity on the channel, OT_ERROR_ABORT when transmission was aborted for other reasons.

### otPlatRadioAddCalibratedPower

```
otError otPlatRadioAddCalibratedPower(
  otInstance *aInstance,
  uint8_t aChannel,
  int16_t aActualPower,
  const uint8_t *aRawPowerSetting,
  uint16_t aRawPowerSettingLength
)
```
Add a calibrated power of the specified channel to the power calibration table.

<br />

> [!NOTE]
> **Note:** This API is an optional radio platform API. It's up to the platform layer to implement it.

The `aActualPower` is the actual measured output power when the parameters of the radio hardware modules are set to the `aRawPowerSetting`.

<br />

The raw power setting is an opaque byte array. OpenThread doesn't define the format of the raw power setting. Its format is radio hardware related and it should be defined by the developers in the platform radio driver. For example, if the radio hardware contains both the radio chip and the FEM chip, the raw power setting can be a combination of the radio power register and the FEM gain value.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aChannel` The radio channel. `[in] aActualPower` The actual power in 0.01dBm. `[in] aRawPowerSetting` A pointer to the raw power setting byte array. `[in] aRawPowerSettingLength` The length of the `aRawPowerSetting`. Return Values `OT_ERROR_NONE` Successfully added the calibrated power to the power calibration table. `OT_ERROR_NO_BUFS` No available entry in the power calibration table. `OT_ERROR_INVALID_ARGS` The `aChannel`, `aActualPower` or `aRawPowerSetting` is invalid or the `aActualPower` already exists in the power calibration table. `OT_ERROR_NOT_IMPLEMENTED` This feature is not implemented.

### otPlatRadioAddSrcMatchExtEntry

```
otError otPlatRadioAddSrcMatchExtEntry(
  otInstance *aInstance,
  const otExtAddress *aExtAddress
)
```
Add an extended address to the source address match table.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aExtAddress` The extended address to be added stored in little-endian byte order. Return Values `OT_ERROR_NONE` Successfully added extended address to the source match table. `OT_ERROR_NO_BUFS` No available entry in the source match table.

### otPlatRadioAddSrcMatchShortEntry

```
otError otPlatRadioAddSrcMatchShortEntry(
  otInstance *aInstance,
  otShortAddress aShortAddress
)
```
Add a short address to the source address match table.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aShortAddress` The short address to be added. Return Values `OT_ERROR_NONE` Successfully added short address to the source match table. `OT_ERROR_NO_BUFS` No available entry in the source match table.

### otPlatRadioAvailabilityUpdated

```
void otPlatRadioAvailabilityUpdated(
  otInstance *aInstance
)
```
The radio driver calls this function to notify OpenThread that the radio availability has changed.

When Thread shares the same radio chip with BT or 2.4GHz WiFi, the radio driver knows when BT or WiFi will occupy the radio. The radio driver calls this function to notify OpenThread, which then retrieves the current schedule via `otPlatRadioGetAvailability()`. The radio availability schedule is intended to be used for Thread Direct scheduling. OpenThread does not use it to perform general radio coexistence.

The radio driver should call this function once the radio is enabled (see `otPlatRadioEnable()`) to report the initial radio availability schedule, and whenever the radio availability schedule changes thereafter.

A radio driver that calls this function MUST implement `otPlatRadioGetAvailability()`.


> [!NOTE]
> **Note:** This function should be called by the same thread that executes all of the other OpenThread code. It should not be called by ISR or any other task.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure.

### otPlatRadioBusLatencyChanged

```
void otPlatRadioBusLatencyChanged(
  otInstance *aInstance
)
```
The radio driver calls this function to notify OpenThread that the spinel bus latency has been changed.


Details Parameters `[in] aInstance` The OpenThread instance structure.

### otPlatRadioCancelScheduledTx

```
otError otPlatRadioCancelScheduledTx(
  otInstance *aInstance
)
```
Cancel a previously scheduled transmission.

This API requires the radio platform to support the `OT_RADIO_CAPS_SCHEDULED_TX` capability.


- If there is no pending scheduled transmission (e.g., none was scheduled, or a previous schedule was already canceled or completed), calling this function MUST take no action and return `OT_ERROR_NONE`.
- If a scheduled transmission is pending and can still be aborted before transmission starts on the air, the radio platform MUST cancel it, release ownership of the scheduled TX frame buffer (`otPlatRadioGetScheduledTxFrame()`) back to the OpenThread stack, and return `OT_ERROR_NONE`. The radio platform MUST NOT invoke `otPlatRadioScheduledTxDone()` for a canceled transmission.
- When `otPlatRadioCancelScheduledTx()` returns `OT_ERROR_NONE`, the OpenThread stack immediately reclaims ownership of the scheduled TX frame buffer and may immediately prepare a new frame in that buffer and call `otPlatRadioScheduleTx()` to schedule a new transmission.
- If the radio platform cannot cancel the scheduled transmission (for example, because the transmission has already started and is currently in progress on the air or waiting for an acknowledgment, or because an `OT_ERROR_ABORT` completion is already queued to be reported), it MUST return `OT_ERROR_BUSY`. In this case:
  - The scheduled transmission is NOT canceled, and the radio platform retains ownership of the scheduled TX frame buffer.
  - The radio platform MUST subsequently report the outcome of the transmission via the `otPlatRadioScheduledTxDone()` callback.
  - The OpenThread stack will wait until `otPlatRadioScheduledTxDone()` is invoked before modifying the scheduled TX frame buffer or scheduling a new transmission.
- Note that if a deferred `OT_ERROR_ABORT` callback is pending (e.g., due to a past/missed target time or Coex denial), the radio platform handles `otPlatRadioCancelScheduledTx()` in one of these two ways: either cancel the pending callback and return `OT_ERROR_NONE`, or return `OT_ERROR_BUSY` and let the `otPlatRadioScheduledTxDone()` callback be invoked.

<br />


Details Parameters `[in] aInstance` The OpenThread instance structure. Return Values `OT_ERROR_NONE` Successfully canceled the scheduled transmission (or no scheduled transmission was pending). `OT_ERROR_BUSY` The scheduled transmission has already started and could not be canceled.

### otPlatRadioClearCalibratedPowers

```
otError otPlatRadioClearCalibratedPowers(
  otInstance *aInstance
)
```
Clear all calibrated powers from the power calibration table.


> [!NOTE]
> **Note:** This API is an optional radio platform API. It's up to the platform layer to implement it.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. Return Values `OT_ERROR_NONE` Successfully cleared all calibrated powers from the power calibration table. `OT_ERROR_NOT_IMPLEMENTED` This feature is not implemented.

### otPlatRadioClearSrcMatchExtEntries

```
void otPlatRadioClearSrcMatchExtEntries(
  otInstance *aInstance
)
```
Clear all the extended/long addresses from source address match table.


Details Parameters `[in] aInstance` The OpenThread instance structure.

### otPlatRadioClearSrcMatchExtEntry

```
otError otPlatRadioClearSrcMatchExtEntry(
  otInstance *aInstance,
  const otExtAddress *aExtAddress
)
```
Remove an extended address from the source address match table.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aExtAddress` The extended address to be removed stored in little-endian byte order. Return Values `OT_ERROR_NONE` Successfully removed the extended address from the source match table. `OT_ERROR_NO_ADDRESS` The extended address is not in source address match table.

### otPlatRadioClearSrcMatchShortEntries

```
void otPlatRadioClearSrcMatchShortEntries(
  otInstance *aInstance
)
```
Clear all short addresses from the source address match table.


Details Parameters `[in] aInstance` The OpenThread instance structure.

### otPlatRadioClearSrcMatchShortEntry

```
otError otPlatRadioClearSrcMatchShortEntry(
  otInstance *aInstance,
  otShortAddress aShortAddress
)
```
Remove a short address from the source address match table.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aShortAddress` The short address to be removed. Return Values `OT_ERROR_NONE` Successfully removed short address from the source match table. `OT_ERROR_NO_ADDRESS` The short address is not in source address match table.

### otPlatRadioConfigureEnhAckProbing

```
otError otPlatRadioConfigureEnhAckProbing(
  otInstance *aInstance,
  otLinkMetrics aLinkMetrics,
  otShortAddress aShortAddress,
  const otExtAddress *aExtAddress
)
```
Enable/disable or update Enhanced-ACK Based Probing in radio for a specific Initiator.

After Enhanced-ACK Based Probing is configured by a specific Probing Initiator, the Enhanced-ACK sent to that node should include Vendor-Specific IE containing Link Metrics data. This function informs the radio to start/stop to collect Link Metrics data and include Vendor-Specific IE that containing the data in Enhanced-ACK sent to that Probing Initiator.

Regarding `aExtAddress`, this function assumes big-endian byte order. Note that this differs from `otPlatRadioSetExtendedAddress()`, `otPlatRadioAddSrcMatchExtEntry()`, and `otPlatRadioClearSrcMatchExtEntry()`, which use little-endian byte order for the Extended MAC address.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aLinkMetrics` This parameter specifies what metrics to query. Per spec 4.11.3.4.4.6, at most 2 metrics can be specified. The probing would be disabled if `` `aLinkMetrics` `` is bitwise 0. `[in] aShortAddress` The short address of the Probing Initiator. `[in] aExtAddress` The extended source address of the Probing Initiator. `aExtAddress` MUST NOT be `NULL`. The `aExtAddress` assumes big-endian byte order. Return Values `OT_ERROR_NONE` Successfully configured the Enhanced-ACK Based Probing. `OT_ERROR_INVALID_ARGS` `aExtAddress` is `NULL`. `OT_ERROR_NOT_FOUND` The Initiator indicated by `aShortAddress` is not found when trying to clear. `OT_ERROR_NO_BUFS` No more Initiator can be supported. `OT_ERROR_NOT_IMPLEMENTED` The feature is not implemented.

### otPlatRadioDisable

```
otError otPlatRadioDisable(
  otInstance *aInstance
)
```
Disable the radio.

If the radio is already disabled, this function MUST return `OT_ERROR_NONE` with no effect. Otherwise, the radio MUST be in the Sleep state, or have a pending transition to Sleep (see `otPlatRadioSleep()`), for it to be disabled successfully.

Disabling the radio MUST be enacted as soon as possible, aborting any ongoing or scheduled operations. (Ongoing operations may exist during a pending transition to Sleep state.) These aborted ongoing operations MUST NOT lead to any callback functions (like `otPlatRadio...Done()`) being called. When this function returns successfully, the radio MUST be in state `OT_RADIO_STATE_DISABLED`.


Details Parameters `[in] aInstance` The OpenThread instance structure. Return Values `OT_ERROR_NONE` Successfully transitioned to Disabled, or was already Disabled. `OT_ERROR_INVALID_STATE` The radio is neither in Sleep state nor transitioning to Sleep state.

### otPlatRadioEnable

```
otError otPlatRadioEnable(
  otInstance *aInstance
)
```
Enable the radio.

If the radio is already enabled, this function MUST return `OT_ERROR_NONE` with no effect.

When the radio is enabled and address filtering is active (i.e., promiscuous mode is disabled; see `otPlatRadioSetPromiscuous()`), the radio platform is expected to perform the following address filtering behaviors:


- Accept received Data and MAC Command frames that have no destination address (Destination Addressing Mode = `0b00`), in addition to Beacon frames and frames addressed to the broadcast address (`0xffff`) or matching the short address (or alternate short address) or extended address configured via `otPlatRadioSetShortAddress()`, `otPlatRadioSetAlternateShortAddress()`, and `otPlatRadioSetExtendedAddress()`.
- Check a received frame's Destination PAN ID against the PAN ID configured via `otPlatRadioSetPanId()` (or the broadcast PAN ID `0xffff`) only when a Destination PAN ID field is present in the frame. Frames that omit the Destination PAN ID field MUST NOT be rejected due to PAN ID mismatch, and the Source PAN ID (if present) MUST NOT be checked against the configured PAN ID.
- Thread frames that omit the destination address (Destination Addressing Mode = `0b00`) always have the Acknowledgment Request (`AR`) bit set to `0`. Received frames with no destination address (Destination Addressing Mode = `0b00`) SHOULD NOT be acknowledged, even if the `AR` bit is set to `1`.

<br />

Address filtering is required by the radio platform for auto-ACK generation. While filtering received frames in the radio platform before calling `otPlatRadioReceiveDone()` is not strictly required (as the OpenThread `Mac` layer also performs address filtering on received frames), it is recommended (especially on RCP platforms to avoid forwarding unaddressed frames over Spinel to the host), and whenever performed by the radio platform, it MUST follow the rules above.


> [!NOTE]
> **Note:** On some IEEE 802.15.4 radio hardware or drivers (e.g., `nrf_802154`), accepting Data and MAC Command frames with no destination address (Destination Addressing Mode = `0b00`) requires enabling PAN Coordinator mode (`macPanCoord = true`). When using such a hardware filter, platform implementations should ensure that it does not reject frames whose Source PAN ID differs from the configured PAN ID when the Destination PAN ID is omitted, and should suppress auto-ACK generation for frames with Destination Addressing Mode = `0b00` even when `AR = 1`.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. Return Values `OT_ERROR_NONE` Successfully enabled or is already enabled. `OT_ERROR_FAILED` The radio could not be enabled. **See also:**   
[otPlatRadioSetPanId()](https://openthread.io/reference/group/radio-config.md.txt#group__radio-config_1ga032e75b6d174c7cb58e8c280fdcd5f26)   
[otPlatRadioSetExtendedAddress()](https://openthread.io/reference/group/radio-config.md.txt#group__radio-config_1ga62cdcfe3e94da49f13f358942a794955)   
[otPlatRadioSetShortAddress()](https://openthread.io/reference/group/radio-config.md.txt#group__radio-config_1ga5cec7c711f3f1e21e7ce83e8019a3332)   
[otPlatRadioSetAlternateShortAddress()](https://openthread.io/reference/group/radio-config.md.txt#group__radio-config_1ga07a7661481c26263f299933e5b0b1857)   
[otPlatRadioSetPromiscuous()](https://openthread.io/reference/group/radio-config.md.txt#group__radio-config_1ga0a905ad5c76c5931ee2ef395342f0dca)   

### otPlatRadioEnableCsl

```
otError otPlatRadioEnableCsl(
  otInstance *aInstance,
  uint32_t aCslPeriod,
  otShortAddress aShortAddr,
  const otExtAddress *aExtAddr
)
```
Enable or disable CSL receiver.

Regarding `aExtAddr`, this function assumes big-endian byte order. Note that this differs from `otPlatRadioSetExtendedAddress()`, `otPlatRadioAddSrcMatchExtEntry()`, and `otPlatRadioClearSrcMatchExtEntry()`, which use little-endian byte order for the Extended MAC address.


> [!NOTE]
> **Note:** Platforms should use CSL peer addresses to include CSL IE when generating enhanced acks.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aCslPeriod` CSL period, 0 for disabling CSL. CSL period is in unit of 10 symbols. `[in] aShortAddr` The short source address of CSL receiver's peer. `[in] aExtAddr` The extended source address of CSL receiver's peer. The `aExtAddr` assumes big-endian byte order. Return Values `OT_ERROR_NOT_IMPLEMENTED` Radio driver doesn't support CSL. `OT_ERROR_FAILED` Other platform specific errors. `OT_ERROR_NONE` Successfully enabled or disabled CSL.

### otPlatRadioEnableSrcMatch

```
void otPlatRadioEnableSrcMatch(
  otInstance *aInstance,
  bool aEnable
)
```
Enable/Disable source address match feature.

The source address match feature controls how the radio layer decides the "frame pending" bit for acks sent in response to data request commands from children.

If disabled, the radio layer must set the "frame pending" on all acks to data request commands.

If enabled, the radio layer uses the source address match table to determine whether to set or clear the "frame
pending" bit in an ack to a data request command.

The source address match table provides the list of children for which there is a pending frame. Either a short address or an extended/long address can be added to the source address match table.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aEnable` Enable/disable source address match feature.

### otPlatRadioEnergyScan

```
otError otPlatRadioEnergyScan(
  otInstance *aInstance,
  uint8_t aScanChannel,
  uint16_t aScanDuration
)
```
Begin the energy scan sequence on the radio.

Is used when radio provides OT_RADIO_CAPS_ENERGY_SCAN capability.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aScanChannel` The channel to perform the energy scan on. `[in] aScanDuration` The duration, in milliseconds, for the channel to be scanned. Return Values `OT_ERROR_NONE` Successfully started scanning the channel. `OT_ERROR_BUSY` The radio is performing energy scanning. `OT_ERROR_NOT_IMPLEMENTED` The radio doesn't support energy scanning.

### otPlatRadioEnergyScanDone

```
void otPlatRadioEnergyScanDone(
  otInstance *aInstance,
  int8_t aEnergyScanMaxRssi
)
```
The radio driver calls this function to notify OpenThread that the energy scan is complete.

Is used when radio provides OT_RADIO_CAPS_ENERGY_SCAN capability.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aEnergyScanMaxRssi` The maximum RSSI encountered on the scanned channel.

### otPlatRadioGetAvailability

```
otError otPlatRadioGetAvailability(
  otInstance *aInstance,
  otRadioAvailability *aAvailability
)
```
Gets the current radio availability schedule.

OpenThread (the caller) provides the `otRadioAvailability` structure pointed to by `aAvailability`, and the radio driver populates all of its fields, including copying the bitmaps into it. OpenThread owns the structure, so the radio driver does not need to keep any buffer valid after this function returns.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[out] aAvailability` A pointer to an `otRadioAvailability` structure to populate. Return Values `OT_ERROR_NONE` Successfully retrieved the radio availability schedule. `OT_ERROR_NOT_IMPLEMENTED` The radio driver does not support reporting radio availability.

### otPlatRadioGetCoexMetrics

```
otError otPlatRadioGetCoexMetrics(
  otInstance *aInstance,
  otRadioCoexMetrics *aCoexMetrics
)
```
Get the radio coexistence metrics.

Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[out] aCoexMetrics` A pointer to the coexistence metrics structure. Return Values `OT_ERROR_NONE` Successfully retrieved the coex metrics. `OT_ERROR_INVALID_ARGS` `aCoexMetrics` was NULL.

### otPlatRadioGetCslAccuracy

```
uint8_t otPlatRadioGetCslAccuracy(
  otInstance *aInstance
)
```
Get the current estimated worst case accuracy (maximum ± deviation from the nominal frequency) of the local radio clock in units of PPM.

This is the clock used to schedule CSL operations.

<br />

> [!NOTE]
> **Note:** Implementations MAY estimate this value based on current operating conditions (e.g. temperature).

In case the implementation does not estimate the current value but returns a fixed value, this value MUST be the worst-case accuracy over all possible foreseen operating conditions (temperature, pressure, etc) of the implementation.

<br />


Details Parameters `[in] aInstance` A pointer to an OpenThread instance. **Returns** The current CSL rx/tx scheduling drift, in PPM.

### otPlatRadioGetCslUncertainty

```
uint8_t otPlatRadioGetCslUncertainty(
  otInstance *aInstance
)
```
The fixed uncertainty (i.e.

random jitter) of the arrival time of CSL transmissions received by this device in units of 10 microseconds.

This designates the worst case constant positive or negative deviation of the actual arrival time of a transmission from the transmission time calculated relative to the local radio clock independent of elapsed time. In addition to uncertainty accumulated over elapsed time, the CSL channel sample ("RX window") must be extended by twice this deviation such that an actual transmission is guaranteed to be detected by the local receiver in the presence of random arrival time jitter.


Details Parameters `[in] aInstance` A pointer to an OpenThread instance. **Returns** The CSL Uncertainty in units of 10 us.

### otPlatRadioGetPreferredChannelMask

```
uint32_t otPlatRadioGetPreferredChannelMask(
  otInstance *aInstance
)
```
Gets the radio preferred channel mask that the device prefers to form on.


Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** The radio preferred channel mask.

### otPlatRadioGetRawPowerSetting

```
otError otPlatRadioGetRawPowerSetting(
  otInstance *aInstance,
  uint8_t aChannel,
  uint8_t *aRawPowerSetting,
  uint16_t *aRawPowerSettingLength
)
```
Get the raw power setting for the given channel.

<br />

> [!NOTE]
> **Note:** OpenThread `src/core/utils` implements a default implementation of the API `otPlatRadioAddCalibratedPower()`, `otPlatRadioClearCalibratedPowers()` and `otPlatRadioSetChannelTargetPower()`. This API is provided by the default implementation to get the raw power setting for the given channel. If the platform doesn't use the default implementation, it can ignore this API.

Platform radio layer should parse the raw power setting based on the radio layer defined format and set the parameters of each radio hardware module.

<br />


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aChannel` The radio channel. `[out] aRawPowerSetting` A pointer to the raw power setting byte array. `[in,out] aRawPowerSettingLength` On input, a pointer to the size of `aRawPowerSetting`. On output, a pointer to the length of the raw power setting data. Return Values `OT_ERROR_NONE` Successfully got the target power. `OT_ERROR_INVALID_ARGS` The `aChannel` is invalid, `aRawPowerSetting` or `aRawPowerSettingLength` is NULL or is too short. `OT_ERROR_NOT_FOUND` The raw power setting for the `aChannel` was not found.

### otPlatRadioGetRegion

```
otError otPlatRadioGetRegion(
  otInstance *aInstance,
  uint16_t *aRegionCode
)
```
Get the region code.

The radio region format is the 2-bytes ascii representation of the ISO 3166 alpha-2 code.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[out] aRegionCode` The radio region. Return Values `OT_ERROR_INVALID_ARGS` `aRegionCode` is NULL. `OT_ERROR_FAILED` Other platform specific errors. `OT_ERROR_NONE` Successfully got region code. `OT_ERROR_NOT_IMPLEMENTED` The feature is not implemented.

### otPlatRadioGetRssi

```
int8_t otPlatRadioGetRssi(
  otInstance *aInstance
)
```
Return a recent RSSI measurement when the radio is in receive state.

If the radio is not in receive state, then `OT_RADIO_RSSI_INVALID` MUST be returned. If the radio is in receive state, then a single RSSI measurement is taken on the current receive channel and returned.


Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** The RSSI in dBm when it is valid. `OT_RADIO_RSSI_INVALID` when RSSI is invalid.

### otPlatRadioGetScheduledTxFrame

```
otRadioFrame * otPlatRadioGetScheduledTxFrame(
  otInstance *aInstance
)
```
Get the radio transmit frame buffer dedicated for scheduled transmissions (`otPlatRadioScheduleTx()`).

This API requires the radio platform to support the `OT_RADIO_CAPS_SCHEDULED_TX` capability.

Similar to how `otPlatRadioGetTransmitBuffer()` provides the `otRadioFrame` buffer used for regular transmissions via `otPlatRadioTransmit()`, this function provides a separate, single `otRadioFrame` buffer used exclusively for scheduled transmissions via `otPlatRadioScheduleTx()`. Having a dedicated frame buffer allows the OpenThread stack to prepare and schedule a future timed transmission independently of ongoing or regular transmissions via `otPlatRadioTransmit()`.

Frame buffer ownership and lifecycle:

- The OpenThread stack forms the IEEE 802.15.4 frame in this buffer and then calls `otPlatRadioScheduleTx()` to schedule its transmission.
- Upon a successful call to `otPlatRadioScheduleTx()` (returning `OT_ERROR_NONE`), the radio platform takes ownership of this frame buffer. The OpenThread stack guarantees that it will not modify or access the frame buffer or its PSDU content while it is owned by the radio platform.
- Ownership of the frame buffer is released back to the OpenThread stack when:
  1. The radio platform invokes the `otPlatRadioScheduledTxDone()` callback,
  2. A call to `otPlatRadioCancelScheduledTx()` succeeds (returning `OT_ERROR_NONE`), or
  3. The radio is disabled via `otPlatRadioDisable()`.
- Once ownership is released back to OpenThread, the stack may immediately modify the buffer to prepare and schedule a new transmission (including directly from within the `otPlatRadioScheduledTxDone()` callback).
- The returned `otRadioFrame` pointer (and its `mPsdu` buffer of at least `OT_RADIO_FRAME_MAX_SIZE` bytes) MUST remain valid and constant for the lifetime of `aInstance` (including before `otPlatRadioEnable()` is called).

<br />


Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** A pointer to the scheduled transmit frame buffer.

### otPlatRadioGetState

```
otRadioState otPlatRadioGetState(
  otInstance *aInstance
)
```
Get current state of the radio.

Is not required by OpenThread. It may be used for debugging and/or application-specific purposes.


> [!NOTE]
> **Note:** This function may be not implemented. It does not affect OpenThread.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** Current state of the radio.

### otPlatRadioGetSupportedChannelMask

```
uint32_t otPlatRadioGetSupportedChannelMask(
  otInstance *aInstance
)
```
Get the radio supported channel mask that the device is allowed to be on.


Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** The radio supported channel mask.

### otPlatRadioGetTransmitBuffer

```
otRadioFrame * otPlatRadioGetTransmitBuffer(
  otInstance *aInstance
)
```
Get the radio transmit frame buffer.

OpenThread forms the IEEE 802.15.4 frame in this buffer then calls `otPlatRadioTransmit()` to request transmission.


Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** A pointer to the transmit frame buffer.

### otPlatRadioIsCoexEnabled

```
bool otPlatRadioIsCoexEnabled(
  otInstance *aInstance
)
```
Check whether radio coex is enabled or not.

Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled.


Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** TRUE if the radio coex is enabled, FALSE otherwise.

### otPlatRadioIsEnabled

```
bool otPlatRadioIsEnabled(
  otInstance *aInstance
)
```
Check whether the radio is enabled or not.


Details Parameters `[in] aInstance` The OpenThread instance structure. **Returns** TRUE if the radio is enabled, FALSE otherwise.

### otPlatRadioReceive

```
otError otPlatRadioReceive(
  otInstance *aInstance,
  uint8_t aChannel
)
```
Transition the radio from Sleep to Receive (turn on the radio), or change the radio's receive channel.

If the radio is already in Receive state on `aChannel`, this function MUST return `OT_ERROR_NONE` with no effect other than canceling any pending transition to Sleep (see `otPlatRadioSleep()`) or any pending channel change.

If `aChannel` differs from the current receive channel, the radio MUST transition to the newly requested channel as soon as possible if the radio is idle (not in a receive operation) on its current receive channel. If the radio is receiving a frame or transmitting an ACK, the ongoing receive operation SHOULD be completed first before switching to `aChannel`. In this case, the channel change is scheduled to occur right after the receive operation is done. In the exceptional case that a frame receive operation is aborted, this event MAY be reported via `otPlatRadioReceiveDone()` with `aError` set to `OT_ERROR_ABORT` (or the callback MAY be omitted).


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aChannel` The channel to use for receiving. Return Values `OT_ERROR_NONE` Successfully transitioned to Receive on channel `aChannel`, or was already receiving on `aChannel`, or successfully scheduled the transition to Receive on channel `aChannel` after the ongoing operation on the current channel completes. `OT_ERROR_INVALID_STATE` The radio was disabled or transmitting.

### otPlatRadioReceiveAt

```
otError otPlatRadioReceiveAt(
  otInstance *aInstance,
  uint8_t aChannel,
  otRadioTime32 aStart,
  uint32_t aDuration
)
```
Schedules a radio reception window at a specific time and duration.

This function is an optional platform API used to schedule a future reception window on a specific channel for features such as Coordinated Sampled Listening (CSL) or Thread Direct.

OpenThread supports two approaches for timed reception:


- Software-driven (default and recommended): OpenThread's `SubMac` layer manages all timed RX internally using software timers and standard `otPlatRadioReceive()` and `otPlatRadioSleep()` calls. In this mode, the radio platform does NOT need to implement `otPlatRadioReceiveAt()`, and MUST omit the `OT_RADIO_CAPS_RECEIVE_TIMING` capability from `otPlatRadioGetCaps()`.
- Platform-offloaded (optional): The radio platform explicitly declares `OT_RADIO_CAPS_RECEIVE_TIMING` via `otPlatRadioGetCaps()` and implements `otPlatRadioReceiveAt()` to handle window timing directly in the platform layer or hardware.

<br />

Because OpenThread's built-in `SubMac` software implementation is comprehensive, robust, and fully tested, it is strongly recommended that radio platform implementers rely on the default software-driven mode and do NOT implement `otPlatRadioReceiveAt()`, unless there is a clear justification for offloading timed reception to the radio platform.

If the radio platform implements this function, the following rules and behaviors are expected:

If this function is called while the radio is disabled (`OT_RADIO_STATE_DISABLED`), the radio platform MUST return `OT_ERROR_INVALID_STATE`.

When the radio is enabled, this function can be called from any radio state (`OT_RADIO_STATE_SLEEP`, `OT_RADIO_STATE_RECEIVE`, or `OT_RADIO_STATE_TRANSMIT`). The radio platform driver MUST handle the scheduling internally: calling this function merely registers a (future) time window for the radio to sample/receive and MUST NOT immediately force the radio into Receive mode at the time of the call (unless the window is already active).

The radio platform MUST execute the scheduled reception as follows:


- Operational Precedence and Radio Sleep:
  - Timed reception scheduled by this function is only applicable when the radio is in the Sleep state (whether the radio is put to sleep explicitly via `otPlatRadioSleep()` or manages sleep state automatically on its own).
  - Any active radio operation, such as transmission (`otPlatRadioTransmit()` or an active scheduled transmission from `otPlatRadioScheduleTx()`) or continuous reception (`otPlatRadioReceive()`), takes precedence over timed reception.
- Starting the Reception Window:
  - At the scheduled start time `aStart`, the radio receiver MUST enter Receive mode on channel `aChannel`, provided the radio is not busy with another operation. This MUST behave the same as if `otPlatRadioReceive()` were called at that time.
  - The OpenThread stack already accounts for and includes any necessary radio ramp-up and receiver settling time when computing `aStart`. Therefore, the radio platform driver does not need to adjust `aStart` or schedule ramp-up ahead of time.
- Ending the Reception Window:
  - At the end of the duration (`aStart` + `aDuration`), the radio MUST automatically transition back to Sleep unless it is actively receiving a frame.
  - If frame reception has started (e.g., SHR detected) before the duration expires, the radio receiver MUST remain on until the frame reception completes (either successfully or with an error) and any subsequent acknowledgment transmission is finished, after which the radio transitions to Sleep.
- Subsequent Schedules and Overlapping Windows:
  - If the start time of a previously scheduled reception window has not yet arrived, a subsequent call to `otPlatRadioReceiveAt()` MUST cancel and replace the previous schedule.
  - If a previous reception window has already started and is currently active:
    - A subsequent call to `otPlatRadioReceiveAt()` with a future start time MUST NOT abort or interrupt the ongoing reception. The new window is scheduled to start at its specified time.
    - At the start time of the new window (or immediately if its start time has already arrived), the radio MUST honor the new window:
      - Channel: If the new window specifies the same channel, reception SHOULD continue seamlessly without toggling the receiver state off and on. If the new window specifies a different channel, the radio MUST switch to the new channel. However, if the radio has started receiving a frame on the previous channel (e.g., SHR detected) or is transmitting an acknowledgment, it MUST complete the frame reception and any acknowledgment transmission before switching to the new channel (or transitioning to Sleep if the new window has already expired).
      - End time: The reception window MUST end according to the new window (`aStart` + `aDuration`). The new window always dictates when reception ends, replacing any previous end time. Note that this behavior is common and often used to shrink an ongoing sample window.
  - If a new window starts immediately upon the end of the previous window (back-to-back), the transition SHOULD occur seamlessly without cycling the radio through Sleep.
- Interactions with Sleep and Other Operations:
  - If the radio is busy executing another operation (such as transmission or continuous reception) when the scheduled window starts or while it is active, that operation takes precedence. Once that operation completes and the radio returns to Sleep, if the scheduled window is still ongoing (before `aStart` + `aDuration`), the radio SHOULD start or resume the scheduled timed reception by entering Receive mode on `aChannel` for the remaining duration of the window.
  - Calls to `otPlatRadioSleep()` MUST NOT cancel a scheduled reception window, nor abort an ongoing active timed reception window. If the radio is already in the Sleep state and performing an active scheduled timed reception, subsequent calls to `otPlatRadioSleep()` MUST NOT interrupt or alter its operation.
  - Calls to `otPlatRadioDisable()` MUST immediately abort and cancel any pending (scheduled) or ongoing active timed reception window.

<br />


> [!NOTE]
> **Note:** While `otPlatRadioGetNow()` returns a 64-bit timestamp (`otRadioTime64`), `aStart` is a 32-bit value (`otRadioTime32`) representing the lower 32 bits of the radio clock. Radio platform drivers MUST account for 32-bit roll-over when scheduling and evaluating reception window timing (e.g., determining whether `aStart` has arrived or `aStart` + `aDuration` has elapsed).

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aChannel` The radio channel on which to receive. `[in] aStart` The receive window start time relative to the local radio clock (see `otPlatRadioGetNow()`), representing the lower 32 bits of the radio clock. `[in] aDuration` The receive window duration in microseconds. Return Values `OT_ERROR_NONE` Successfully scheduled receive window. `OT_ERROR_FAILED` The receive window could not be scheduled. `OT_ERROR_INVALID_STATE` The radio is disabled. `OT_ERROR_INVALID_ARGS` Invalid arguments provided (e.g., invalid channel).

### otPlatRadioReceiveDone

```
void otPlatRadioReceiveDone(
  otInstance *aInstance,
  otRadioFrame *aFrame,
  otError aError
)
```
The radio driver calls this function to notify OpenThread of a received frame.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aFrame` A pointer to the received frame when `aError` is `OT_ERROR_NONE`, or NULL if the receive operation failed, was aborted, or resulted in an invalid frame. `[in] aError` OT_ERROR_NONE when successfully received a frame, OT_ERROR_ABORT when reception was aborted and a frame was not (fully) received, OT_ERROR_NO_BUFS when a frame could not be received due to lack of rx buffer space, OT_ERROR_FCS when a frame was received with an invalid FCS, OT_ERROR_NO_FRAME_RECEIVED when the frame content was missing or malformed, OT_ERROR_DESTINATION_ADDRESS_FILTERED when the frame was filtered out by dest address, OT_ERROR_PARSE when the received frame could not be parsed, OT_ERROR_FAILED when reception failed for any other reason.

### otPlatRadioResetCsl

```
otError otPlatRadioResetCsl(
  otInstance *aInstance
)
```
Reset CSL receiver in the platform.


> [!NOTE]
> **Note:** Defaults to `otPlatRadioEnableCsl(aInstance,0, Mac::kShortAddrInvalid, NULL);`

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. Return Values `OT_ERROR_NOT_IMPLEMENTED` Radio driver doesn't support CSL. `OT_ERROR_FAILED` Other platform specific errors. `OT_ERROR_NONE` Successfully disabled CSL.

### otPlatRadioScheduleTx

```
otError otPlatRadioScheduleTx(
  otInstance *aInstance,
  otRadioTime64 aTxTime
)
```
Schedule a radio frame transmission at a specific target time.

This API requires the radio platform to support the `OT_RADIO_CAPS_SCHEDULED_TX` capability. Its primary purpose is to support Thread Direct, though it may also be used for other time-sensitive transmission use cases in the future.

The caller forms the IEEE 802.15.4 frame in the buffer provided by `otPlatRadioGetScheduledTxFrame()` before calling this function to schedule the transmission at `aTxTime`.

The radio platform MUST execute the scheduled transmission according to the following rules:


- Target Transmission Time and Strict On-Time Requirement:
  - The radio platform MUST transmit the requested frame at the exact specified time `aTxTime`.
  - `aTxTime` is an `otRadioTime64` value in microseconds relative to the local radio clock (see `otPlatRadioGetNow()`).
  - `aTxTime` SHALL point to the exact point in time when the end of the Start of Frame Delimiter (SFD) will be present at the local antenna. The radio platform driver MUST account for any necessary radio ramp-up, channel switching, Clear Channel Assessment (CCA, if enabled), and SHR (preamble and SFD) transmission durations so that the end of the SFD aligns with `aTxTime`.
  - Strict on-time execution (no early or late transmission): It is critical that the frame is transmitted at `aTxTime`. If at the target transmission time the radio driver determines that it cannot transmit the frame at `aTxTime` (for example, due to Coex denial or hardware unavailability), it MUST NOT transmit the frame earlier or later. Instead, it MUST abort the transmission and invoke `otPlatRadioScheduledTxDone()` with `OT_ERROR_ABORT` to indicate that the frame was not sent.
  - Past or missed `aTxTime` at schedule time: The OpenThread stack calls `otPlatRadioScheduleTx()` as early as possible (as soon as it knows a scheduled transmission is needed), providing the radio platform with ample lead time ahead of `aTxTime` (for example, to account for radio ramp-up, Coex requests, etc.). However, `aTxTime` may still occasionally be in the past or too close to the current radio time `otPlatRadioGetNow()` (for example, if a frame is queued very close to the target slot, or if a blocking operation such as a flash re-write stalls execution). In this case, the radio platform MUST NOT transmit the frame. `otPlatRadioScheduleTx()` MUST still return `OT_ERROR_NONE` and asynchronously report the failure by invoking `otPlatRadioScheduledTxDone()` with `OT_ERROR_ABORT`. The radio platform MUST NOT invoke `otPlatRadioScheduledTxDone()` synchronously from within `otPlatRadioScheduleTx()`. If `otPlatRadioCancelScheduledTx()` is called before this deferred `OT_ERROR_ABORT` callback is invoked, the radio platform MUST either cancel the pending callback and return `OT_ERROR_NONE`, or return `OT_ERROR_BUSY` and proceed with invoking the `otPlatRadioScheduledTxDone()` callback.
- Operational Precedence, Preemption, and State Restoration:
  - A scheduled transmission SHOULD be prioritized over other radio operations when `aTxTime` arrives:
    - Ongoing Receive or Acknowledgment TX: If the radio is in Receive mode and is in the middle of receiving a frame (e.g., after SHR detection) or transmitting an acknowledgment for a received frame when the radio needs to prepare/transmit for `aTxTime`, the scheduled transmission SHOULD take precedence---the active reception or acknowledgment transmission SHOULD be stopped/aborted so that the scheduled transmission goes out on time at `aTxTime`. When an ongoing frame reception is aborted, the radio platform MAY report this via `otPlatRadioReceiveDone()` with `OT_ERROR_ABORT` (or omit invoking [otPlatRadioReceiveDone()](https://openthread.io/reference/group/radio-operation.md.txt#group__radio-operation_1ga00f23e5fdd33b94627f1cb68a0d91ade)). If a frame was already received and only its ACK transmission was aborted, and the radio platform still delivers the received frame via `otPlatRadioReceiveDone()` with OT_ERROR_NONE, then `mAckedWithFramePending` and `mAckedWithSecEnhAck` MUST be both set to false.
    - Concurrent `otPlatRadioTransmit()`: If the radio is instructed to transmit a frame via `otPlatRadioTransmit()` close to or overlapping with a previously scheduled transmission, the scheduled transmission SHOULD take precedence and be performed at `aTxTime`. For the conflicting `otPlatRadioTransmit()` operation, the radio platform MUST either:
      - Abort the `otPlatRadioTransmit()` operation and invoke `otPlatRadioTxDone()` with `OT_ERROR_ABORT` (so the OpenThread stack does not remain blocked waiting for `otPlatRadioTxDone()` and can handle any retries), or
      - Defer the `otPlatRadioTransmit()` operation until after the scheduled transmission completes, provided that the `otPlatRadioTransmit()` has not yet started on the air (`otPlatRadioTxStarted()` has not been invoked) and is not a timed transmission (`mTxDelay != 0`) whose target time would be missed. If the `otPlatRadioTransmit()` has already started on the air or is a timed transmission whose target time would be missed, it MUST be aborted via `otPlatRadioTxDone()` with `OT_ERROR_ABORT`.
  - Radio State and Post-Transmission Restoration:
    - If this function is called while the radio is disabled (`OT_RADIO_STATE_DISABLED`), it MUST return `OT_ERROR_INVALID_STATE`. Calling `otPlatRadioDisable()` while a scheduled TX is pending or active MUST immediately abort and cancel it without invoking `otPlatRadioScheduledTxDone()` (and MUST NOT fail with `OT_ERROR_INVALID_STATE` due to the active scheduled TX when the underlying state is `Sleep`).
    - When the radio is enabled, `otPlatRadioScheduleTx()` can be called from any radio state (`Sleep`, `Receive`, or `Transmit`). Conversely, subsequent calls to `otPlatRadioSleep()`, `otPlatRadioReceive()`, `otPlatRadioReceiveAt()`, or `otPlatRadioTransmit()` while a scheduled TX is pending MUST NOT cancel or alter the pending scheduled transmission (only `otPlatRadioCancelScheduledTx()` or `otPlatRadioDisable()` cancels it).
    - If `otPlatRadioSleep()` or `otPlatRadioReceive()` is called while the scheduled transmission is actively in progress on the air (or waiting for its acknowledgment) at `aTxTime`, the radio platform MUST NOT abort the ongoing scheduled transmission and MUST NOT fail the call with `OT_ERROR_BUSY` or `OT_ERROR_INVALID_STATE`. Instead, it MUST return `OT_ERROR_NONE`, complete the scheduled transmission, and then transition to the newly requested state (`Sleep` or `Receive` on the requested channel).
    - Once the scheduled transmission completes (after transmitting the frame and receiving the acknowledgment or timing out when an acknowledgment is requested, or if CCA fails or the transmission is aborted), the radio platform MUST automatically return to its target state (the state prior to the scheduled transmission, or any updated state requested via `otPlatRadioSleep()` or `otPlatRadioReceive()` while the scheduled transmission was pending/active) and resume what it was doing:
      - If the target state is `Receive` on a channel (from `otPlatRadioReceive()`), it MUST return to `Receive` on that receive channel (`mRxChannelAfterTxDone` in `otRadioFrame` MUST be ignored).
      - If the target state is `Sleep` with an active timed reception window (from `otPlatRadioReceiveAt()` whose window has not yet expired), it MUST return to `Receive` on that window's channel for the remaining duration of the window before transitioning back to `Sleep`.
      - If the target state is `Sleep` (and not in an active timed reception window), it MUST return to `Sleep`.
      - If a transmission requested via `otPlatRadioTransmit()` was deferred for the scheduled transmission, the radio platform SHOULD proceed with that transmission.
- Single Active Schedule and Frame Buffer Ownership:
  - At most one scheduled transmission request can be active at any time, using the single `otRadioFrame` provided by `otPlatRadioGetScheduledTxFrame()`.
  - After a successful `otPlatRadioScheduleTx()` call (and before it is canceled via `otPlatRadioCancelScheduledTx()` or `otPlatRadioDisable()`, or completed via `otPlatRadioScheduledTxDone()`), any new call to `otPlatRadioScheduleTx()` MUST be rejected by returning `OT_ERROR_BUSY` without affecting the active schedule. The OpenThread stack will generally not call `otPlatRadioScheduleTx()` again until the previous schedule is canceled or completed via `otPlatRadioScheduledTxDone()`.
  - Upon a successful `otPlatRadioScheduleTx()` call, the radio platform takes ownership of the frame buffer from `otPlatRadioGetScheduledTxFrame()`. The OpenThread stack guarantees that it will not touch or modify the frame buffer or its contents while owned by the radio platform.
  - Invoking the `otPlatRadioScheduledTxDone()` callback, a successful `otPlatRadioCancelScheduledTx()` call (returning `OT_ERROR_NONE`), or `otPlatRadioDisable()` releases ownership of the frame buffer back to the OpenThread stack, allowing the stack to modify the frame again.
- Handling of `otRadioFrame` (`mTxInfo`) fields:
  - `mTxDelayBaseTime` and `mTxDelay`: MUST be ignored. The target transmission time is specified solely by the `aTxTime` parameter.
  - `mCsmaCaEnabled`: Indicates whether CCA MUST be performed before transmitting the frame:
    - When set to `false`, the frame MUST be transmitted at `aTxTime` without performing CCA.
    - When set to `true`, CCA MUST be performed prior to transmission (timed so that the end of the SFD still occurs at `aTxTime`). If CCA fails, the radio platform MUST NOT transmit the frame and MUST report `OT_ERROR_CHANNEL_ACCESS_FAILURE` via `otPlatRadioScheduledTxDone()`.
  - `mMaxCsmaBackoffs`: MUST always be ignored (treated as `0`). The radio platform MUST NOT perform any CSMA backoff for a scheduled transmission.
  - `mMaxFrameRetries`: MUST always be ignored (treated as `0`). A scheduled transmission is a single transmission attempt with no retries by the radio platform (the OpenThread stack manages any retransmissions in subsequent time slots).
  - `mRxChannelAfterTxDone`: MUST be ignored. Upon completing the scheduled transmission, the radio MUST return to its previous state and receive channel (if it was receiving).
  - `mIsARetx` and `mCslPresent`: MUST be ignored.
  - `mTimestamp`: When the frame is transmitted, the radio platform MUST update this field with the local radio clock timestamp (in microseconds) when the end of the SFD was present at the local antenna before invoking `otPlatRadioScheduledTxDone()`.
  - `mIsHeaderUpdated` and `mIsSecurityProcessed`: Follow their existing behavior as defined for `otPlatRadioTransmit()` when `OT_RADIO_CAPS_TRANSMIT_SEC` is supported. When `mIsHeaderUpdated` is `false`, the radio platform MUST assign the MAC frame counter and perform security processing when preparing the frame for transmission at `aTxTime` (rather than when `otPlatRadioScheduleTx()` is called), ensuring that frame counters are used in order on the air if other transmissions or enhanced acknowledgments occur before `aTxTime` and that no frame counter is wasted if the scheduled transmission is canceled or aborted before the frame is prepared at `aTxTime`.
  - All other fields (`mChannel`, `mAesKey`, `mIeInfo`, `mTxPower`) MUST follow their existing behavior as defined for `otPlatRadioTransmit()`.
- Completion and Callbacks:
  - The radio platform MUST report the outcome of the scheduled transmission using the `otPlatRadioScheduledTxDone()` callback.
  - Aside from `OT_ERROR_INVALID_STATE` (when the radio is disabled) and `OT_ERROR_BUSY` (when a previously scheduled transmission is still active), `otPlatRadioScheduleTx()` MUST NOT return any other error synchronously. Any other runtime failure to schedule or transmit the frame (for example, if `mChannel` on the scheduled TX frame is invalid or unsupported) MUST still return `OT_ERROR_NONE` from `otPlatRadioScheduleTx()` and be reported asynchronously by invoking `otPlatRadioScheduledTxDone()` with `OT_ERROR_ABORT`.
  - A scheduled transmission MUST NOT invoke `otPlatRadioTxStarted()` or `otPlatRadioTxDone()`. Those callbacks are used exclusively for transmissions initiated via `otPlatRadioTransmit()`.

<br />

Why a dedicated scheduled TX API is used (and comparison with `OT_RADIO_CAPS_TRANSMIT_TIMING`):


- Coexistence (Coex) and Radio Arbitration: While the OpenThread stack can track time and schedule radio operations in software, it does not have visibility into platform-level radio coexistence (Coex) with other radios sharing the same device or antenna (such as Wi-Fi or Bluetooth/BLE). The radio platform driver is responsible for managing Coex arbitration and is therefore in a much better position to request appropriate Coex priority ahead of time and ensure the scheduled transmission goes out at the exact specified target time `aTxTime`. Similarly, the radio platform can directly preempt ongoing radio activity (such as an active frame reception, acknowledgment transmission, or a regular `otPlatRadioTransmit()` operation) when `aTxTime` arrives.
- Differences from `OT_RADIO_CAPS_TRANSMIT_TIMING` (`mTxDelayBaseTime` and `mTxDelay`): `OT_RADIO_CAPS_TRANSMIT_TIMING` was originally introduced to support CSL in Thread 1.2 by extending the existing `otPlatRadioTransmit()` API using `mTxDelayBaseTime` and `mTxDelay`. That model has several limitations for more strict protocols like Thread Direct:
  - Existing vendor implementations of `OT_RADIO_CAPS_TRANSMIT_TIMING` vary in their behavior when the target transmission time is missed (for example, some implementations still transmit the frame after a delay even if the target time has passed). While a slightly delayed transmission may still fall within a peer's CSL sample window, transmitting late or outside the designated time slot in Thread Direct could result in unpredictable failures. `otPlatRadioScheduleTx()` defines strict, explicit requirements on timing accuracy, operational precedence, and missed-target handling.
  - `otPlatRadioTransmit()` is a blocking state-transition operation: once called, the OpenThread stack must wait for `otPlatRadioTxDone()` before it can issue any other transmit, receive, or sleep commands to the radio (which also forces the stack to wait until just before the target time to issue a timed `otPlatRadioTransmit()` so the radio is not tied up prematurely). In contrast, `otPlatRadioScheduleTx()` schedules a future transmission using a dedicated frame buffer as soon as the stack knows a scheduled transmission is needed---allowing the radio to continue other operations in the meantime and supporting explicit cancellation via `otPlatRadioCancelScheduledTx()`.

<br />


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aTxTime` The target transmission time (end of SFD at the local antenna) in microseconds relative to the local radio clock (see `otPlatRadioGetNow()`). Return Values `OT_ERROR_NONE` Successfully scheduled the frame transmission. `OT_ERROR_BUSY` A previously scheduled transmission is still active. `OT_ERROR_INVALID_STATE` The radio is disabled.

### otPlatRadioScheduledTxDone

```
void otPlatRadioScheduledTxDone(
  otInstance *aInstance,
  otRadioFrame *aAckFrame,
  otError aError
)
```
The radio driver calls this function to notify OpenThread that a scheduled transmission (initiated via `otPlatRadioScheduleTx()`) has completed, providing both the transmission outcome and, if applicable, the received acknowledgment frame.

This callback is used when the radio platform provides the `OT_RADIO_CAPS_SCHEDULED_TX` capability.

When the radio provides the `OT_RADIO_CAPS_TRANSMIT_SEC` capability, the radio platform layer updates the scheduled TX frame (`otPlatRadioGetScheduledTxFrame()`) with the security frame counter and key index values maintained by the radio (following the same rules as `otPlatRadioTxDone()`).

Frame buffer ownership and re-entrancy:

- Invoking this callback transfers ownership of the scheduled TX frame buffer (`otPlatRadioGetScheduledTxFrame()`) from the radio platform back to the OpenThread stack.
- Importantly, from within the `otPlatRadioScheduledTxDone()` callback itself, the OpenThread stack may immediately modify the scheduled TX frame buffer and call `otPlatRadioScheduleTx()` to schedule a new transmission. The radio platform implementation MUST support `otPlatRadioScheduleTx()` being called directly from within this callback.

<br />


> [!NOTE]
> **Note:** This function should be called by the same thread that executes all of the other OpenThread code. It should not be called by an ISR or any other task.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aAckFrame` A pointer to the received ACK frame, or `NULL` if no ACK was received. `[in] aError` `OT_ERROR_NONE` when the frame was transmitted at the target time (and an Ack was received if Ack was requested in the MAC header), `OT_ERROR_NO_ACK` when the frame was transmitted at the target time but no Ack was received, `OT_ERROR_CHANNEL_ACCESS_FAILURE` when transmission at the target time could not take place due to activity on the channel (CCA failure when `mCsmaCaEnabled` is `true`), `OT_ERROR_ABORT` when the frame could not be transmitted at the exact target time (e.g., due to Coex denial or missed target time) or the transmission was aborted for other reasons.

### otPlatRadioSetChannelMaxTransmitPower

```
otError otPlatRadioSetChannelMaxTransmitPower(
  otInstance *aInstance,
  uint8_t aChannel,
  int8_t aMaxPower
)
```
Set the max transmit power for a specific channel.


> [!NOTE]
> **Note:** This function will be deprecated in October 2027. It is recommended to use the function `otPlatRadioSetChannelTargetPower()`.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aChannel` The radio channel. `[in] aMaxPower` The max power in dBm, passing OT_RADIO_RSSI_INVALID will disable this channel. Return Values `OT_ERROR_NOT_IMPLEMENTED` The feature is not implemented `OT_ERROR_INVALID_ARGS` The specified channel is not valid. `OT_ERROR_FAILED` Other platform specific errors. `OT_ERROR_NONE` Successfully set max transmit power.

### otPlatRadioSetChannelTargetPower

```
otError otPlatRadioSetChannelTargetPower(
  otInstance *aInstance,
  uint8_t aChannel,
  int16_t aTargetPower
)
```
Set the target power for the given channel.

<br />

> [!NOTE]
> **Note:** This API is an optional radio platform API. It's up to the platform layer to implement it. If this function and `otPlatRadioSetTransmitPower()` are implemented at the same time:
>
> - If neither of these two functions is called, the radio outputs the platform-defined default power.
> - If both functions are called, the last one to be called takes effect.

The radio driver should set the actual output power to be less than or equal to the `aTargetPower` and as close as possible to the `aTargetPower`. If the `aTargetPower` is lower than the minimum output power supported by the platform, the output power should be set to the minimum output power supported by the platform. If the `aTargetPower` is higher than the maximum output power supported by the platform, the output power should be set to the maximum output power supported by the platform. If the `aTargetPower` is set to `OT_RADIO_POWER_INVALID_IN_MBM`, the corresponding channel is disabled.

<br />


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aChannel` The radio channel. `[in] aTargetPower` The target power in 0.01dBm. Return Values `OT_ERROR_NONE` Successfully set the target power. `OT_ERROR_INVALID_ARGS` The `aChannel` is invalid. `OT_ERROR_NOT_IMPLEMENTED` The feature is not implemented.

### otPlatRadioSetCoexEnabled

```
otError otPlatRadioSetCoexEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enable the radio coex.

Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aEnabled` TRUE to enable the radio coex, FALSE otherwise. Return Values `OT_ERROR_NONE` Successfully enabled. `OT_ERROR_FAILED` The radio coex could not be enabled.

### otPlatRadioSetRegion

```
otError otPlatRadioSetRegion(
  otInstance *aInstance,
  uint16_t aRegionCode
)
```
Set the region code.

The radio region format is the 2-bytes ascii representation of the ISO 3166 alpha-2 code.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aRegionCode` The radio region code. The `aRegionCode >> 8` is first ascii char and the `aRegionCode & 0xff` is the second ascii char. Return Values `OT_ERROR_FAILED` Other platform specific errors. `OT_ERROR_NONE` Successfully set region code. `OT_ERROR_NOT_IMPLEMENTED` The feature is not implemented.

### otPlatRadioSleep

```
otError otPlatRadioSleep(
  otInstance *aInstance
)
```
Transition the radio to the Sleep state (turn off the radio).

If the radio is already in the Sleep state, this function MUST return `OT_ERROR_NONE` with no effect.

If `otPlatRadioSleep()` is called while the radio is in the middle of receiving a frame or transmitting an ACK (e.g., during AIFS/turnaround wait or actively transmitting the ACK frame), the radio MUST complete the ongoing operation (finish frame reception and/or ACK transmission) and transition to Sleep immediately thereafter. In this scenario:

- The radio MUST return `OT_ERROR_NONE` to indicate that the sleep request has been accepted and scheduled.
- Upon finishing the frame reception (and any associated ACK transmission), the radio driver MUST invoke `otPlatRadioReceiveDone()` to deliver the received frame (or report reception error) before transitioning to Sleep.

<br />

If subsequently any radio state transition function (e.g., `otPlatRadioTransmit()`, `otPlatRadioReceive()` or `otPlatRadioDisable()`) is called while a scheduled transition to Sleep is pending, the pending transition MUST be canceled/superseded, and the radio MUST perform the operations as specified for the called function. Specifically, this includes the handling of any ongoing frame reception and/or ACK frame transmission that initially caused the transition to Sleep to be pending.


Details Parameters `[in] aInstance` The OpenThread instance structure. Return Values `OT_ERROR_NONE` Successfully transitioned to Sleep, radio is already in Sleep, or transition is accepted and scheduled. `OT_ERROR_BUSY` The radio was transmitting a frame (initiated by `otPlatRadioTransmit()`). `OT_ERROR_INVALID_STATE` The radio was disabled.

### otPlatRadioTransmit

```
otError otPlatRadioTransmit(
  otInstance *aInstance,
  otRadioFrame *aFrame
)
```
Begin the transmit sequence on the radio.

The caller must form the IEEE 802.15.4 frame in the buffer provided by `otPlatRadioGetTransmitBuffer()` before requesting transmission. The channel and transmit power are also included in the [otRadioFrame](https://openthread.io/reference/struct/ot-radio-frame.md.txt) structure.

The transmit sequence consists of:

1. Transitioning the radio to Transmit from one of the following states:
   - Receive if RX is on when the device is idle or OT_RADIO_CAPS_SLEEP_TO_TX is not supported
   - Sleep if RX is off when the device is idle and OT_RADIO_CAPS_SLEEP_TO_TX is supported.
2. Transmits the frame (PSDU) on the given channel and at the given transmit power.

<br />

If the radio is actively receiving a frame or transmitting an ACK at the time it would perform CCA for the frame (PSDU), or would start its transmission, the channel MUST be considered busy and the ongoing receive operation is not aborted. This requirement holds even when the requested transmit channel differs from the channel on which the radio is currently doing its receive operation. In this case, `OT_ERROR_NONE` is returned, and:

- If the radio provides `OT_RADIO_CAPS_CSMA_BACKOFF` and/or `OT_RADIO_CAPS_TRANSMIT_RETRIES`, it handles a busy channel like a failed CCA within its own CSMA-CA backoff procedure (when `mCsmaCaEnabled` is `true`, up to `mMaxCsmaBackoffs`) and/or frame retry procedure (up to `mMaxFrameRetries`). `otPlatRadioTxDone()` is called with `OT_ERROR_CHANNEL_ACCESS_FAILURE` only after all allowed attempts were completed unsuccessfully.
- Otherwise, `otPlatRadioTxDone()` SHOULD be called as soon as possible with `aError` value `OT_ERROR_CHANNEL_ACCESS_FAILURE`.

<br />

An exception to the above requirement is time-scheduled transmissions (see `mTxDelayBaseTime`, `mTxDelay`, and `OT_RADIO_CAPS_TRANSMIT_TIMING`). In that case, the timed frame transmission has priority over ongoing reception and the ongoing receive operation (frame reception and/or ACK transmission) MUST be aborted if the radio determines it cannot finish the operation before the scheduled frame transmission is due. An ongoing frame reception that is aborted MAY be reported via `otPlatRadioReceiveDone()` with `aError` set to `OT_ERROR_ABORT` (or the callback MAY be omitted).


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aFrame` A pointer to the frame to be transmitted. Return Values `OT_ERROR_NONE` Successfully transitioned to Transmit. `OT_ERROR_INVALID_STATE` The radio was not in one of the states required to transition.

### otPlatRadioTxDone

```
void otPlatRadioTxDone(
  otInstance *aInstance,
  otRadioFrame *aFrame,
  otRadioFrame *aAckFrame,
  otError aError
)
```
The radio driver calls this function to notify OpenThread that the transmit operation has completed, providing both the transmitted frame and, if applicable, the received ack frame.

When radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability, radio platform layer updates `aFrame` with the security frame counter and key index values maintained by the radio.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aFrame` A pointer to the frame that was transmitted. `[in] aAckFrame` A pointer to the ACK frame, NULL if no ACK was received. `[in] aError` OT_ERROR_NONE when the frame was transmitted, OT_ERROR_NO_ACK when the frame was transmitted but no ACK was received, OT_ERROR_CHANNEL_ACCESS_FAILURE tx could not take place due to activity on the channel, OT_ERROR_ABORT when transmission was aborted for other reasons.

### otPlatRadioTxStarted

```
void otPlatRadioTxStarted(
  otInstance *aInstance,
  otRadioFrame *aFrame
)
```
The radio driver calls this function to notify OpenThread that the transmission has started.


> [!NOTE]
> **Note:** This function should be called by the same thread that executes all of the other OpenThread code. It should not be called by ISR or any other task.

<br />

Details Parameters `[in] aInstance` A pointer to the OpenThread instance structure. `[in] aFrame` A pointer to the frame that is being transmitted.

### otPlatRadioUpdateCslSampleTime

```
void otPlatRadioUpdateCslSampleTime(
  otInstance *aInstance,
  otRadioTime32 aCslSampleTime
)
```
Update CSL sample time in radio driver.

Sample time is stored in radio driver as a copy to calculate phase when sending ACK with CSL IE. The CSL sample (window) of the CSL receiver extends before and after the sample time. The CSL sample time marks a timestamp in the CSL sample window when a frame should be received in "ideal conditions" if there would be no inaccuracy/clock-drift.


Details Parameters `[in] aInstance` The OpenThread instance structure. `[in] aCslSampleTime` The next sample time, in microseconds. It is the time when the first symbol of the MHR of the frame is expected.

## 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.md.txt).