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
otMeshDiagChildEntry typedef
Represents information about a child entry from otMeshDiagQueryChildTable().
otMeshDiagChildInfo typedef
Represents information about a discovered child in Thread mesh using otMeshDiagDiscoverTopology().
otMeshDiagChildIp6AddrsCallback)(otError aError, uint16_t aChildRloc16, otMeshDiagIp6AddrIterator *aIp6AddrIterator, void *aContext) typedef
void(*
Represents the callback used by otMeshDiagQueryChildrenIp6Addrs() to provide information about an MTD child and its list of IPv6 addresses.
otMeshDiagChildIterator typedef
An opaque iterator to iterate over list of children of a router.
otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext) typedef
void(*
Pointer type represents the callback used by otMeshDiagDiscoverTopology() to provide information about a discovered router.
otMeshDiagDiscoverConfig typedef
Represents the set of configurations used when discovering mesh topology indicating which items to discover.
otMeshDiagIp6AddrIterator typedef
An opaque iterator to iterate over list of IPv6 addresses of a router.
otMeshDiagQueryChildTableCallback)(otError aError, const otMeshDiagChildEntry *aChildEntry, void *aContext) typedef
void(*
Represents the callback used by otMeshDiagQueryChildTable() to provide information about child table entries.
otMeshDiagQueryRouterNeighborTableCallback)(otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext) typedef
void(*
Represents the callback used by otMeshDiagQueryRouterNeighborTable() to provide information about neighbor router table entries.
otMeshDiagRouterInfo typedef
Represents information about a router in Thread mesh discovered using otMeshDiagDiscoverTopology().
otMeshDiagRouterNeighborEntry typedef
Represents information about a router neighbor entry from otMeshDiagQueryRouterNeighborTable().
otMeshDiagTlvInfo typedef
Represents information about a parsed Network Diagnostic TLV.
otMeshDiagTlvIterator typedef
An opaque iterator to iterate over the list of extra Network Diagnostic TLVs returned by a router.

Functions
otMeshDiagCancel(otInstance *aInstance)
void
Cancels an ongoing topology discovery if there is one, otherwise no action.
otMeshDiagDiscoverTopology(otInstance *aInstance, const otMeshDiagDiscoverConfig *aConfig, otMeshDiagDiscoverCallback aCallback, void *aContext)
Starts network topology discovery.
otMeshDiagGetNextChildInfo(otMeshDiagChildIterator *aIterator, otMeshDiagChildInfo *aChildInfo)
Iterates through the discovered children of a router.
otMeshDiagGetNextIp6Address(otMeshDiagIp6AddrIterator *aIterator, otIp6Address *aIp6Address)
Iterates through the discovered IPv6 addresses of a router or an MTD child.
otMeshDiagGetNextTlvInfo(otMeshDiagTlvIterator *aIterator, otMeshDiagTlvInfo *aTlvInfo)
Iterates through the discovered extra Network Diagnostic TLVs of a router.
otMeshDiagGetResponseTimeout(otInstance *aInstance)
uint32_t
Gets the response timeout value.
otMeshDiagQueryChildTable(otInstance *aInstance, uint16_t aRloc16, otMeshDiagQueryChildTableCallback aCallback, void *aContext)
Starts query for child table for a given router.
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.
otMeshDiagQueryRouterNeighborTable(otInstance *aInstance, uint16_t aRloc16, otMeshDiagQueryRouterNeighborTableCallback aCallback, void *aContext)
Starts query for router neighbor table for a given router.
otMeshDiagSetResponseTimeout(otInstance *aInstance, uint32_t aTimeout)
void
Sets the response timeout value to use for any future mesh diagnostic queries.

Macros
OT_MESH_DIAG_VERSION_UNKNOWN 0xffff
Specifies that Thread Version is unknown.

Structs
otMeshDiagChildEntry

Represents information about a child entry from otMeshDiagQueryChildTable().

otMeshDiagChildInfo

Represents information about a discovered child in Thread mesh using otMeshDiagDiscoverTopology().

otMeshDiagDiscoverConfig

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

otMeshDiagRouterInfo

Represents information about a router in Thread mesh discovered using otMeshDiagDiscoverTopology().

otMeshDiagRouterNeighborEntry

Represents information about a router neighbor entry from otMeshDiagQueryRouterNeighborTable().

Typedefs

otMeshDiagChildEntry

struct otMeshDiagChildEntry otMeshDiagChildEntry

Represents information about a child entry from otMeshDiagQueryChildTable().

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 otMeshDiagDiscoverTopology().

otMeshDiagChildIp6AddrsCallback

void(* otMeshDiagChildIp6AddrsCallback)(otError aError, uint16_t aChildRloc16, otMeshDiagIp6AddrIterator *aIp6AddrIterator, void *aContext)

Represents the callback used by otMeshDiagQueryChildrenIp6Addrs() 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.

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 otMeshDiagGetNextIp6Address(). 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 otMeshDiagRouterInfo.

otMeshDiagDiscoverCallback

void(* otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext)

Pointer type represents the callback used by otMeshDiagDiscoverTopology() 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.

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

otMeshDiagQueryChildTableCallback

void(* otMeshDiagQueryChildTableCallback)(otError aError, const otMeshDiagChildEntry *aChildEntry, void *aContext)

Represents the callback used by otMeshDiagQueryChildTable() 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.

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 otMeshDiagQueryRouterNeighborTable() 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.

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 otMeshDiagDiscoverTopology().

otMeshDiagRouterNeighborEntry

struct otMeshDiagRouterNeighborEntry otMeshDiagRouterNeighborEntry

Represents information about a router neighbor entry from otMeshDiagQueryRouterNeighborTable().

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

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 otMeshDiagDiscoverTopology() 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.

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.

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 otMeshDiagDiscoverCallback() and use the mChildIterator from the aRouterInfo struct that is provided as input to the callback.

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

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 otMeshDiagDiscoverCallback() and use the mTlvIterator from the aRouterInfo struct that is provided as input to the callback.

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.

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.

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.

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.

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.

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 otMeshDiagRouterInfo 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. For more information, or to contribute to our documentation, refer to Resources.