This module includes functions that control link-layer configuration.

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

struct	otMacFilterEntry
	This structure represents a Mac Filter entry.

struct	otMacCounters
	This structure represents the MAC layer counters.

struct	otActiveScanResult
	This structure represents a received IEEE 802.15.4 Beacon.

struct	otEnergyScanResult
	This structure represents an energy scan result.

Macros
#define	OT_US_PER_TEN_SYMBOLS 160
	The microseconds per 10 symbols.

#define	OT_MAC_FILTER_FIXED_RSS_DISABLED 127
	Used to indicate no fixed received signal strength was set.

#define	OT_MAC_FILTER_ITERATOR_INIT 0
	Initializer for otMacFilterIterator.

Typedefs
typedef struct otThreadLinkInfo	otThreadLinkInfo
	This structure represents link-specific information for messages received from the Thread radio.

typedef uint8_t	otMacFilterIterator
	Used to iterate through mac filter entries.

typedef enum otMacFilterAddressMode	otMacFilterAddressMode
	Defines address mode of the mac filter.

typedef struct otMacFilterEntry	otMacFilterEntry
	This structure represents a Mac Filter entry.

typedef struct otMacCounters	otMacCounters
	This structure represents the MAC layer counters.

typedef struct otActiveScanResult	otActiveScanResult
	This structure represents a received IEEE 802.15.4 Beacon.

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

