Link Metrics

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)
Sends an MLE Link Metrics Management Request to configure or 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)
Sends an MLE Link Probe message.

Detailed Description

This module includes functions that control the Link Metrics protocol.

Typedef Documentation

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

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
)

Sends an MLE Link Metrics Management Request to configure or 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
)

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.