Modules#

otThreadLinkInfo

otMacFilterEntry

otMacCounters

otActiveScanResult

otEnergyScanResult

Link#

This module includes functions that control link-layer configuration.

Enumerations#

enum
OT_MAC_FILTER_ADDRESS_MODE_DISABLED
OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST
OT_MAC_FILTER_ADDRESS_MODE_DENYLIST
}

Defines address mode of the mac filter.

Typedefs#

typedef struct otThreadLinkInfo

This structure represents link-specific information for messages received from the Thread radio.

typedef uint8_t

Used to iterate through mac filter entries.

Defines address mode of the mac filter.

typedef struct otMacFilterEntry

This structure represents a Mac Filter entry.

typedef struct otMacCounters

This structure represents the MAC layer counters.

typedef struct otActiveScanResult

This structure represents a received IEEE 802.15.4 Beacon.

typedef struct otEnergyScanResult

This structure represents an energy scan result.

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

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

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

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

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

This function pointer is called when an IEEE 802.15.4 frame is received.

Functions#

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

This function starts an IEEE 802.15.4 Active Scan.

bool
otLinkIsActiveScanInProgress(otInstance *aInstance)

This function indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress.

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

This function starts an IEEE 802.15.4 Energy Scan.

bool
otLinkIsEnergyScanInProgress(otInstance *aInstance)

This function indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress.

otLinkSendDataRequest(otInstance *aInstance)

This function enqueues an IEEE 802.15.4 Data Request message for transmission.

bool
otLinkIsInTransmitState(otInstance *aInstance)

This function indicates whether or not an IEEE 802.15.4 MAC is in the transmit state.

uint8_t
otLinkGetChannel(otInstance *aInstance)

Get the IEEE 802.15.4 channel.

otLinkSetChannel(otInstance *aInstance, uint8_t aChannel)

Set the IEEE 802.15.4 channel.

uint32_t
otLinkGetSupportedChannelMask(otInstance *aInstance)

Get the supported channel mask of MAC layer.

otLinkSetSupportedChannelMask(otInstance *aInstance, uint32_t aChannelMask)

Set the supported channel mask of MAC layer.

const otExtAddress *
otLinkGetExtendedAddress(otInstance *aInstance)

Gets the IEEE 802.15.4 Extended Address.

otLinkSetExtendedAddress(otInstance *aInstance, const otExtAddress *aExtAddress)

Sets the IEEE 802.15.4 Extended Address.

void
otLinkGetFactoryAssignedIeeeEui64(otInstance *aInstance, otExtAddress *aEui64)

Get the factory-assigned IEEE EUI-64.

otLinkGetPanId(otInstance *aInstance)

Get the IEEE 802.15.4 PAN ID.

otLinkSetPanId(otInstance *aInstance, otPanId aPanId)

Set the IEEE 802.15.4 PAN ID.

uint32_t
otLinkGetPollPeriod(otInstance *aInstance)

Get the data poll period of sleepy end device.

otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod)

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

otLinkGetShortAddress(otInstance *aInstance)

Get the IEEE 802.15.4 Short Address.

uint8_t
otLinkGetMaxFrameRetriesDirect(otInstance *aInstance)

This method returns the maximum number of frame retries during direct transmission.

void
otLinkSetMaxFrameRetriesDirect(otInstance *aInstance, uint8_t aMaxFrameRetriesDirect)

This method sets the maximum number of frame retries during direct transmission.

uint8_t
otLinkGetMaxFrameRetriesIndirect(otInstance *aInstance)

This method returns the maximum number of frame retries during indirect transmission.

void
otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRetriesIndirect)

This method sets the maximum number of frame retries during indirect transmission.

otLinkFilterGetAddressMode(otInstance *aInstance)

This function gets the address mode of MAC filter.

void
otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aMode)

This function sets the address mode of MAC filter.

otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAddress)

This method adds an Extended Address to MAC filter.

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

This method removes an Extended Address from MAC filter.

void
otLinkFilterClearAddresses(otInstance *aInstance)

This method clears all the Extended Addresses from MAC filter.

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

This method gets an in-use address filter entry.

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

This method adds a fixed received signal strength (in dBm) entry for the messages from a given Extended Address in MAC Filter.

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

This method removes a MAC Filter entry for fixed received signal strength setting for a given Extended Address.

void
otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss)

This method sets the default received signal strength (in dBm) on MAC Filter.

void
otLinkFilterClearDefaultRssIn(otInstance *aInstance)

This method clears any previously set default received signal strength (in dBm) on MAC Filter.

