nRF5 SDK for Thread v0.11.0
Typedefs | Functions
Link

This module includes functions that control link-layer configuration. More...

Typedefs

typedef void(OTCALLotHandleActiveScanResult )(otActiveScanResult *aResult, void *aContext)
 
typedef void(OTCALLotHandleEnergyScanResult )(otEnergyScanResult *aResult, void *aContext)
 
typedef void(* otLinkPcapCallback )(const otRadioFrame *aFrame, void *aContext)
 

Functions

OTAPI otError OTCALL otLinkActiveScan (otInstance *aInstance, uint32_t aScanChannels, uint16_t aScanDuration, otHandleActiveScanResult aCallback, void *aCallbackContext)
 
OTAPI bool OTCALL otLinkIsActiveScanInProgress (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkEnergyScan (otInstance *aInstance, uint32_t aScanChannels, uint16_t aScanDuration, otHandleEnergyScanResult aCallback, void *aCallbackContext)
 
OTAPI bool OTCALL otLinkIsEnergyScanInProgress (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkSendDataRequest (otInstance *aInstance)
 
OTAPI bool OTCALL otLinkIsInTransmitState (otInstance *aInstance)
 
OTAPI uint8_t OTCALL otLinkGetChannel (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkSetChannel (otInstance *aInstance, uint8_t aChannel)
 
OTAPI const otExtAddress *OTCALL otLinkGetExtendedAddress (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkSetExtendedAddress (otInstance *aInstance, const otExtAddress *aExtAddress)
 
OTAPI void OTCALL otLinkGetFactoryAssignedIeeeEui64 (otInstance *aInstance, otExtAddress *aEui64)
 
OTAPI int8_t OTCALL otLinkGetMaxTransmitPower (otInstance *aInstance)
 
OTAPI void OTCALL otLinkSetMaxTransmitPower (otInstance *aInstance, int8_t aPower)
 
OTAPI otPanId OTCALL otLinkGetPanId (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkSetPanId (otInstance *aInstance, otPanId aPanId)
 
OTAPI uint32_t OTCALL otLinkGetPollPeriod (otInstance *aInstance)
 
OTAPI void OTCALL otLinkSetPollPeriod (otInstance *aInstance, uint32_t aPollPeriod)
 
OTAPI otShortAddress OTCALL otLinkGetShortAddress (otInstance *aInstance)
 
OTAPI otMacFilterAddressMode OTCALL otLinkFilterGetAddressMode (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkFilterSetAddressMode (otInstance *aInstance, otMacFilterAddressMode aMode)
 
OTAPI otError OTCALL otLinkFilterAddAddress (otInstance *aInstance, const otExtAddress *aExtAddress)
 
OTAPI otError OTCALL otLinkFilterRemoveAddress (otInstance *aInstance, const otExtAddress *aExtAddress)
 
OTAPI void OTCALL otLinkFilterClearAddresses (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkFilterGetNextAddress (otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry)
 
OTAPI otError OTCALL otLinkFilterAddRssIn (otInstance *aInstance, const otExtAddress *aExtAddress, int8_t aRss)
 
OTAPI otError OTCALL otLinkFilterRemoveRssIn (otInstance *aInstance, const otExtAddress *aExtAddress)
 
OTAPI void OTCALL otLinkFilterClearRssIn (otInstance *aInstance)
 
OTAPI otError OTCALL otLinkFilterGetNextRssIn (otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry)
 
uint8_t otLinkConvertRssToLinkQuality (otInstance *aInstance, int8_t aRss)
 
int8_t otLinkConvertLinkQualityToRss (otInstance *aInstance, uint8_t aLinkQuality)
 
OTAPI const otMacCounters *OTCALL otLinkGetCounters (otInstance *aInstance)
 
void otLinkSetPcapCallback (otInstance *aInstance, otLinkPcapCallback aPcapCallback, void *aCallbackContext)
 
bool otLinkIsPromiscuous (otInstance *aInstance)
 
otError otLinkSetPromiscuous (otInstance *aInstance, bool aPromiscuous)
 

Detailed Description

This module includes functions that control link-layer configuration.

Typedef Documentation

typedef void(OTCALL * 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.
typedef void(OTCALL * 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.
typedef void(* otLinkPcapCallback)(const otRadioFrame *aFrame, 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 and mSecurityValid in aFrame will always be false.
Parameters
[in]aFrameA pointer to the received IEEE 802.15.4 frame.
[in]aContextA pointer to application-specific context.

Function Documentation

OTAPI otError OTCALL 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.
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.
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.
OTAPI otError OTCALL 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.
OTAPI otError OTCALL otLinkFilterAddAddress ( otInstance aInstance,
const otExtAddress aExtAddress 
)

This method adds an Extended Address to MAC filter.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA reference to the Extended Address.
Return values
OT_ERROR_NONESuccessfully added aExtAddress to MAC filter.
OT_ERROR_ALREADYIf aExtAddress was already in MAC filter.
OT_ERROR_INVALID_ARGSIf aExtAddress is NULL.
OT_ERROR_NO_BUFSNo available entry exists.
See Also
otLinkFilterGetAddressMode
otLinkFilterSetAddressMode
otLinkFilterRemoveAddress
otLinkFilterClearAddresses
otLinkFilterGetNextAddress
otLinkFilterAddRssIn
otLinkFilterRemoveRssIn
otLinkFilterClearRssIn
otLinkFilterGetNextRssIn
OTAPI otError OTCALL 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA pointer to the IEEE 802.15.4 Extended Address, or NULL to set the default received signal strength.
[in]aRssThe received signal strength (in dBm) to set.
Return values
OT_ERROR_NONESuccessfully set aRss for aExtAddress or set the default aRss for all received messages if aExtAddress is NULL.
OT_ERROR_NO_BUFSNo available entry exists.
See Also
otLinkFilterGetAddressMode
otLinkFilterSetAddressMode
otLinkFilterAddAddress
otLinkFilterRemoveAddress
otLinkFilterClearAddresses
otLinkFilterGetNextAddress
otLinkFilterRemoveRssIn
otLinkFilterClearRssIn
otLinkFilterGetNextRssIn
OTAPI void OTCALL otLinkFilterClearAddresses ( otInstance aInstance)
OTAPI void OTCALL otLinkFilterClearRssIn ( otInstance aInstance)
OTAPI otMacFilterAddressMode OTCALL otLinkFilterGetAddressMode ( otInstance aInstance)

This function gets the address mode of MAC filter.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
the address mode.
See Also
otLinkFilterSetAddressMode
otLinkFilterAddAddress
otLinkFilterRemoveAddress
otLinkFilterClearAddresses
otLinkFilterGetNextAddress
otLinkFilterAddRssIn
otLinkFilterRemoveRssIn
otLinkFilterClearRssIn
otLinkFilterGetNextRssIn
OTAPI otError OTCALL otLinkFilterGetNextAddress ( otInstance aInstance,
otMacFilterIterator aIterator,
otMacFilterEntry aEntry 
)

This method gets an in-use address filter entry.

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.
[out]aEntryA pointer to where the information is placed.
Return values
OT_ERROR_NONESuccessfully retrieved an in-use address filter entry.
OT_ERROR_INVALID_ARGSIf aIterator or aEntry is NULL.
OT_ERROR_NOT_FOUNDNo subsequent entry exists.
See Also
otLinkFilterGetAddressMode
otLinkFilterSetAddressMode
otLinkFilterAddAddress
otLinkFilterRemoveAddress
otLinkFilterClearAddresses
otLinkFilterAddRssIn
otLinkFilterRemoveRssIn
otLinkFilterClearRssIn
otLinkFilterGetNextRssIn
OTAPI otError OTCALL otLinkFilterGetNextRssIn ( otInstance aInstance,
otMacFilterIterator aIterator,
otMacFilterEntry aEntry 
)

This method gets an in-use RssIn filter entry.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in,out]aIteratorA 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]aEntryA 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.
Return values
OT_ERROR_NONESuccessfully retrieved an in-use RssIn Filter entry.
OT_ERROR_INVALID_ARGSIf aIterator or aEntry is NULL.
OT_ERROR_NOT_FOUNDNo subsequent entry exists.
See Also
otLinkFilterGetAddressMode
otLinkFilterSetAddressMode
otLinkFilterAddAddress
otLinkFilterRemoveAddress
otLinkFilterClearAddresses
otLinkFilterGetNextAddress
otLinkFilterAddRssIn
otLinkFilterRemoveRssIn
otLinkFilterClearRssIn
OTAPI otError OTCALL otLinkFilterRemoveAddress ( otInstance aInstance,
const otExtAddress aExtAddress 
)

This method removes an Extended Address from MAC filter.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA reference to the Extended Address.
Return values
OT_ERROR_NONESuccessfully removed aExtAddress from MAC filter.
OT_ERROR_INVALID_ARGSIf aExtAddress is NULL.
OT_ERROR_NOT_FOUNDaExtAddress is not in MAC filter.
See Also
otLinkFilterGetAddressMode
otLinkFilterSetAddressMode
otLinkFilterAddAddress
otLinkFilterClearAddresses
otLinkFilterGetNextAddress
otLinkFilterAddRssIn
otLinkFilterRemoveRssIn
otLinkFilterClearRssIn
otLinkFilterGetNextRssIn
OTAPI otError OTCALL 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aExtAddressA pointer to the IEEE 802.15.4 Extended Address, or NULL to reset the default received signal strength.
Return values
OT_ERROR_NONESuccessfully removed received signal strength setting for aExtAddress or removed the default received signal strength setting if aExtAddress is NULL.
OT_ERROR_NOT_FOUNDaExtAddress is not in MAC filter if it is not NULL.
See Also
otLinkFilterGetAddressMode
otLinkFilterSetAddressMode
otLinkFilterAddAddress
otLinkFilterRemoveAddress
otLinkFilterClearAddresses
otLinkFilterGetNextAddress
otLinkFilterAddRssIn
otLinkFilterClearRssIn
otLinkFilterGetNextRssIn
OTAPI otError OTCALL otLinkFilterSetAddressMode ( otInstance aInstance,
otMacFilterAddressMode  aMode 
)

This function sets the address mode of MAC filter.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aModeThe address mode to set.
Return values
OT_ERROR_NONESuccessfully set the address mode.
OT_ERROR_INVALID_ARGSaMode is not valid.
See Also
otLinkFilterGetAddressMode
otLinkFilterAddAddress
otLinkFilterRemoveAddress
otLinkFilterClearAddresses
otLinkFilterGetNextAddress
otLinkFilterAddRssIn
otLinkFilterRemoveRssIn
otLinkFilterClearRssIn
otLinkFilterGetNextRssIn
OTAPI uint8_t OTCALL 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
OTAPI const otMacCounters* OTCALL otLinkGetCounters ( otInstance aInstance)

Get the MAC layer counters.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
A pointer to the MAC layer counters.
OTAPI const otExtAddress* OTCALL 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.
OTAPI void OTCALL 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.
OTAPI int8_t OTCALL otLinkGetMaxTransmitPower ( otInstance aInstance)

This function returns the maximum transmit power setting in dBm.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
The maximum transmit power setting.
OTAPI otPanId OTCALL 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
OTAPI uint32_t OTCALL 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
OTAPI otShortAddress OTCALL 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.
OTAPI bool OTCALL 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.
OTAPI bool OTCALL 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.
OTAPI bool OTCALL 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.
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.
OTAPI otError OTCALL 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.
OTAPI otError OTCALL 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 aChnanel is not in the range [11, 26].
OT_ERROR_INVALID_STATEThread protocols are enabled.
See Also
otLinkGetChannel
OTAPI otError OTCALL otLinkSetExtendedAddress ( otInstance aInstance,
const otExtAddress aExtAddress 
)

This function sets the IEEE 802.15.4 Extended Address.

This function succeedsm 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.
OTAPI void OTCALL otLinkSetMaxTransmitPower ( otInstance aInstance,
int8_t  aPower 
)

This function sets the maximum transmit power in dBm.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPowerThe maximum transmit power in dBm.
OTAPI otError OTCALL 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
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.
OTAPI void OTCALL otLinkSetPollPeriod ( otInstance aInstance,
uint32_t  aPollPeriod 
)

Set the data poll period for sleepy end device.

Note
This function updates only poll period of sleepy end device. To update child timeout the function otSetChildTimeout() shall be called.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPollPerioddata poll period in milliseconds.
See Also
otLinkGetPollPeriod
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.

Documentation feedback | Developer Zone | Subscribe | Updated