Radio Operation#

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

• This function may be not implemented. It does not affect OpenThread.

Returns

• Current state of the radio.

otPlatRadioEnable#

otError otPlatRadioEnable (otInstance * aInstance)

Enable the radio.

otPlatRadioDisable#

otError otPlatRadioDisable (otInstance * aInstance)

Disable the radio.

otPlatRadioIsEnabled#

bool otPlatRadioIsEnabled (otInstance * aInstance)

Check whether radio is enabled or not.

Returns

• TRUE if the radio is enabled, FALSE otherwise.

otPlatRadioSleep#

otError otPlatRadioSleep (otInstance * aInstance)

Transition the radio from Receive to Sleep (turn off the radio).

otPlatRadioReceive#

otError otPlatRadioReceive (otInstance * aInstance, uint8_t aChannel)

Transition the radio from Sleep to Receive (turn on the radio).

otPlatRadioReceiveAt#

otError otPlatRadioReceiveAt (otInstance * aInstance, uint8_t aChannel, uint32_t aStart, uint32_t aDuration)

Schedule a radio reception window at a specific time and duration.

otPlatRadioReceiveDone#

void otPlatRadioReceiveDone (otInstance * aInstance, otRadioFrame * aFrame, otError aError)

The radio driver calls this method to notify OpenThread of a received frame.

otPlatDiagRadioReceiveDone#

void otPlatDiagRadioReceiveDone (otInstance * aInstance, otRadioFrame * aFrame, otError aError)

The radio driver calls this method to notify OpenThread diagnostics module of a received frame.

Is used when diagnostics is enabled.

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.

Returns

• A pointer to the transmit frame buffer.

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 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 psdu on the given channel and at the given transmit power.

otPlatRadioTxStarted#

void otPlatRadioTxStarted (otInstance * aInstance, otRadioFrame * aFrame)

The radio driver calls this method to notify OpenThread that the transmission has started.

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.

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.

otPlatDiagRadioTransmitDone#

void otPlatDiagRadioTransmitDone (otInstance * aInstance, otRadioFrame * aFrame, otError aError)

The radio driver calls this method to notify OpenThread diagnostics module that the transmission has completed.

Is used when diagnostics is enabled.

otPlatRadioGetRssi#

int8_t otPlatRadioGetRssi (otInstance * aInstance)

Get the most recent RSSI measurement.

Returns

• The RSSI in dBm when it is valid. 127 when RSSI is invalid.

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.

otPlatRadioEnergyScanDone#

void otPlatRadioEnergyScanDone (otInstance * aInstance, int8_t aEnergyScanMaxRssi)

The radio driver calls this method to notify OpenThread that the energy scan is complete.

Is used when radio provides OT_RADIO_CAPS_ENERGY_SCAN capability.

otPlatRadioBusLatencyChanged#

void otPlatRadioBusLatencyChanged (otInstance * aInstance)

The radio driver calls this method to notify OpenThread that the spinel bus latency has been changed.

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.

otPlatRadioAddSrcMatchShortEntry#

otError otPlatRadioAddSrcMatchShortEntry (otInstance * aInstance, otShortAddress aShortAddress)

Add a short address to the source address match table.

otPlatRadioAddSrcMatchExtEntry#

otError otPlatRadioAddSrcMatchExtEntry (otInstance * aInstance, const otExtAddress * aExtAddress)

Add an extended address to the source address match table.

otPlatRadioClearSrcMatchShortEntry#

otError otPlatRadioClearSrcMatchShortEntry (otInstance * aInstance, otShortAddress aShortAddress)

Remove a short address from the source address match table.

otPlatRadioClearSrcMatchExtEntry#

otError otPlatRadioClearSrcMatchExtEntry (otInstance * aInstance, const otExtAddress * aExtAddress)

Remove an extended address from the source address match table.

otPlatRadioClearSrcMatchShortEntries#

void otPlatRadioClearSrcMatchShortEntries (otInstance * aInstance)

Clear all short addresses from the source address match table.

otPlatRadioClearSrcMatchExtEntries#

void otPlatRadioClearSrcMatchExtEntries (otInstance * aInstance)

Clear all the extended/long addresses from source address match table.

otPlatRadioGetSupportedChannelMask#

uint32_t otPlatRadioGetSupportedChannelMask (otInstance * aInstance)

Get the radio supported channel mask that the device is allowed to be on.

Returns

• The radio supported channel mask.

otPlatRadioGetPreferredChannelMask#

uint32_t otPlatRadioGetPreferredChannelMask (otInstance * aInstance)

Gets the radio preferred channel mask that the device prefers to form on.

Returns

• The radio preferred channel mask.

otPlatRadioSetCoexEnabled#

otError otPlatRadioSetCoexEnabled (otInstance * aInstance, bool aEnabled)

Enable the radio coex.

Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled.

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.

Returns

• TRUE if the radio coex is enabled, FALSE otherwise.

otPlatRadioGetCoexMetrics#

otError otPlatRadioGetCoexMetrics (otInstance * aInstance, otRadioCoexMetrics * aCoexMetrics)

Get the radio coexistence metrics.

Is used when feature OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE is enabled.

otPlatRadioEnableCsl#

otError otPlatRadioEnableCsl (otInstance * aInstance, uint32_t aCslPeriod, otShortAddress aShortAddr, const otExtAddress * aExtAddr)

Enable or disable CSL receiver.

Note

• Platforms should use CSL peer addresses to include CSL IE when generating enhanced acks.

otPlatRadioResetCsl#

otError otPlatRadioResetCsl (otInstance * aInstance)

Reset CSL receiver in the platform.

Note

• Defaults to otPlatRadioEnableCsl(aInstance,0, Mac::kShortAddrInvalid, nullptr);

otPlatRadioUpdateCslSampleTime#

void otPlatRadioUpdateCslSampleTime (otInstance * aInstance, uint32_t 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.

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.

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.

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.

Returns

• The CSL Uncertainty in units of 10 us.

otPlatRadioSetChannelMaxTransmitPower#

otError otPlatRadioSetChannelMaxTransmitPower (otInstance * aInstance, uint8_t aChannel, int8_t aMaxPower)

Set the max transmit power for a specific channel.

Note

• This function will be deprecated in October 2027. It is recommended to use the function otPlatRadioSetChannelTargetPower().

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.

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.

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 method 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.

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.

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.

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.

otPlatRadioClearCalibratedPowers#

otError otPlatRadioClearCalibratedPowers (otInstance * aInstance)

Clear all calibrated powers from the power calibration table.

Note

• This API is an optional radio platform API. It's up to the platform layer to implement it.

otPlatRadioSetChannelTargetPower#

otError otPlatRadioSetChannelTargetPower (otInstance * aInstance, uint8_t aChannel, int16_t aTargetPower)

Set the target power for the given channel.

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 INT16_MAX, the corresponding channel is disabled.

otPlatRadioGetRawPowerSetting#

otError otPlatRadioGetRawPowerSetting (otInstance * aInstance, uint8_t aChannel, uint8_t * aRawPowerSetting, uint16_t * aRawPowerSettingLength)

Get the raw power setting for the given channel.

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.