void
otLinkFilterClearAllRssIn(otInstance *aInstance)

This method clears all the received signal strength entries (including default RSS-in) on MAC Filter.

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

This method gets an in-use RssIn filter entry.

void
otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled)

This function enables/disables IEEE 802.15.4 radio filter mode.

bool
otLinkIsRadioFilterEnabled(otInstance *aInstance)

This function indicates whether the IEEE 802.15.4 radio filter is enabled or not.

uint8_t
otLinkConvertRssToLinkQuality(otInstance *aInstance, int8_t aRss)

This method converts received signal strength to link quality.

int8_t
otLinkConvertLinkQualityToRss(otInstance *aInstance, uint8_t aLinkQuality)

This method converts link quality to typical received signal strength.

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

This method gets histogram of retries for a single direct packet until success.

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

This method gets histogram of retries for a single indirect packet until success.

void
otLinkResetTxRetrySuccessHistogram(otInstance *aInstance)

This method clears histogram statistics for direct and indirect transmissions.

otLinkGetCounters(otInstance *aInstance)

Get the MAC layer counters.

void
otLinkResetCounters(otInstance *aInstance)

Resets the MAC layer counters.

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

This function registers a callback to provide received raw IEEE 802.15.4 frames.

bool
otLinkIsPromiscuous(otInstance *aInstance)

This function indicates whether or not promiscuous mode is enabled at the link layer.

otLinkSetPromiscuous(otInstance *aInstance, bool aPromiscuous)

This function enables or disables the link layer promiscuous mode.

uint8_t
otLinkCslGetChannel(otInstance *aInstance)

This function gets the CSL channel.

otLinkCslSetChannel(otInstance *aInstance, uint8_t aChannel)

Sets the CSL channel.

uint16_t
otLinkCslGetPeriod(otInstance *aInstance)

This function gets the CSL period.

otLinkCslSetPeriod(otInstance *aInstance, uint16_t aPeriod)

Sets the CSL period in units of 10 symbols.

uint32_t
otLinkCslGetTimeout(otInstance *aInstance)

This function gets the CSL timeout.

otLinkCslSetTimeout(otInstance *aInstance, uint32_t aTimeout)

Sets the CSL timeout in seconds.

uint16_t
otLinkGetCcaFailureRate(otInstance *aInstance)

This function returns the current CCA (Clear Channel Assessment) failure rate.

otLinkSetEnabled(otInstance *aInstance, bool aEnable)

This function enables or disables the link layer.

bool
otLinkIsEnabled(otInstance *aInstance)

This function indicates whether or not the link layer is enabled.

otLinkSendEmptyData(otInstance *aInstance)

This function instructs the device to send an empty IEEE 802.15.4 data frame.

Macros#

#define
OT_US_PER_TEN_SYMBOLS OT_RADIO_TEN_SYMBOLS_TIME

Time for 10 symbols in units of microseconds.

#define

Used to indicate no fixed received signal strength was set.

#define

Initializer for otMacFilterIterator.

Enumeration Documentation#

otMacFilterAddressMode#

otMacFilterAddressMode

Defines address mode of the mac filter.

Enumerator
OT_MAC_FILTER_ADDRESS_MODE_DISABLED

Address filter is disabled.

OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST

Allowlist address filter mode is enabled.

OT_MAC_FILTER_ADDRESS_MODE_DENYLIST

Denylist address filter mode is enabled.


Definition at line 92 of file include/openthread/link.h

Typedef Documentation#

otThreadLinkInfo#

typedef struct otThreadLinkInfo otThreadLinkInfo

This structure represents link-specific information for messages received from the Thread radio.


Definition at line 76 of file include/openthread/link.h

otMacFilterIterator#

typedef uint8_t otMacFilterIterator

Used to iterate through mac filter entries.


Definition at line 86 of file include/openthread/link.h

otMacFilterAddressMode#

typedef enum otMacFilterAddressMode otMacFilterAddressMode

Defines address mode of the mac filter.


Definition at line 97 of file include/openthread/link.h

otMacFilterEntry#

typedef struct otMacFilterEntry otMacFilterEntry

This structure represents a Mac Filter entry.


Definition at line 107 of file include/openthread/link.h

otMacCounters#

typedef struct otMacCounters otMacCounters

This structure represents the MAC layer counters.


Definition at line 374 of file include/openthread/link.h

otActiveScanResult#

typedef struct otActiveScanResult otActiveScanResult

This structure represents a received IEEE 802.15.4 Beacon.


Definition at line 398 of file include/openthread/link.h

otEnergyScanResult#

typedef struct otEnergyScanResult otEnergyScanResult

