| /* |
| * Copyright (c) 2023, The OpenThread Authors. |
| * All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions are met: |
| * 1. Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * 2. Redistributions in binary form must reproduce the above copyright |
| * notice, this list of conditions and the following disclaimer in the |
| * documentation and/or other materials provided with the distribution. |
| * 3. Neither the name of the copyright holder nor the |
| * names of its contributors may be used to endorse or promote products |
| * derived from this software without specific prior written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
| * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| * POSSIBILITY OF SUCH DAMAGE. |
| */ |
| |
| /** |
| * @file |
| * @brief |
| * This file defines the OpenThread Mesh Diagnostic APIs. |
| */ |
| |
| #ifndef OPENTHREAD_MESH_DIAG_H_ |
| #define OPENTHREAD_MESH_DIAG_H_ |
| |
| #include <openthread/instance.h> |
| #include <openthread/thread.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @addtogroup api-mesh-diag |
| * |
| * @brief |
| * This module includes definitions and functions for Mesh Diagnostics. |
| * |
| * The Mesh Diagnostics APIs require `OPENTHREAD_CONFIG_MESH_DIAG_ENABLE` and `OPENTHREAD_FTD`. |
| * |
| * @{ |
| * |
| */ |
| |
| /** |
| * Represents the set of configurations used when discovering mesh topology indicating which items to |
| * discover. |
| * |
| */ |
| typedef struct otMeshDiagDiscoverConfig |
| { |
| bool mDiscoverIp6Addresses : 1; ///< Whether or not to discover IPv6 addresses of every router. |
| bool mDiscoverChildTable : 1; ///< Whether or not to discover children of every router. |
| } otMeshDiagDiscoverConfig; |
| |
| /** |
| * An opaque iterator to iterate over list of IPv6 addresses of a router. |
| * |
| * Pointers to instance of this type are provided in `otMeshDiagRouterInfo`. |
| * |
| */ |
| typedef struct otMeshDiagIp6AddrIterator otMeshDiagIp6AddrIterator; |
| |
| /** |
| * An opaque iterator to iterate over list of children of a router. |
| * |
| * Pointers to instance of this type are provided in `otMeshDiagRouterInfo`. |
| * |
| */ |
| typedef struct otMeshDiagChildIterator otMeshDiagChildIterator; |
| |
| /** |
| * 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. |
| * |
| */ |
| #define OT_MESH_DIAG_VERSION_UNKNOWN 0xffff |
| |
| /** |
| * Represents information about a router in Thread mesh discovered using `otMeshDiagDiscoverTopology()`. |
| * |
| */ |
| typedef struct otMeshDiagRouterInfo |
| { |
| otExtAddress mExtAddress; ///< Extended MAC address. |
| uint16_t mRloc16; ///< RLOC16. |
| uint8_t mRouterId; ///< Router ID. |
| uint16_t mVersion; ///< Thread Version. `OT_MESH_DIAG_VERSION_UNKNOWN` if unknown. |
| bool mIsThisDevice : 1; ///< Whether router is this device itself. |
| bool mIsThisDeviceParent : 1; ///< Whether router is parent of this device (when device is a child). |
| bool mIsLeader : 1; ///< Whether router is leader. |
| bool mIsBorderRouter : 1; ///< Whether router acts as a border router providing ext connectivity. |
| |
| /** |
| * Provides the link quality from this router to other routers, also indicating whether a link is established |
| * between the routers. |
| * |
| * The array is indexed based on Router ID. `mLinkQualities[routerId]` indicates the incoming link quality, the |
| * router sees to the router with `routerId`. Link quality is a value in [0, 3]. Value zero indicates no link. |
| * Larger value indicate better link quality (as defined by Thread specification). |
| * |
| */ |
| uint8_t mLinkQualities[OT_NETWORK_MAX_ROUTER_ID + 1]; |
| |
| /** |
| * A pointer to an iterator to go through the list of IPv6 addresses of the router. |
| * |
| * The pointer is valid only while `otMeshDiagRouterInfo` is valid. It can be used in `otMeshDiagGetNextIp6Address` |
| * to iterate through the IPv6 addresses. |
| * |
| * The pointer can be NULL when there was no request to discover IPv6 addresses (in `otMeshDiagDiscoverConfig`) or |
| * if the router did not provide the list. |
| * |
| */ |
| otMeshDiagIp6AddrIterator *mIp6AddrIterator; |
| |
| /** |
| * A pointer to an iterator to go through the list of children of the router. |
| * |
| * The pointer is valid only while `otMeshDiagRouterInfo` is valid. It can be used in `otMeshDiagGetNextChildInfo` |
| * to iterate through the children of the router. |
| * |
| * The pointer can be NULL when there was no request to discover children (in `otMeshDiagDiscoverConfig`) or |
| * if the router did not provide the list. |
| * |
| */ |
| otMeshDiagChildIterator *mChildIterator; |
| } otMeshDiagRouterInfo; |
| |
| /** |
| * Represents information about a discovered child in Thread mesh using `otMeshDiagDiscoverTopology()`. |
| * |
| */ |
| typedef struct otMeshDiagChildInfo |
| { |
| uint16_t mRloc16; ///< RLOC16. |
| otLinkModeConfig mMode; ///< Device mode. |
| uint8_t mLinkQuality; ///< Incoming link quality to child from parent. |
| bool mIsThisDevice : 1; ///< Whether child is this device itself. |
| bool mIsBorderRouter : 1; ///< Whether child acts as a border router providing ext connectivity. |
| } otMeshDiagChildInfo; |
| |
| /** |
| * Pointer type represents the callback used by `otMeshDiagDiscoverTopology()` to provide information |
| * about a discovered router. |
| * |
| * When @p 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. |
| * |
| * @param[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. |
| * @param[in] aRouterInfo The discovered router info (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT). |
| * @param[in] aContext Application-specific context. |
| * |
| */ |
| typedef void (*otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext); |
| |
| /** |
| * Starts network topology discovery. |
| * |
| * @param[in] aInstance The OpenThread instance. |
| * @param[in] aConfig The configuration to use for discovery (e.g., which items to discover). |
| * @param[in] aCallback The callback to report the discovered routers. |
| * @param[in] aContext A context to pass in @p aCallback. |
| * |
| * @retval OT_ERROR_NONE The network topology discovery started successfully. |
| * @retval OT_ERROR_BUSY A previous discovery request is still ongoing. |
| * @retval OT_ERROR_INVALID_STATE Device is not attached. |
| * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send discovery messages. |
| * |
| */ |
| otError otMeshDiagDiscoverTopology(otInstance *aInstance, |
| const otMeshDiagDiscoverConfig *aConfig, |
| otMeshDiagDiscoverCallback aCallback, |
| void *aContext); |
| |
| /** |
| * 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. |
| * |
| */ |
| void otMeshDiagCancel(otInstance *aInstance); |
| |
| /** |
| * 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`. |
| * |
| * @param[in,out] aIterator The address iterator to use. |
| * @param[out] aIp6Address A pointer to return the next IPv6 address (if any). |
| * |
| * @retval OT_ERROR_NONE Successfully retrieved the next address. @p aIp6Address and @p aIterator are updated. |
| * @retval OT_ERROR_NOT_FOUND No more address. Reached the end of the list. |
| * |
| */ |
| otError otMeshDiagGetNextIp6Address(otMeshDiagIp6AddrIterator *aIterator, otIp6Address *aIp6Address); |
| |
| /** |
| * 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. |
| * |
| * @param[in,out] aIterator The address iterator to use. |
| * @param[out] aChildInfo A pointer to return the child info (if any). |
| * |
| * @retval OT_ERROR_NONE Successfully retrieved the next child. @p aChildInfo and @p aIterator are updated. |
| * @retval OT_ERROR_NOT_FOUND No more child. Reached the end of the list. |
| * |
| */ |
| otError otMeshDiagGetNextChildInfo(otMeshDiagChildIterator *aIterator, otMeshDiagChildInfo *aChildInfo); |
| |
| /** |
| * 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). |
| * |
| */ |
| typedef struct otMeshDiagChildEntry |
| { |
| bool mRxOnWhenIdle : 1; ///< Is rx-on when idle (vs sleepy). |
| bool mDeviceTypeFtd : 1; ///< Is device FTD (vs MTD). |
| bool mFullNetData : 1; ///< Whether device gets full Network Data (vs stable sub-set). |
| bool mCslSynchronized : 1; ///< Is CSL capable and CSL synchronized. |
| bool mSupportsErrRate : 1; ///< `mFrameErrorRate` and `mMessageErrorRate` values are valid. |
| uint16_t mRloc16; ///< RLOC16. |
| otExtAddress mExtAddress; ///< Extended Address. |
| uint16_t mVersion; ///< Version. |
| uint32_t mTimeout; ///< Timeout in seconds. |
| uint32_t mAge; ///< Seconds since last heard from the child. |
| uint32_t mConnectionTime; ///< Seconds since child attach. |
| uint16_t mSupervisionInterval; ///< Supervision interval in seconds. Zero to indicate not used. |
| uint8_t mLinkMargin; ///< Link Margin in dB. |
| int8_t mAverageRssi; ///< Average RSSI. |
| int8_t mLastRssi; ///< RSSI of last received frame. |
| uint16_t mFrameErrorRate; ///< Frame error rate (0x0000->0%, 0xffff->100%). |
| uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0x0000->0%, 0xffff->100%). |
| uint16_t mQueuedMessageCount; ///< Number of queued messages for indirect tx to child. |
| uint16_t mCslPeriod; ///< CSL Period in unit of 10-symbols-time. Zero indicates CSL is disabled. |
| uint32_t mCslTimeout; ///< CSL Timeout in seconds. |
| uint8_t mCslChannel; ///< CSL channel. |
| } otMeshDiagChildEntry; |
| |
| /** |
| * Represents the callback used by `otMeshDiagQueryChildTable()` to provide information about child table entries. |
| * |
| * When @p aError is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be |
| * invoked again. |
| * |
| * @param[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. |
| * @param[in] aChildEntry The child entry (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT or OT_ERROR_NONE). |
| * @param[in] aContext Application-specific context. |
| * |
| */ |
| typedef void (*otMeshDiagQueryChildTableCallback)(otError aError, |
| const otMeshDiagChildEntry *aChildEntry, |
| void *aContext); |
| |
| /** |
| * Starts query for child table for a given router. |
| * |
| * @param[in] aInstance The OpenThread instance. |
| * @param[in] aRloc16 The RLOC16 of router to query. |
| * @param[in] aCallback The callback to report the queried child table. |
| * @param[in] aContext A context to pass in @p aCallback. |
| * |
| * @retval OT_ERROR_NONE The query started successfully. |
| * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. |
| * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid router RLOC16. |
| * @retval OT_ERROR_INVALID_STATE Device is not attached. |
| * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. |
| * |
| */ |
| otError otMeshDiagQueryChildTable(otInstance *aInstance, |
| uint16_t aRloc16, |
| otMeshDiagQueryChildTableCallback aCallback, |
| void *aContext); |
| |
| /** |
| * Represents the callback used by `otMeshDiagQueryChildrenIp6Addrs()` to provide information about an MTD child and |
| * its list of IPv6 addresses. |
| * |
| * When @p aError is `OT_ERROR_PENDING`, it indicates that there are more children and the callback will be invoked |
| * again. |
| * |
| * @param[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. |
| * @param[in] aChildRloc16 The RLOC16 of the child. `0xfffe` is used on `OT_ERROR_RESPONSE_TIMEOUT`. |
| * @param[in] aIp6AddrIterator An iterator to go through the IPv6 addresses of the child with @p aRloc using |
| * `otMeshDiagGetNextIp6Address()`. Set to NULL on `OT_ERROR_RESPONSE_TIMEOUT`. |
| * @param[in] aContext Application-specific context. |
| * |
| */ |
| typedef void (*otMeshDiagChildIp6AddrsCallback)(otError aError, |
| uint16_t aChildRloc16, |
| otMeshDiagIp6AddrIterator *aIp6AddrIterator, |
| void *aContext); |
| |
| /** |
| * Sends a query to a parent to retrieve the IPv6 addresses of all its MTD children. |
| * |
| * @param[in] aInstance The OpenThread instance. |
| * @param[in] aRloc16 The RLOC16 of parent to query. |
| * @param[in] aCallback The callback to report the queried child IPv6 address list. |
| * @param[in] aContext A context to pass in @p aCallback. |
| * |
| * @retval OT_ERROR_NONE The query started successfully. |
| * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. |
| * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid RLOC16. |
| * @retval OT_ERROR_INVALID_STATE Device is not attached. |
| * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. |
| * |
| */ |
| otError otMeshDiagQueryChildrenIp6Addrs(otInstance *aInstance, |
| uint16_t aRloc16, |
| otMeshDiagChildIp6AddrsCallback aCallback, |
| void *aContext); |
| |
| /** |
| * 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). |
| * |
| */ |
| typedef struct otMeshDiagRouterNeighborEntry |
| { |
| bool mSupportsErrRate : 1; ///< `mFrameErrorRate` and `mMessageErrorRate` values are valid. |
| uint16_t mRloc16; ///< RLOC16. |
| otExtAddress mExtAddress; ///< Extended Address. |
| uint16_t mVersion; ///< Version. |
| uint32_t mConnectionTime; ///< Seconds since link establishment. |
| uint8_t mLinkMargin; ///< Link Margin in dB. |
| int8_t mAverageRssi; ///< Average RSSI. |
| int8_t mLastRssi; ///< RSSI of last received frame. |
| uint16_t mFrameErrorRate; ///< Frame error rate (0x0000->0%, 0xffff->100%). |
| uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0x0000->0%, 0xffff->100%). |
| } otMeshDiagRouterNeighborEntry; |
| |
| /** |
| * Represents the callback used by `otMeshDiagQueryRouterNeighborTable()` to provide information about neighbor router |
| * table entries. |
| * |
| * When @p aError is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be |
| * invoked again. |
| * |
| * @param[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. |
| * @param[in] aNeighborEntry The neighbor entry (can be null if `aError` is RESPONSE_TIMEOUT or NONE). |
| * @param[in] aContext Application-specific context. |
| * |
| */ |
| typedef void (*otMeshDiagQueryRouterNeighborTableCallback)(otError aError, |
| const otMeshDiagRouterNeighborEntry *aNeighborEntry, |
| void *aContext); |
| |
| /** |
| * Starts query for router neighbor table for a given router. |
| * |
| * @param[in] aInstance The OpenThread instance. |
| * @param[in] aRloc16 The RLOC16 of router to query. |
| * @param[in] aCallback The callback to report the queried table. |
| * @param[in] aContext A context to pass in @p aCallback. |
| * |
| * @retval OT_ERROR_NONE The query started successfully. |
| * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. |
| * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid router RLOC16. |
| * @retval OT_ERROR_INVALID_STATE Device is not attached. |
| * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. |
| * |
| */ |
| otError otMeshDiagQueryRouterNeighborTable(otInstance *aInstance, |
| uint16_t aRloc16, |
| otMeshDiagQueryRouterNeighborTableCallback aCallback, |
| void *aContext); |
| |
| /** |
| * @} |
| * |
| */ |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // OPENTHREAD_MESH_DIAG_H_ |
