Radio Configuration

This module includes the platform abstraction for radio configuration.

Summary

Functions
`otPlatRadioGetBusLatency(otInstance *aInstance)`	`uint32_t` Get the bus latency in microseconds between the host and the radio chip.
`otPlatRadioGetBusSpeed(otInstance *aInstance)`	`uint32_t` Get the bus speed in bits/second between the host and the radio chip.
`otPlatRadioGetCaps(otInstance *aInstance)`	`otRadioCaps` Get the radio capabilities.
`otPlatRadioGetCcaEnergyDetectThreshold(otInstance aInstance, int8_t aThreshold)`	`otError` Get the radio's CCA ED threshold in dBm measured at antenna connector per IEEE 802.15.4 - 2015 section 10.1.4.
`otPlatRadioGetFemLnaGain(otInstance aInstance, int8_t aGain)`	`otError` Gets the external FEM's Rx LNA gain in dBm.
`otPlatRadioGetIeeeEui64(otInstance aInstance, uint8_t aIeeeEui64)`	`void` Gets the factory-assigned IEEE EUI-64 for this interface.
`otPlatRadioGetNow(otInstance *aInstance)`	`uint64_t` Get the current time in microseconds referenced to a continuous monotonic local radio clock (64 bits width).
`otPlatRadioGetPromiscuous(otInstance *aInstance)`	`bool` Get the status of promiscuous mode.
`otPlatRadioGetReceiveSensitivity(otInstance *aInstance)`	`int8_t` Get the radio receive sensitivity value.
`otPlatRadioGetTransmitPower(otInstance aInstance, int8_t aPower)`	`otError` Get the radio's transmit power in dBm.
`otPlatRadioGetVersionString(otInstance *aInstance)`	`const char *` Get the radio version string.
`otPlatRadioSetAlternateShortAddress(otInstance *aInstance, otShortAddress aShortAddress)`	`void` Set the alternate short address.
`otPlatRadioSetCcaEnergyDetectThreshold(otInstance *aInstance, int8_t aThreshold)`	`otError` Set the radio's CCA ED threshold in dBm measured at antenna connector per IEEE 802.15.4 - 2015 section 10.1.4.
`otPlatRadioSetExtendedAddress(otInstance aInstance, const otExtAddress aExtAddress)`	`void` Set the Extended Address for address filtering.
`otPlatRadioSetFemLnaGain(otInstance *aInstance, int8_t aGain)`	`otError` Sets the external FEM's Rx LNA gain in dBm.
`otPlatRadioSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCounter)`	`void` Sets the current MAC frame counter value.
`otPlatRadioSetMacFrameCounterIfLarger(otInstance *aInstance, uint32_t aMacFrameCounter)`	`void` Sets the current MAC frame counter value only if the new given value is larger than the current value.
`otPlatRadioSetMacKey(otInstance aInstance, uint8_t aKeyIdMode, uint8_t aKeyId, const otMacKeyMaterial aPrevKey, const otMacKeyMaterial aCurrKey, const otMacKeyMaterial aNextKey, otRadioKeyType aKeyType)`	`void` Update MAC keys and key index.
`otPlatRadioSetPanId(otInstance *aInstance, otPanId aPanId)`	`void` Set the PAN ID for address filtering.
`otPlatRadioSetPromiscuous(otInstance *aInstance, bool aEnable)`	`void` Enable or disable promiscuous mode.
`otPlatRadioSetRxOnWhenIdle(otInstance *aInstance, bool aEnable)`	`void` Sets the rx-on-when-idle state to the radio platform.
`otPlatRadioSetShortAddress(otInstance *aInstance, otShortAddress aShortAddress)`	`void` Set the Short Address for address filtering.
`otPlatRadioSetTransmitPower(otInstance *aInstance, int8_t aPower)`	`otError` Set the radio's transmit power in dBm for all channels.

Functions

otPlatRadioGetBusLatency

uint32_t otPlatRadioGetBusLatency(
  otInstance *aInstance
)

