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
otMeshDiagChildInfo typedef
Represents information about a discovered child in Thread mesh.
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.
otMeshDiagRouterInfo typedef
Represents information about a router in Thread mesh.

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 address of a router.

Macros
OT_MESH_DIAG_VERSION_UNKNOWN 0xffff
This constant indicates that Thread Version is unknown.

Structs
otMeshDiagChildInfo

Represents information about a discovered child in Thread mesh.

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.

Typedefs

otMeshDiagChildInfo

struct otMeshDiagChildInfo otMeshDiagChildInfo

Represents information about a discovered child in Thread mesh.

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.

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.

otMeshDiagRouterInfo

struct otMeshDiagRouterInfo otMeshDiagRouterInfo

Represents information about a router in Thread mesh.

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.

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.

otMeshDiagGetNextChildInfo

otError otMeshDiagGetNextChildInfo(
  otMeshDiagChildIterator *aIterator,
  otMeshDiagChildInfo *aChildInfo
)

Iterates through the discovered children of a router.

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 address of a router.

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.

Macros

OT_MESH_DIAG_VERSION_UNKNOWN

 OT_MESH_DIAG_VERSION_UNKNOWN 0xffff

This constant indicates 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.