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#
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.
Represents information about a router in Thread mesh discovered using otMeshDiagDiscoverTopology()
.
Represents information about a discovered child in Thread mesh using otMeshDiagDiscoverTopology()
.
Pointer type represents the callback used by otMeshDiagDiscoverTopology()
to provide information about a discovered router.
Represents information about a child entry from otMeshDiagQueryChildTable()
.
Represents the callback used by otMeshDiagQueryChildTable()
to provide information about child table entries.
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()
.
Represents the callback used by otMeshDiagQueryRouterNeighborTable()
to provide information about neighbor router table entries.
Functions#
Starts network topology discovery.
Cancels an ongoing topology discovery if there is one, otherwise no action.
Iterates through the discovered IPv6 addresses of a router or an MTD child.
Iterates through the discovered children of a router.
Starts query for child table for a given router.
Sends a query to a parent to retrieve the IPv6 addresses of all its MTD children.
Starts query for router neighbor table for a given router.
Macros#
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.
66
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
.
74
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
.
82
of file include/openthread/mesh_diag.h
otMeshDiagRouterInfo#
typedef struct otMeshDiagRouterInfo otMeshDiagRouterInfo
Represents information about a router in Thread mesh discovered using otMeshDiagDiscoverTopology()
.
142
of file include/openthread/mesh_diag.h
otMeshDiagChildInfo#
typedef struct otMeshDiagChildInfo otMeshDiagChildInfo
Represents information about a discovered child in Thread mesh using otMeshDiagDiscoverTopology()
.
155
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.
[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 |
[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.
171
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).
265
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.
[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 |
[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.
280
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.
[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. |
[in] | aIp6AddrIterator | An iterator to go through the IPv6 addresses of the child with |
[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.
320
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).
367
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.
[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 |
[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.
383
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.
[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 |
187
of file include/openthread/mesh_diag.h
otMeshDiagCancel#
void otMeshDiagCancel (otInstance * aInstance)
Cancels an ongoing topology discovery if there is one, otherwise no action.
N/A | aInstance |
When ongoing discovery is cancelled, the callback from otMeshDiagDiscoverTopology()
will not be called anymore.
198
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.
[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 themIp6AddrIterator
from theaRouterInfo
struct that is provided as input to the callback, orfrom the callback
otMeshDiagChildIp6AddrsCallback()
along with providedaIp6AddrIterator
.
215
of file include/openthread/mesh_diag.h
otMeshDiagGetNextChildInfo#
otError otMeshDiagGetNextChildInfo (otMeshDiagChildIterator * aIterator, otMeshDiagChildInfo * aChildInfo)
Iterates through the discovered children of a router.
[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.
230
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.
[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 |
299
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.
[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 |
340
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.
[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 |
402
of file include/openthread/mesh_diag.h
Macro Definition Documentation#
OT_MESH_DIAG_VERSION_UNKNOWN#
#define OT_MESH_DIAG_VERSION_UNKNOWNValue:
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.
91
of file include/openthread/mesh_diag.h