Get the bus latency in microseconds between the host and the radio chip.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

The bus latency in microseconds between the host and the radio chip. Return 0 when the MAC and above layer and Radio layer resides on the same chip.

otPlatRadioGetBusSpeed

uint32_t otPlatRadioGetBusSpeed(
  otInstance *aInstance
)

Get the bus speed in bits/second between the host and the radio chip.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

The bus speed in bits/second between the host and the radio chip. Return 0 when the MAC and above layer and Radio layer resides on the same chip.

otPlatRadioGetCaps

otRadioCaps otPlatRadioGetCaps(
  otInstance *aInstance
)

Get the radio capabilities.

Details

Parameters

[in] aInstance

The OpenThread instance structure.

Returns

The radio capability bit vector (see OT_RADIO_CAP_* definitions).

otPlatRadioGetCcaEnergyDetectThreshold

otError otPlatRadioGetCcaEnergyDetectThreshold(
  otInstance *aInstance,
  int8_t *aThreshold
)

Get the radio's CCA ED threshold in dBm measured at antenna connector per IEEE 802.15.4 - 2015 section 10.1.4.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[out] aThreshold`	The CCA ED threshold in dBm.

Return Values

`OT_ERROR_NONE`	Successfully retrieved the CCA ED threshold.
`OT_ERROR_INVALID_ARGS`	`aThreshold` was NULL.
`OT_ERROR_NOT_IMPLEMENTED`	CCA ED threshold configuration via dBm is not implemented.

otPlatRadioGetFemLnaGain

otError otPlatRadioGetFemLnaGain(
  otInstance *aInstance,
  int8_t *aGain
)

Gets the external FEM's Rx LNA gain in dBm.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[out] aGain`	The external FEM's Rx LNA gain in dBm.

Return Values

`OT_ERROR_NONE`	Successfully retrieved the external FEM's LNA gain.
`OT_ERROR_INVALID_ARGS`	`aGain` was NULL.
`OT_ERROR_NOT_IMPLEMENTED`	External FEM's LNA setting is not implemented.

otPlatRadioGetIeeeEui64

void otPlatRadioGetIeeeEui64(
  otInstance *aInstance,
  uint8_t *aIeeeEui64
)

Gets the factory-assigned IEEE EUI-64 for this interface.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[out] aIeeeEui64`	A pointer to the factory-assigned IEEE EUI-64.

otPlatRadioGetNow

uint64_t otPlatRadioGetNow(
  otInstance *aInstance
)

Get the current time in microseconds referenced to a continuous monotonic local radio clock (64 bits width).

The radio clock SHALL NOT wrap during the device's uptime. Implementations SHALL therefore identify and compensate for internal counter overflows. The clock does not have a defined epoch and it SHALL NOT introduce any continuous or discontinuous adjustments (e.g. leap seconds). Implementations SHALL compensate for any sleep times of the device.

Implementations MAY choose to discipline the radio clock and compensate for sleep times by any means (e.g. by combining a high precision/low power RTC with a high resolution counter) as long as the exposed combined clock provides continuous monotonic microsecond resolution ticks within the accuracy limits announced by otPlatRadioGetCslAccuracy.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

The current time in microseconds. UINT64_MAX when platform does not support or radio time is not ready.

otPlatRadioGetPromiscuous

bool otPlatRadioGetPromiscuous(
  otInstance *aInstance
)

Get the status of promiscuous mode.

Details

Parameters

[in] aInstance

The OpenThread instance structure.

Return Values

`TRUE`	Promiscuous mode is enabled.
`FALSE`	Promiscuous mode is disabled.

otPlatRadioGetReceiveSensitivity

int8_t otPlatRadioGetReceiveSensitivity(
  otInstance *aInstance
)

Get the radio receive sensitivity value.

Details

Parameters

[in] aInstance

The OpenThread instance structure.

Returns

The radio receive sensitivity value in dBm.

otPlatRadioGetTransmitPower

otError otPlatRadioGetTransmitPower(
  otInstance *aInstance,
  int8_t *aPower
)

Get the radio's transmit power in dBm.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[out] aPower`	The transmit power in dBm.

