Link

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 otExtAddressotLinkGetExtendedAddress (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.
 
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 otMacCountersotLinkGetCounters (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]aResultA valid pointer to the beacon information or NULL when the active scan completes.
[in]aContextA 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]aResultA valid pointer to the energy scan result information or NULL when the energy scan completes.
[in]aContextA 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]aFrameA pointer to the received IEEE 802.15.4 frame.
[in]aIsTxWhether this frame is transmitted, not received.
[in]aContextA pointer to application-specific context.

Enumeration Type Documentation

◆ 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]aInstanceA pointer to an OpenThread instance.
[in]aScanChannelsA bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK).
[in]aScanDurationThe time in milliseconds to spend scanning each channel.
[in]aCallbackA pointer to a function called on receiving a beacon or scan completes.
[in]aCallbackContextA pointer to application-specific context.
Return values
OT_ERROR_NONEAccepted the Active Scan request.
OT_ERROR_BUSYAlready 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]aInstanceA pointer to an OpenThread instance.
[in]aLinkQualityLinkQuality 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]aInstanceA pointer to an OpenThread instance.
[in]aRssThe 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]aInstanceA pointer to an OpenThread instance.
Returns
The CSL channel.

◆ otLinkCslGetPeriod()

uint16_t otLinkCslGetPeriod ( otInstance aInstance)

This function gets the CSL period.

Parameters
[in]aInstanceA 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]aInstanceA 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]aInstanceA pointer to an OpenThread instance.
[in]aChannelThe 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_NONESuccessfully set the CSL parameters.
OT_ERROR_INVALID_ARGSInvalid aChannel.

◆ otLinkCslSetPeriod()

otError otLinkCslSetPeriod ( otInstance aInstance,
uint16_t  aPeriod 
)

This function sets the CSL period.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPeriodThe CSL period in units of 10 symbols.
Return values
OT_ERROR_NONESuccessfully set the CSL period.
OT_ERROR_INVALID_ARGSInvalid CSL period.

◆ otLinkCslSetTimeout()

otError otLinkCslSetTimeout ( otInstance aInstance,
uint32_t  aTimeout 
)

This function sets the CSL timeout.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aTimeoutThe CSL timeout in seconds.
Return values
OT_ERROR_NONESuccessfully set the CSL timeout.
OT_ERROR_INVALID_ARGSInvalid 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]aInstanceA pointer to an OpenThread instance.
[in]aScanChannelsA bit vector indicating on which channels to perform energy scan.
[in]aScanDurationThe time in milliseconds to spend scanning each channel.
[in]aCallbackA pointer to a function called to pass on scan result on indicate scan completion.
[in]aCallbackContextA pointer to application-specific context.
Return values
OT_ERROR_NONEAccepted the Energy Scan request.
OT_ERROR_BUSYCould 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]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA pointer to the Extended Address (MUST NOT be NULL).
Return values
OT_ERROR_NONESuccessfully added aExtAddress to MAC filter.
OT_ERROR_NO_BUFSNo 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]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL.
[in]aRssA received signal strength (in dBm).
Return values
OT_ERROR_NONESuccessfully added an entry for aExtAddress and aRss.
OT_ERROR_NO_BUFSNo 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]aInstanceA 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]aInstanceA 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]aInstanceA 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]aInstanceA 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]aInstanceA pointer to an OpenThread instance.
[in,out]aIteratorA 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]aEntryA pointer to where the information is placed. MUST NOT be NULL.
Return values
OT_ERROR_NONESuccessfully retrieved an in-use address filter entry.
OT_ERROR_NOT_FOUNDNo 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]aInstanceA pointer to an OpenThread instance.
[in,out]aIteratorA 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]aEntryA 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_NONESuccessfully retrieved the next entry.
OT_ERROR_NOT_FOUNDNo 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]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA 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]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA 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]aInstanceA pointer to an OpenThread instance.
[in]aModeThe 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]aInstanceA pointer to an OpenThread instance.
[in]aRssThe 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]aInstanceA 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]aInstanceA 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]aInstanceA 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]aInstanceA pointer to the OpenThread instance.
[out]aEui64A 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]aInstanceA 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]aInstanceA 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]aInstanceA 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]aInstanceA 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]aInstanceA 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]aInstanceA 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]aInstanceA pointer to an OpenThread instance.
[out]aNumberOfEntriesA 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]aInstanceA pointer to an OpenThread instance.
[out]aNumberOfEntriesA 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]aInstanceA 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]aInstanceA pointer to an OpenThread instance.
Return values
trueLink layer is enabled.
falseLink 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]aInstanceA 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]aInstanceA 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]aInstanceA pointer to an OpenThread instance.
Return values
truePromiscuous mode is enabled.
falsePromiscuous mode is not enabled.