Enumerations
enum	otMacFilterAddressMode { 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.

Functions
otError	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.

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

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

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

otError	otLinkSetSupportedChannelMask ( otInstance *aInstance, uint32_t aChannelMask)
	Set the supported channel mask of MAC layer.

const otExtAddress *	otLinkGetExtendedAddress ( otInstance *aInstance)
	Get the IEEE 802.15.4 Extended Address.

otError	otLinkSetExtendedAddress ( otInstance aInstance, const otExtAddress aExtAddress)
	This function sets the IEEE 802.15.4 Extended Address.

void	otLinkGetFactoryAssignedIeeeEui64 ( otInstance aInstance, otExtAddress aEui64)
	Get the factory-assigned IEEE EUI-64.

otPanId	otLinkGetPanId ( otInstance *aInstance)
	Get the IEEE 802.15.4 PAN ID.

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

otError	otLinkSetPollPeriod ( otInstance *aInstance, uint32_t aPollPeriod)
	Set/clear user-specified/external data poll period for sleepy end device.

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

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

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

otError	otLinkFilterGetNextAddress ( otInstance aInstance, otMacFilterIterator aIterator, otMacFilterEntry *aEntry)
	This method gets an in-use address filter entry.

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

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

const otMacCounters *	otLinkGetCounters ( otInstance *aInstance)
	Get the MAC layer counters.

void	otLinkResetCounters ( otInstance *aInstance)
	Reset 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.

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

otError	otLinkCslSetChannel ( otInstance *aInstance, uint8_t aChannel)
	This function sets the CSL channel.

uint16_t	otLinkCslGetPeriod ( otInstance *aInstance)
	This function gets the CSL period.

otError	otLinkCslSetPeriod ( otInstance *aInstance, uint16_t aPeriod)
	This function sets the CSL period.

uint32_t	otLinkCslGetTimeout ( otInstance *aInstance)
	This function gets the CSL timeout.

otError	otLinkCslSetTimeout ( otInstance *aInstance, uint32_t aTimeout)
	This function sets the CSL timeout.

uint16_t	otLinkGetCcaFailureRate ( otInstance *aInstance)
	This function returns the current CCA (Clear Channel Assessment) failure rate.

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

otError	otLinkSendEmptyData ( otInstance *aInstance)
	This function instructs the device to send an empty IEEE 802.15.4 data frame.

Detailed Description

This module includes functions that control link-layer configuration.

Macro Definition Documentation

◆ OT_MAC_FILTER_FIXED_RSS_DISABLED

#define OT_MAC_FILTER_FIXED_RSS_DISABLED 127

Used to indicate no fixed received signal strength was set.

Typedef Documentation

◆ otHandleActiveScanResult

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.

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

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.

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

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

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

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.

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.

Enumeration Type Documentation

◆ otMacFilterAddressMode

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

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.

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

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

◆ otLinkConvertRssToLinkQuality()

uint8_t otLinkConvertRssToLinkQuality	(	otInstance *	`aInstance,`
		int8_t	`aRss`
	)

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

◆ otLinkCslGetChannel()

uint8_t otLinkCslGetChannel ( otInstance * aInstance )

This function gets the CSL channel.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Returns: The CSL channel.

◆ otLinkCslGetPeriod()

uint16_t otLinkCslGetPeriod ( otInstance * aInstance )

This function gets the CSL period.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Returns: The CSL period in units of 10 symbols.

◆ otLinkCslGetTimeout()

uint32_t otLinkCslGetTimeout ( otInstance * aInstance )

This function gets the CSL timeout.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Returns: The CSL timeout in seconds.

◆ otLinkCslSetChannel()

otError otLinkCslSetChannel	(	otInstance *	`aInstance,`
		uint8_t	`aChannel`
	)

This function 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 .

Return values

`OT_ERROR_NONE`	Successfully set the CSL parameters.
`OT_ERROR_INVALID_ARGS`	Invalid `aChannel` .

◆ otLinkCslSetPeriod()

otError otLinkCslSetPeriod	(	otInstance *	`aInstance,`
		uint16_t	`aPeriod`
	)

This function sets the CSL period.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aPeriod`	The CSL period in units of 10 symbols.

Return values

`OT_ERROR_NONE`	Successfully set the CSL period.
`OT_ERROR_INVALID_ARGS`	Invalid CSL period.

◆ otLinkCslSetTimeout()

otError otLinkCslSetTimeout	(	otInstance *	`aInstance,`
		uint32_t	`aTimeout`
	)

This function sets the CSL timeout.

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.

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

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

This method adds an Extended Address to MAC filter.

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

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

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

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

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 )

This method clears all the Extended Addresses from MAC filter.

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Parameters

[in] aInstance A pointer to an OpenThread instance.

◆ otLinkFilterClearAllRssIn()

void otLinkFilterClearAllRssIn ( otInstance * aInstance )

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

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Parameters

[in] aInstance A pointer to an OpenThread instance.

◆ otLinkFilterClearDefaultRssIn()

void otLinkFilterClearDefaultRssIn ( otInstance * aInstance )

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

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Parameters

[in] aInstance A pointer to an OpenThread instance.

◆ otLinkFilterGetAddressMode()

otMacFilterAddressMode otLinkFilterGetAddressMode ( otInstance * aInstance )

This function gets the address mode of MAC filter.

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Returns: the address mode.

◆ otLinkFilterGetNextAddress()

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

This method gets an in-use address filter entry.

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

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

This method gets an in-use RssIn filter entry.

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

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

This method removes an Extended Address from MAC filter.

This function 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.

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

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

This function 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.

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

This function sets the address mode of MAC filter.

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Parameters

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

◆ otLinkFilterSetDefaultRssIn()

void otLinkFilterSetDefaultRssIn	(	otInstance *	`aInstance,`
		int8_t	`aRss`
	)

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

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

Parameters

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

◆ otLinkGetCcaFailureRate()

uint16_t otLinkGetCcaFailureRate ( otInstance * aInstance )

This function 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.

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.

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.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Returns: A pointer to the MAC layer counters.

◆ otLinkGetExtendedAddress()

const otExtAddress * otLinkGetExtendedAddress ( otInstance * aInstance )

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

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

◆ otLinkGetMaxFrameRetriesDirect()

uint8_t otLinkGetMaxFrameRetriesDirect ( otInstance * aInstance )

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

◆ otLinkGetMaxFrameRetriesIndirect()

uint8_t otLinkGetMaxFrameRetriesIndirect ( otInstance * aInstance )

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

◆ 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: otLinkSetPanId

◆ 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: otLinkSetPollPeriod

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

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

◆ otLinkGetTxDirectRetrySuccessHistogram()

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

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

This function is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

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

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

This function is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

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.

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

◆ otLinkIsEnabled()

bool otLinkIsEnabled ( otInstance * aInstance )

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

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 )

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.

◆ otLinkIsInTransmitState()

bool otLinkIsInTransmitState ( otInstance * aInstance )

This function 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.

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 )

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

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 )

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

This function is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.

Return values

`TRUE`	If the radio filter is enabled.
`FALSE`	If the radio filter is disabled.

◆ otLinkResetCounters()

void otLinkResetCounters ( otInstance * aInstance )

Reset the MAC layer counters.

Parameters

[in] aInstance A pointer to an OpenThread instance.

◆ otLinkResetTxRetrySuccessHistogram()

void otLinkResetTxRetrySuccessHistogram ( otInstance * aInstance )

This method clears histogram statistics for direct and indirect transmissions.

This function is valid when OPENTHREAD_CONFIG_MAC_RETRY_SUCCESS_HISTOGRAM_ENABLE configuration is enabled.

Parameters

[in] aInstance A pointer to an OpenThread instance.

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

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 )

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

This function 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.

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.

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.

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

◆ otLinkSetEnabled()

otError otLinkSetEnabled	(	otInstance *	`aInstance,`
		bool	`aEnable`
	)

This function enables or disables the link layer.

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

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

This function sets the IEEE 802.15.4 Extended Address.

This function succeeds only when Thread protocols are disabled.

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

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

◆ otLinkSetMaxFrameRetriesIndirect()

void otLinkSetMaxFrameRetriesIndirect	(	otInstance *	`aInstance,`
		uint8_t	`aMaxFrameRetriesIndirect`
	)

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

◆ otLinkSetPanId()

otError otLinkSetPanId	(	otInstance *	`aInstance,`
		otPanId	`aPanId`
	)

Set the IEEE 802.15.4 PAN ID.

This function 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.

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

This function 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.

◆ otLinkSetPollPeriod()

otError otLinkSetPollPeriod	(	otInstance *	`aInstance,`
		uint32_t	`aPollPeriod`
	)

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

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.

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

This function enables or disables the link layer promiscuous mode.

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

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

This function enables/disables IEEE 802.15.4 radio filter mode.

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

Parameters

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

◆ otLinkSetSupportedChannelMask()

otError otLinkSetSupportedChannelMask	(	otInstance *	`aInstance,`
		uint32_t	`aChannelMask`
	)

Set the supported channel mask of MAC layer.

This function succeeds only when Thread protocols are disabled.

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.

Link API > Link

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OT_MAC_FILTER_FIXED_RSS_DISABLED

Typedef Documentation

◆ otHandleActiveScanResult

◆ otHandleEnergyScanResult

◆ otLinkPcapCallback

Enumeration Type Documentation

◆ otMacFilterAddressMode

Function Documentation

◆ otLinkActiveScan()

◆ otLinkConvertLinkQualityToRss()

◆ otLinkConvertRssToLinkQuality()

◆ otLinkCslGetChannel()

◆ otLinkCslGetPeriod()

◆ otLinkCslGetTimeout()

◆ otLinkCslSetChannel()

◆ otLinkCslSetPeriod()

◆ otLinkCslSetTimeout()

◆ otLinkEnergyScan()

◆ otLinkFilterAddAddress()

◆ otLinkFilterAddRssIn()

◆ otLinkFilterClearAddresses()

◆ otLinkFilterClearAllRssIn()

◆ otLinkFilterClearDefaultRssIn()

◆ otLinkFilterGetAddressMode()

◆ otLinkFilterGetNextAddress()

◆ otLinkFilterGetNextRssIn()

◆ otLinkFilterRemoveAddress()

◆ otLinkFilterRemoveRssIn()

◆ otLinkFilterSetAddressMode()

◆ otLinkFilterSetDefaultRssIn()

◆ otLinkGetCcaFailureRate()

◆ otLinkGetChannel()

◆ otLinkGetCounters()

◆ otLinkGetExtendedAddress()

◆ otLinkGetFactoryAssignedIeeeEui64()

◆ otLinkGetMaxFrameRetriesDirect()

◆ otLinkGetMaxFrameRetriesIndirect()

◆ otLinkGetPanId()

◆ otLinkGetPollPeriod()

◆ otLinkGetShortAddress()

◆ otLinkGetSupportedChannelMask()

◆ otLinkGetTxDirectRetrySuccessHistogram()

◆ otLinkGetTxIndirectRetrySuccessHistogram()

◆ otLinkIsActiveScanInProgress()

◆ otLinkIsEnabled()

◆ otLinkIsEnergyScanInProgress()

◆ otLinkIsInTransmitState()

◆ otLinkIsPromiscuous()

◆ otLinkIsRadioFilterEnabled()

◆ otLinkResetCounters()

◆ otLinkResetTxRetrySuccessHistogram()

◆ otLinkSendDataRequest()

◆ otLinkSendEmptyData()

◆ otLinkSetChannel()

◆ otLinkSetEnabled()

◆ otLinkSetExtendedAddress()

◆ otLinkSetMaxFrameRetriesDirect()

◆ otLinkSetMaxFrameRetriesIndirect()

◆ otLinkSetPanId()

◆ otLinkSetPcapCallback()

◆ otLinkSetPollPeriod()

◆ otLinkSetPromiscuous()

◆ otLinkSetRadioFilterEnabled()

◆ otLinkSetSupportedChannelMask()

Link
API > Link