Return Values

`OT_ERROR_NONE`	Successfully retrieved the transmit power.
`OT_ERROR_INVALID_ARGS`	`aPower` was NULL.
`OT_ERROR_NOT_IMPLEMENTED`	Transmit power configuration via dBm is not implemented.

otPlatRadioGetVersionString

const char * otPlatRadioGetVersionString(
  otInstance *aInstance
)

Get the radio version string.

This is an optional radio driver platform function. If not provided by platform radio driver, OpenThread uses the OpenThread version instead (

Details

Parameters

[in] aInstance

The OpenThread instance structure.

Returns

A pointer to the OpenThread radio version.

See also:
otGetVersionString()).

otPlatRadioSetAlternateShortAddress

void otPlatRadioSetAlternateShortAddress(
  otInstance *aInstance,
  otShortAddress aShortAddress
)

Set the alternate short address.

This is an optional radio platform API. The radio platform MUST indicate support for this API by including the capability OT_RADIO_CAPS_ALT_SHORT_ADDR in otPlatRadioGetCaps().

When supported, the radio should accept received frames destined to the specified alternate short address in addition to the short address provided in otPlatRadioSetShortAddress().

The aShortAddress can be set to OT_RADIO_INVALID_SHORT_ADDR (0xfffe) to clear any previously set alternate short address.

This function is used by OpenThread stack during child-to-router role transitions, allowing the device to continue receiving frames addressed to its previous short address for a short period.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aShortAddress`	The alternate IEEE 802.15.4 short address. `OT_RADIO_INVALID_SHORT_ADDR` to clear.

otPlatRadioSetCcaEnergyDetectThreshold

otError otPlatRadioSetCcaEnergyDetectThreshold(
  otInstance *aInstance,
  int8_t aThreshold
)

Set the radio's CCA ED threshold in dBm measured at antenna connector per IEEE 802.15.4 - 2015 section 10.1.4.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aThreshold`	The CCA ED threshold in dBm.

Return Values

`OT_ERROR_NONE`	Successfully set the transmit power.
`OT_ERROR_INVALID_ARGS`	Given threshold is out of range.
`OT_ERROR_NOT_IMPLEMENTED`	CCA ED threshold configuration via dBm is not implemented.

otPlatRadioSetExtendedAddress

void otPlatRadioSetExtendedAddress(
  otInstance *aInstance,
  const otExtAddress *aExtAddress
)

Set the Extended Address for address filtering.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aExtAddress`	A pointer to the IEEE 802.15.4 Extended Address stored in little-endian byte order.

otPlatRadioSetFemLnaGain

otError otPlatRadioSetFemLnaGain(
  otInstance *aInstance,
  int8_t aGain
)

Sets the external FEM's Rx LNA gain in dBm.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aGain`	The external FEM's Rx LNA gain in dBm.

Return Values

`OT_ERROR_NONE`	Successfully set the external FEM's LNA gain.
`OT_ERROR_NOT_IMPLEMENTED`	External FEM's LNA gain setting is not implemented.

otPlatRadioSetMacFrameCounter

void otPlatRadioSetMacFrameCounter(
  otInstance *aInstance,
  uint32_t aMacFrameCounter
)

Sets the current MAC frame counter value.

Is used when radio provides OT_RADIO_CAPS_TRANSMIT_SEC capability.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aMacFrameCounter`	The MAC frame counter value.

otPlatRadioSetMacFrameCounterIfLarger

void otPlatRadioSetMacFrameCounterIfLarger(
  otInstance *aInstance,
  uint32_t aMacFrameCounter
)

Sets the current MAC frame counter value only if the new given value is larger than the current value.

Is used when radio provides OT_RADIO_CAPS_TRANSMIT_SEC capability.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aMacFrameCounter`	The MAC frame counter value.

otPlatRadioSetMacKey

