Mesh Diagnostics#

This module includes definitions and functions for Mesh Diagnostics.

The Mesh Diagnostics APIs require OPENTHREAD_CONFIG_MESH_DIAG_ENABLE and OPENTHREAD_FTD.

Modules#

otMeshDiagDiscoverConfig

otMeshDiagRouterInfo

otMeshDiagChildInfo

otMeshDiagChildEntry

otMeshDiagRouterNeighborEntry

Typedefs#

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

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

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

typedef struct otMeshDiagRouterInfo

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

typedef struct otMeshDiagChildInfo

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

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

Pointer type represents the callback used by otMeshDiagDiscoverTopology() to provide information about a discovered router.

typedef struct otMeshDiagChildEntry

Represents information about a child entry from otMeshDiagQueryChildTable().

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

Represents the callback used by otMeshDiagQueryChildTable() to provide information about child table entries.

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

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

typedef void(*
otMeshDiagQueryRouterNeighborTableCallback)(otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext)

Represents the callback used by otMeshDiagQueryRouterNeighborTable() to provide information about neighbor router table entries.

Functions#

otMeshDiagDiscoverTopology(otInstance *aInstance, const otMeshDiagDiscoverConfig *aConfig, otMeshDiagDiscoverCallback aCallback, void *aContext)

Starts network topology discovery.

void
otMeshDiagCancel(otInstance *aInstance)

Cancels an ongoing topology discovery if there is one, otherwise no action.

otMeshDiagGetNextIp6Address(otMeshDiagIp6AddrIterator *aIterator, otIp6Address *aIp6Address)

Iterates through the discovered IPv6 addresses of a router or an MTD child.

otMeshDiagGetNextChildInfo(otMeshDiagChildIterator *aIterator, otMeshDiagChildInfo *aChildInfo)

Iterates through the discovered children of a router.

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.

Macros#

#define

Specifies that Thread Version is unknown.

Typedef Documentation#

otMeshDiagDiscoverConfig#

typedef struct otMeshDiagDiscoverConfig otMeshDiagDiscoverConfig

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


Definition at line 64 of file include/openthread/mesh_diag.h

otMeshDiagIp6AddrIterator#

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


Definition at line 71 of file include/openthread/mesh_diag.h

otMeshDiagChildIterator#

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


Definition at line 78 of file include/openthread/mesh_diag.h

otMeshDiagRouterInfo#

typedef struct otMeshDiagRouterInfo otMeshDiagRouterInfo

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


Definition at line 133 of file include/openthread/mesh_diag.h

otMeshDiagChildInfo#

typedef struct otMeshDiagChildInfo otMeshDiagChildInfo

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


Definition at line 145 of file include/openthread/mesh_diag.h

otMeshDiagDiscoverCallback#

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

Pointer type represents the callback used by otMeshDiagDiscoverTopology() to provide information about a discovered router.

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.

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.


Definition at line 160 of file include/openthread/mesh_diag.h

otMeshDiagChildEntry#

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


Definition at line 249 of file include/openthread/mesh_diag.h

otMeshDiagQueryChildTableCallback#

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

Represents the callback used by otMeshDiagQueryChildTable() to provide information about child table entries.

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.

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


Definition at line 263 of file include/openthread/mesh_diag.h

otMeshDiagChildIp6AddrsCallback#

typedef void(* otMeshDiagChildIp6AddrsCallback) (otError aError, uint16_t aChildRloc16, otMeshDiagIp6AddrIterator *aIp6AddrIterator, void *aContext) )(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.

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.

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


Definition at line 301 of file include/openthread/mesh_diag.h

otMeshDiagRouterNeighborEntry#

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


Definition at line 346 of file include/openthread/mesh_diag.h

otMeshDiagQueryRouterNeighborTableCallback#

typedef void(* otMeshDiagQueryRouterNeighborTableCallback) (otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext) )(otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext)

Represents the callback used by otMeshDiagQueryRouterNeighborTable() to provide information about neighbor router table entries.

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.

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


Definition at line 361 of file include/openthread/mesh_diag.h

Function Documentation#

otMeshDiagDiscoverTopology#

otError otMeshDiagDiscoverTopology (otInstance * aInstance, const otMeshDiagDiscoverConfig * aConfig, otMeshDiagDiscoverCallback aCallback, void * aContext)

Starts network topology discovery.

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.


Definition at line 175 of file include/openthread/mesh_diag.h

otMeshDiagCancel#

void otMeshDiagCancel (otInstance * aInstance)

Cancels an ongoing topology discovery if there is one, otherwise no action.

Parameters
N/AaInstance

When ongoing discovery is cancelled, the callback from otMeshDiagDiscoverTopology() will not be called anymore.


Definition at line 185 of file include/openthread/mesh_diag.h

otMeshDiagGetNextIp6Address#

otError otMeshDiagGetNextIp6Address (otMeshDiagIp6AddrIterator * aIterator, otIp6Address * aIp6Address)

Iterates through the discovered IPv6 addresses of a router or an MTD child.

Parameters
[inout]aIterator

The address iterator to use.

[out]aIp6Address

A pointer to return the next IPv6 address (if any).

MUST be used

  • from the callback otMeshDiagDiscoverCallback() and use the mIp6AddrIterator from the aRouterInfo struct that is provided as input to the callback, or

  • from the callback otMeshDiagChildIp6AddrsCallback() along with provided aIp6AddrIterator.


Definition at line 201 of file include/openthread/mesh_diag.h

otMeshDiagGetNextChildInfo#

otError otMeshDiagGetNextChildInfo (otMeshDiagChildIterator * aIterator, otMeshDiagChildInfo * aChildInfo)

Iterates through the discovered children of a router.

Parameters
[inout]aIterator

The address iterator to use.

[out]aChildInfo

A pointer to return the child info (if any).

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.


Definition at line 215 of file include/openthread/mesh_diag.h

otMeshDiagQueryChildTable#

otError otMeshDiagQueryChildTable (otInstance * aInstance, uint16_t aRloc16, otMeshDiagQueryChildTableCallback aCallback, void * aContext)

Starts query for child table for a given router.

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.


Definition at line 281 of file include/openthread/mesh_diag.h

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.

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.


Definition at line 320 of file include/openthread/mesh_diag.h

otMeshDiagQueryRouterNeighborTable#

otError otMeshDiagQueryRouterNeighborTable (otInstance * aInstance, uint16_t aRloc16, otMeshDiagQueryRouterNeighborTableCallback aCallback, void * aContext)

Starts query for router neighbor table for a given router.

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.


Definition at line 379 of file include/openthread/mesh_diag.h

Macro Definition Documentation#

OT_MESH_DIAG_VERSION_UNKNOWN#

#define OT_MESH_DIAG_VERSION_UNKNOWN
Value:
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.


Definition at line 86 of file include/openthread/mesh_diag.h