# Mesh Diagnostics

This module includes definitions and functions for Mesh Diagnostics.

## Summary

The Mesh Diagnostics APIs require `OPENTHREAD_CONFIG_MESH_DIAG_ENABLE` and `OPENTHREAD_FTD`.

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga783068418c19b2dc5c20beaf8b4c67ab` | typedef `struct https://openthread.io/reference/struct/ot-mesh-diag-child-entry` Represents information about a child entry from `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga18ee2865034a08f2c48ecd8a8060347d`. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga72882e93e3c4fb130eed2220aeea2bbe` | typedef `struct https://openthread.io/reference/struct/ot-mesh-diag-child-info` Represents information about a discovered child in Thread mesh using `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a`. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad760dc8af01b6a832e46cf81f09195a0)(otError aError, uint16_t aChildRloc16, otMeshDiagIp6AddrIterator *aIp6AddrIterator, void *aContext)` | typedef `void(*` Represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga0d1abaad22e01b6c1c59337e6b7c322b` to provide information about an MTD child and its list of IPv6 addresses. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gab8bec167674afe5db2f84b8cb4f21bb4` | typedef `struct https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gab8bec167674afe5db2f84b8cb4f21bb4` An opaque iterator to iterate over list of children of a router. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga82a5a4bca9a0ff7797b9feecd5427b5f)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext)` | typedef `void(*` Pointer type represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a` to provide information about a discovered router. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gaea63e2dd4d061eac252022387dbb668a` | typedef `struct https://openthread.io/reference/struct/ot-mesh-diag-discover-config` Represents the set of configurations used when discovering mesh topology indicating which items to discover. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gae5a7d43450ad825715ea520ce8be63c6` | typedef `struct https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gae5a7d43450ad825715ea520ce8be63c6` An opaque iterator to iterate over list of IPv6 addresses of a router. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga260111e3cf350e8b5e9c738e0cfe9ad2)(otError aError, const otMeshDiagChildEntry *aChildEntry, void *aContext)` | typedef `void(*` Represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga18ee2865034a08f2c48ecd8a8060347d` to provide information about child table entries. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga2a54059c86b309f0b20c8cf561213c67)(otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext)` | typedef `void(*` Represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad7ccd5df782c0ae1f3cd58fc358fb567` to provide information about neighbor router table entries. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gafca9cbdc26b74a9543bf17664845427d` | typedef `struct https://openthread.io/reference/struct/ot-mesh-diag-router-info` Represents information about a router in Thread mesh discovered using `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a`. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gae52cccaa2795e42e1ae803e139e300d5` | typedef `struct https://openthread.io/reference/struct/ot-mesh-diag-router-neighbor-entry` Represents information about a router neighbor entry from `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad7ccd5df782c0ae1f3cd58fc358fb567`. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5c210c6baeaef2cf255c87089501ad78` | typedef `https://openthread.io/reference/struct/ot-network-diag-tlv` Represents information about a parsed Network Diagnostic TLV. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga1ef742308d032ac823ff8e002af4fdc1` | typedef `struct https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga1ef742308d032ac823ff8e002af4fdc1` An opaque iterator to iterate over the list of extra Network Diagnostic TLVs returned by a router. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gab4ee95a3b302b9fc5015513e544e2895(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Cancels an ongoing topology discovery if there is one, otherwise no action. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-mesh-diag-discover-config *aConfig, https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga82a5a4bca9a0ff7797b9feecd5427b5f aCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts network topology discovery. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga78baee038d68cb48210e5044244fb965(https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gab8bec167674afe5db2f84b8cb4f21bb4 *aIterator, https://openthread.io/reference/struct/ot-mesh-diag-child-info *aChildInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Iterates through the discovered children of a router. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga3a629de56049a929d6e43ea35fdc2fe7(https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gae5a7d43450ad825715ea520ce8be63c6 *aIterator, https://openthread.io/reference/struct/ot-ip6-address *aIp6Address)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Iterates through the discovered IPv6 addresses of a router or an MTD child. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gac27f1e93d20ae7ba9577a6df32ff7bca(https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga1ef742308d032ac823ff8e002af4fdc1 *aIterator, https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5c210c6baeaef2cf255c87089501ad78 *aTlvInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Iterates through the discovered extra Network Diagnostic TLVs of a router. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga2826d5b798d846cf49e885b98d7fe157(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint32_t` Gets the response timeout value. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga18ee2865034a08f2c48ecd8a8060347d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aRloc16, https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga260111e3cf350e8b5e9c738e0cfe9ad2 aCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts query for child table for a given router. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga0d1abaad22e01b6c1c59337e6b7c322b(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aRloc16, https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad760dc8af01b6a832e46cf81f09195a0 aCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a query to a parent to retrieve the IPv6 addresses of all its MTD children. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad7ccd5df782c0ae1f3cd58fc358fb567(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aRloc16, https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga2a54059c86b309f0b20c8cf561213c67 aCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts query for router neighbor table for a given router. |
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gaf2de5b28b659b07e5eb05261ae8abdbc(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint32_t aTimeout)` | `void` Sets the response timeout value to use for any future mesh diagnostic queries. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gaa291eaaba57ab48d0f4869bfc6895318 0xffff` | Specifies that Thread Version is unknown. |