◆ otLinkResetCounters()

void otLinkResetCounters ( otInstance aInstance)

Reset the MAC layer counters.

Parameters
[in]aInstanceA 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]aInstanceA 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]aInstanceA pointer to an OpenThread instance.
Return values
OT_ERROR_NONESuccessfully enqueued an IEEE 802.15.4 Data Request message.
OT_ERROR_ALREADYAn IEEE 802.15.4 Data Request message is already enqueued.
OT_ERROR_INVALID_STATEDevice is not in rx-off-when-idle mode.
OT_ERROR_NO_BUFSInsufficient 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]aInstanceA pointer to an OpenThread instance.
Return values
OT_ERROR_NONESuccessfully enqueued an empty message.
OT_ERROR_INVALID_STATEDevice is not in Rx-Off-When-Idle mode.
OT_ERROR_NO_BUFSInsufficient 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]aInstanceA pointer to an OpenThread instance.
[in]aChannelThe IEEE 802.15.4 channel.
Return values
OT_ERROR_NONESuccessfully set the channel.
OT_ERROR_INVALID_ARGSIf aChannel is not in the range [11, 26] or is not in the supported channel mask.
OT_ERROR_INVALID_STATEThread 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]aInstanceA pointer to an OpenThread instance.
[in]aEnabletrue to enable the link layer, or false otherwise.
Return values
OT_ERROR_NONESuccessfully enabled / disabled the link layer.
OT_ERROR_INVALID_STATECould 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]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA pointer to the IEEE 802.15.4 Extended Address.
Return values
OT_ERROR_NONESuccessfully set the IEEE 802.15.4 Extended Address.
OT_ERROR_INVALID_ARGSaExtAddress was NULL.
OT_ERROR_INVALID_STATEThread 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]aInstanceA pointer to an OpenThread instance.
[in]aMaxFrameRetriesDirectThe 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]aInstanceA pointer to an OpenThread instance.
[in]aMaxFrameRetriesIndirectThe 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]aInstanceA pointer to an OpenThread instance.
[in]aPanIdThe IEEE 802.15.4 PAN ID.
Return values
OT_ERROR_NONESuccessfully set the PAN ID.
OT_ERROR_INVALID_ARGSIf aPanId is not in the range [0, 65534].
OT_ERROR_INVALID_STATEThread 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]aInstanceA pointer to an OpenThread instance.
[in]aPcapCallbackA pointer to a function that is called when receiving an IEEE 802.15.4 link frame or NULL to disable the callback.
[in]aCallbackContextA 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]aInstanceA pointer to an OpenThread instance.
[in]aPollPerioddata poll period in milliseconds.
Return values
OT_ERROR_NONESuccessfully set/cleared user-specified poll period.
OT_ERROR_INVALID_ARGSIf 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]aInstanceA pointer to an OpenThread instance.
[in]aPromiscuoustrue to enable promiscuous mode, or false otherwise.
Return values
OT_ERROR_NONESuccessfully enabled promiscuous mode.
OT_ERROR_INVALID_STATECould not enable promiscuous mode because the Thread interface is enabled.

◆ 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]aInstanceA pointer to an OpenThread instance.
[in]aChannelMaskThe supported channel mask (bit 0 or lsb mapping to channel 0, and so on).
Return values
OT_ERROR_NONESuccessfully set the supported channel mask.
OT_ERROR_INVALID_STATEThread protocols are enabled.