This module includes functions that control the Link Metrics protocol.

Classes
struct	otLinkMetricsValues
	This structure represents the result (value) for a Link Metrics query.

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

Typedefs
typedef struct otLinkMetricsValues	otLinkMetricsValues
	This structure represents the result (value) for a Link Metrics query.

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

typedef enum otLinkMetricsEnhAckFlags	otLinkMetricsEnhAckFlags
	Enhanced-ACK Flags.

typedef enum otLinkMetricsStatus	otLinkMetricsStatus
	Link Metrics Status values.

typedef 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.

typedef void(*	otLinkMetricsMgmtResponseCallback ) (const otIp6Address aSource, uint8_t aStatus, void aContext)
	This function pointer is called when a Link Metrics Management Response is received.

typedef void(*	otLinkMetricsEnhAckProbingIeReportCallback ) ( otShortAddress aShortAddress, const otExtAddress aExtAddress, const otLinkMetricsValues aMetricsValues, void *aContext)
	This function pointer is called when Enh-ACK Probing IE is received.

Enumerations
enum	otLinkMetricsEnhAckFlags { OT_LINK_METRICS_ENH_ACK_CLEAR = 0, OT_LINK_METRICS_ENH_ACK_REGISTER = 1 }
	Enhanced-ACK Flags.

enum	otLinkMetricsStatus { OT_LINK_METRICS_STATUS_SUCCESS = 0, OT_LINK_METRICS_STATUS_CANNOT_SUPPORT_NEW_SERIES = 1, OT_LINK_METRICS_STATUS_SERIESID_ALREADY_REGISTERED = 2, OT_LINK_METRICS_STATUS_SERIESID_NOT_RECOGNIZED = 3, OT_LINK_METRICS_STATUS_NO_MATCHING_FRAMES_RECEIVED = 4, OT_LINK_METRICS_STATUS_OTHER_ERROR = 254 }
	Link Metrics Status values.

Functions
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.

otError	otLinkMetricsConfigForwardTrackingSeries ( otInstance aInstance, const otIp6Address aDestination, uint8_t aSeriesId, otLinkMetricsSeriesFlags aSeriesFlags, const otLinkMetrics aLinkMetricsFlags, otLinkMetricsMgmtResponseCallback aCallback, void aCallbackContext)
	This function sends an MLE Link Metrics Management Request to configure/clear a Forward Tracking Series.

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.

otError	otLinkMetricsSendLinkProbe ( otInstance aInstance, const otIp6Address aDestination, uint8_t aSeriesId, uint8_t aLength)
	This function sends an MLE Link Probe message.

Detailed Description

This module includes functions that control the Link Metrics protocol.

Typedef Documentation

◆ otLinkMetricsEnhAckFlags

typedef enum otLinkMetricsEnhAckFlags otLinkMetricsEnhAckFlags

Enhanced-ACK Flags.

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

◆ otLinkMetricsEnhAckProbingIeReportCallback

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

This function pointer is called when Enh-ACK Probing IE is received.

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

typedef void(* otLinkMetricsMgmtResponseCallback) (const otIp6Address *aSource, uint8_t aStatus, void *aContext)

This function pointer is called when a Link Metrics Management Response is received.

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

typedef 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.

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.

Enumeration Type Documentation

◆ otLinkMetricsEnhAckFlags

enum otLinkMetricsEnhAckFlags

Enhanced-ACK Flags.

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

Enumerator
OT_LINK_METRICS_ENH_ACK_CLEAR	Clear.
OT_LINK_METRICS_ENH_ACK_REGISTER	Register.

Function Documentation

◆ 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.

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`
	)

This function sends an MLE Link Metrics Management Request to configure/clear a Forward Tracking Series.

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.

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`
	)

This function sends an MLE Link Probe message.

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.

Link Metrics API > Link

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ otLinkMetricsEnhAckFlags

◆ otLinkMetricsEnhAckProbingIeReportCallback

◆ otLinkMetricsMgmtResponseCallback

◆ otLinkMetricsReportCallback

Enumeration Type Documentation

◆ otLinkMetricsEnhAckFlags

Function Documentation

◆ otLinkMetricsConfigEnhAckProbing()

◆ otLinkMetricsConfigForwardTrackingSeries()

◆ otLinkMetricsQuery()

◆ otLinkMetricsSendLinkProbe()

Link Metrics
API > Link