void otPlatRadioSetMacKey(
  otInstance *aInstance,
  uint8_t aKeyIdMode,
  uint8_t aKeyId,
  const otMacKeyMaterial *aPrevKey,
  const otMacKeyMaterial *aCurrKey,
  const otMacKeyMaterial *aNextKey,
  otRadioKeyType aKeyType
)

Update MAC keys and key index.

Is used when radio provides OT_RADIO_CAPS_TRANSMIT_SEC capability.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aKeyIdMode`	The key ID mode.
`[in] aKeyId`	Current MAC key index.
`[in] aPrevKey`	A pointer to the previous MAC key.
`[in] aCurrKey`	A pointer to the current MAC key.
`[in] aNextKey`	A pointer to the next MAC key.
`[in] aKeyType`	Key Type used.

otPlatRadioSetPanId

void otPlatRadioSetPanId(
  otInstance *aInstance,
  otPanId aPanId
)

Set the PAN ID for address filtering.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aPanId`	The IEEE 802.15.4 PAN ID.

otPlatRadioSetPromiscuous

void otPlatRadioSetPromiscuous(
  otInstance *aInstance,
  bool aEnable
)

Enable or disable promiscuous mode.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aEnable`	TRUE to enable or FALSE to disable promiscuous mode.

otPlatRadioSetRxOnWhenIdle

void otPlatRadioSetRxOnWhenIdle(
  otInstance *aInstance,
  bool aEnable
)

Sets the rx-on-when-idle state to the radio platform.

There are a few situations that the radio can enter sleep state if the device is in rx-off-when-idle state but it's hard and costly for the SubMac to identify these situations and instruct the radio to enter sleep:

Finalization of a regular frame reception task, provided that:
- The frame is received without errors and passes the filtering and it's not an spurious ACK.
- ACK is not requested or transmission of ACK is not possible due to internal conditions.
Finalization of a frame transmission or transmission of an ACK frame, when ACK is not requested in the transmitted frame.
Finalization of the reception operation of a requested ACK due to:
- ACK timeout expiration.
- Reception of an invalid ACK or not an ACK frame.
- Reception of the proper ACK, unless the transmitted frame was a Data Request Command and the frame pending bit on the received ACK is set to true. In this case the radio platform implementation SHOULD keep the receiver on until a determined timeout which triggers an idle period start.OPENTHREAD_CONFIG_MAC_DATA_POLL_TIMEOUT can be taken as a reference for this.
Finalization of a stand alone CCA task.
Finalization of a CCA operation with busy result during CSMA/CA procedure.
Finalization of an Energy Detection task.
Finalization of a radio reception window scheduled with otPlatRadioReceiveAt.

If a platform supports OT_RADIO_CAPS_RX_ON_WHEN_IDLE it must also support OT_RADIO_CAPS_CSMA_BACKOFF and handle idle periods after CCA as described above.

Upon the transition of the "RxOnWhenIdle" flag from TRUE to FALSE, the radio platform should enter sleep mode. If the radio is currently in receive mode, it should enter sleep mode immediately. Otherwise, it should enter sleep mode after the current operation is completed.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aEnable`	TRUE to keep radio in Receive state, FALSE to put to Sleep state during idle periods.

otPlatRadioSetShortAddress

void otPlatRadioSetShortAddress(
  otInstance *aInstance,
  otShortAddress aShortAddress
)

Set the Short Address for address filtering.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aShortAddress`	The IEEE 802.15.4 Short Address.

otPlatRadioSetTransmitPower

otError otPlatRadioSetTransmitPower(
  otInstance *aInstance,
  int8_t aPower
)

Set the radio's transmit power in dBm for all channels.

Note: The real transmit power will be no larger than the power specified in the max power table for the current channel that was configured by otPlatRadioSetChannelMaxTransmitPower().

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aPower`	The transmit power in dBm.

Return Values

`OT_ERROR_NONE`	Successfully set the transmit power.
`OT_ERROR_NOT_IMPLEMENTED`	Transmit power configuration via dBm is not implemented.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.