This module includes functions that control link-layer configuration. More...
Data Structures | |
struct | otThreadLinkInfo |
struct | otMacFilterEntry |
struct | otMacCounters |
struct | otActiveScanResult |
struct | otEnergyScanResult |
Macros | |
#define | OT_MAC_FILTER_FIXED_RSS_DISABLED 127 |
#define | OT_MAC_FILTER_ITERATOR_INIT 0 |
Initializer for otMacFilterIterator. | |
Typedefs | |
typedef struct otThreadLinkInfo | otThreadLinkInfo |
typedef uint8_t | otMacFilterIterator |
Used to iterate through mac filter entries. | |
typedef enum otMacFilterAddressMode | otMacFilterAddressMode |
typedef struct otMacFilterEntry | otMacFilterEntry |
typedef struct otMacCounters | otMacCounters |
typedef struct otActiveScanResult | otActiveScanResult |
typedef struct otEnergyScanResult | otEnergyScanResult |
typedef void(* | otHandleActiveScanResult )(otActiveScanResult *aResult, void *aContext) |
typedef void(* | otHandleEnergyScanResult )(otEnergyScanResult *aResult, void *aContext) |
typedef void(* | otLinkPcapCallback )(const otRadioFrame *aFrame, bool aIsTx, void *aContext) |
Enumerations | |
enum | otMacFilterAddressMode { OT_MAC_FILTER_ADDRESS_MODE_DISABLED, OT_MAC_FILTER_ADDRESS_MODE_WHITELIST, OT_MAC_FILTER_ADDRESS_MODE_BLACKLIST } |
This module includes functions that control link-layer configuration.
#define OT_MAC_FILTER_FIXED_RSS_DISABLED 127 |
Used to indicate no fixed received signal strength was set
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.
[in] | aResult | A valid pointer to the beacon information or NULL when the active scan completes. |
[in] | aContext | A pointer to application-specific context. |
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.
[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. |
typedef void(* otLinkPcapCallback)(const otRadioFrame *aFrame, bool aIsTx, void *aContext) |
This function pointer is called when an IEEE 802.15.4 frame is received.
aFrame
may not contain the actual FCS that was received.[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. |
typedef struct otMacCounters otMacCounters |
This structure represents the MAC layer counters.
typedef enum otMacFilterAddressMode otMacFilterAddressMode |
Defines address mode of the mac filter.
typedef struct otMacFilterEntry otMacFilterEntry |
This structure represents a Mac Filter entry.
typedef struct otThreadLinkInfo otThreadLinkInfo |
This structure represents link-specific information for messages received from the Thread radio.
otError otLinkActiveScan | ( | otInstance * | aInstance, |
uint32_t | aScanChannels, | ||
uint16_t | aScanDuration, | ||
otHandleActiveScanResult | aCallback, | ||
void * | aCallbackContext | ||
) |
This function starts an IEEE 802.15.4 Active Scan
[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. |
OT_ERROR_NONE | Accepted the Active Scan request. |
OT_ERROR_BUSY | Already performing an Active Scan. |
int8_t otLinkConvertLinkQualityToRss | ( | otInstance * | aInstance, |
uint8_t | aLinkQuality | ||
) |
This method converts link quality to typical received signal strength.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aLinkQuality | LinkQuality value, should be in range [0,3]. |
aLinkQuality
. uint8_t otLinkConvertRssToLinkQuality | ( | otInstance * | aInstance, |
int8_t | aRss | ||
) |
This method converts received signal strength to link quality.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aRss | The received signal strength value to be converted. |
aRss
. otError otLinkEnergyScan | ( | otInstance * | aInstance, |
uint32_t | aScanChannels, | ||
uint16_t | aScanDuration, | ||
otHandleEnergyScanResult | aCallback, | ||
void * | aCallbackContext | ||
) |
This function starts an IEEE 802.15.4 Energy Scan
[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. |
OT_ERROR_NONE | Accepted the Energy Scan request. |
OT_ERROR_BUSY | Could not start the energy scan. |
otError otLinkFilterAddAddress | ( | otInstance * | aInstance, |
const otExtAddress * | aExtAddress | ||
) |
This method adds an Extended Address to MAC filter.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aExtAddress | A reference to the Extended Address. |
OT_ERROR_NONE | Successfully added aExtAddress to MAC filter. |
OT_ERROR_ALREADY | If aExtAddress was already in MAC filter. |
OT_ERROR_INVALID_ARGS | If aExtAddress is NULL. |
OT_ERROR_NO_BUFS | No available entry exists. |
otError otLinkFilterAddRssIn | ( | otInstance * | aInstance, |
const otExtAddress * | aExtAddress, | ||
int8_t | aRss | ||
) |
This method sets the received signal strength (in dBm) for the messages from the Extended Address. The default received signal strength for all received messages would be set if no Extended Address is specified.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aExtAddress | A pointer to the IEEE 802.15.4 Extended Address, or NULL to set the default received signal strength. |
[in] | aRss | The received signal strength (in dBm) to set. |
OT_ERROR_NONE | Successfully set aRss for aExtAddress or set the default aRss for all received messages if aExtAddress is NULL. |
OT_ERROR_NO_BUFS | No available entry exists. |
void otLinkFilterClearAddresses | ( | otInstance * | aInstance | ) |
This method clears all the Extended Addresses from MAC filter.
[in] | aInstance | A pointer to an OpenThread instance. |
void otLinkFilterClearRssIn | ( | otInstance * | aInstance | ) |
This method clears all the received signal strength settings.
[in] | aInstance | A pointer to an OpenThread instance. |
otMacFilterAddressMode otLinkFilterGetAddressMode | ( | otInstance * | aInstance | ) |
This function gets the address mode of MAC filter.
[in] | aInstance | A pointer to an OpenThread instance. |
otError otLinkFilterGetNextAddress | ( | otInstance * | aInstance, |
otMacFilterIterator * | aIterator, | ||
otMacFilterEntry * | aEntry | ||
) |
This method gets an in-use address filter entry.
[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. |
[out] | aEntry | A pointer to where the information is placed. |
OT_ERROR_NONE | Successfully retrieved an in-use address filter entry. |
OT_ERROR_INVALID_ARGS | If aIterator or aEntry is NULL. |
OT_ERROR_NOT_FOUND | No subsequent entry exists. |
otError otLinkFilterGetNextRssIn | ( | otInstance * | aInstance, |
otMacFilterIterator * | aIterator, | ||
otMacFilterEntry * | aEntry | ||
) |
This method gets an in-use RssIn filter entry.
[in] | aInstance | A pointer to an OpenThread instance. |
[in,out] | aIterator | A reference to the MAC filter iterator context. To get the first in-use RssIn Filter entry, it should be set to OT_MAC_FILTER_ITERATOR_INIT. |
[out] | aEntry | A reference 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. |
OT_ERROR_NONE | Successfully retrieved an in-use RssIn Filter entry. |
OT_ERROR_INVALID_ARGS | If aIterator or aEntry is NULL. |
OT_ERROR_NOT_FOUND | No subsequent entry exists. |
otError otLinkFilterRemoveAddress | ( | otInstance * | aInstance, |
const otExtAddress * | aExtAddress | ||
) |
This method removes an Extended Address from MAC filter.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aExtAddress | A reference to the Extended Address. |
OT_ERROR_NONE | Successfully removed aExtAddress from MAC filter. |
OT_ERROR_INVALID_ARGS | If aExtAddress is NULL. |
OT_ERROR_NOT_FOUND | aExtAddress is not in MAC filter. |
otError otLinkFilterRemoveRssIn | ( | otInstance * | aInstance, |
const otExtAddress * | aExtAddress | ||
) |
This method removes the received signal strength setting for the received messages from the Extended Address or removes the default received signal strength setting if no Extended Address is specified.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aExtAddress | A pointer to the IEEE 802.15.4 Extended Address, or NULL to reset the default received signal strength. |
OT_ERROR_NONE | Successfully removed received signal strength setting for aExtAddress or removed the default received signal strength setting if aExtAddress is NULL. |
OT_ERROR_NOT_FOUND | aExtAddress is not in MAC filter if it is not NULL. |
otError otLinkFilterSetAddressMode | ( | otInstance * | aInstance, |
otMacFilterAddressMode | aMode | ||
) |
This function sets the address mode of MAC filter.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aMode | The address mode to set. |
OT_ERROR_NONE | Successfully set the address mode. |
OT_ERROR_INVALID_ARGS | aMode is not valid. |
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.
0xffff
corresponding to 100% failure rate. uint8_t otLinkGetChannel | ( | otInstance * | aInstance | ) |
Get the IEEE 802.15.4 channel.
[in] | aInstance | A pointer to an OpenThread instance. |
const otMacCounters* otLinkGetCounters | ( | otInstance * | aInstance | ) |
Get the MAC layer counters.
[in] | aInstance | A pointer to an OpenThread instance. |
const otExtAddress* otLinkGetExtendedAddress | ( | otInstance * | aInstance | ) |
Get the IEEE 802.15.4 Extended Address.
[in] | aInstance | A pointer to an OpenThread instance. |
void otLinkGetFactoryAssignedIeeeEui64 | ( | otInstance * | aInstance, |
otExtAddress * | aEui64 | ||
) |
Get the factory-assigned IEEE EUI-64.
[in] | aInstance | A pointer to the OpenThread instance. |
[out] | aEui64 | A pointer to where the factory-assigned IEEE EUI-64 is placed. |
uint8_t otLinkGetMaxFrameRetriesDirect | ( | otInstance * | aInstance | ) |
This method returns the maximum number of frame retries during direct transmission.
[in] | aInstance | A pointer to an OpenThread instance. |
uint8_t otLinkGetMaxFrameRetriesIndirect | ( | otInstance * | aInstance | ) |
This method returns the maximum number of frame retries during indirect transmission.
[in] | aInstance | A pointer to an OpenThread instance. |
otPanId otLinkGetPanId | ( | otInstance * | aInstance | ) |
Get the IEEE 802.15.4 PAN ID.
[in] | aInstance | A pointer to an OpenThread instance. |
uint32_t otLinkGetPollPeriod | ( | otInstance * | aInstance | ) |
Get the data poll period of sleepy end device.
[in] | aInstance | A pointer to an OpenThread instance. |
otShortAddress otLinkGetShortAddress | ( | otInstance * | aInstance | ) |
Get the IEEE 802.15.4 Short Address.
[in] | aInstance | A pointer to an OpenThread instance. |
uint32_t otLinkGetSupportedChannelMask | ( | otInstance * | aInstance | ) |
Get the supported channel mask of MAC layer.
[in] | aInstance | A pointer to an OpenThread instance. |
uint32_t
with bit 0 (lsb) mapping to channel 0, bit 1 to channel 1, so on. 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.
[in] | aInstance | A pointer to an OpenThread instance. |
[out] | aNumberOfEntries | A pointer to where the size of returned histogram array is placed. |
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.
[in] | aInstance | A pointer to an OpenThread instance. |
[out] | aNumberOfEntries | A pointer to where the size of returned histogram array is placed. |
bool otLinkIsActiveScanInProgress | ( | otInstance * | aInstance | ) |
This function indicates whether or not an IEEE 802.15.4 Active Scan is currently in progress.
[in] | aInstance | A pointer to an OpenThread instance. |
bool otLinkIsEnabled | ( | otInstance * | aInstance | ) |
This function indicates whether or not the link layer is enabled.
[in] | aInstance | A pointer to an OpenThread instance. |
true | Link layer is enabled. |
false | Link layer is not enabled. |
bool otLinkIsEnergyScanInProgress | ( | otInstance * | aInstance | ) |
This function indicates whether or not an IEEE 802.15.4 Energy Scan is currently in progress.
[in] | aInstance | A pointer to an OpenThread instance. |
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.
[in] | aInstance | A pointer to an OpenThread instance. |
bool otLinkIsPromiscuous | ( | otInstance * | aInstance | ) |
This function indicates whether or not promiscuous mode is enabled at the link layer.
[in] | aInstance | A pointer to an OpenThread instance. |
true | Promiscuous mode is enabled. |
false | Promiscuous mode is not enabled. |
otError otLinkOutOfBandTransmitRequest | ( | otInstance * | aInstance, |
otRadioFrame * | aOobFrame | ||
) |
This function enqueues an IEEE 802.15.4 out of band Frame for transmission.
An Out of Band frame is one that was generated outside of OpenThread.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aOobFrame | A pointer to the frame to transmit. |
OT_ERROR_NONE | Successfully scheduled the frame transmission. |
OT_ERROR_ALREADY | MAC layer is busy sending a previously requested frame. |
OT_ERROR_INVALID_STATE | The MAC layer is not enabled. |
OT_ERROR_INVALID_ARGS | The argument aOobFrame is NULL. |
void otLinkResetCounters | ( | otInstance * | aInstance | ) |
Reset the MAC layer counters.
[in] | aInstance | A pointer to an OpenThread instance. |
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.
[in] | aInstance | A pointer to an OpenThread instance. |
otError otLinkSendDataRequest | ( | otInstance * | aInstance | ) |
This function enqueues an IEEE 802.15.4 Data Request message for transmission.
[in] | aInstance | A pointer to an OpenThread instance. |
OT_ERROR_NONE | Successfully enqueued an IEEE 802.15.4 Data Request message. |
OT_ERROR_ALREADY | An IEEE 802.15.4 Data Request message is already enqueued. |
OT_ERROR_INVALID_STATE | Device is not in rx-off-when-idle mode. |
OT_ERROR_NO_BUFS | Insufficient message buffers available. |
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.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aChannel | The IEEE 802.15.4 channel. |
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. |
otError otLinkSetEnabled | ( | otInstance * | aInstance, |
bool | aEnable | ||
) |
This function enables or disables the link layer.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aEnable | true to enable the link layer, or false otherwise. |
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. |
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.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aExtAddress | A pointer to the IEEE 802.15.4 Extended Address. |
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. |
void otLinkSetMaxFrameRetriesDirect | ( | otInstance * | aInstance, |
uint8_t | aMaxFrameRetriesDirect | ||
) |
This method sets the maximum number of frame retries during direct transmission.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aMaxFrameRetriesDirect | The maximum number of retries during direct transmission. |
void otLinkSetMaxFrameRetriesIndirect | ( | otInstance * | aInstance, |
uint8_t | aMaxFrameRetriesIndirect | ||
) |
This method sets the maximum number of frame retries during indirect transmission.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aMaxFrameRetriesIndirect | The maximum number of retries during indirect transmission. |
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.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aPanId | The IEEE 802.15.4 PAN ID. |
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. |
void otLinkSetPcapCallback | ( | otInstance * | aInstance, |
otLinkPcapCallback | aPcapCallback, | ||
void * | aCallbackContext | ||
) |
This function registers a callback to provide received raw IEEE 802.15.4 frames.
[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. |
otError otLinkSetPollPeriod | ( | otInstance * | aInstance, |
uint32_t | aPollPeriod | ||
) |
Set/clear user-specified/external data poll period for sleepy end device.
otThreadSetChildTimeout()
shall be called.OPENTHREAD_CONFIG_MAC_MINIMUM_POLL_PERIOD
(10ms). Or zero to clear user-specified poll period.[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aPollPeriod | data poll period in milliseconds. |
OT_ERROR_NONE | Successfully set/cleared user-specified poll period. |
OT_ERROR_INVALID_ARGS | If aPollPeriod is invalid. |
otError otLinkSetPromiscuous | ( | otInstance * | aInstance, |
bool | aPromiscuous | ||
) |
This function enables or disables the link layer promiscuous mode.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aPromiscuous | true to enable promiscuous mode, or false otherwise. |
OT_ERROR_NONE | Successfully enabled promiscuous mode. |
OT_ERROR_INVALID_STATE | Could not enable promiscuous mode because the Thread interface is enabled. |
otError otLinkSetSupportedChannelMask | ( | otInstance * | aInstance, |
uint32_t | aChannelMask | ||
) |
Set the supported channel mask of MAC layer.
This function succeeds only when Thread protocols are disabled.
[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). |
OT_ERROR_NONE | Successfully set the supported channel mask. |
OT_ERROR_INVALID_STATE | Thread protocols are enabled. |