Link Metrics

This module includes functions that control the Link Metrics protocol.

Summary

Enumerations
otLinkMetricsEnhAckFlags{
  OT_LINK_METRICS_ENH_ACK_CLEAR = 0,
  OT_LINK_METRICS_ENH_ACK_REGISTER = 1
} 		enum
Enhanced-ACK Flags.
otLinkMetricsStatus enum
Link Metrics Status values.

Typedefs
otLinkMetricsEnhAckFlags typedef
Enhanced-ACK Flags.
otLinkMetricsEnhAckProbingIeReportCallback)(otShortAddress aShortAddress, const otExtAddress *aExtAddress, const otLinkMetricsValues *aMetricsValues, void *aContext) typedef
void(*
Pointer is called when Enh-ACK Probing IE is received.
otLinkMetricsMgmtResponseCallback)(const otIp6Address *aSource, otLinkMetricsStatus aStatus, void *aContext) typedef
void(*
Pointer is called when a Link Metrics Management Response is received.
otLinkMetricsReportCallback)(const otIp6Address *aSource, const otLinkMetricsValues *aMetricsValues, otLinkMetricsStatus aStatus, void *aContext) typedef
void(*
Pointer is called when a Link Metrics report is received.
otLinkMetricsSeriesFlags typedef
Represents which frames are accounted in a Forward Tracking Series.
otLinkMetricsStatus typedef
Link Metrics Status values.
otLinkMetricsValues typedef
Represents the result (value) for a Link Metrics query.

Functions
otLinkMetricsConfigEnhAckProbing(otInstance *aInstance, const otIp6Address *aDestination, otLinkMetricsEnhAckFlags aEnhAckFlags, const otLinkMetrics *aLinkMetricsFlags, otLinkMetricsMgmtResponseCallback aCallback, void *aCallbackContext, otLinkMetricsEnhAckProbingIeReportCallback aEnhAckCallback, void *aEnhAckCallbackContext)
Sends an MLE Link Metrics Management Request to configure/clear an Enhanced-ACK Based Probing.
otLinkMetricsConfigForwardTrackingSeries(otInstance *aInstance, const otIp6Address *aDestination, uint8_t aSeriesId, otLinkMetricsSeriesFlags aSeriesFlags, const otLinkMetrics *aLinkMetricsFlags, otLinkMetricsMgmtResponseCallback aCallback, void *aCallbackContext)
Sends an MLE Link Metrics Management Request to configure or clear a Forward Tracking Series.
otLinkMetricsManagerGetMetricsValueByExtAddr(otInstance *aInstance, const otExtAddress *aExtAddress, otLinkMetricsValues *aLinkMetricsValues)
Get Link Metrics data of a neighbor by its extended address.
otLinkMetricsManagerIsEnabled(otInstance *aInstance)
bool
If Link Metrics Manager is enabled.
otLinkMetricsManagerSetEnabled(otInstance *aInstance, bool aEnable)
void
Enable or disable Link Metrics Manager.
otLinkMetricsQuery(otInstance *aInstance, const otIp6Address *aDestination, uint8_t aSeriesId, const otLinkMetrics *aLinkMetricsFlags, otLinkMetricsReportCallback aCallback, void *aCallbackContext)
Sends an MLE Data Request to query Link Metrics.
otLinkMetricsSendLinkProbe(otInstance *aInstance, const otIp6Address *aDestination, uint8_t aSeriesId, uint8_t aLength)
Sends an MLE Link Probe message.

Structs
otLinkMetricsSeriesFlags

Represents which frames are accounted in a Forward Tracking Series.

otLinkMetricsValues

Represents the result (value) for a Link Metrics query.

Enumerations

otLinkMetricsEnhAckFlags

 otLinkMetricsEnhAckFlags

Enhanced-ACK Flags.

These are used in Enhanced-ACK Based Probing to indicate whether to register or clear the probing.

Properties
OT_LINK_METRICS_ENH_ACK_CLEAR

Clear.

OT_LINK_METRICS_ENH_ACK_REGISTER

Register.

otLinkMetricsStatus

 otLinkMetricsStatus

Link Metrics Status values.

Typedefs

otLinkMetricsEnhAckFlags

enum otLinkMetricsEnhAckFlags otLinkMetricsEnhAckFlags

Enhanced-ACK Flags.

These are used in Enhanced-ACK Based Probing to indicate whether to register or clear the probing.

otLinkMetricsEnhAckProbingIeReportCallback

void(* otLinkMetricsEnhAckProbingIeReportCallback)(otShortAddress aShortAddress, const otExtAddress *aExtAddress, const otLinkMetricsValues *aMetricsValues, void *aContext)

Pointer is called when Enh-ACK Probing IE is received.

Details
Parameters
[in] aShortAddress
The Mac short address of the Probing Subject.
[in] aExtAddress
A pointer to the Mac extended address of the Probing Subject.
[in] aMetricsValues
A pointer to the Link Metrics values obtained from the IE.
[in] aContext
A pointer to application-specific context.

otLinkMetricsMgmtResponseCallback

void(* otLinkMetricsMgmtResponseCallback)(const otIp6Address *aSource, otLinkMetricsStatus aStatus, void *aContext)

Pointer is called when a Link Metrics Management Response is received.

Details
Parameters
[in] aSource
A pointer to the source address.
[in] aStatus
The status code in the response.
[in] aContext
A pointer to application-specific context.

otLinkMetricsReportCallback

void(* otLinkMetricsReportCallback)(const otIp6Address *aSource, const otLinkMetricsValues *aMetricsValues, otLinkMetricsStatus aStatus, void *aContext)

Pointer is called when a Link Metrics report is received.

Details
Parameters
[in] aSource
A pointer to the source address.
[in] aMetricsValues
A pointer to the Link Metrics values (the query result).
[in] aStatus
The status code in the report (only useful when aMetricsValues is NULL).
[in] aContext
A pointer to application-specific context.

otLinkMetricsSeriesFlags

struct otLinkMetricsSeriesFlags otLinkMetricsSeriesFlags

Represents which frames are accounted in a Forward Tracking Series.

otLinkMetricsStatus

enum otLinkMetricsStatus otLinkMetricsStatus

Link Metrics Status values.

otLinkMetricsValues

struct otLinkMetricsValues otLinkMetricsValues

Represents the result (value) for a Link Metrics query.

Functions

otLinkMetricsConfigEnhAckProbing

otError otLinkMetricsConfigEnhAckProbing(
  otInstance *aInstance,
  const otIp6Address *aDestination,
  otLinkMetricsEnhAckFlags aEnhAckFlags,
  const otLinkMetrics *aLinkMetricsFlags,
  otLinkMetricsMgmtResponseCallback aCallback,
  void *aCallbackContext,
  otLinkMetricsEnhAckProbingIeReportCallback aEnhAckCallback,
  void *aEnhAckCallbackContext
)

Sends an MLE Link Metrics Management Request to configure/clear an Enhanced-ACK Based Probing.

This functionality requires OT_LINK_METRICS_INITIATOR feature enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aDestination
A pointer to the destination address.
[in] aEnhAckFlags
Enh-ACK Flags to indicate whether to register or clear the probing. 0 to clear and 1 to register. Other values are reserved.
[in] aLinkMetricsFlags
A pointer to flags specifying what metrics to query. Should be NULL when aEnhAckFlags is 0.
[in] aCallback
A pointer to a function that is called when an Enhanced Ack with Link Metrics is received.
[in] aCallbackContext
A pointer to application-specific context.
Return Values
OT_ERROR_NONE
Successfully sent a Link Metrics Management Request message.
OT_ERROR_NO_BUFS
Insufficient buffers to generate the MLE Link Metrics Management Request message.
OT_ERROR_INVALID_ARGS
aEnhAckFlags is not a valid value or aLinkMetricsFlags isn't correct.
OT_ERROR_UNKNOWN_NEIGHBOR
aDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLE
The neighbor is not a Thread 1.2 device and does not support Link Metrics.

otLinkMetricsConfigForwardTrackingSeries

otError otLinkMetricsConfigForwardTrackingSeries(
  otInstance *aInstance,
  const otIp6Address *aDestination,
  uint8_t aSeriesId,
  otLinkMetricsSeriesFlags aSeriesFlags,
  const otLinkMetrics *aLinkMetricsFlags,
  otLinkMetricsMgmtResponseCallback aCallback,
  void *aCallbackContext
)

Sends an MLE Link Metrics Management Request to configure or clear a Forward Tracking Series.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aDestination
A pointer to the destination address.
[in] aSeriesId
The Series ID to operate with.
[in] aSeriesFlags
The Series Flags that specifies which frames are to be accounted.
[in] aLinkMetricsFlags
A pointer to flags specifying what metrics to query. Should be NULL when aSeriesFlags is 0.
[in] aCallback
A pointer to a function that is called when Link Metrics Management Response is received.
[in] aCallbackContext
A pointer to application-specific context.
Return Values
OT_ERROR_NONE
Successfully sent a Link Metrics Management Request message.
OT_ERROR_NO_BUFS
Insufficient buffers to generate the MLE Link Metrics Management Request message.
OT_ERROR_INVALID_ARGS
aSeriesId is not within the valid range.
OT_ERROR_UNKNOWN_NEIGHBOR
aDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLE
The neighbor is not a Thread 1.2 device and does not support Link Metrics.

otLinkMetricsManagerGetMetricsValueByExtAddr

otError otLinkMetricsManagerGetMetricsValueByExtAddr(
  otInstance *aInstance,
  const otExtAddress *aExtAddress,
  otLinkMetricsValues *aLinkMetricsValues
)

Get Link Metrics data of a neighbor by its extended address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aExtAddress
A pointer to the Mac extended address of the Probing Subject.
[out] aLinkMetricsValues
A pointer to the Link Metrics values of the subject.
Return Values
OT_ERROR_NONE
Successfully got the Link Metrics data.
OT_ERROR_INVALID_ARGS
The arguments are invalid.
OT_ERROR_NOT_FOUND
No neighbor with the given extended address is found.

otLinkMetricsManagerIsEnabled

bool otLinkMetricsManagerIsEnabled(
  otInstance *aInstance
)

If Link Metrics Manager is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
Link Metrics Manager is enabled.
FALSE
Link Metrics Manager is not enabled.

otLinkMetricsManagerSetEnabled

void otLinkMetricsManagerSetEnabled(
  otInstance *aInstance,
  bool aEnable
)

Enable or disable Link Metrics Manager.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnable
A boolean indicating to enable or disable.

otLinkMetricsQuery

otError otLinkMetricsQuery(
  otInstance *aInstance,
  const otIp6Address *aDestination,
  uint8_t aSeriesId,
  const otLinkMetrics *aLinkMetricsFlags,
  otLinkMetricsReportCallback aCallback,
  void *aCallbackContext
)

Sends an MLE Data Request to query Link Metrics.

It could be either Single Probe or Forward Tracking Series.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aDestination
A pointer to the destination address.
[in] aSeriesId
The Series ID to query about, 0 for Single Probe.
[in] aLinkMetricsFlags
A pointer to flags specifying what metrics to query.
[in] aCallback
A pointer to a function that is called when Link Metrics report is received.
[in] aCallbackContext
A pointer to application-specific context.
Return Values
OT_ERROR_NONE
Successfully sent a Link Metrics query message.
OT_ERROR_NO_BUFS
Insufficient buffers to generate the MLE Data Request message.
OT_ERROR_UNKNOWN_NEIGHBOR
aDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLE
The neighbor is not a Thread 1.2 device and does not support Link Metrics.

otLinkMetricsSendLinkProbe

otError otLinkMetricsSendLinkProbe(
  otInstance *aInstance,
  const otIp6Address *aDestination,
  uint8_t aSeriesId,
  uint8_t aLength
)

Sends an MLE Link Probe message.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aDestination
A pointer to the destination address.
[in] aSeriesId
The Series ID [1, 254] which the Probe message aims at.
[in] aLength
The length of the data payload in Link Probe TLV, 0, 64.
Return Values
OT_ERROR_NONE
Successfully sent a Link Probe message.
OT_ERROR_NO_BUFS
Insufficient buffers to generate the MLE Link Probe message.
OT_ERROR_INVALID_ARGS
aSeriesId or aLength is not within the valid range.
OT_ERROR_UNKNOWN_NEIGHBOR
aDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLE
The neighbor is not a Thread 1.2 device and does not support Link Metrics.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.