This structure represents an energy scan result.


Definition at line 408 of file include/openthread/link.h

otHandleActiveScanResult#

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

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

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.


Definition at line 418 of file include/openthread/link.h

otHandleEnergyScanResult#

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

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

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.


Definition at line 456 of file include/openthread/link.h

otLinkPcapCallback#

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

This function pointer is called when an IEEE 802.15.4 frame is received.

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.

Note

  • This callback is called after FCS processing and aFrame may not contain the actual FCS that was received.

  • This callback is called before IEEE 802.15.4 security processing.


Definition at line 987 of file include/openthread/link.h

Function Documentation#

otLinkActiveScan#

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

This function starts an IEEE 802.15.4 Active Scan.

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.


Definition at line 433 of file include/openthread/link.h

otLinkIsActiveScanInProgress#

bool otLinkIsActiveScanInProgress (otInstance *aInstance)

This function indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • true if an IEEE 802.15.4 Active Scan is in progress, false otherwise.


Definition at line 446 of file include/openthread/link.h

otLinkEnergyScan#

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

This function starts an IEEE 802.15.4 Energy Scan.

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.


Definition at line 471 of file include/openthread/link.h

otLinkIsEnergyScanInProgress#

bool otLinkIsEnergyScanInProgress (otInstance *aInstance)

This function indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • true if an IEEE 802.15.4 Energy Scan is in progress, false otherwise.


Definition at line 485 of file include/openthread/link.h

otLinkSendDataRequest#

otError otLinkSendDataRequest (otInstance *aInstance)

This function enqueues an IEEE 802.15.4 Data Request message for transmission.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 497 of file include/openthread/link.h

otLinkIsInTransmitState#

bool otLinkIsInTransmitState (otInstance *aInstance)

This function indicates whether or not an IEEE 802.15.4 MAC is in the transmit state.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.

Returns

  • true if an IEEE 802.15.4 MAC is in the transmit state, false otherwise.


Definition at line 511 of file include/openthread/link.h

otLinkGetChannel#

uint8_t otLinkGetChannel (otInstance *aInstance)

Get the IEEE 802.15.4 channel.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The IEEE 802.15.4 channel.

See Also


Definition at line 523 of file include/openthread/link.h

otLinkSetChannel#

otError otLinkSetChannel (otInstance *aInstance, uint8_t aChannel)

Set the IEEE 802.15.4 channel.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aChannel

The IEEE 802.15.4 channel.

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

See Also


Definition at line 541 of file include/openthread/link.h

otLinkGetSupportedChannelMask#

uint32_t otLinkGetSupportedChannelMask (otInstance *aInstance)

Get the supported channel mask of MAC layer.

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.


Definition at line 551 of file include/openthread/link.h

otLinkSetSupportedChannelMask#

otError otLinkSetSupportedChannelMask (otInstance *aInstance, uint32_t aChannelMask)

Set the supported channel mask of MAC layer.

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

This function succeeds only when Thread protocols are disabled.


Definition at line 565 of file include/openthread/link.h

otLinkGetExtendedAddress#

const otExtAddress * otLinkGetExtendedAddress (otInstance *aInstance)

Gets the IEEE 802.15.4 Extended Address.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • A pointer to the IEEE 802.15.4 Extended Address.


Definition at line 575 of file include/openthread/link.h

otLinkSetExtendedAddress#

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

Sets the IEEE 802.15.4 Extended Address.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aExtAddress

A pointer to the IEEE 802.15.4 Extended Address.

Note

  • Only succeeds when Thread protocols are disabled.


Definition at line 590 of file include/openthread/link.h

otLinkGetFactoryAssignedIeeeEui64#

void otLinkGetFactoryAssignedIeeeEui64 (otInstance *aInstance, otExtAddress *aEui64)

Get the factory-assigned IEEE EUI-64.

Parameters
[in]aInstance

A pointer to the OpenThread instance.

[out]aEui64

A pointer to where the factory-assigned IEEE EUI-64 is placed.


Definition at line 599 of file include/openthread/link.h

otLinkGetPanId#

otPanId otLinkGetPanId (otInstance *aInstance)

Get the IEEE 802.15.4 PAN ID.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The IEEE 802.15.4 PAN ID.

See Also


Definition at line 611 of file include/openthread/link.h

otLinkSetPanId#

otError otLinkSetPanId (otInstance *aInstance, otPanId aPanId)

Set the IEEE 802.15.4 PAN ID.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aPanId

The IEEE 802.15.4 PAN ID.

This function succeeds only when Thread protocols are disabled. A successful call to this functi