Link#

This module includes functions that control link-layer configuration.

Modules#

otThreadLinkInfo

otMacFilterEntry

otMacCounters

otActiveScanResult

otEnergyScanResult

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

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

Represents a Mac Filter entry.

typedef struct otMacCounters

Represents the MAC layer counters.

typedef struct otActiveScanResult

Represents a received IEEE 802.15.4 Beacon.

typedef struct otEnergyScanResult

Represents an energy scan result.

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

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

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

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)

Starts an IEEE 802.15.4 Active Scan.

bool
otLinkIsActiveScanInProgress(otInstance *aInstance)

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)

Starts an IEEE 802.15.4 Energy Scan.

bool
otLinkIsEnergyScanInProgress(otInstance *aInstance)

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

otLinkSendDataRequest(otInstance *aInstance)

Enqueues an IEEE 802.15.4 Data Request message for transmission.

bool
otLinkIsInTransmitState(otInstance *aInstance)

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)

Returns the maximum number of frame retries during direct transmission.

void
otLinkSetMaxFrameRetriesDirect(otInstance *aInstance, uint8_t aMaxFrameRetriesDirect)

Sets the maximum number of frame retries during direct transmission.

uint8_t
otLinkGetMaxFrameRetriesIndirect(otInstance *aInstance)

Returns the maximum number of frame retries during indirect transmission.

void
otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRetriesIndirect)

Sets the maximum number of frame retries during indirect transmission.

otLinkFilterGetAddressMode(otInstance *aInstance)

Gets the address mode of MAC filter.

void
otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aMode)

Sets the address mode of MAC filter.

otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAddress)

Adds an Extended Address to MAC filter.

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

Removes an Extended Address from MAC filter.

void
otLinkFilterClearAddresses(otInstance *aInstance)

Clears all the Extended Addresses from MAC filter.

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

Gets an in-use address filter entry.

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.

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

Removes the specified Extended Address from the RssIn list.

void
otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss)

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

void
otLinkFilterClearDefaultRssIn(otInstance *aInstance)

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

void
otLinkFilterClearAllRssIn(otInstance *aInstance)

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

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

Gets an in-use RssIn filter entry.

void
otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled)

Enables/disables IEEE 802.15.4 radio filter mode.

bool
otLinkIsRadioFilterEnabled(otInstance *aInstance)

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

uint8_t
otLinkConvertRssToLinkQuality(otInstance *aInstance, int8_t aRss)

Converts received signal strength to link quality.

int8_t
otLinkConvertLinkQualityToRss(otInstance *aInstance, uint8_t aLinkQuality)

Converts link quality to typical received signal strength.

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

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

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

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

void
otLinkResetTxRetrySuccessHistogram(otInstance *aInstance)

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)

Registers a callback to provide received raw IEEE 802.15.4 frames.

bool
otLinkIsPromiscuous(otInstance *aInstance)

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

otLinkSetPromiscuous(otInstance *aInstance, bool aPromiscuous)

Enables or disables the link layer promiscuous mode.

uint8_t
otLinkGetCslChannel(otInstance *aInstance)

Gets the CSL channel.

otLinkSetCslChannel(otInstance *aInstance, uint8_t aChannel)

Sets the CSL channel.

uint32_t
otLinkGetCslPeriod(otInstance *aInstance)

Gets the CSL period in microseconds.

otLinkSetCslPeriod(otInstance *aInstance, uint32_t aPeriod)

Sets the CSL period in microseconds.

uint32_t
otLinkGetCslTimeout(otInstance *aInstance)

Gets the CSL timeout.

otLinkSetCslTimeout(otInstance *aInstance, uint32_t aTimeout)

Sets the CSL timeout in seconds.

uint16_t
otLinkGetCcaFailureRate(otInstance *aInstance)

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

otLinkSetEnabled(otInstance *aInstance, bool aEnable)

Enables or disables the link layer.

bool
otLinkIsEnabled(otInstance *aInstance)

Indicates whether or not the link layer is enabled.

bool
otLinkIsCslEnabled(otInstance *aInstance)

Indicates whether or not CSL is enabled.

bool
otLinkIsCslSupported(otInstance *aInstance)

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

otLinkSendEmptyData(otInstance *aInstance)

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

otLinkSetRegion(otInstance *aInstance, uint16_t aRegionCode)

Sets the region code.

otLinkGetRegion(otInstance *aInstance, uint16_t *aRegionCode)

Get the region code.

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.

#define

Represents CSL period ten symbols unit in microseconds.

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

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

Represents a Mac Filter entry.


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

otMacCounters#

typedef struct otMacCounters otMacCounters

Represents the MAC layer counters.


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

otActiveScanResult#

typedef struct otActiveScanResult otActiveScanResult

Represents a received IEEE 802.15.4 Beacon.


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

otEnergyScanResult#

