Link

This module includes functions that control link-layer configuration.

Summary

Enumerations
otMacFilterAddressMode{
  OT_MAC_FILTER_ADDRESS_MODE_DISABLED,
  OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST,
  OT_MAC_FILTER_ADDRESS_MODE_DENYLIST
} 		enum
Defines address mode of the mac filter.

Typedefs
otActiveScanResult typedef
Represents a received IEEE 802.15.4 Beacon.
otEnergyScanResult typedef
Represents an energy scan result.
otHandleActiveScanResult)(otActiveScanResult *aResult, void *aContext) typedef
void(*
Pointer is called during an IEEE 802.15.4 Active Scan when an IEEE 802.15.4 Beacon is received or the scan completes.
otHandleEnergyScanResult)(otEnergyScanResult *aResult, void *aContext) typedef
void(*
Pointer is called during an IEEE 802.15.4 Energy Scan when the result for a channel is ready or the scan completes.
otLinkPcapCallback)(const otRadioFrame *aFrame, bool aIsTx, void *aContext) typedef
void(*
Pointer is called when an IEEE 802.15.4 frame is received.
otMacCounters typedef
struct otMacCounters
Represents the MAC layer counters.
otMacFilterAddressMode typedef
Defines address mode of the mac filter.
otMacFilterEntry typedef
Represents a Mac Filter entry.
otMacFilterIterator typedef
uint8_t
Used to iterate through mac filter entries.

Functions
otLinkActiveScan(otInstance *aInstance, uint32_t aScanChannels, uint16_t aScanDuration, otHandleActiveScanResult aCallback, void *aCallbackContext)
Starts an IEEE 802.15.4 Active Scan.
otLinkConvertLinkQualityToRss(otInstance *aInstance, uint8_t aLinkQuality)
int8_t
Converts link quality to typical received signal strength.
otLinkConvertRssToLinkQuality(otInstance *aInstance, int8_t aRss)
uint8_t
Converts received signal strength to link quality.
otLinkEnergyScan(otInstance *aInstance, uint32_t aScanChannels, uint16_t aScanDuration, otHandleEnergyScanResult aCallback, void *aCallbackContext)
Starts an IEEE 802.15.4 Energy Scan.
otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAddress)
Adds an Extended Address to MAC filter.
otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddress, int8_t aRss)
Adds the specified Extended Address to the RssIn list (or modifies an existing address in the RssIn list) and sets the received signal strength (in dBm) entry for messages from that address.
otLinkFilterClearAddresses(otInstance *aInstance)
void
Clears all the Extended Addresses from MAC filter.
otLinkFilterClearAllRssIn(otInstance *aInstance)
void
Clears all the received signal strength (rss) and link quality indicator (lqi) entries (including defaults) from the RssIn list.
otLinkFilterClearDefaultRssIn(otInstance *aInstance)
void
Clears any previously set default received signal strength (in dBm) on MAC Filter.
otLinkFilterGetAddressMode(otInstance *aInstance)
Gets the address mode of MAC filter.
otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry)
Gets an in-use address filter entry.
otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry)
Gets an in-use RssIn filter entry.
otLinkFilterRemoveAddress(otInstance *aInstance, const otExtAddress *aExtAddress)
void
Removes an Extended Address from MAC filter.
otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddress)
void
Removes the specified Extended Address from the RssIn list.
otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aMode)
void
Sets the address mode of MAC filter.
otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss)
void
Sets the default received signal strength (in dBm) on MAC Filter.
otLinkGetAlternateShortAddress(otInstance *aInstance)
Get the IEEE 802.15.4 alternate short address.
otLinkGetCcaFailureRate(otInstance *aInstance)
uint16_t
Returns the current CCA (Clear Channel Assessment) failure rate.
otLinkGetChannel(otInstance *aInstance)
uint8_t
Get the IEEE 802.15.4 channel.
otLinkGetCounters(otInstance *aInstance)
const otMacCounters *
Get the MAC layer counters.
otLinkGetCslChannel(otInstance *aInstance)
uint8_t
Gets the CSL channel.
otLinkGetCslPeriod(otInstance *aInstance)
uint32_t
Gets the CSL period in microseconds.
otLinkGetCslTimeout(otInstance *aInstance)
uint32_t
Gets the CSL timeout.
otLinkGetExtendedAddress(otInstance *aInstance)
const otExtAddress *
Gets the IEEE 802.15.4 Extended Address.
otLinkGetFactoryAssignedIeeeEui64(otInstance *aInstance, otExtAddress *aEui64)
void
Get the factory-assigned IEEE EUI-64.
otLinkGetFrameCounter(otInstance *aInstance)
uint32_t
Gets the current MAC frame counter value.
otLinkGetMaxFrameRetriesDirect(otInstance *aInstance)
uint8_t
Returns the maximum number of frame retries during direct transmission.
otLinkGetMaxFrameRetriesIndirect(otInstance *aInstance)
uint8_t
Returns the maximum number of frame retries during indirect transmission.
otLinkGetPanId(otInstance *aInstance)
Get the IEEE 802.15.4 PAN ID.
otLinkGetPollPeriod(otInstance *aInstance)
uint32_t
Get the data poll period of sleepy end device.
otLinkGetRegion(otInstance *aInstance, uint16_t *aRegionCode)
Get the region code.
otLinkGetShortAddress(otInstance *aInstance)
Get the IEEE 802.15.4 Short Address.
otLinkGetSupportedChannelMask(otInstance *aInstance)
uint32_t
Get the supported channel mask of MAC layer.
otLinkGetTxDirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries)
const uint32_t *
Gets histogram of retries for a single direct packet until success.
otLinkGetTxIndirectRetrySuccessHistogram(otInstance *aInstance, uint8_t *aNumberOfEntries)
const uint32_t *
Gets histogram of retries for a single indirect packet until success.
otLinkGetWakeupChannel(otInstance *aInstance)
uint8_t
Gets the Wake-up channel.
otLinkGetWakeupListenParameters(otInstance *aInstance, uint32_t *aInterval, uint32_t *aDuration)
void
Get the wake-up listen parameters.
otLinkIsActiveScanInProgress(otInstance *aInstance)
bool
Indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress.
otLinkIsCslEnabled(otInstance *aInstance)
bool
Indicates whether or not CSL is enabled.
otLinkIsCslSupported(otInstance *aInstance)
bool
Indicates whether the device is connected to a parent which supports CSL.
otLinkIsEnabled(otInstance *aInstance)
bool
Indicates whether or not the link layer is enabled.
otLinkIsEnergyScanInProgress(otInstance *aInstance)
bool
Indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress.
otLinkIsInTransmitState(otInstance *aInstance)
bool
Indicates whether or not an IEEE 802.15.4 MAC is in the transmit state.
otLinkIsPromiscuous(otInstance *aInstance)
bool
Indicates whether or not promiscuous mode is enabled at the link layer.
otLinkIsRadioFilterEnabled(otInstance *aInstance)
bool
Indicates whether the IEEE 802.15.4 radio filter is enabled or not.
otLinkIsWakeupListenEnabled(otInstance *aInstance)
bool
Returns whether listening for wake-up frames is enabled.
otLinkResetCounters(otInstance *aInstance)
void
Resets the MAC layer counters.
otLinkResetTxRetrySuccessHistogram(otInstance *aInstance)
void
Clears histogram statistics for direct and indirect transmissions.
otLinkSendDataRequest(otInstance *aInstance)
Enqueues an IEEE 802.15.4 Data Request message for transmission.
otLinkSendEmptyData(otInstance *aInstance)
Instructs the device to send an empty IEEE 802.15.4 data frame.
otLinkSetChannel(otInstance *aInstance, uint8_t aChannel)
Set the IEEE 802.15.4 channel.
otLinkSetCslChannel(otInstance *aInstance, uint8_t aChannel)
Sets the CSL channel.
otLinkSetCslPeriod(otInstance *aInstance, uint32_t aPeriod)
Sets the CSL period in microseconds.
otLinkSetCslTimeout(otInstance *aInstance, uint32_t aTimeout)
Sets the CSL timeout in seconds.
otLinkSetEnabled(otInstance *aInstance, bool aEnable)
Enables or disables the link layer.
otLinkSetExtendedAddress(otInstance *aInstance, const otExtAddress *aExtAddress)
Sets the IEEE 802.15.4 Extended Address.
otLinkSetMaxFrameRetriesDirect(otInstance *aInstance, uint8_t aMaxFrameRetriesDirect)
void
Sets the maximum number of frame retries during direct transmission.
otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRetriesIndirect)
void
Sets the maximum number of frame retries during indirect transmission.
otLinkSetPanId(otInstance *aInstance, otPanId aPanId)
Set the IEEE 802.15.4 PAN ID.
otLinkSetPcapCallback(otInstance *aInstance, otLinkPcapCallback aPcapCallback, void *aCallbackContext)
void
Registers a callback to provide received raw IEEE 802.15.4 frames.
otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod)
Set/clear user-specified/external data poll period for sleepy end device.
otLinkSetPromiscuous(otInstance *aInstance, bool aPromiscuous)
Enables or disables the link layer promiscuous mode.
otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled)
void
Enables/disables IEEE 802.15.4 radio filter mode.
otLinkSetRegion(otInstance *aInstance, uint16_t aRegionCode)
Sets the region code.
otLinkSetRxOnWhenIdle(otInstance *aInstance, bool aRxOnWhenIdle)
Sets the rx-on-when-idle state.
otLinkSetSupportedChannelMask(otInstance *aInstance, uint32_t aChannelMask)
Set the supported channel mask of MAC layer.
otLinkSetWakeUpListenEnabled(otInstance *aInstance, bool aEnable)
Enables or disables listening for wake-up frames.
otLinkSetWakeupChannel(otInstance *aInstance, uint8_t aChannel)
Sets the Wake-up channel.
otLinkSetWakeupListenParameters(otInstance *aInstance, uint32_t aInterval, uint32_t aDuration)
Set the wake-up listen parameters.

