Link Metrics#

This module includes functions that control the Link Metrics protocol.

Modules#

otLinkMetricsValues

otLinkMetricsSeriesFlags

Enumerations#

enum
OT_LINK_METRICS_ENH_ACK_CLEAR = 0
OT_LINK_METRICS_ENH_ACK_REGISTER = 1
}

Enhanced-ACK Flags.

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

Typedefs#

typedef struct otLinkMetricsValues

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

Represents which frames are accounted in a Forward Tracking Series.

Enhanced-ACK Flags.

typedef enum otLinkMetricsStatus

Link Metrics Status values.

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

Pointer is called when a Link Metrics report is received.

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

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

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

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

Functions#

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.

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.

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.

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

Sends an MLE Link Probe message.

bool
otLinkMetricsManagerIsEnabled(otInstance *aInstance)

If Link Metrics Manager is enabled.

void
otLinkMetricsManagerSetEnabled(otInstance *aInstance, bool aEnable)

Enable or disable Link Metrics Manager.

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

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

Enumeration Documentation#

otLinkMetricsEnhAckFlags#

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.


Definition at line 84 of file include/openthread/link_metrics.h

otLinkMetricsStatus#

otLinkMetricsStatus

Link Metrics Status values.

Enumerator
OT_LINK_METRICS_STATUS_SUCCESS
OT_LINK_METRICS_STATUS_CANNOT_SUPPORT_NEW_SERIES
OT_LINK_METRICS_STATUS_SERIESID_ALREADY_REGISTERED
OT_LINK_METRICS_STATUS_SERIESID_NOT_RECOGNIZED
OT_LINK_METRICS_STATUS_NO_MATCHING_FRAMES_RECEIVED
OT_LINK_METRICS_STATUS_OTHER_ERROR

Definition at line 93 of file include/openthread/link_metrics.h

Typedef Documentation#

otLinkMetricsValues#

typedef struct otLinkMetricsValues otLinkMetricsValues

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


Definition at line 66 of file include/openthread/link_metrics.h

otLinkMetricsSeriesFlags#

typedef struct otLinkMetricsSeriesFlags otLinkMetricsSeriesFlags

Represents which frames are accounted in a Forward Tracking Series.


Definition at line 77 of file include/openthread/link_metrics.h

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.


Definition at line 88 of file include/openthread/link_metrics.h

otLinkMetricsStatus#

typedef enum otLinkMetricsStatus otLinkMetricsStatus

Link Metrics Status values.


Definition at line 101 of file include/openthread/link_metrics.h

otLinkMetricsReportCallback#

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

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.


Definition at line 111 of file include/openthread/link_metrics.h

otLinkMetricsMgmtResponseCallback#

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

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.


Definition at line 122 of file include/openthread/link_metrics.h

otLinkMetricsEnhAckProbingIeReportCallback#

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

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.


Definition at line 134 of file include/openthread/link_metrics.h

Function Documentation#

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.

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.

It could be either Single Probe or Forward Tracking Series.


Definition at line 156 of file include/openthread/link_metrics.h

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.


Definition at line 182 of file include/openthread/link_metrics.h

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.

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.

N/AaEnhAckCallback
N/AaEnhAckCallbackContext

This functionality requires OT_LINK_METRICS_INITIATOR feature enabled.


Definition at line 210 of file include/openthread/link_metrics.h

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] (per Thread 1.2 spec, 4.4.37).


Definition at line 233 of file include/openthread/link_metrics.h

otLinkMetricsManagerIsEnabled#

bool otLinkMetricsManagerIsEnabled (otInstance * aInstance)

If Link Metrics Manager is enabled.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 246 of file include/openthread/link_metrics.h

otLinkMetricsManagerSetEnabled#

void otLinkMetricsManagerSetEnabled (otInstance * aInstance, bool aEnable)

Enable or disable Link Metrics Manager.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aEnable

A boolean indicating to enable or disable.


Definition at line 254 of file include/openthread/link_metrics.h

otLinkMetricsManagerGetMetricsValueByExtAddr#

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

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

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.


Definition at line 267 of file include/openthread/link_metrics.h