typedef struct otEnergyScanResult otEnergyScanResult

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)

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)

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)

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 996 of file include/openthread/link.h

Function Documentation#

otLinkActiveScan#

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

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)

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)

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)

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)

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)

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.

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

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.

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.

See Also


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

otLinkGetPollPeriod#

uint32_t otLinkGetPollPeriod (otInstance * aInstance)

Get the data poll period of sleepy end device.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The data poll period of sleepy end device in milliseconds.

See Also


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

otLinkSetPollPeriod#

otError otLinkSetPollPeriod (otInstance * aInstance, uint32_t aPollPeriod)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aPollPeriod

data poll period in milliseconds.

Note

  • This function updates only poll period of sleepy end device. To update child timeout the function otThreadSetChildTimeout() shall be called.

  • Minimal non-zero value should be OPENTHREAD_CONFIG_MAC_MINIMUM_POLL_PERIOD (10ms). Or zero to clear user-specified poll period.

  • User-specified value should be no more than the maximal value 0x3FFFFFF ((1 << 26) - 1) allowed, otherwise it would be clipped by the maximal value.

See Also


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

otLinkGetShortAddress#

otShortAddress otLinkGetShortAddress (otInstance * aInstance)

Get the IEEE 802.15.4 Short Address.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • A pointer to the IEEE 802.15.4 Short Address.


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

otLinkGetMaxFrameRetriesDirect#

uint8_t otLinkGetMaxFrameRetriesDirect (otInstance * aInstance)

Returns the maximum number of frame retries during direct transmission.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The maximum number of retries during direct transmission.


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

otLinkSetMaxFrameRetriesDirect#

void otLinkSetMaxFrameRetriesDirect (otInstance * aInstance, uint8_t aMaxFrameRetriesDirect)

Sets the maximum number of frame retries during direct transmission.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aMaxFrameRetriesDirect

The maximum number of retries during direct transmission.


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

otLinkGetMaxFrameRetriesIndirect#

uint8_t otLinkGetMaxFrameRetriesIndirect (otInstance * aInstance)

Returns the maximum number of frame retries during indirect transmission.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The maximum number of retries during indirect transmission.


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

otLinkSetMaxFrameRetriesIndirect#

void otLinkSetMaxFrameRetriesIndirect (otInstance * aInstance, uint8_t aMaxFrameRetriesIndirect)

Sets the maximum number of frame retries during indirect transmission.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aMaxFrameRetriesIndirect

The maximum number of retries during indirect transmission.


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

otLinkFilterGetAddressMode#

otMacFilterAddressMode otLinkFilterGetAddressMode (otInstance * aInstance)

Gets the address mode of MAC filter.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Returns

  • the address mode.


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

otLinkFilterSetAddressMode#

void otLinkFilterSetAddressMode (otInstance * aInstance, otMacFilterAddressMode aMode)

Sets the address mode of MAC filter.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aMode

The address mode to set.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

otLinkFilterAddAddress#

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

Adds an Extended Address to MAC filter.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aExtAddress

A pointer to the Extended Address (MUST NOT be NULL).

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

otLinkFilterRemoveAddress#

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

Removes an Extended Address from MAC filter.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aExtAddress

A pointer to the Extended Address (MUST NOT be NULL).

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.


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

otLinkFilterClearAddresses#

void otLinkFilterClearAddresses (otInstance * aInstance)

Clears all the Extended Addresses from MAC filter.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

otLinkFilterGetNextAddress#

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

Gets an in-use address filter entry.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[inout]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.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

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.

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

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

  • The RssIn list contains Extended Addresses whose rss or link quality indicator (lqi) values have been set to be different from the defaults.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

otLinkFilterRemoveRssIn#

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

Removes the specified Extended Address from the RssIn list.

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.

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.


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

otLinkFilterSetDefaultRssIn#

void otLinkFilterSetDefaultRssIn (otInstance * aInstance, int8_t aRss)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aRss

The default received signal strength (in dBm) to set.

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


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

otLinkFilterClearDefaultRssIn#