Macros
OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC (160)
Represents CSL period ten symbols unit in microseconds.
OT_MAC_FILTER_FIXED_RSS_DISABLED 127
Used to indicate no fixed received signal strength was set.
OT_MAC_FILTER_ITERATOR_INIT 0
Initializer for otMacFilterIterator.
OT_US_PER_TEN_SYMBOLS OT_RADIO_TEN_SYMBOLS_TIME
Time for 10 symbols in units of microseconds.

Structs
otActiveScanResult

Represents a received IEEE 802.15.4 Beacon.

otEnergyScanResult

Represents an energy scan result.

otMacCounters

Represents the MAC layer counters.

otMacFilterEntry

Represents a Mac Filter entry.

Enumerations

otMacFilterAddressMode

 otMacFilterAddressMode

Defines address mode of the mac filter.

Properties
OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST

Allowlist address filter mode is enabled.

OT_MAC_FILTER_ADDRESS_MODE_DENYLIST

Denylist address filter mode is enabled.

OT_MAC_FILTER_ADDRESS_MODE_DISABLED

Address filter is disabled.

Typedefs

otActiveScanResult

struct otActiveScanResult otActiveScanResult

Represents a received IEEE 802.15.4 Beacon.

otEnergyScanResult

struct otEnergyScanResult otEnergyScanResult

