1 /* 2 * Copyright (c) 2023, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the OpenThread Mesh Diagnostic APIs. 33 */ 34 35 #ifndef OPENTHREAD_MESH_DIAG_H_ 36 #define OPENTHREAD_MESH_DIAG_H_ 37 38 #include <openthread/instance.h> 39 #include <openthread/thread.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-mesh-diag 47 * 48 * @brief 49 * This module includes definitions and functions for Mesh Diagnostics. 50 * 51 * The Mesh Diagnostics APIs require `OPENTHREAD_CONFIG_MESH_DIAG_ENABLE` and `OPENTHREAD_FTD`. 52 * 53 * @{ 54 * 55 */ 56 57 /** 58 * Represents the set of configurations used when discovering mesh topology indicating which items to 59 * discover. 60 * 61 */ 62 typedef struct otMeshDiagDiscoverConfig 63 { 64 bool mDiscoverIp6Addresses : 1; ///< Whether or not to discover IPv6 addresses of every router. 65 bool mDiscoverChildTable : 1; ///< Whether or not to discover children of every router. 66 } otMeshDiagDiscoverConfig; 67 68 /** 69 * An opaque iterator to iterate over list of IPv6 addresses of a router. 70 * 71 * Pointers to instance of this type are provided in `otMeshDiagRouterInfo`. 72 * 73 */ 74 typedef struct otMeshDiagIp6AddrIterator otMeshDiagIp6AddrIterator; 75 76 /** 77 * An opaque iterator to iterate over list of children of a router. 78 * 79 * Pointers to instance of this type are provided in `otMeshDiagRouterInfo`. 80 * 81 */ 82 typedef struct otMeshDiagChildIterator otMeshDiagChildIterator; 83 84 /** 85 * Specifies that Thread Version is unknown. 86 * 87 * This is used in `otMeshDiagRouterInfo` for `mVersion` property when device does not provide its version. This 88 * indicates that device is likely running 1.3.0 (version value 4) or earlier. 89 * 90 */ 91 #define OT_MESH_DIAG_VERSION_UNKNOWN 0xffff 92 93 /** 94 * Represents information about a router in Thread mesh discovered using `otMeshDiagDiscoverTopology()`. 95 * 96 */ 97 typedef struct otMeshDiagRouterInfo 98 { 99 otExtAddress mExtAddress; ///< Extended MAC address. 100 uint16_t mRloc16; ///< RLOC16. 101 uint8_t mRouterId; ///< Router ID. 102 uint16_t mVersion; ///< Thread Version. `OT_MESH_DIAG_VERSION_UNKNOWN` if unknown. 103 bool mIsThisDevice : 1; ///< Whether router is this device itself. 104 bool mIsThisDeviceParent : 1; ///< Whether router is parent of this device (when device is a child). 105 bool mIsLeader : 1; ///< Whether router is leader. 106 bool mIsBorderRouter : 1; ///< Whether router acts as a border router providing ext connectivity. 107 108 /** 109 * Provides the link quality from this router to other routers, also indicating whether a link is established 110 * between the routers. 111 * 112 * The array is indexed based on Router ID. `mLinkQualities[routerId]` indicates the incoming link quality, the 113 * router sees to the router with `routerId`. Link quality is a value in [0, 3]. Value zero indicates no link. 114 * Larger value indicate better link quality (as defined by Thread specification). 115 * 116 */ 117 uint8_t mLinkQualities[OT_NETWORK_MAX_ROUTER_ID + 1]; 118 119 /** 120 * A pointer to an iterator to go through the list of IPv6 addresses of the router. 121 * 122 * The pointer is valid only while `otMeshDiagRouterInfo` is valid. It can be used in `otMeshDiagGetNextIp6Address` 123 * to iterate through the IPv6 addresses. 124 * 125 * The pointer can be NULL when there was no request to discover IPv6 addresses (in `otMeshDiagDiscoverConfig`) or 126 * if the router did not provide the list. 127 * 128 */ 129 otMeshDiagIp6AddrIterator *mIp6AddrIterator; 130 131 /** 132 * A pointer to an iterator to go through the list of children of the router. 133 * 134 * The pointer is valid only while `otMeshDiagRouterInfo` is valid. It can be used in `otMeshDiagGetNextChildInfo` 135 * to iterate through the children of the router. 136 * 137 * The pointer can be NULL when there was no request to discover children (in `otMeshDiagDiscoverConfig`) or 138 * if the router did not provide the list. 139 * 140 */ 141 otMeshDiagChildIterator *mChildIterator; 142 } otMeshDiagRouterInfo; 143 144 /** 145 * Represents information about a discovered child in Thread mesh using `otMeshDiagDiscoverTopology()`. 146 * 147 */ 148 typedef struct otMeshDiagChildInfo 149 { 150 uint16_t mRloc16; ///< RLOC16. 151 otLinkModeConfig mMode; ///< Device mode. 152 uint8_t mLinkQuality; ///< Incoming link quality to child from parent. 153 bool mIsThisDevice : 1; ///< Whether child is this device itself. 154 bool mIsBorderRouter : 1; ///< Whether child acts as a border router providing ext connectivity. 155 } otMeshDiagChildInfo; 156 157 /** 158 * Pointer type represents the callback used by `otMeshDiagDiscoverTopology()` to provide information 159 * about a discovered router. 160 * 161 * When @p aError is `OT_ERROR_PENDING`, it indicates that the discovery is not yet finished and there will be more 162 * routers to discover and the callback will be invoked again. 163 * 164 * @param[in] aError OT_ERROR_PENDING Indicates there are more routers to be discovered. 165 * OT_ERROR_NONE Indicates this is the last router and mesh discovery is done. 166 * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response from one or more routers. 167 * @param[in] aRouterInfo The discovered router info (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT). 168 * @param[in] aContext Application-specific context. 169 * 170 */ 171 typedef void (*otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext); 172 173 /** 174 * Starts network topology discovery. 175 * 176 * @param[in] aInstance The OpenThread instance. 177 * @param[in] aConfig The configuration to use for discovery (e.g., which items to discover). 178 * @param[in] aCallback The callback to report the discovered routers. 179 * @param[in] aContext A context to pass in @p aCallback. 180 * 181 * @retval OT_ERROR_NONE The network topology discovery started successfully. 182 * @retval OT_ERROR_BUSY A previous discovery request is still ongoing. 183 * @retval OT_ERROR_INVALID_STATE Device is not attached. 184 * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send discovery messages. 185 * 186 */ 187 otError otMeshDiagDiscoverTopology(otInstance *aInstance, 188 const otMeshDiagDiscoverConfig *aConfig, 189 otMeshDiagDiscoverCallback aCallback, 190 void *aContext); 191 192 /** 193 * Cancels an ongoing topology discovery if there is one, otherwise no action. 194 * 195 * When ongoing discovery is cancelled, the callback from `otMeshDiagDiscoverTopology()` will not be called anymore. 196 * 197 */ 198 void otMeshDiagCancel(otInstance *aInstance); 199 200 /** 201 * Iterates through the discovered IPv6 addresses of a router or an MTD child. 202 * 203 * MUST be used 204 * - from the callback `otMeshDiagDiscoverCallback()` and use the `mIp6AddrIterator` from the `aRouterInfo` struct that 205 * is provided as input to the callback, or 206 * - from the callback `otMeshDiagChildIp6AddrsCallback()` along with provided `aIp6AddrIterator`. 207 * 208 * @param[in,out] aIterator The address iterator to use. 209 * @param[out] aIp6Address A pointer to return the next IPv6 address (if any). 210 * 211 * @retval OT_ERROR_NONE Successfully retrieved the next address. @p aIp6Address and @p aIterator are updated. 212 * @retval OT_ERROR_NOT_FOUND No more address. Reached the end of the list. 213 * 214 */ 215 otError otMeshDiagGetNextIp6Address(otMeshDiagIp6AddrIterator *aIterator, otIp6Address *aIp6Address); 216 217 /** 218 * Iterates through the discovered children of a router. 219 * 220 * This function MUST be used from the callback `otMeshDiagDiscoverCallback()` and use the `mChildIterator` from the 221 * `aRouterInfo` struct that is provided as input to the callback. 222 * 223 * @param[in,out] aIterator The address iterator to use. 224 * @param[out] aChildInfo A pointer to return the child info (if any). 225 * 226 * @retval OT_ERROR_NONE Successfully retrieved the next child. @p aChildInfo and @p aIterator are updated. 227 * @retval OT_ERROR_NOT_FOUND No more child. Reached the end of the list. 228 * 229 */ 230 otError otMeshDiagGetNextChildInfo(otMeshDiagChildIterator *aIterator, otMeshDiagChildInfo *aChildInfo); 231 232 /** 233 * Represents information about a child entry from `otMeshDiagQueryChildTable()`. 234 * 235 * `mSupportsErrRate` indicates whether or not the error tracking feature is supported and `mFrameErrorRate` and 236 * `mMessageErrorRate` values are valid. The frame error rate tracks frame tx errors (towards the child) at MAC 237 * layer, while `mMessageErrorRate` tracks the IPv6 message error rate (above MAC layer and after MAC retries) when 238 * an IPv6 message is dropped. For example, if the message is large and requires 6LoWPAN fragmentation, message tx is 239 * considered as failed if one of its fragment frame tx fails (for example, never acked). 240 * 241 */ 242 typedef struct otMeshDiagChildEntry 243 { 244 bool mRxOnWhenIdle : 1; ///< Is rx-on when idle (vs sleepy). 245 bool mDeviceTypeFtd : 1; ///< Is device FTD (vs MTD). 246 bool mFullNetData : 1; ///< Whether device gets full Network Data (vs stable sub-set). 247 bool mCslSynchronized : 1; ///< Is CSL capable and CSL synchronized. 248 bool mSupportsErrRate : 1; ///< `mFrameErrorRate` and `mMessageErrorRate` values are valid. 249 uint16_t mRloc16; ///< RLOC16. 250 otExtAddress mExtAddress; ///< Extended Address. 251 uint16_t mVersion; ///< Version. 252 uint32_t mTimeout; ///< Timeout in seconds. 253 uint32_t mAge; ///< Seconds since last heard from the child. 254 uint32_t mConnectionTime; ///< Seconds since child attach. 255 uint16_t mSupervisionInterval; ///< Supervision interval in seconds. Zero to indicate not used. 256 uint8_t mLinkMargin; ///< Link Margin in dB. 257 int8_t mAverageRssi; ///< Average RSSI. 258 int8_t mLastRssi; ///< RSSI of last received frame. 259 uint16_t mFrameErrorRate; ///< Frame error rate (0x0000->0%, 0xffff->100%). 260 uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0x0000->0%, 0xffff->100%). 261 uint16_t mQueuedMessageCount; ///< Number of queued messages for indirect tx to child. 262 uint16_t mCslPeriod; ///< CSL Period in unit of 10-symbols-time. Zero indicates CSL is disabled. 263 uint32_t mCslTimeout; ///< CSL Timeout in seconds. 264 uint8_t mCslChannel; ///< CSL channel. 265 } otMeshDiagChildEntry; 266 267 /** 268 * Represents the callback used by `otMeshDiagQueryChildTable()` to provide information about child table entries. 269 * 270 * When @p aError is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be 271 * invoked again. 272 * 273 * @param[in] aError OT_ERROR_PENDING Indicates there are more entries in the table. 274 * OT_ERROR_NONE Indicates the table is finished. 275 * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. 276 * @param[in] aChildEntry The child entry (can be null if `aError` is OT_ERROR_RESPONSE_TIMEOUT or OT_ERROR_NONE). 277 * @param[in] aContext Application-specific context. 278 * 279 */ 280 typedef void (*otMeshDiagQueryChildTableCallback)(otError aError, 281 const otMeshDiagChildEntry *aChildEntry, 282 void *aContext); 283 284 /** 285 * Starts query for child table for a given router. 286 * 287 * @param[in] aInstance The OpenThread instance. 288 * @param[in] aRloc16 The RLOC16 of router to query. 289 * @param[in] aCallback The callback to report the queried child table. 290 * @param[in] aContext A context to pass in @p aCallback. 291 * 292 * @retval OT_ERROR_NONE The query started successfully. 293 * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. 294 * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid router RLOC16. 295 * @retval OT_ERROR_INVALID_STATE Device is not attached. 296 * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. 297 * 298 */ 299 otError otMeshDiagQueryChildTable(otInstance *aInstance, 300 uint16_t aRloc16, 301 otMeshDiagQueryChildTableCallback aCallback, 302 void *aContext); 303 304 /** 305 * Represents the callback used by `otMeshDiagQueryChildrenIp6Addrs()` to provide information about an MTD child and 306 * its list of IPv6 addresses. 307 * 308 * When @p aError is `OT_ERROR_PENDING`, it indicates that there are more children and the callback will be invoked 309 * again. 310 * 311 * @param[in] aError OT_ERROR_PENDING Indicates there are more children in the table. 312 * OT_ERROR_NONE Indicates the table is finished. 313 * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. 314 * @param[in] aChildRloc16 The RLOC16 of the child. `0xfffe` is used on `OT_ERROR_RESPONSE_TIMEOUT`. 315 * @param[in] aIp6AddrIterator An iterator to go through the IPv6 addresses of the child with @p aRloc using 316 * `otMeshDiagGetNextIp6Address()`. Set to NULL on `OT_ERROR_RESPONSE_TIMEOUT`. 317 * @param[in] aContext Application-specific context. 318 * 319 */ 320 typedef void (*otMeshDiagChildIp6AddrsCallback)(otError aError, 321 uint16_t aChildRloc16, 322 otMeshDiagIp6AddrIterator *aIp6AddrIterator, 323 void *aContext); 324 325 /** 326 * Sends a query to a parent to retrieve the IPv6 addresses of all its MTD children. 327 * 328 * @param[in] aInstance The OpenThread instance. 329 * @param[in] aRloc16 The RLOC16 of parent to query. 330 * @param[in] aCallback The callback to report the queried child IPv6 address list. 331 * @param[in] aContext A context to pass in @p aCallback. 332 * 333 * @retval OT_ERROR_NONE The query started successfully. 334 * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. 335 * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid RLOC16. 336 * @retval OT_ERROR_INVALID_STATE Device is not attached. 337 * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. 338 * 339 */ 340 otError otMeshDiagQueryChildrenIp6Addrs(otInstance *aInstance, 341 uint16_t aRloc16, 342 otMeshDiagChildIp6AddrsCallback aCallback, 343 void *aContext); 344 345 /** 346 * Represents information about a router neighbor entry from `otMeshDiagQueryRouterNeighborTable()`. 347 * 348 * `mSupportsErrRate` indicates whether or not the error tracking feature is supported and `mFrameErrorRate` and 349 * `mMessageErrorRate` values are valid. The frame error rate tracks frame tx errors (towards the child) at MAC 350 * layer, while `mMessageErrorRate` tracks the IPv6 message error rate (above MAC layer and after MAC retries) when 351 * an IPv6 message is dropped. For example, if the message is large and requires 6LoWPAN fragmentation, message tx is 352 * considered as failed if one of its fragment frame tx fails (for example, never acked). 353 * 354 */ 355 typedef struct otMeshDiagRouterNeighborEntry 356 { 357 bool mSupportsErrRate : 1; ///< `mFrameErrorRate` and `mMessageErrorRate` values are valid. 358 uint16_t mRloc16; ///< RLOC16. 359 otExtAddress mExtAddress; ///< Extended Address. 360 uint16_t mVersion; ///< Version. 361 uint32_t mConnectionTime; ///< Seconds since link establishment. 362 uint8_t mLinkMargin; ///< Link Margin in dB. 363 int8_t mAverageRssi; ///< Average RSSI. 364 int8_t mLastRssi; ///< RSSI of last received frame. 365 uint16_t mFrameErrorRate; ///< Frame error rate (0x0000->0%, 0xffff->100%). 366 uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0x0000->0%, 0xffff->100%). 367 } otMeshDiagRouterNeighborEntry; 368 369 /** 370 * Represents the callback used by `otMeshDiagQueryRouterNeighborTable()` to provide information about neighbor router 371 * table entries. 372 * 373 * When @p aError is `OT_ERROR_PENDING`, it indicates that the table still has more entries and the callback will be 374 * invoked again. 375 * 376 * @param[in] aError OT_ERROR_PENDING Indicates there are more entries in the table. 377 * OT_ERROR_NONE Indicates the table is finished. 378 * OT_ERROR_RESPONSE_TIMEOUT Timed out waiting for response. 379 * @param[in] aNeighborEntry The neighbor entry (can be null if `aError` is RESPONSE_TIMEOUT or NONE). 380 * @param[in] aContext Application-specific context. 381 * 382 */ 383 typedef void (*otMeshDiagQueryRouterNeighborTableCallback)(otError aError, 384 const otMeshDiagRouterNeighborEntry *aNeighborEntry, 385 void *aContext); 386 387 /** 388 * Starts query for router neighbor table for a given router. 389 * 390 * @param[in] aInstance The OpenThread instance. 391 * @param[in] aRloc16 The RLOC16 of router to query. 392 * @param[in] aCallback The callback to report the queried table. 393 * @param[in] aContext A context to pass in @p aCallback. 394 * 395 * @retval OT_ERROR_NONE The query started successfully. 396 * @retval OT_ERROR_BUSY A previous discovery or query request is still ongoing. 397 * @retval OT_ERROR_INVALID_ARGS The @p aRloc16 is not a valid router RLOC16. 398 * @retval OT_ERROR_INVALID_STATE Device is not attached. 399 * @retval OT_ERROR_NO_BUFS Could not allocate buffer to send query messages. 400 * 401 */ 402 otError otMeshDiagQueryRouterNeighborTable(otInstance *aInstance, 403 uint16_t aRloc16, 404 otMeshDiagQueryRouterNeighborTableCallback aCallback, 405 void *aContext); 406 407 /** 408 * @} 409 * 410 */ 411 412 #ifdef __cplusplus 413 } // extern "C" 414 #endif 415 416 #endif // OPENTHREAD_MESH_DIAG_H_ 417