| ### Structs ||
|---|---|
| [otMeshDiagChildEntry](https://openthread.io/reference/struct/ot-mesh-diag-child-entry) | Represents information about a child entry from `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga18ee2865034a08f2c48ecd8a8060347d`. |
| [otMeshDiagChildInfo](https://openthread.io/reference/struct/ot-mesh-diag-child-info) | Represents information about a discovered child in Thread mesh using `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a`. |
| [otMeshDiagDiscoverConfig](https://openthread.io/reference/struct/ot-mesh-diag-discover-config) | Represents the set of configurations used when discovering mesh topology indicating which items to discover. |
| [otMeshDiagRouterInfo](https://openthread.io/reference/struct/ot-mesh-diag-router-info) | Represents information about a router in Thread mesh discovered using `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a`. |
| [otMeshDiagRouterNeighborEntry](https://openthread.io/reference/struct/ot-mesh-diag-router-neighbor-entry) | Represents information about a router neighbor entry from `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad7ccd5df782c0ae1f3cd58fc358fb567`. |

## Typedefs

### otMeshDiagChildEntry

```
struct otMeshDiagChildEntry otMeshDiagChildEntry
```
Represents information about a child entry from `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga18ee2865034a08f2c48ecd8a8060347d`.

`mSupportsErrRate` indicates whether or not the error tracking feature is supported and `mFrameErrorRate` and `mMessageErrorRate` values are valid. The frame error rate tracks frame tx errors (towards the child) at MAC layer, while `mMessageErrorRate` tracks the IPv6 message error rate (above MAC layer and after MAC retries) when an IPv6 message is dropped. For example, if the message is large and requires 6LoWPAN fragmentation, message tx is considered as failed if one of its fragment frame tx fails (for example, never acked).

### otMeshDiagChildInfo

```
struct otMeshDiagChildInfo otMeshDiagChildInfo
```
Represents information about a discovered child in Thread mesh using `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a`.

### otMeshDiagChildIp6AddrsCallback

```
void(* otMeshDiagChildIp6AddrsCallback)(otError aError, uint16_t aChildRloc16, otMeshDiagIp6AddrIterator *aIp6AddrIterator, void *aContext)
```
Represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga0d1abaad22e01b6c1c59337e6b7c322b` to provide information about an MTD child and its list of IPv6 addresses.

When `aError` is `OT_ERROR_PENDING`, it indicates that there are more children and the callback will be invoked again.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | OT_ERROR_PENDING Indicates there are more children in the table. OT_ERROR_NONE Indicates the table is finished. OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. | | `[in] aChildRloc16` | The RLOC16 of the child. `0xfffe` is used on `OT_ERROR_RESPONSE_TIMEOUT`. | | `[in] aIp6AddrIterator` | An iterator to go through the IPv6 addresses of the child with `aRloc` using `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga3a629de56049a929d6e43ea35fdc2fe7`. Set to NULL on `OT_ERROR_RESPONSE_TIMEOUT`. | | `[in] aContext` | Application-specific context. | |

### otMeshDiagChildIterator

```
struct otMeshDiagChildIterator otMeshDiagChildIterator
```
An opaque iterator to iterate over list of children of a router.

Pointers to instance of this type are provided in `https://openthread.io/reference/struct/ot-mesh-diag-router-info`.

### otMeshDiagDiscoverCallback

```
void(* otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext)
```
Pointer type represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a` to provide information about a discovered router.

When `aError` is `OT_ERROR_PENDING`, it indicates that the discovery is not yet finished and there will be more routers to discover and the callback will be invoked again.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | OT_ERROR_PENDING Indicates there are more routers to be discovered. OT_ERROR_NONE Indicates this is the last router and mesh discovery is done. OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response from one or more routers. | | `[in] aRouterInfo` | The discovered router info (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT). | | `[in] aContext` | Application-specific context. | |

### otMeshDiagDiscoverConfig

```
struct otMeshDiagDiscoverConfig otMeshDiagDiscoverConfig
```
Represents the set of configurations used when discovering mesh topology indicating which items to discover.

The `mExtraTlvTypes` pointer can be NULL if `mExtraTlvTypesLength` is zero.

### otMeshDiagIp6AddrIterator

```
struct otMeshDiagIp6AddrIterator otMeshDiagIp6AddrIterator
```
An opaque iterator to iterate over list of IPv6 addresses of a router.

Pointers to instance of this type are provided in `https://openthread.io/reference/struct/ot-mesh-diag-router-info`.

### otMeshDiagQueryChildTableCallback

```
void(* otMeshDiagQueryChildTableCallback)(otError aError, const otMeshDiagChildEntry *aChildEntry, void *aContext)
```
Represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga18ee2865034a08f2c48ecd8a8060347d` to provide information about child table entries.

When `aError` is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be invoked again.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | OT_ERROR_PENDING Indicates there are more entries in the table. OT_ERROR_NONE Indicates the table is finished. OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. | | `[in] aChildEntry` | The child entry (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT or OT_ERROR_NONE). | | `[in] aContext` | Application-specific context. | |

### otMeshDiagQueryRouterNeighborTableCallback

```
void(* otMeshDiagQueryRouterNeighborTableCallback)(otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext)
```
Represents the callback used by `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad7ccd5df782c0ae1f3cd58fc358fb567` to provide information about neighbor router table entries.

When `aError` is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be invoked again.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | OT_ERROR_PENDING Indicates there are more entries in the table. OT_ERROR_NONE Indicates the table is finished. OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. | | `[in] aNeighborEntry` | The neighbor entry (can be null if `aError` is RESPONSE_TIMEOUT or NONE). | | `[in] aContext` | Application-specific context. | |

### otMeshDiagRouterInfo

```
struct otMeshDiagRouterInfo otMeshDiagRouterInfo
```
Represents information about a router in Thread mesh discovered using `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a`.

### otMeshDiagRouterNeighborEntry

```
struct otMeshDiagRouterNeighborEntry otMeshDiagRouterNeighborEntry
```
Represents information about a router neighbor entry from `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad7ccd5df782c0ae1f3cd58fc358fb567`.

`mSupportsErrRate` indicates whether or not the error tracking feature is supported and `mFrameErrorRate` and `mMessageErrorRate` values are valid. The frame error rate tracks frame tx errors (towards the child) at MAC layer, while `mMessageErrorRate` tracks the IPv6 message error rate (above MAC layer and after MAC retries) when an IPv6 message is dropped. For example, if the message is large and requires 6LoWPAN fragmentation, message tx is considered as failed if one of its fragment frame tx fails (for example, never acked).

### otMeshDiagTlvInfo

```
otNetworkDiagTlv otMeshDiagTlvInfo
```
Represents information about a parsed Network Diagnostic TLV.

### otMeshDiagTlvIterator

```
struct otMeshDiagTlvIterator otMeshDiagTlvIterator
```
An opaque iterator to iterate over the list of extra Network Diagnostic TLVs returned by a router.

Pointers to instances of this type are provided in `https://openthread.io/reference/struct/ot-mesh-diag-router-info`.

## Functions

### otMeshDiagCancel

```
void otMeshDiagCancel(
  otInstance *aInstance
)
```
Cancels an ongoing topology discovery if there is one, otherwise no action.

When ongoing discovery is cancelled, the callback from `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga5a11838d4525fd78682d462c2cbbae7a` will not be called anymore.

### otMeshDiagDiscoverTopology

```
otError otMeshDiagDiscoverTopology(
  otInstance *aInstance,
  const otMeshDiagDiscoverConfig *aConfig,
  otMeshDiagDiscoverCallback aCallback,
  void *aContext
)
```
Starts network topology discovery.

This function initiates a query to discover routers in the Thread network.

The `aConfig` configuration controls what optional topology information is discovered:

- If `mDiscoverIp6Addresses` is set to true, the list of IPv6 addresses for each router is discovered.
- If `mDiscoverChildTable` is set to true, the list of children for each router is discovered.

<br />

The `aConfig` parameter can be used to request additional standard Network Diagnostic TLVs to be retrieved from each discovered router during topology discovery. These extra TLVs can then be accessed via the `mTlvIterator` in the callback's router info.

The following restrictions and recommendations apply to the use of `mExtraTlvTypes`:

- It MUST NOT contain any of the TLV types that are already requested by the discovery process itself. These are:
  - `OT_NETWORK_DIAGNOSTIC_TLV_SHORT_ADDRESS`
  - `OT_NETWORK_DIAGNOSTIC_TLV_EXT_ADDRESS`
  - `OT_NETWORK_DIAGNOSTIC_TLV_ROUTE`
  - `OT_NETWORK_DIAGNOSTIC_TLV_VERSION`
  - `OT_NETWORK_DIAGNOSTIC_TLV_IP6_ADDR_LIST`
  - `OT_NETWORK_DIAGNOSTIC_TLV_CHILD_TABLE` If any of these types are included in `aConfig.mExtraTlvTypes`, `OT_ERROR_INVALID_ARGS` is returned.
- The total number of requested TLV types is limited to 32. This limit applies to all TLV types combined, including those automatically added by the discovery process and any additional TLVs specified by the caller in `mExtraTlvTypes`. If the total count exceeds this limit, `OT_ERROR_NO_BUFS` is returned.
- It is highly recommended to keep the number of additional TLVs small. Requesting many or large TLVs increases the size of the Network Diagnostics responses, which can cause message fragmentation, higher network traffic, or response packet drops.
- Additional TLVs should be restricted to small metadata elements useful during topology discovery (for example, `OT_NETWORK_DIAGNOSTIC_TLV_VENDOR_NAME`, `OT_NETWORK_DIAGNOSTIC_TLV_VENDOR_MODEL`, etc). For retrieving larger information (like counters, etc.), separate individual queries should be sent to specific nodes instead of using this method.
- The `aConfig` struct and the memory pointed to by its `mExtraTlvTypes` array do not need to persist beyond the call to this function.

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aConfig` | The configuration to use for discovery (e.g., which items to discover). | | `[in] aCallback` | The callback to report the discovered routers. | | `[in] aContext` | A context to pass in `aCallback`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The network topology discovery started successfully. | | `OT_ERROR_BUSY` | A previous discovery request is still ongoing. | | `OT_ERROR_INVALID_STATE` | Device is not attached. | | `OT_ERROR_NO_BUFS` | Could not allocate buffer to send discovery messages or too many extra TLVs. | | `OT_ERROR_INVALID_ARGS` | Invalid `aConfig` (e.g., includes restricted extra TLVs as listed above). | |

### otMeshDiagGetNextChildInfo

```
otError otMeshDiagGetNextChildInfo(
  otMeshDiagChildIterator *aIterator,
  otMeshDiagChildInfo *aChildInfo
)
```
Iterates through the discovered children of a router.

This function MUST be used from the callback `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga82a5a4bca9a0ff7797b9feecd5427b5f` and use the `mChildIterator` from the `aRouterInfo` struct that is provided as input to the callback.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in,out] aIterator` | The address iterator to use. | | `[out] aChildInfo` | A pointer to return the child info (if any). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully retrieved the next child. `aChildInfo` and `aIterator` are updated. | | `OT_ERROR_NOT_FOUND` | No more child. Reached the end of the list. | |

### otMeshDiagGetNextIp6Address

```
otError otMeshDiagGetNextIp6Address(
  otMeshDiagIp6AddrIterator *aIterator,
  otIp6Address *aIp6Address
)
```
Iterates through the discovered IPv6 addresses of a router or an MTD child.

MUST be used

- from the callback `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga82a5a4bca9a0ff7797b9feecd5427b5f` and use the `mIp6AddrIterator` from the `aRouterInfo` struct that is provided as input to the callback, or
- from the callback `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1gad760dc8af01b6a832e46cf81f09195a0` along with provided `aIp6AddrIterator`.

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in,out] aIterator` | The address iterator to use. | | `[out] aIp6Address` | A pointer to return the next IPv6 address (if any). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully retrieved the next address. `aIp6Address` and `aIterator` are updated. | | `OT_ERROR_NOT_FOUND` | No more address. Reached the end of the list. | |

### otMeshDiagGetNextTlvInfo

```
otError otMeshDiagGetNextTlvInfo(
  otMeshDiagTlvIterator *aIterator,
  otMeshDiagTlvInfo *aTlvInfo
)
```
Iterates through the discovered extra Network Diagnostic TLVs of a router.

This function MUST be used from the callback `https://openthread.io/reference/group/api-mesh-diag#group__api-mesh-diag_1ga82a5a4bca9a0ff7797b9feecd5427b5f` and use the `mTlvIterator` from the `aRouterInfo` struct that is provided as input to the callback.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in,out] aIterator` | The TLV iterator to use. | | `[out] aTlvInfo` | A pointer to return the extra TLV info (if any). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully retrieved the next extra TLV. `aTlvInfo` and `aIterator` are updated. | | `OT_ERROR_NOT_FOUND` | No more extra TLVs. Reached the end of the list. | |

### otMeshDiagGetResponseTimeout

```
uint32_t otMeshDiagGetResponseTimeout(
  otInstance *aInstance
)
```
Gets the response timeout value.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The response timeout interval in milliseconds. |

### otMeshDiagQueryChildTable

```
otError otMeshDiagQueryChildTable(
  otInstance *aInstance,
  uint16_t aRloc16,
  otMeshDiagQueryChildTableCallback aCallback,
  void *aContext
)
```
Starts query for child table for a given router.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aRloc16` | The RLOC16 of router to query. | | `[in] aCallback` | The callback to report the queried child table. | | `[in] aContext` | A context to pass in `aCallback`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The query started successfully. | | `OT_ERROR_BUSY` | A previous discovery or query request is still ongoing. | | `OT_ERROR_INVALID_ARGS` | The `aRloc16` is not a valid router RLOC16. | | `OT_ERROR_INVALID_STATE` | Device is not attached. | | `OT_ERROR_NO_BUFS` | Could not allocate buffer to send query messages. | |

### otMeshDiagQueryChildrenIp6Addrs

```
otError otMeshDiagQueryChildrenIp6Addrs(
  otInstance *aInstance,
  uint16_t aRloc16,
  otMeshDiagChildIp6AddrsCallback aCallback,
  void *aContext
)
```
Sends a query to a parent to retrieve the IPv6 addresses of all its MTD children.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aRloc16` | The RLOC16 of parent to query. | | `[in] aCallback` | The callback to report the queried child IPv6 address list. | | `[in] aContext` | A context to pass in `aCallback`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The query started successfully. | | `OT_ERROR_BUSY` | A previous discovery or query request is still ongoing. | | `OT_ERROR_INVALID_ARGS` | The `aRloc16` is not a valid RLOC16. | | `OT_ERROR_INVALID_STATE` | Device is not attached. | | `OT_ERROR_NO_BUFS` | Could not allocate buffer to send query messages. | |

### otMeshDiagQueryRouterNeighborTable

```
otError otMeshDiagQueryRouterNeighborTable(
  otInstance *aInstance,
  uint16_t aRloc16,
  otMeshDiagQueryRouterNeighborTableCallback aCallback,
  void *aContext
)
```
Starts query for router neighbor table for a given router.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aRloc16` | The RLOC16 of router to query. | | `[in] aCallback` | The callback to report the queried table. | | `[in] aContext` | A context to pass in `aCallback`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The query started successfully. | | `OT_ERROR_BUSY` | A previous discovery or query request is still ongoing. | | `OT_ERROR_INVALID_ARGS` | The `aRloc16` is not a valid router RLOC16. | | `OT_ERROR_INVALID_STATE` | Device is not attached. | | `OT_ERROR_NO_BUFS` | Could not allocate buffer to send query messages. | |

### otMeshDiagSetResponseTimeout

```
void otMeshDiagSetResponseTimeout(
  otInstance *aInstance,
  uint32_t aTimeout
)
```
Sets the response timeout value to use for any future mesh diagnostic queries.

The default response timeout value is specified by `OPENTHREAD_CONFIG_MESH_DIAG_RESPONSE_TIMEOUT` configuration.

Changing the response timeout does not impact any ongoing query.

The provided `aTimeout` value will be clamped to stay between 50 milliseconds and 10 minutes.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aTimeout` | The timeout interval in milliseconds. | |

## Macros

### OT_MESH_DIAG_VERSION_UNKNOWN

```
 OT_MESH_DIAG_VERSION_UNKNOWN 0xffff
```
Specifies that Thread Version is unknown.

This is used in `https://openthread.io/reference/struct/ot-mesh-diag-router-info` for `mVersion` property when device does not provide its version. This indicates that device is likely running 1.3.0 (version value 4) or earlier.

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