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 `struct otMeshDiagChildEntry` Represents information about a child entry from `otMeshDiagQueryChildTable()`.
`otMeshDiagChildInfo`	typedef `struct otMeshDiagChildInfo` 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 `struct otMeshDiagChildIterator` 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 `struct otMeshDiagDiscoverConfig` Represents the set of configurations used when discovering mesh topology indicating which items to discover.
`otMeshDiagIp6AddrIterator`	typedef `struct otMeshDiagIp6AddrIterator` 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 `struct otMeshDiagRouterInfo` Represents information about a router in Thread mesh discovered using `otMeshDiagDiscoverTopology()`.
`otMeshDiagRouterNeighborEntry`	typedef `struct otMeshDiagRouterNeighborEntry` Represents information about a router neighbor entry from `otMeshDiagQueryRouterNeighborTable()`.

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)`	`otError` Starts network topology discovery.
`otMeshDiagGetNextChildInfo(otMeshDiagChildIterator aIterator, otMeshDiagChildInfo aChildInfo)`	`otError` Iterates through the discovered children of a router.
`otMeshDiagGetNextIp6Address(otMeshDiagIp6AddrIterator aIterator, otIp6Address aIp6Address)`	`otError` Iterates through the discovered IPv6 addresses of a router or an MTD child.
`otMeshDiagQueryChildTable(otInstance aInstance, uint16_t aRloc16, otMeshDiagQueryChildTableCallback aCallback, void aContext)`	`otError` Starts query for child table for a given router.
`otMeshDiagQueryChildrenIp6Addrs(otInstance aInstance, uint16_t aRloc16, otMeshDiagChildIp6AddrsCallback aCallback, void aContext)`	`otError` 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)`	`otError` Starts query for router neighbor table for a given router.

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.

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

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.

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

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.

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.

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.

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.

Mesh Diagnostics

Summary

Typedefs

Functions

Macros

Structs

Typedefs

otMeshDiagChildEntry

otMeshDiagChildInfo

otMeshDiagChildIp6AddrsCallback

otMeshDiagChildIterator

otMeshDiagDiscoverCallback

otMeshDiagDiscoverConfig

otMeshDiagIp6AddrIterator

otMeshDiagQueryChildTableCallback

otMeshDiagQueryRouterNeighborTableCallback

otMeshDiagRouterInfo

otMeshDiagRouterNeighborEntry

Functions

otMeshDiagCancel

otMeshDiagDiscoverTopology

otMeshDiagGetNextChildInfo

otMeshDiagGetNextIp6Address

otMeshDiagQueryChildTable

otMeshDiagQueryChildrenIp6Addrs

otMeshDiagQueryRouterNeighborTable

Macros

OT_MESH_DIAG_VERSION_UNKNOWN

Resources