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 enum otLinkMetricsEnhAckFlags Enhanced-ACK Flags.
otLinkMetricsEnhAckProbingIeReportCallback)(otShortAddress aShortAddress, const otExtAddress *aExtAddress, const otLinkMetricsValues *aMetricsValues, void *aContext)	typedef void(* This function pointer is called when Enh-ACK Probing IE is received.
otLinkMetricsMgmtResponseCallback)(const otIp6Address *aSource, uint8_t aStatus, void *aContext)	typedef void(* This function pointer is called when a Link Metrics Management Response is received.
otLinkMetricsReportCallback)(const otIp6Address *aSource, const otLinkMetricsValues *aMetricsValues, uint8_t aStatus, void *aContext)	typedef void(* This function pointer is called when a Link Metrics report is received.
otLinkMetricsSeriesFlags	typedef struct otLinkMetricsSeriesFlags This structure represents which frames are accounted in a Forward Tracking Series.
otLinkMetricsStatus	typedef enum otLinkMetricsStatus Link Metrics Status values.
otLinkMetricsValues	typedef struct otLinkMetricsValues This structure 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)	otError This function 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)	otError Sends an MLE Link Metrics Management Request to configure or clear a Forward Tracking Series.
otLinkMetricsQuery(otInstance *aInstance, const otIp6Address *aDestination, uint8_t aSeriesId, const otLinkMetrics *aLinkMetricsFlags, otLinkMetricsReportCallback aCallback, void *aCallbackContext)	otError This function sends an MLE Data Request to query Link Metrics.
otLinkMetricsSendLinkProbe(otInstance *aInstance, const otIp6Address *aDestination, uint8_t aSeriesId, uint8_t aLength)	otError Sends an MLE Link Probe message.

Structs
otLinkMetricsSeriesFlags	This structure represents which frames are accounted in a Forward Tracking Series.
otLinkMetricsValues	This structure 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)

This function 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, uint8_t aStatus, void *aContext)

This function 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, uint8_t aStatus, void *aContext)

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

This structure represents which frames are accounted in a Forward Tracking Series.

otLinkMetricsStatus

enum otLinkMetricsStatus otLinkMetricsStatus

Link Metrics Status values.

otLinkMetricsValues

struct otLinkMetricsValues otLinkMetricsValues

This structure 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
)

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

otLinkMetricsQuery

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

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