Represents an energy scan result.

otHandleActiveScanResult

void(* otHandleActiveScanResult)(otActiveScanResult *aResult, void *aContext)

Pointer is called during an IEEE 802.15.4 Active Scan when an IEEE 802.15.4 Beacon is received or the scan completes.

Details
Parameters
[in] aResult
A valid pointer to the beacon information or NULL when the active scan completes.
[in] aContext
A pointer to application-specific context.

otHandleEnergyScanResult

void(* otHandleEnergyScanResult)(otEnergyScanResult *aResult, void *aContext)

Pointer is called during an IEEE 802.15.4 Energy Scan when the result for a channel is ready or the scan completes.

Details
Parameters
[in] aResult
A valid pointer to the energy scan result information or NULL when the energy scan completes.
[in] aContext
A pointer to application-specific context.

otLinkPcapCallback

void(* otLinkPcapCallback)(const otRadioFrame *aFrame, bool aIsTx, void *aContext)

Pointer is called when an IEEE 802.15.4 frame is received.

Details
Parameters
[in] aFrame
A pointer to the received IEEE 802.15.4 frame.
[in] aIsTx
Whether this frame is transmitted, not received.
[in] aContext
A pointer to application-specific context.

otMacCounters

struct otMacCounters otMacCounters

Represents the MAC layer counters.

otMacFilterAddressMode

enum otMacFilterAddressMode otMacFilterAddressMode

Defines address mode of the mac filter.

otMacFilterEntry

struct otMacFilterEntry otMacFilterEntry

Represents a Mac Filter entry.

otMacFilterIterator

uint8_t otMacFilterIterator

Used to iterate through mac filter entries.

Functions

otLinkActiveScan

otError otLinkActiveScan(
  otInstance *aInstance,
  uint32_t aScanChannels,
  uint16_t aScanDuration,
  otHandleActiveScanResult aCallback,
  void *aCallbackContext
)

Starts an IEEE 802.15.4 Active Scan.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aScanChannels
A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK).
[in] aScanDuration
The time in milliseconds to spend scanning each channel.
[in] aCallback
A pointer to a function called on receiving a beacon or scan completes.
[in] aCallbackContext
A pointer to application-specific context.
Return Values
OT_ERROR_NONE
Accepted the Active Scan request.
OT_ERROR_BUSY
Already performing an Active Scan.

otLinkConvertLinkQualityToRss

int8_t otLinkConvertLinkQualityToRss(
  otInstance *aInstance,
  uint8_t aLinkQuality
)

Converts link quality to typical received signal strength.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aLinkQuality
LinkQuality value, should be in range [0,3].
Returns
Typical platform received signal strength mapping to aLinkQuality.

otLinkConvertRssToLinkQuality

uint8_t otLinkConvertRssToLinkQuality(
  otInstance *aInstance,
  int8_t aRss
)

Converts received signal strength to link quality.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aRss
The received signal strength value to be converted.
Returns
Link quality value mapping to aRss.

otLinkEnergyScan

