/* * 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 #include #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_