[mesh-diag] add API to configure response timeout (#11753)

This change introduces new APIs to allow configuration of the response
timeout for mesh diagnostic queries. A corresponding CLI command
`meshdiag responsetimeout` is also added to get or set the timeout
value.

When set, the new response timeout is used for subsequent queries and
does not affect any that are ongoing. The timeout value is clamped
between 50 milliseconds and 10 minutes to ensure it stays within a
reasonable range.

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (521)
+#define OPENTHREAD_API_VERSION (522)
 
 /**
  * @addtogroup api-instance

include/openthread/mesh_diag.h

@@ -387,6 +387,29 @@ otError otMeshDiagQueryRouterNeighborTable(otInstance
                                            otMeshDiagQueryRouterNeighborTableCallback aCallback,
                                            void                                      *aContext);
 
+/**
+ * Sets the response timeout value to use for any future mesh diagnostic queries.
+ *
+ * The default response timeout value is specified by `OPENTHREAD_CONFIG_MESH_DIAG_RESPONSE_TIMEOUT` configuration.
+ *
+ * Changing the response timeout does not impact any ongoing query.
+ *
+ * The provided @p aTimeout value will be clamped to stay between 50 milliseconds and 10 minutes.
+ *
+ * @param[in] aInstance  A pointer to an OpenThread instance.
+ * @param[in] aTimeout   The timeout interval in milliseconds.
+ */
+void otMeshDiagSetResponseTimeout(otInstance *aInstance, uint32_t aTimeout);
+
+/**
+ * Gets the response timeout value.
+ *
+ * @param[in] aInstance  A pointer to an OpenThread instance.
+ *
+ * @returns The response timeout interval in milliseconds.
+ */
+uint32_t otMeshDiagGetResponseTimeout(otInstance *aInstance);
+
 /**
  * @}
  */

src/cli/README.md

@@ -2594,6 +2594,27 @@ rloc16:0x7c00 ext-addr:4ed24fceec9bf6d3 ver:4
 Done
 ```
 
+### meshdiag responsetimeout [\<timeout-msec\>]
+
+Get or set the response timeout value (in milliseconds).
+
+The default response timeout value is specified by `OPENTHREAD_CONFIG_MESH_DIAG_RESPONSE_TIMEOUT` configuration.
+
+Changing the response timeout does not impact any ongoing query. The given timeout value will be clamped to stay between 50 milliseconds and 10 minutes.
+
+```bash
+> responsetimeout
+5000
+Done
+
+> responsetimeout 7000
+Done
+
+> responsetimeout
+7000
+Done
+```
+
 ### mliid \<iid\>
 
 Set the Mesh Local IID.

src/cli/cli_mesh_diag.cpp

@@ -49,6 +49,29 @@ MeshDiag::MeshDiag(otInstance *aInstance, OutputImplementer &aOutputImplementer)
 {
 }
 
+/** @cli responsetimeout
+ * @code
+ * responsetimeout
+ * 5000
+ * Done
+ * @endcode
+ * @par api_copy
+ * #otMeshDiagGetResponseTimeout
+ */
+template <> otError MeshDiag::Process<Cmd("responsetimeout")>(Arg aArgs[])
+{
+    /** @cli responsetimeout (set)
+     * @code
+     * responsetimeout 7000
+     * Done
+     * @endcode
+     * @cparam responsetimeout @ca{timeout-msec}
+     * @par api_copy
+     * #otMeshDiagSetResponseTimeout
+     */
+    return ProcessGetSet(aArgs, otMeshDiagGetResponseTimeout, otMeshDiagSetResponseTimeout);
+}
+
 template <> otError MeshDiag::Process<Cmd("topology")>(Arg aArgs[])
 {
     /**
@@ -274,9 +297,7 @@ otError MeshDiag::Process(Arg aArgs[])
     }
 
     static constexpr Command kCommands[] = {
-        CmdEntry("childip6"),
+        CmdEntry("childip6"), CmdEntry("childtable"), CmdEntry("responsetimeout"), CmdEntry("routerneighbortable"),
-        CmdEntry("childtable"),
-        CmdEntry("routerneighbortable"),
         CmdEntry("topology"),
     };
 

src/core/api/mesh_diag_api.cpp

@@ -84,4 +84,14 @@ otError otMeshDiagQueryRouterNeighborTable(otInstance
     return AsCoreType(aInstance).Get<Utils::MeshDiag>().QueryRouterNeighborTable(aRloc16, aCallback, aContext);
 }
 
+void otMeshDiagSetResponseTimeout(otInstance *aInstance, uint32_t aTimeout)
+{
+    AsCoreType(aInstance).Get<Utils::MeshDiag>().SetResponseTimeout(aTimeout);
+}
+
+uint32_t otMeshDiagGetResponseTimeout(otInstance *aInstance)
+{
+    return AsCoreType(aInstance).Get<Utils::MeshDiag>().GetResponseTimeout();
+}
+
 #endif // OPENTHREAD_CONFIG_MESH_DIAG_ENABLE && OPENTHREAD_FTD

src/core/utils/mesh_diag.cpp

@@ -52,10 +52,16 @@ MeshDiag::MeshDiag(Instance &aInstance)
     , mState(kStateIdle)
     , mExpectedQueryId(0)
     , mExpectedAnswerIndex(0)
+    , mResponseTimeout(kResponseTimeout)
     , mTimer(aInstance)
 {
 }
 
+void MeshDiag::SetResponseTimeout(uint32_t aTimeout)
+{
+    mResponseTimeout = Clamp(aTimeout, kMinResponseTimeout, kMaxResponseTimeout);
+}
+
 Error MeshDiag::DiscoverTopology(const DiscoverConfig &aConfig, DiscoverCallback aCallback, void *aContext)
 {
     static constexpr uint8_t kMaxTlvsToRequest = 6;
@@ -101,7 +107,7 @@ Error MeshDiag::DiscoverTopology(const DiscoverConfig &aConfig, DiscoverCallback
 
     mDiscover.mCallback.Set(aCallback, aContext);
     mState = kStateDiscoverTopology;
-    mTimer.Start(kResponseTimeout);
+    mTimer.Start(mResponseTimeout);
 
 exit:
     return error;
@@ -178,7 +184,7 @@ Error MeshDiag::SendQuery(uint16_t aRloc16, const uint8_t *aTlvs, uint8_t aTlvsL
     mExpectedQueryId     = Get<Client>().GetLastQueryId();
     mExpectedAnswerIndex = 0;
 
-    mTimer.Start(kResponseTimeout);
+    mTimer.Start(mResponseTimeout);
 
 exit:
     return error;

src/core/utils/mesh_diag.hpp

@@ -156,6 +156,24 @@ public:
      */
     explicit MeshDiag(Instance &aInstance);
 
+    /**
+     * Sets the response timeout value to use for any future queries.
+     *
+     * Changing the response timeout does not impact any ongoing query.
+     *
+     * The provided @p aTimeout value will be clamped to stay between 50 milliseconds and 10 minutes.
+     *
+     * @param[in] aTimeout   The timeout interval in milliseconds.
+     */
+    void SetResponseTimeout(uint32_t aTimeout);
+
+    /**
+     * Gets the response timeout value.
+     *
+     * @returns The response timeout interval in milliseconds.
+     */
+    uint32_t GetResponseTimeout(void) const { return mResponseTimeout; }
+
     /**
      * Starts network topology discovery.
      *
@@ -226,7 +244,9 @@ public:
 private:
     typedef ot::NetworkDiagnostic::Tlv Tlv;
 
-    static constexpr uint32_t kResponseTimeout = OPENTHREAD_CONFIG_MESH_DIAG_RESPONSE_TIMEOUT;
+    static constexpr uint32_t kResponseTimeout    = OPENTHREAD_CONFIG_MESH_DIAG_RESPONSE_TIMEOUT;
+    static constexpr uint32_t kMinResponseTimeout = 50;
+    static constexpr uint32_t kMaxResponseTimeout = 10 * Time::kOneMinuteInMsec;
 
     enum State : uint8_t
     {
@@ -298,6 +318,7 @@ private:
     State        mState;
     uint16_t     mExpectedQueryId;
     uint16_t     mExpectedAnswerIndex;
+    uint32_t     mResponseTimeout;
     TimeoutTimer mTimer;
 
     union