otError otLinkEnergyScan(
  otInstance *aInstance,
  uint32_t aScanChannels,
  uint16_t aScanDuration,
  otHandleEnergyScanResult aCallback,
  void *aCallbackContext
)

Starts an IEEE 802.15.4 Energy Scan.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aScanChannels
A bit vector indicating on which channels to perform energy scan.
[in] aScanDuration
The time in milliseconds to spend scanning each channel.
[in] aCallback
A pointer to a function called to pass on scan result on indicate scan completion.
[in] aCallbackContext
A pointer to application-specific context.
Return Values
OT_ERROR_NONE
Accepted the Energy Scan request.
OT_ERROR_BUSY
Could not start the energy scan.

otLinkFilterAddAddress

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

Adds an Extended Address to MAC filter.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aExtAddress
A pointer to the Extended Address (MUST NOT be NULL).
Return Values
OT_ERROR_NONE
Successfully added aExtAddress to MAC filter.
OT_ERROR_NO_BUFS
No available entry exists.

otLinkFilterAddRssIn

otError otLinkFilterAddRssIn(
  otInstance *aInstance,
  const otExtAddress *aExtAddress,
  int8_t aRss
)

Adds the specified Extended Address to the RssIn list (or modifies an existing address in the RssIn list) and sets the received signal strength (in dBm) entry for messages from that address.

The Extended Address does not necessarily have to be in the address allowlist/denylist filter to set the rss.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aExtAddress
A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL.
[in] aRss
A received signal strength (in dBm).
Return Values
OT_ERROR_NONE
Successfully added an entry for aExtAddress and aRss.
OT_ERROR_NO_BUFS
No available entry exists.

otLinkFilterClearAddresses

void otLinkFilterClearAddresses(
  otInstance *aInstance
)

Clears all the Extended Addresses from MAC filter.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otLinkFilterClearAllRssIn

void otLinkFilterClearAllRssIn(
  otInstance *aInstance
)

Clears all the received signal strength (rss) and link quality indicator (lqi) entries (including defaults) from the RssIn list.

Performing this action means that all Extended Addresses will use the on-air signal.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otLinkFilterClearDefaultRssIn

void otLinkFilterClearDefaultRssIn(
  otInstance *aInstance
)

Clears any previously set default received signal strength (in dBm) on MAC Filter.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otLinkFilterGetAddressMode

otMacFilterAddressMode otLinkFilterGetAddressMode(
  otInstance *aInstance
)

Gets the address mode of MAC filter.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
the address mode.

otLinkFilterGetNextAddress

otError otLinkFilterGetNextAddress(
  otInstance *aInstance,
  otMacFilterIterator *aIterator,
  otMacFilterEntry *aEntry
)

Gets an in-use address filter entry.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in,out] aIterator
A pointer to the MAC filter iterator context. To get the first in-use address filter entry, it should be set to OT_MAC_FILTER_ITERATOR_INIT. MUST NOT be NULL.
[out] aEntry
A pointer to where the information is placed. MUST NOT be NULL.
Return Values
OT_ERROR_NONE
Successfully retrieved an in-use address filter entry.
OT_ERROR_NOT_FOUND
No subsequent entry exists.

otLinkFilterGetNextRssIn

otError otLinkFilterGetNextRssIn(
  otInstance *aInstance,
  otMacFilterIterator *aIterator,
  otMacFilterEntry *aEntry
)

Gets an in-use RssIn filter entry.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in,out] aIterator
A pointer to the MAC filter iterator context. MUST NOT be NULL. To get the first entry, it should be set to OT_MAC_FILTER_ITERATOR_INIT.
[out] aEntry
A pointer to where the information is placed. The last entry would have the extended address as all 0xff to indicate the default received signal strength if it was set. aEntry MUST NOT be NULL.
Return Values
OT_ERROR_NONE
Successfully retrieved the next entry.
OT_ERROR_NOT_FOUND
No subsequent entry exists.

otLinkFilterRemoveAddress

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

Removes an Extended Address from MAC filter.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

No action is performed if there is no existing entry in Filter matching the given Extended Address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aExtAddress
A pointer to the Extended Address (MUST NOT be NULL).

otLinkFilterRemoveRssIn

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

Removes the specified Extended Address from the RssIn list.

Once removed from the RssIn list, this MAC address will instead use the default rss and lqi settings, assuming defaults have been set. (If no defaults have been set, the over-air signal is used.)

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

No action is performed if there is no existing entry in the RssIn list matching the specified Extended Address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aExtAddress
A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL.

otLinkFilterSetAddressMode

void otLinkFilterSetAddressMode(
  otInstance *aInstance,
  otMacFilterAddressMode aMode
)

Sets the address mode of MAC filter.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aMode
The address mode to set.

otLinkFilterSetDefaultRssIn

void otLinkFilterSetDefaultRssIn(
  otInstance *aInstance,
  int8_t aRss
)