void otLinkFilterClearDefaultRssIn (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

otLinkFilterClearAllRssIn#

void otLinkFilterClearAllRssIn (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.


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

otLinkFilterGetNextRssIn#

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

Gets an in-use RssIn filter entry.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[inout]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.

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

otLinkSetRadioFilterEnabled#

void otLinkSetRadioFilterEnabled (otInstance * aInstance, bool aFilterEnabled)

Enables/disables IEEE 802.15.4 radio filter mode.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aFilterEnabled

TRUE to enable radio filter, FALSE to disable

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


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

otLinkIsRadioFilterEnabled#

bool otLinkIsRadioFilterEnabled (otInstance * aInstance)

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

Parameters
N/AaInstance

Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.


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

otLinkConvertRssToLinkQuality#

uint8_t otLinkConvertRssToLinkQuality (otInstance * aInstance, int8_t aRss)

Converts received signal strength to link quality.

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.


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

otLinkConvertLinkQualityToRss#

int8_t otLinkConvertLinkQualityToRss (otInstance * aInstance, uint8_t aLinkQuality)

Converts link quality to typical received signal strength.

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.


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

otLinkGetTxDirectRetrySuccessHistogram#

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

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aNumberOfEntries

A pointer to where the size of returned histogram array is placed.

Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

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.


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

otLinkGetTxIndirectRetrySuccessHistogram#

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

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aNumberOfEntries

A pointer to where the size of returned histogram array is placed.

Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

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.


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

otLinkResetTxRetrySuccessHistogram#

void otLinkResetTxRetrySuccessHistogram (otInstance * aInstance)

Clears histogram statistics for direct and indirect transmissions.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.


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

otLinkGetCounters#

const otMacCounters * otLinkGetCounters (otInstance * aInstance)

Get the MAC layer counters.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • A pointer to the MAC layer counters.


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

otLinkResetCounters#

void otLinkResetCounters (otInstance * aInstance)

Resets the MAC layer counters.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


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

otLinkSetPcapCallback#

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

Registers a callback to provide received raw IEEE 802.15.4 frames.

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.


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

otLinkIsPromiscuous#

bool otLinkIsPromiscuous (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.


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

otLinkSetPromiscuous#

otError otLinkSetPromiscuous (otInstance * aInstance, bool aPromiscuous)

Enables or disables the link layer promiscuous mode.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aPromiscuous

true to enable promiscuous mode, or false otherwise.

Note

  • Promiscuous mode may only be enabled when the Thread interface is disabled.


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

otLinkGetCslChannel#

uint8_t otLinkGetCslChannel (otInstance * aInstance)

Gets the CSL channel.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The CSL channel.


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

otLinkSetCslChannel#

otError otLinkSetCslChannel (otInstance * aInstance, uint8_t aChannel)

Sets the CSL channel.

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] (if 2.4 GHz supported).


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

otLinkGetCslPeriod#

uint32_t otLinkGetCslPeriod (otInstance * aInstance)

Gets the CSL period in microseconds.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The CSL period in microseconds.


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

otLinkSetCslPeriod#

otError otLinkSetCslPeriod (otInstance * aInstance, uint32_t aPeriod)

Sets the CSL period in microseconds.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aPeriod

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.


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

otLinkGetCslTimeout#

uint32_t otLinkGetCslTimeout (otInstance * aInstance)

Gets the CSL timeout.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The CSL timeout in seconds.


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

otLinkSetCslTimeout#

otError otLinkSetCslTimeout (otInstance * aInstance, uint32_t aTimeout)

Sets the CSL timeout in seconds.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aTimeout

The CSL timeout in seconds.


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

otLinkGetCcaFailureRate#

uint16_t otLinkGetCcaFailureRate (otInstance * aInstance)

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

Parameters
N/AaInstance

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

Returns

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


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

otLinkSetEnabled#

otError otLinkSetEnabled (otInstance * aInstance, bool aEnable)

Enables or disables the link layer.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aEnable

true to enable the link layer, or false otherwise.

Note

  • The link layer may only be enabled / disabled when the Thread Interface is disabled.


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

otLinkIsEnabled#

bool otLinkIsEnabled (otInstance * aInstance)

Indicates whether or not the link layer is enabled.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


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

otLinkIsCslEnabled#

bool otLinkIsCslEnabled (otInstance * aInstance)

Indicates whether or not CSL is enabled.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


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

otLinkIsCslSupported#

bool otLinkIsCslSupported (otInstance * aInstance)

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

Parameters
N/AaInstance

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

otLinkSendEmptyData#

otError otLinkSendEmptyData (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.


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

otLinkSetRegion#

otError otLinkSetRegion (otInstance * aInstance, uint16_t aRegionCode)

Sets the region code.

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.

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


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

otLinkGetRegion#

otError otLinkGetRegion (otInstance * aInstance, uint16_t * aRegionCode)

Get the region code.

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.

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


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

Macro Definition Documentation#

OT_US_PER_TEN_SYMBOLS#

#define OT_US_PER_TEN_SYMBOLS
Value:
OT_RADIO_TEN_SYMBOLS_TIME

Time for 10 symbols in units of microseconds.


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

OT_MAC_FILTER_FIXED_RSS_DISABLED#

#define OT_MAC_FILTER_FIXED_RSS_DISABLED
Value:
127

Used to indicate no fixed received signal strength was set.


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

OT_MAC_FILTER_ITERATOR_INIT#

#define OT_MAC_FILTER_ITERATOR_INIT
Value:
0

Initializer for otMacFilterIterator.


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

OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC#

#define OT_LINK_CSL_PERIOD_TEN_SYMBOLS_UNIT_IN_USEC
Value:
(160)

Represents CSL period ten symbols unit in microseconds.

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


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