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]aShortAddressThe Mac short address of the Probing Subject.
[in]aExtAddressA pointer to the Mac extended address of the Probing Subject.
[in]aMetricsValuesA pointer to the Link Metrics values obtained from the IE.
[in]aContextA 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]aSourceA pointer to the source address.
[in]aStatusThe status code in the response.
[in]aContextA 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]aSourceA pointer to the source address.
[in]aMetricsValuesA pointer to the Link Metrics values (the query result).
[in]aStatusThe status code in the report (only useful when aMetricsValues is NULL).
[in]aContextA 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]aInstanceA pointer to an OpenThread instance.
[in]aDestinationA pointer to the destination address.
[in]aEnhAckFlagsEnh-ACK Flags to indicate whether to register or clear the probing. 0 to clear and 1 to register. Other values are reserved.
[in]aLinkMetricsFlagsA pointer to flags specifying what metrics to query. Should be NULL when aEnhAckFlags is 0.
[in]aCallbackA pointer to a function that is called when an Enhanced Ack with Link Metrics is received.
[in]aCallbackContextA pointer to application-specific context.
Return values
OT_ERROR_NONESuccessfully sent a Link Metrics Management Request message.
OT_ERROR_NO_BUFSInsufficient buffers to generate the MLE Link Metrics Management Request message.
OT_ERROR_INVALID_ARGSaEnhAckFlags is not a valid value or aLinkMetricsFlags isn't correct.
OT_ERROR_UNKNOWN_NEIGHBORaDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aDestinationA pointer to the destination address.
[in]aSeriesIdThe Series ID to operate with.
[in]aSeriesFlagsThe Series Flags that specifies which frames are to be accounted.
[in]aLinkMetricsFlagsA pointer to flags specifying what metrics to query. Should be NULL when aSeriesFlags is 0.
[in]aCallbackA pointer to a function that is called when Link Metrics Management Response is received.
[in]aCallbackContextA pointer to application-specific context.
Return values
OT_ERROR_NONESuccessfully sent a Link Metrics Management Request message.
OT_ERROR_NO_BUFSInsufficient buffers to generate the MLE Link Metrics Management Request message.
OT_ERROR_INVALID_ARGSaSeriesId is not within the valid range.
OT_ERROR_UNKNOWN_NEIGHBORaDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aDestinationA pointer to the destination address.
[in]aSeriesIdThe Series ID to query about, 0 for Single Probe.
[in]aLinkMetricsFlagsA pointer to flags specifying what metrics to query.
[in]aCallbackA pointer to a function that is called when Link Metrics report is received.
[in]aCallbackContextA pointer to application-specific context.
Return values
OT_ERROR_NONESuccessfully sent a Link Metrics query message.
OT_ERROR_NO_BUFSInsufficient buffers to generate the MLE Data Request message.
OT_ERROR_UNKNOWN_NEIGHBORaDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aDestinationA pointer to the destination address.
[in]aSeriesIdThe Series ID [1, 254] which the Probe message aims at.
[in]aLengthThe length of the data payload in Link Probe TLV, 0, 64.
Return values
OT_ERROR_NONESuccessfully sent a Link Probe message.
OT_ERROR_NO_BUFSInsufficient buffers to generate the MLE Link Probe message.
OT_ERROR_INVALID_ARGSaSeriesId or aLength is not within the valid range.
OT_ERROR_UNKNOWN_NEIGHBORaDestination is not link-local or the neighbor is not found.
OT_ERROR_NOT_CAPABLEThe neighbor is not a Thread 1.2 device and does not support Link Metrics.