# Link Metrics

# Link Metrics

This module includes functions that control the Link Metrics protocol.

## Summary

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga80083a62a99c5c1b4a5092e3939fbf06{ https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gga80083a62a99c5c1b4a5092e3939fbf06adf401b47ac88714f48bda2cb260e3076 = 0, https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gga80083a62a99c5c1b4a5092e3939fbf06a18ce0c158f2c7de417a19d625122c5ca = 1 }` | enumEnhanced-ACK Flags. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gae3823fa919d8c13457f3c52325447eb2` | enumLink Metrics Status values. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gaed255b55407513e357ac7ada13f56634` | typedef `enum https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga80083a62a99c5c1b4a5092e3939fbf06` Enhanced-ACK Flags. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga42511a299160c43a177f9cf051b75888)(otShortAddress aShortAddress, const otExtAddress *aExtAddress, const otLinkMetricsValues *aMetricsValues, void *aContext)` | typedef `void(*` Pointer is called when Enh-ACK Probing IE is received. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga8924874aba6350c0fdaa6792947b7246)(const otIp6Address *aSource, otLinkMetricsStatus aStatus, void *aContext)` | typedef `void(*` Pointer is called when a Link Metrics Management Response is received. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gab71c5cc2e401ad2fc09ed6ce07a652b1)(const otIp6Address *aSource, const otLinkMetricsValues *aMetricsValues, otLinkMetricsStatus aStatus, void *aContext)` | typedef `void(*` Pointer is called when a Link Metrics report is received. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga4542b67ef895704ce77e515ae6be5ce7` | typedef `struct https://openthread.io/reference/struct/ot-link-metrics-series-flags` Represents which frames are accounted in a Forward Tracking Series. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga2d7656564f806577daaf43a57fc78d24` | typedef `enum https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gae3823fa919d8c13457f3c52325447eb2` Link Metrics Status values. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga8577bfad4c556dc0d7cc00f58e38422e` | typedef `struct https://openthread.io/reference/struct/ot-link-metrics-values` Represents the result (value) for a Link Metrics query. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gaf86783e1548420dcd77819c615313cdc(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-ip6-address *aDestination, https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga80083a62a99c5c1b4a5092e3939fbf06 aEnhAckFlags, const https://openthread.io/reference/struct/ot-link-metrics *aLinkMetricsFlags, https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga8924874aba6350c0fdaa6792947b7246 aCallback, void *aCallbackContext, https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga42511a299160c43a177f9cf051b75888 aEnhAckCallback, void *aEnhAckCallbackContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends an MLE Link Metrics Management Request to configure/clear an Enhanced-ACK Based Probing. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gadbb127e677c4f131b6020ecbdb68d535(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-ip6-address *aDestination, uint8_t aSeriesId, https://openthread.io/reference/struct/ot-link-metrics-series-flags aSeriesFlags, const https://openthread.io/reference/struct/ot-link-metrics *aLinkMetricsFlags, https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga8924874aba6350c0fdaa6792947b7246 aCallback, void *aCallbackContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends an MLE Link Metrics Management Request to configure or clear a Forward Tracking Series. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga8a375dc3db7e2e3d3d00bb8b855b9cbf(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-ext-address *aExtAddress, https://openthread.io/reference/struct/ot-link-metrics-values *aLinkMetricsValues)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Get Link Metrics data of a neighbor by its extended address. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gabd5d027d8c03c6281d0d8ad49586e891(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` If Link Metrics Manager is enabled. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gad179dc4ac498a0d7dbeef765b0788ae3(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnable)` | `void` Enable or disable Link Metrics Manager. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gaaa4fedad5a2046c0e1b7cdae701d8285(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-ip6-address *aDestination, uint8_t aSeriesId, const https://openthread.io/reference/struct/ot-link-metrics *aLinkMetricsFlags, https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1gab71c5cc2e401ad2fc09ed6ce07a652b1 aCallback, void *aCallbackContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends an MLE Data Request to query Link Metrics. |
| `https://openthread.io/reference/group/api-link-metrics#group__api-link-metrics_1ga69460ed6e31b72ff1109087ca794c918(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-ip6-address *aDestination, uint8_t aSeriesId, uint8_t aLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends an MLE Link Probe message. |

| ### Structs ||
|---|---|
| [otLinkMetricsSeriesFlags](https://openthread.io/reference/struct/ot-link-metrics-series-flags) | Represents which frames are accounted in a Forward Tracking Series. |
| [otLinkMetricsValues](https://openthread.io/reference/struct/ot-link-metrics-values) | 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)
```
Pointer is called when Enh-ACK Probing IE is received.

<br />

| 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, otLinkMetricsStatus aStatus, void *aContext)
```
Pointer is called when a Link Metrics Management Response is received.

<br />

| 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, otLinkMetricsStatus aStatus, void *aContext)
```
Pointer is called when a Link Metrics report is received.

<br />

| 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
```
Represents which frames are accounted in a Forward Tracking Series.

### otLinkMetricsStatus

```
enum otLinkMetricsStatus otLinkMetricsStatus
```
Link Metrics Status values.

### otLinkMetricsValues

```
struct otLinkMetricsValues otLinkMetricsValues
```
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
)
```
Sends an MLE Link Metrics Management Request to configure/clear an Enhanced-ACK Based Probing.

This functionality requires OT_LINK_METRICS_INITIATOR feature enabled.

<br />

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

<br />

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

### otLinkMetricsManagerGetMetricsValueByExtAddr

```
otError otLinkMetricsManagerGetMetricsValueByExtAddr(
  otInstance *aInstance,
  const otExtAddress *aExtAddress,
  otLinkMetricsValues *aLinkMetricsValues
)
```
Get Link Metrics data of a neighbor by its extended address.

<br />

| Details ||
|---|---|
| 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. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully got the Link Metrics data. | | `OT_ERROR_INVALID_ARGS` | The arguments are invalid. | | `OT_ERROR_NOT_FOUND` | No neighbor with the given extended address is found. | |

### otLinkMetricsManagerIsEnabled

```
bool otLinkMetricsManagerIsEnabled(
  otInstance *aInstance
)
```
If Link Metrics Manager is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | Link Metrics Manager is enabled. | | `FALSE` | Link Metrics Manager is not enabled. | |

### otLinkMetricsManagerSetEnabled

```
void otLinkMetricsManagerSetEnabled(
  otInstance *aInstance,
  bool aEnable
)
```
Enable or disable Link Metrics Manager.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aEnable` | A boolean indicating to enable or disable. | |

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

It could be either Single Probe or Forward Tracking Series.

<br />

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

<br />

| 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](https://openthread.io/reference/group/per Thread 1.2 spec, 4.4.37). | |
| 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](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).