Sets the default received signal strength (in dBm) on MAC Filter.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry in the Filter list (added using otLinkFilterAddRssIn()).

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aRss
The default received signal strength (in dBm) to set.

otLinkGetAlternateShortAddress

otShortAddress otLinkGetAlternateShortAddress(
  otInstance *aInstance
)

Get the IEEE 802.15.4 alternate short address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The alternate short address, or OT_RADIO_INVALID_SHORT_ADDR (0xfffe) if there is no alternate address.

otLinkGetCcaFailureRate

uint16_t otLinkGetCcaFailureRate(
  otInstance *aInstance
)

Returns the current CCA (Clear Channel Assessment) failure rate.

The rate is maintained over a window of (roughly) last OPENTHREAD_CONFIG_CCA_FAILURE_RATE_AVERAGING_WINDOW frame transmissions.

Details
Returns
The CCA failure rate with maximum value 0xffff corresponding to 100% failure rate.

otLinkGetChannel

uint8_t otLinkGetChannel(
  otInstance *aInstance
)

Get the IEEE 802.15.4 channel.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The IEEE 802.15.4 channel.
See also:
otLinkSetChannel

otLinkGetCounters

const otMacCounters * otLinkGetCounters(
  otInstance *aInstance
)

Get the MAC layer counters.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the MAC layer counters.

otLinkGetCslChannel

uint8_t otLinkGetCslChannel(
  otInstance *aInstance
)

Gets the CSL channel.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The CSL channel.

otLinkGetCslPeriod

uint32_t otLinkGetCslPeriod(
  otInstance *aInstance
)

Gets the CSL period in microseconds.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The CSL period in microseconds.

otLinkGetCslTimeout

uint32_t otLinkGetCslTimeout(
  otInstance *aInstance
)

Gets the CSL timeout.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The CSL timeout in seconds.

otLinkGetExtendedAddress

const otExtAddress * otLinkGetExtendedAddress(
  otInstance *aInstance
)

Gets the IEEE 802.15.4 Extended Address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the IEEE 802.15.4 Extended Address.

otLinkGetFactoryAssignedIeeeEui64

void otLinkGetFactoryAssignedIeeeEui64(
  otInstance *aInstance,
  otExtAddress *aEui64
)

Get the factory-assigned IEEE EUI-64.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
[out] aEui64
A pointer to where the factory-assigned IEEE EUI-64 is placed.

otLinkGetFrameCounter

uint32_t otLinkGetFrameCounter(
  otInstance *aInstance
)

Gets the current MAC frame counter value.

Details
Parameters
[in] aInstance
A pointer to the OpenThread instance.
Returns
The current MAC frame counter value.

otLinkGetMaxFrameRetriesDirect

uint8_t otLinkGetMaxFrameRetriesDirect(
  otInstance *aInstance
)

Returns the maximum number of frame retries during direct transmission.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The maximum number of retries during direct transmission.

otLinkGetMaxFrameRetriesIndirect

uint8_t otLinkGetMaxFrameRetriesIndirect(
  otInstance *aInstance
)

Returns the maximum number of frame retries during indirect transmission.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The maximum number of retries during indirect transmission.

otLinkGetPanId

otPanId otLinkGetPanId(
  otInstance *aInstance
)

Get the IEEE 802.15.4 PAN ID.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The IEEE 802.15.4 PAN ID.
See also:
otLinkSetPanId

otLinkGetPollPeriod

uint32_t otLinkGetPollPeriod(
  otInstance *aInstance
)

Get the data poll period of sleepy end device.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The data poll period of sleepy end device in milliseconds.
See also:
otLinkSetPollPeriod

otLinkGetRegion

otError otLinkGetRegion(
  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 code. The aRegionCode >> 8 is first ascii char and the aRegionCode & 0xff is the second ascii char.
Return Values
OT_ERROR_INVALID_ARGS
aRegionCode is nullptr.
OT_ERROR_FAILED
Other platform specific errors.
OT_ERROR_NONE
Successfully got region code.
OT_ERROR_NOT_IMPLEMENTED
The feature is not implemented.

otLinkGetShortAddress

otShortAddress otLinkGetShortAddress(
  otInstance *aInstance
)

Get the IEEE 802.15.4 Short Address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The IEEE 802.15.4 Short Address.

otLinkGetSupportedChannelMask

uint32_t otLinkGetSupportedChannelMask(
  otInstance *aInstance
)

Get the supported channel mask of MAC layer.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The supported channel mask as uint32_t with bit 0 (lsb) mapping to channel 0, bit 1 to channel 1, so on.

otLinkGetTxDirectRetrySuccessHistogram

const uint32_t * otLinkGetTxDirectRetrySuccessHistogram(
  otInstance *aInstance,
  uint8_t *aNumberOfEntries
)

Gets histogram of retries for a single direct packet until success.

Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aNumberOfEntries
A pointer to where the size of returned histogram array is placed.
Returns
A pointer to the histogram of retries (in a form of an array). The n-th element indicates that the packet has been sent with n-th retry.

otLinkGetTxIndirectRetrySuccessHistogram

const uint32_t * otLinkGetTxIndirectRetrySuccessHistogram(
  otInstance *aInstance,
  uint8_t *aNumberOfEntries
)

Gets histogram of retries for a single indirect packet until success.

Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aNumberOfEntries
A pointer to where the size of returned histogram array is placed.
Returns
A pointer to the histogram of retries (in a form of an array). The n-th element indicates that the packet has been sent with n-th retry.

otLinkGetWakeupChannel

uint8_t otLinkGetWakeupChannel(
  otInstance *aInstance
)

Gets the Wake-up channel.

Requires OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE or OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The Wake-up channel.

otLinkGetWakeupListenParameters

void otLinkGetWakeupListenParameters(
  otInstance *aInstance,
  uint32_t *aInterval,
  uint32_t *aDuration
)

Get the wake-up listen parameters.

Requires OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aInterval
A pointer to return the wake-up listen interval in microseconds.
[out] aDuration
A pointer to return the wake-up listen duration in microseconds.

otLinkIsActiveScanInProgress

bool otLinkIsActiveScanInProgress(
  otInstance *aInstance
)

Indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
true if an IEEE 802.15.4 Active Scan is in progress, false otherwise.

otLinkIsCslEnabled

bool otLinkIsCslEnabled(
  otInstance *aInstance
)

Indicates whether or not CSL is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
Link layer is CSL enabled.
FALSE
Link layer is not CSL enabled.

otLinkIsCslSupported

bool otLinkIsCslSupported(
  otInstance *aInstance
)

Indicates whether the device is connected to a parent which supports CSL.

Details
Return Values
TRUE
If parent supports CSL.
FALSE
If parent does not support CSL.

otLinkIsEnabled

bool otLinkIsEnabled(
  otInstance *aInstance
)

Indicates whether or not the link layer is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
Link layer is enabled.
FALSE
Link layer is not enabled.

otLinkIsEnergyScanInProgress

bool otLinkIsEnergyScanInProgress(
  otInstance *aInstance
)

Indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
true if an IEEE 802.15.4 Energy Scan is in progress, false otherwise.

otLinkIsInTransmitState

bool otLinkIsInTransmitState(
  otInstance *aInstance
)

Indicates whether or not an IEEE 802.15.4 MAC is in the transmit state.

MAC module is in the transmit state during CSMA/CA procedure, CCA, Data, Beacon or Data Request frame transmission and receiving an ACK of a transmitted frame. MAC module is not in the transmit state during transmission of an ACK frame or a Beacon Request frame.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
true if an IEEE 802.15.4 MAC is in the transmit state, false otherwise.

otLinkIsPromiscuous

bool otLinkIsPromiscuous(
  otInstance *aInstance
)

Indicates whether or not promiscuous mode is enabled at the link layer.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
Promiscuous mode is enabled.
FALSE
Promiscuous mode is not enabled.

otLinkIsRadioFilterEnabled

bool otLinkIsRadioFilterEnabled(
  otInstance *aInstance
)

Indicates whether the IEEE 802.15.4 radio filter is enabled or not.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Details
Return Values
TRUE
If the radio filter is enabled.
FALSE
If the radio filter is disabled.

otLinkIsWakeupListenEnabled

bool otLinkIsWakeupListenEnabled(
  otInstance *aInstance
)

Returns whether listening for wake-up frames is enabled.

Requires OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
If listening for wake-up frames is enabled.
FALSE
If listening for wake-up frames is not enabled.

otLinkResetCounters

void otLinkResetCounters(
  otInstance *aInstance
)

Resets the MAC layer counters.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otLinkResetTxRetrySuccessHistogram

void otLinkResetTxRetrySuccessHistogram(
  otInstance *aInstance
)

Clears histogram statistics for direct and indirect transmissions.

Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otLinkSendDataRequest

otError otLinkSendDataRequest(
  otInstance *aInstance
)

Enqueues an IEEE 802.15.4 Data Request message for transmission.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_ERROR_NONE
Successfully enqueued an IEEE 802.15.4 Data Request message.
OT_ERROR_INVALID_STATE
Device is not in rx-off-when-idle mode.
OT_ERROR_NO_BUFS
Insufficient message buffers available.

otLinkSendEmptyData

otError otLinkSendEmptyData(
  otInstance *aInstance
)

Instructs the device to send an empty IEEE 802.15.4 data frame.

Is only supported on an Rx-Off-When-Idle device to send an empty data frame to its parent. Note: available only when OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_ERROR_NONE
Successfully enqueued an empty message.
OT_ERROR_INVALID_STATE
Device is not in Rx-Off-When-Idle mode.
OT_ERROR_NO_BUFS
Insufficient message buffers available.

otLinkSetChannel

otError otLinkSetChannel(
  otInstance *aInstance,
  uint8_t aChannel
)

Set the IEEE 802.15.4 channel.

Succeeds only when Thread protocols are disabled. A successful call to this function invalidates the Active and Pending Operational Datasets in non-volatile memory.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aChannel
The IEEE 802.15.4 channel.
Return Values
OT_ERROR_NONE
Successfully set the channel.
OT_ERROR_INVALID_ARGS
If aChannel is not in the range [11, 26] or is not in the supported channel mask.
OT_ERROR_INVALID_STATE
Thread protocols are enabled.
See also:
otLinkGetChannel

otLinkSetCslChannel

otError otLinkSetCslChannel(
  otInstance *aInstance,
  uint8_t aChannel
)

Sets the CSL channel.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aChannel
The CSL sample channel. Channel value should be 0 (Set CSL Channel unspecified) or within the range [1, 10] (if 915-MHz supported) and 11, 26.
Return Values
OT_ERROR_NONE
Successfully set the CSL parameters.
OT_ERROR_INVALID_ARGS
Invalid aChannel.

otLinkSetCslPeriod

otError otLinkSetCslPeriod(
  otInstance *aInstance,
  uint32_t aPeriod
)

Sets the CSL period in microseconds.

Disable CSL by setting this parameter to 0.

The CSL period MUST be a multiple of OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC, otherwise OT_ERROR_INVALID_ARGS is returned.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPeriod
The CSL period in microseconds.
Return Values
OT_ERROR_NONE
Successfully set the CSL period.
OT_ERROR_INVALID_ARGS
Invalid CSL period

otLinkSetCslTimeout

otError otLinkSetCslTimeout(
  otInstance *aInstance,
  uint32_t aTimeout
)

Sets the CSL timeout in seconds.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aTimeout
The CSL timeout in seconds.
Return Values
OT_ERROR_NONE
Successfully set the CSL timeout.
OT_ERROR_INVALID_ARGS
Invalid CSL timeout.

otLinkSetEnabled

otError otLinkSetEnabled(
  otInstance *aInstance,
  bool aEnable
)

Enables or disables the link layer.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnable
true to enable the link layer, or false otherwise.
Return Values
OT_ERROR_NONE
Successfully enabled / disabled the link layer.
OT_ERROR_INVALID_STATE
Could not disable the link layer because the Thread interface is enabled.

otLinkSetExtendedAddress

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

Sets the IEEE 802.15.4 Extended Address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aExtAddress
A pointer to the IEEE 802.15.4 Extended Address.
Return Values
OT_ERROR_NONE
Successfully set the IEEE 802.15.4 Extended Address.
OT_ERROR_INVALID_ARGS
aExtAddress was NULL.
OT_ERROR_INVALID_STATE
Thread protocols are enabled.

otLinkSetMaxFrameRetriesDirect

void otLinkSetMaxFrameRetriesDirect(
  otInstance *aInstance,
  uint8_t aMaxFrameRetriesDirect
)

Sets the maximum number of frame retries during direct transmission.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aMaxFrameRetriesDirect
The maximum number of retries during direct transmission.

otLinkSetMaxFrameRetriesIndirect

void otLinkSetMaxFrameRetriesIndirect(
  otInstance *aInstance,
  uint8_t aMaxFrameRetriesIndirect
)

Sets the maximum number of frame retries during indirect transmission.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aMaxFrameRetriesIndirect
The maximum number of retries during indirect transmission.

otLinkSetPanId

otError otLinkSetPanId(
  otInstance *aInstance,
  otPanId aPanId
)

Set the IEEE 802.15.4 PAN ID.

Succeeds only when Thread protocols are disabled. A successful call to this function also invalidates the Active and Pending Operational Datasets in non-volatile memory.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPanId
The IEEE 802.15.4 PAN ID.
Return Values
OT_ERROR_NONE
Successfully set the PAN ID.
OT_ERROR_INVALID_ARGS
If aPanId is not in the range [0, 65534].
OT_ERROR_INVALID_STATE
Thread protocols are enabled.
See also:
otLinkGetPanId

otLinkSetPcapCallback

void otLinkSetPcapCallback(
  otInstance *aInstance,
  otLinkPcapCallback aPcapCallback,
  void *aCallbackContext
)

Registers a callback to provide received raw IEEE 802.15.4 frames.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPcapCallback
A pointer to a function that is called when receiving an IEEE 802.15.4 link frame or NULL to disable the callback.
[in] aCallbackContext
A pointer to application-specific context.

otLinkSetPollPeriod

otError otLinkSetPollPeriod(
  otInstance *aInstance,
  uint32_t aPollPeriod
)

Set/clear user-specified/external data poll period for sleepy end device.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPollPeriod
data poll period in milliseconds.
Return Values
OT_ERROR_NONE
Successfully set/cleared user-specified poll period.
OT_ERROR_INVALID_ARGS
If aPollPeriod is invalid.
See also:
otLinkGetPollPeriod

otLinkSetPromiscuous

otError otLinkSetPromiscuous(
  otInstance *aInstance,
  bool aPromiscuous
)

Enables or disables the link layer promiscuous mode.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPromiscuous
true to enable promiscuous mode, or false otherwise.
Return Values
OT_ERROR_NONE
Successfully enabled promiscuous mode.
OT_ERROR_INVALID_STATE
Could not enable promiscuous mode because the Thread interface is enabled.

otLinkSetRadioFilterEnabled

void otLinkSetRadioFilterEnabled(
  otInstance *aInstance,
  bool aFilterEnabled
)

Enables/disables IEEE 802.15.4 radio filter mode.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

The radio filter is mainly intended for testing. It can be used to temporarily block all tx/rx on the 802.15.4 radio. When radio filter is enabled, radio is put to sleep instead of receive (to ensure device does not receive any frame and/or potentially send ack). Also the frame transmission requests return immediately without sending the frame over the air (return "no ack" error if ack is requested, otherwise return success).

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aFilterEnabled
TRUE to enable radio filter, FALSE to disable

otLinkSetRegion

otError otLinkSetRegion(
  otInstance *aInstance,
  uint16_t aRegionCode
)

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

otLinkSetRxOnWhenIdle

otError otLinkSetRxOnWhenIdle(
  otInstance *aInstance,
  bool aRxOnWhenIdle
)

Sets the rx-on-when-idle state.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aRxOnWhenIdle
TRUE to keep radio in Receive state, FALSE to put to Sleep state during idle periods.
Return Values
OT_ERROR_NONE
If successful.
OT_ERROR_INVALID_STATE
If the raw link-layer isn't enabled.

otLinkSetSupportedChannelMask

otError otLinkSetSupportedChannelMask(
  otInstance *aInstance,
  uint32_t aChannelMask
)

Set the supported channel mask of MAC layer.

Succeeds only when Thread protocols are disabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aChannelMask
The supported channel mask (bit 0 or lsb mapping to channel 0, and so on).
Return Values
OT_ERROR_NONE
Successfully set the supported channel mask.
OT_ERROR_INVALID_STATE
Thread protocols are enabled.

otLinkSetWakeUpListenEnabled

otError otLinkSetWakeUpListenEnabled(
  otInstance *aInstance,
  bool aEnable
)

Enables or disables listening for wake-up frames.

Requires OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnable
true to enable listening for wake-up frames, or false otherwise.
Return Values
OT_ERROR_NONE
Successfully enabled / disabled the listening for wake-up frames.
OT_ERROR_INVALID_ARGS
The listen duration is greater than the listen interval.
OT_ERROR_INVALID_STATE
Could not enable listening for wake-up frames due to bad configuration.

otLinkSetWakeupChannel

otError otLinkSetWakeupChannel(
  otInstance *aInstance,
  uint8_t aChannel
)

Sets the Wake-up channel.

Requires OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE or OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aChannel
The Wake-up sample channel. Channel value should be 0 (Set Wake-up Channel unspecified, which means the device will use the PAN channel) or within the range [1, 10] (if 915-MHz supported) and 11, 26.
Return Values
OT_ERROR_NONE
Successfully set the Wake-up channel.
OT_ERROR_INVALID_ARGS
Invalid aChannel.

otLinkSetWakeupListenParameters

otError otLinkSetWakeupListenParameters(
  otInstance *aInstance,
  uint32_t aInterval,
  uint32_t aDuration
)

Set the wake-up listen parameters.

The listen interval must be greater than the listen duration. The listen duration must be greater or equal than the minimum supported.

Requires OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aInterval
The wake-up listen interval in microseconds.
[in] aDuration
The wake-up listen duration in microseconds.
Return Values
OT_ERROR_NONE
Successfully set the wake-up listen parameters.
OT_ERROR_INVALID_ARGS
Invalid wake-up listen parameters.

Macros

 OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC (160)

Represents CSL period ten symbols unit in microseconds.

The CSL period (in micro seconds) MUST be a multiple of this value.

OT_MAC_FILTER_FIXED_RSS_DISABLED

 OT_MAC_FILTER_FIXED_RSS_DISABLED 127

Used to indicate no fixed received signal strength was set.

OT_MAC_FILTER_ITERATOR_INIT

 OT_MAC_FILTER_ITERATOR_INIT 0

Initializer for otMacFilterIterator.

OT_US_PER_TEN_SYMBOLS

 OT_US_PER_TEN_SYMBOLS OT_RADIO_TEN_SYMBOLS_TIME

Time for 10 symbols in units of microseconds.

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.