From 23c01d7eaf1a52dab2af893bcf7045c0c28b20c2 Mon Sep 17 00:00:00 2001 From: Sarah <91494325+sarah-iot@users.noreply.github.com> Date: Wed, 12 Oct 2022 14:34:45 -0700 Subject: [PATCH] [docs] CLI commands ifconfig - linkmetrics (#8253) --- include/openthread/instance.h | 2 +- include/openthread/ip6.h | 26 +- include/openthread/link_metrics.h | 4 +- include/openthread/thread.h | 22 +- include/openthread/thread_ftd.h | 8 +- src/cli/cli.cpp | 393 ++++++++++++++++++++++++++++++ 6 files changed, 424 insertions(+), 31 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 6ed45ee4e..7d9419721 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (249) +#define OPENTHREAD_API_VERSION (250) /** * @addtogroup api-instance diff --git a/include/openthread/ip6.h b/include/openthread/ip6.h index d289536e2..359cc5b19 100644 --- a/include/openthread/ip6.h +++ b/include/openthread/ip6.h @@ -257,9 +257,9 @@ enum }; /** - * This function brings up/down the IPv6 interface. + * Brings the IPv6 interface up or down. * - * Call this function to enable/disable IPv6 communication. + * Call this to enable or disable IPv6 communication. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aEnabled TRUE to enable IPv6, FALSE otherwise. @@ -272,7 +272,7 @@ enum otError otIp6SetEnabled(otInstance *aInstance, bool aEnabled); /** - * This function indicates whether or not the IPv6 interface is up. + * Indicates whether or not the IPv6 interface is up. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -283,10 +283,10 @@ otError otIp6SetEnabled(otInstance *aInstance, bool aEnabled); bool otIp6IsEnabled(otInstance *aInstance); /** - * Add a Network Interface Address to the Thread interface. + * Adds a Network Interface Address to the Thread interface. * * The passed-in instance @p aAddress is copied by the Thread interface. The Thread interface only - * supports a fixed number of externally added unicast addresses. See OPENTHREAD_CONFIG_IP6_MAX_EXT_UCAST_ADDRS. + * supports a fixed number of externally added unicast addresses. See `OPENTHREAD_CONFIG_IP6_MAX_EXT_UCAST_ADDRS`. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aAddress A pointer to a Network Interface Address. @@ -298,7 +298,7 @@ bool otIp6IsEnabled(otInstance *aInstance); otError otIp6AddUnicastAddress(otInstance *aInstance, const otNetifAddress *aAddress); /** - * Remove a Network Interface Address from the Thread interface. + * Removes a Network Interface Address from the Thread interface. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aAddress A pointer to an IP Address. @@ -310,7 +310,7 @@ otError otIp6AddUnicastAddress(otInstance *aInstance, const otNetifAddress *aAdd otError otIp6RemoveUnicastAddress(otInstance *aInstance, const otIp6Address *aAddress); /** - * Get the list of IPv6 addresses assigned to the Thread interface. + * Gets the list of IPv6 addresses assigned to the Thread interface. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -319,10 +319,10 @@ otError otIp6RemoveUnicastAddress(otInstance *aInstance, const otIp6Address *aAd const otNetifAddress *otIp6GetUnicastAddresses(otInstance *aInstance); /** - * Subscribe the Thread interface to a Network Interface Multicast Address. + * Subscribes the Thread interface to a Network Interface Multicast Address. * * The passed in instance @p aAddress will be copied by the Thread interface. The Thread interface only - * supports a fixed number of externally added multicast addresses. See OPENTHREAD_CONFIG_IP6_MAX_EXT_MCAST_ADDRS. + * supports a fixed number of externally added multicast addresses. See `OPENTHREAD_CONFIG_IP6_MAX_EXT_MCAST_ADDRS`. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aAddress A pointer to an IP Address. @@ -338,7 +338,7 @@ const otNetifAddress *otIp6GetUnicastAddresses(otInstance *aInstance); otError otIp6SubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aAddress); /** - * Unsubscribe the Thread interface to a Network Interface Multicast Address. + * Unsubscribes the Thread interface to a Network Interface Multicast Address. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aAddress A pointer to an IP Address. @@ -351,7 +351,7 @@ otError otIp6SubscribeMulticastAddress(otInstance *aInstance, const otIp6Address otError otIp6UnsubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aAddress); /** - * Get the list of IPv6 multicast addresses subscribed to the Thread interface. + * Gets the list of IPv6 multicast addresses subscribed to the Thread interface. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -361,7 +361,7 @@ otError otIp6UnsubscribeMulticastAddress(otInstance *aInstance, const otIp6Addre const otNetifMulticastAddress *otIp6GetMulticastAddresses(otInstance *aInstance); /** - * Check if multicast promiscuous mode is enabled on the Thread interface. + * Checks if multicast promiscuous mode is enabled on the Thread interface. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -371,7 +371,7 @@ const otNetifMulticastAddress *otIp6GetMulticastAddresses(otInstance *aInstance) bool otIp6IsMulticastPromiscuousEnabled(otInstance *aInstance); /** - * Enable multicast promiscuous mode on the Thread interface. + * Enables or disables multicast promiscuous mode on the Thread interface. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aEnabled TRUE to enable Multicast Promiscuous mode, FALSE otherwise. diff --git a/include/openthread/link_metrics.h b/include/openthread/link_metrics.h index 0b039b57a..267654bfe 100644 --- a/include/openthread/link_metrics.h +++ b/include/openthread/link_metrics.h @@ -170,7 +170,7 @@ otError otLinkMetricsQuery(otInstance * aInstance, void * aCallbackContext); /** - * This function sends an MLE Link Metrics Management Request to configure/clear a Forward Tracking Series. + * Sends an MLE Link Metrics Management Request to configure or clear a Forward Tracking Series. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDestination A pointer to the destination address. @@ -228,7 +228,7 @@ otError otLinkMetricsConfigEnhAckProbing(otInstance * void * aEnhAckCallbackContext); /** - * This function sends an MLE Link Probe message. + * Sends an MLE Link Probe message. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDestination A pointer to the destination address. diff --git a/include/openthread/thread.h b/include/openthread/thread.h index 0eb4d2f86..1a61fdd2a 100644 --- a/include/openthread/thread.h +++ b/include/openthread/thread.h @@ -459,7 +459,7 @@ otError otThreadSetNetworkKey(otInstance *aInstance, const otNetworkKey *aKey); otError otThreadSetNetworkKeyRef(otInstance *aInstance, otNetworkKeyRef aKeyRef); /** - * This function returns a pointer to the Thread Routing Locator (RLOC) address. + * Gets the Thread Routing Locator (RLOC) address. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -469,7 +469,7 @@ otError otThreadSetNetworkKeyRef(otInstance *aInstance, otNetworkKeyRef aKeyRef) const otIp6Address *otThreadGetRloc(otInstance *aInstance); /** - * This function returns a pointer to the Mesh Local EID address. + * Gets the Mesh Local EID address. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -505,7 +505,7 @@ const otMeshLocalPrefix *otThreadGetMeshLocalPrefix(otInstance *aInstance); otError otThreadSetMeshLocalPrefix(otInstance *aInstance, const otMeshLocalPrefix *aMeshLocalPrefix); /** - * This function returns the Thread link-local IPv6 address. + * Gets the Thread link-local IPv6 address. * * The Thread link local address is derived using IEEE802.15.4 Extended Address as Interface Identifier. * @@ -517,9 +517,9 @@ otError otThreadSetMeshLocalPrefix(otInstance *aInstance, const otMeshLocalPrefi const otIp6Address *otThreadGetLinkLocalIp6Address(otInstance *aInstance); /** - * This function returns the Thread Link-Local All Thread Nodes multicast address. + * Gets the Thread Link-Local All Thread Nodes multicast address. * - * The address is a link-local Unicast Prefix-Based Multcast Address [RFC 3306], with: + * The address is a link-local Unicast Prefix-Based Multicast Address [RFC 3306], with: * - flgs set to 3 (P = 1 and T = 1) * - scop set to 2 * - plen set to 64 @@ -534,9 +534,9 @@ const otIp6Address *otThreadGetLinkLocalIp6Address(otInstance *aInstance); const otIp6Address *otThreadGetLinkLocalAllThreadNodesMulticastAddress(otInstance *aInstance); /** - * This function returns the Thread Realm-Local All Thread Nodes multicast address. + * Gets the Thread Realm-Local All Thread Nodes multicast address. * - * The address is a realm-local Unicast Prefix-Based Multcast Address [RFC 3306], with: + * The address is a realm-local Unicast Prefix-Based Multicast Address [RFC 3306], with: * - flgs set to 3 (P = 1 and T = 1) * - scop set to 3 * - plen set to 64 @@ -656,7 +656,7 @@ otError otThreadSetFixedDuaInterfaceIdentifier(otInstance *aInstance, const otIp const otIp6InterfaceIdentifier *otThreadGetFixedDuaInterfaceIdentifier(otInstance *aInstance); /** - * Get the thrKeySequenceCounter. + * Gets the thrKeySequenceCounter. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -668,7 +668,7 @@ const otIp6InterfaceIdentifier *otThreadGetFixedDuaInterfaceIdentifier(otInstanc uint32_t otThreadGetKeySequenceCounter(otInstance *aInstance); /** - * Set the thrKeySequenceCounter. + * Sets the thrKeySequenceCounter. * * @note This API is reserved for testing and demo purposes only. Changing settings with * this API will render a production application non-compliant with the Thread Specification. @@ -682,7 +682,7 @@ uint32_t otThreadGetKeySequenceCounter(otInstance *aInstance); void otThreadSetKeySequenceCounter(otInstance *aInstance, uint32_t aKeySequenceCounter); /** - * Get the thrKeySwitchGuardTime + * Gets the thrKeySwitchGuardTime (in hours). * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -694,7 +694,7 @@ void otThreadSetKeySequenceCounter(otInstance *aInstance, uint32_t aKeySequenceC uint32_t otThreadGetKeySwitchGuardTime(otInstance *aInstance); /** - * Set the thrKeySwitchGuardTime + * Sets the thrKeySwitchGuardTime (in hours). * * @note This API is reserved for testing and demo purposes only. Changing settings with * this API will render a production application non-compliant with the Thread Specification. diff --git a/include/openthread/thread_ftd.h b/include/openthread/thread_ftd.h index 6cb3ddc3d..5d7904d42 100644 --- a/include/openthread/thread_ftd.h +++ b/include/openthread/thread_ftd.h @@ -196,7 +196,7 @@ otError otThreadSetRouterEligible(otInstance *aInstance, bool aEligible); otError otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId); /** - * Get the Thread Leader Weight used when operating in the Leader role. + * Gets the Thread Leader Weight used when operating in the Leader role. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -208,7 +208,7 @@ otError otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId); uint8_t otThreadGetLocalLeaderWeight(otInstance *aInstance); /** - * Set the Thread Leader Weight used when operating in the Leader role. + * Sets the Thread Leader Weight used when operating in the Leader role. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aWeight The Thread Leader Weight value. @@ -238,7 +238,7 @@ uint32_t otThreadGetPreferredLeaderPartitionId(otInstance *aInstance); void otThreadSetPreferredLeaderPartitionId(otInstance *aInstance, uint32_t aPartitionId); /** - * Get the Joiner UDP Port. + * Gets the Joiner UDP Port. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -250,7 +250,7 @@ void otThreadSetPreferredLeaderPartitionId(otInstance *aInstance, uint32_t aPart uint16_t otThreadGetJoinerUdpPort(otInstance *aInstance); /** - * Set the Joiner UDP Port. + * Sets the Joiner UDP Port. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aJoinerUdpPort The Joiner UDP Port number. diff --git a/src/cli/cli.cpp b/src/cli/cli.cpp index f77fd4530..3cf1f7b78 100644 --- a/src/cli/cli.cpp +++ b/src/cli/cli.cpp @@ -3474,6 +3474,21 @@ template <> otError Interpreter::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; + /** + * @cli ifconfig + * @code + * ifconfig + * down + * Done + * @endcode + * @code + * ifconfig + * up + * Done + * @endcode + * @par api_copy + * #otIp6IsEnabled + */ if (aArgs[0].IsEmpty()) { if (otIp6IsEnabled(GetInstancePtr())) @@ -3485,6 +3500,20 @@ template <> otError Interpreter::Process(Arg aArgs[]) OutputLine("down"); } } + /** + * @cli ifconfig (up,down) + * @code + * ifconfig up + * Done + * @endcode + * @code + * ifconfig down + * Done + * @endcode + * @cparam ifconfig @ca{up|down} + * @par api_copy + * #otIp6SetEnabled + */ else if (aArgs[0] == "up") { SuccessOrExit(error = otIp6SetEnabled(GetInstancePtr(), true)); @@ -3530,6 +3559,27 @@ template <> otError Interpreter::Process(Arg aArgs[]) verbose = true; } + /** + * @cli ipaddr + * @code + * ipaddr + * fdde:ad00:beef:0:0:ff:fe00:0 + * fdde:ad00:beef:0:558:f56b:d688:799 + * fe80:0:0:0:f3d9:2a82:c8d8:fe43 + * Done + * @endcode + * @code + * ipaddr -v + * fdde:ad00:beef:0:0:ff:fe00:0 origin:thread + * fdde:ad00:beef:0:558:f56b:d688:799 origin:thread + * fe80:0:0:0:f3d9:2a82:c8d8:fe43 origin:thread + * Done + * @endcode + * @cparam ipaddr [@ca{-v}] + * Use `-v` to get verbose IP Address information. + * @par api_copy + * #otIp6GetUnicastAddresses + */ if (aArgs[0].IsEmpty()) { const otNetifAddress *unicastAddrs = otIp6GetUnicastAddresses(GetInstancePtr()); @@ -3546,6 +3596,16 @@ template <> otError Interpreter::Process(Arg aArgs[]) OutputLine(""); } } + /** + * @cli ipaddr add + * @code + * ipaddr add 2001::dead:beef:cafe + * Done + * @endcode + * @cparam ipaddr add @ca{aAddress} + * @par api_copy + * #otIp6AddUnicastAddress + */ else if (aArgs[0] == "add") { otNetifAddress address; @@ -3558,6 +3618,16 @@ template <> otError Interpreter::Process(Arg aArgs[]) error = otIp6AddUnicastAddress(GetInstancePtr(), &address); } + /** + * @cli ipaddr del + * @code + * ipaddr del 2001::dead:beef:cafe + * Done + * @endcode + * @cparam ipaddr del @ca{aAddress} + * @par api_copy + * #otIp6RemoveUnicastAddress + */ else if (aArgs[0] == "del") { otIp6Address address; @@ -3565,14 +3635,44 @@ template <> otError Interpreter::Process(Arg aArgs[]) SuccessOrExit(error = aArgs[1].ParseAsIp6Address(address)); error = otIp6RemoveUnicastAddress(GetInstancePtr(), &address); } + /** + * @cli ipaddr linklocal + * @code + * ipaddr linklocal + * fe80:0:0:0:f3d9:2a82:c8d8:fe43 + * Done + * @endcode + * @par api_copy + * #otThreadGetLinkLocalIp6Address + */ else if (aArgs[0] == "linklocal") { OutputIp6AddressLine(*otThreadGetLinkLocalIp6Address(GetInstancePtr())); } + /** + * @cli ipaddr rloc + * @code + * ipaddr rloc + * fdde:ad00:beef:0:0:ff:fe00:0 + * Done + * @endcode + * @par api_copy + * #otThreadGetRloc + */ else if (aArgs[0] == "rloc") { OutputIp6AddressLine(*otThreadGetRloc(GetInstancePtr())); } + /** + * @cli ipaddr mleid + * @code + * ipaddr mleid + * fdde:ad00:beef:0:558:f56b:d688:799 + * Done + * @endcode + * @par api_copy + * #otThreadGetMeshLocalEid + */ else if (aArgs[0] == "mleid") { OutputIp6AddressLine(*otThreadGetMeshLocalEid(GetInstancePtr())); @@ -3590,6 +3690,18 @@ template <> otError Interpreter::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; + /** + * @cli ipmaddr + * @code + * ipmaddr + * ff05:0:0:0:0:0:0:1 + * ff33:40:fdde:ad00:beef:0:0:1 + * ff32:40:fdde:ad00:beef:0:0:1 + * Done + * @endcode + * @par api_copy + * #otIp6GetMulticastAddresses + */ if (aArgs[0].IsEmpty()) { for (const otNetifMulticastAddress *addr = otIp6GetMulticastAddresses(GetInstancePtr()); addr; @@ -3598,6 +3710,16 @@ template <> otError Interpreter::Process(Arg aArgs[]) OutputIp6AddressLine(addr->mAddress); } } + /** + * @cli ipmaddr add + * @code + * ipmaddr add ff05::1 + * Done + * @endcode + * @cparam ipmaddr add @ca{aAddress} + * @par api_copy + * #otIp6SubscribeMulticastAddress + */ else if (aArgs[0] == "add") { otIp6Address address; @@ -3615,6 +3737,16 @@ template <> otError Interpreter::Process(Arg aArgs[]) while (false); #endif } + /** + * @cli ipmaddr del + * @code + * ipmaddr del ff05::1 + * Done + * @endcode + * @cparam ipmaddr del @ca{aAddress} + * @par api_copy + * #otIp6UnsubscribeMulticastAddress + */ else if (aArgs[0] == "del") { otIp6Address address; @@ -3622,12 +3754,36 @@ template <> otError Interpreter::Process(Arg aArgs[]) SuccessOrExit(error = aArgs[1].ParseAsIp6Address(address)); error = otIp6UnsubscribeMulticastAddress(GetInstancePtr(), &address); } + /** + * @cli ipmaddr promiscuous + * @code + * ipmaddr promiscuous + * Disabled + * Done + * @endcode + * @par api_copy + * #otIp6IsMulticastPromiscuousEnabled + */ else if (aArgs[0] == "promiscuous") { if (aArgs[1].IsEmpty()) { OutputEnabledDisabledStatus(otIp6IsMulticastPromiscuousEnabled(GetInstancePtr())); } + /** + * @cli ipmaddr promiscuous (enable,disable) + * @code + * ipmaddr promiscuous enable + * Done + * @endcode + * @code + * ipmaddr promiscuous disable + * Done + * @endcode + * @cparam ipmaddr promiscuous @ca{enable|disable} + * @par api_copy + * #otIp6SetMulticastPromiscuousEnabled + */ else { bool enable; @@ -3636,10 +3792,30 @@ template <> otError Interpreter::Process(Arg aArgs[]) otIp6SetMulticastPromiscuousEnabled(GetInstancePtr(), enable); } } + /** + * @cli ipmaddr llatn + * @code + * ipmaddr llatn + * ff32:40:fdde:ad00:beef:0:0:1 + * Done + * @endcode + * @par api_copy + * #otThreadGetLinkLocalAllThreadNodesMulticastAddress + */ else if (aArgs[0] == "llatn") { OutputIp6AddressLine(*otThreadGetLinkLocalAllThreadNodesMulticastAddress(GetInstancePtr())); } + /** + * @cli ipmaddr rlatn + * @code + * ipmaddr rlatn + * ff33:40:fdde:ad00:beef:0:0:1 + * Done + * @endcode + * @par api_copy + * #otThreadGetRealmLocalAllThreadNodesMulticastAddress + */ else if (aArgs[0] == "rlatn") { OutputIp6AddressLine(*otThreadGetRealmLocalAllThreadNodesMulticastAddress(GetInstancePtr())); @@ -3657,18 +3833,74 @@ template <> otError Interpreter::Process(Arg aArgs[]) { otError error = OT_ERROR_INVALID_ARGS; + /** + * @cli keysequence counter + * @code + * keysequence counter + * 10 + * Done + * @endcode + * @par api_copy + * #otThreadGetKeySequenceCounter + */ if (aArgs[0] == "counter") { + /** + * @cli keysequence counter (set) + * @code + * keysequence counter 10 + * Done + * @endcode + * @cparam keysequence counter @ca{counter} + * @par api_copy + * #otThreadSetKeySequenceCounter + */ error = ProcessGetSet(aArgs + 1, otThreadGetKeySequenceCounter, otThreadSetKeySequenceCounter); } + /** + * @cli keysequence guardtime + * @code + * keysequence guardtime + * 0 + * Done + * @endcode + * @par api_copy + * #otThreadGetKeySwitchGuardTime + */ else if (aArgs[0] == "guardtime") { + /** + * @cli keysequence guardtime (set) + * @code + * keysequence guardtime 0 + * Done + * @endcode + * @cparam keysequence guardtime @ca{guardtime-hours} + * Use `0` to `Thread Key Switch` immediately if there's a key index match. + * @par api_copy + * #otThreadSetKeySwitchGuardTime + */ error = ProcessGetSet(aArgs + 1, otThreadGetKeySwitchGuardTime, otThreadSetKeySwitchGuardTime); } return error; } +/** + * @cli leaderdata + * @code + * leaderdata + * Partition ID: 1077744240 + * Weighting: 64 + * Data Version: 109 + * Stable Data Version: 211 + * Leader Router ID: 60 + * Done + * @endcode + * @par + * Gets the Thread Leader Data. + * @sa otThreadGetLeaderData + */ template <> otError Interpreter::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs); @@ -3708,8 +3940,28 @@ template <> otError Interpreter::Process(Arg aArgs[]) return error; } +/** + * @cli leaderweight + * @code + * leaderweight + * 128 + * Done + * @endcode + * @par api_copy + * #otThreadGetLocalLeaderWeight + */ template <> otError Interpreter::Process(Arg aArgs[]) { + /** + * @cli leaderweight (set) + * @code + * leaderweight 128 + * Done + * @endcode + * @cparam leaderweight @ca{weight} + * @par api_copy + * #otThreadSetLocalLeaderWeight + */ return ProcessGetSet(aArgs, otThreadGetLocalLeaderWeight, otThreadSetLocalLeaderWeight); } #endif // OPENTHREAD_FTD @@ -3850,11 +4102,50 @@ template <> otError Interpreter::Process(Arg aArgs[]) SuccessOrExit(error = aArgs[1].ParseAsIp6Address(address)); + /** + * @cli linkmetrics query single + * @code + * linkmetrics query fe80:0:0:0:3092:f334:1455:1ad2 single qmr + * Done + * > Received Link Metrics Report from: fe80:0:0:0:3092:f334:1455:1ad2 + * - LQI: 76 (Exponential Moving Average) + * - Margin: 82 (dB) (Exponential Moving Average) + * - RSSI: -18 (dBm) (Exponential Moving Average) + * @endcode + * @cparam linkmetrics query @ca{peer-ipaddr} single [@ca{pqmr}] + * - `peer-ipaddr`: Peer address. + * - [`p`, `q`, `m`, and `r`] map to #otLinkMetrics. + * - `p`: Layer 2 Number of PDUs received. + * - `q`: Layer 2 LQI. + * - `m`: Link Margin. + * - `r`: RSSI. + * @par + * Perform a Link Metrics query (Single Probe). + * @sa otLinkMetricsQuery + */ if (aArgs[2] == "single") { isSingle = true; SuccessOrExit(error = ParseLinkMetricsFlags(linkMetrics, aArgs[3])); } + /** + * @cli linkmetrics query forward + * @code + * linkmetrics query fe80:0:0:0:3092:f334:1455:1ad2 forward 1 + * Done + * > Received Link Metrics Report from: fe80:0:0:0:3092:f334:1455:1ad2 + * - PDU Counter: 2 (Count/Summation) + * - LQI: 76 (Exponential Moving Average) + * - Margin: 82 (dB) (Exponential Moving Average) + * - RSSI: -18 (dBm) (Exponential Moving Average) + * @endcode + * @cparam linkmetrics query @ca{peer-ipaddr} forward @ca{series-id} + * - `peer-ipaddr`: Peer address. + * - `series-id`: The Series ID. + * @par + * Perform a Link Metrics query (Forward Tracking Series). + * @sa otLinkMetricsQuery + */ else if (aArgs[2] == "forward") { isSingle = false; @@ -3880,6 +4171,19 @@ template <> otError Interpreter::Process(Arg aArgs[]) { error = ProcessLinkMetricsMgmt(aArgs + 1); } + /** + * @cli linkmetrics probe + * @code + * linkmetrics probe fe80:0:0:0:3092:f334:1455:1ad2 1 10 + * Done + * @endcode + * @cparam linkmetrics probe @ca{peer-ipaddr} @ca{series-id} @ca{length} + * - `peer-ipaddr`: Peer address. + * - `series-id`: The Series ID for which this Probe message targets. + * - `length`: The length of the Probe message. A valid range is [0, 64]. + * @par api_copy + * #otLinkMetricsSendLinkProbe + */ else if (aArgs[0] == "probe") { otIp6Address address; @@ -3945,6 +4249,32 @@ otError Interpreter::ProcessLinkMetricsMgmt(Arg aArgs[]) memset(&seriesFlags, 0, sizeof(otLinkMetricsSeriesFlags)); + /** + * @cli linkmetrics mgmt forward + * @code + * linkmetrics mgmt fe80:0:0:0:3092:f334:1455:1ad2 forward 1 dra pqmr + * Done + * > Received Link Metrics Management Response from: fe80:0:0:0:3092:f334:1455:1ad2 + * Status: SUCCESS + * @endcode + * @cparam linkmetrics mgmt @ca{peer-ipaddr} forward @ca{series-id} [@ca{ldraX}][@ca{pqmr}] + * - `peer-ipaddr`: Peer address. + * - `series-id`: The Series ID. + * - [`l`, `d`, `r`, and `a`] map to #otLinkMetricsSeriesFlags. `X` represents none of the + * `otLinkMetricsSeriesFlags`, and stops the accounting and removes the series. + * - `l`: MLE Link Probe. + * - `d`: MAC Data. + * - `r`: MAC Data Request. + * - `a`: MAC Ack. + * - `X`: Can only be used without any other flags. + * - [`p`, `q`, `m`, and `r`] map to #otLinkMetricsValues. + * - `p`: Layer 2 Number of PDUs received. + * - `q`: Layer 2 LQI. + * - `m`: Link Margin. + * - `r`: RSSI. + * @par api_copy + * #otLinkMetricsConfigForwardTrackingSeries + */ if (aArgs[1] == "forward") { uint8_t seriesId; @@ -4001,11 +4331,54 @@ otError Interpreter::ProcessLinkMetricsMgmt(Arg aArgs[]) otLinkMetrics linkMetrics; otLinkMetrics * pLinkMetrics = &linkMetrics; + /** + * @cli linkmetrics mgmt enhanced-ack clear + * @code + * linkmetrics mgmt fe80:0:0:0:3092:f334:1455:1ad2 enhanced-ack clear + * Done + * > Received Link Metrics Management Response from: fe80:0:0:0:3092:f334:1455:1ad2 + * Status: Success + * @endcode + * @cparam linkmetrics mgmt @ca{peer-ipaddr} enhanced-ack clear + * `peer-ipaddr` should be the Link Local address of the neighboring device. + * @par + * Sends a Link Metrics Management Request to clear an Enhanced-ACK Based Probing. + * @sa otLinkMetricsConfigEnhAckProbing + */ if (aArgs[2] == "clear") { enhAckFlags = OT_LINK_METRICS_ENH_ACK_CLEAR; pLinkMetrics = nullptr; } + /** + * @cli linkmetrics mgmt enhanced-ack register + * @code + * linkmetrics mgmt fe80:0:0:0:3092:f334:1455:1ad2 enhanced-ack register qm + * Done + * > Received Link Metrics Management Response from: fe80:0:0:0:3092:f334:1455:1ad2 + * Status: Success + * @endcode + * @code + * > linkmetrics mgmt fe80:0:0:0:3092:f334:1455:1ad2 enhanced-ack register qm r + * Done + * > Received Link Metrics Management Response from: fe80:0:0:0:3092:f334:1455:1ad2 + * Status: Cannot support new series + * @endcode + * @cparam linkmetrics mgmt @ca{peer-ipaddr} enhanced-ack register [@ca{qmr}][@ca{r}] + * [`q`, `m`, and `r`] map to #otLinkMetricsValues. Per spec 4.11.3.4.4.6, you can + * only use a maximum of two options at once, for example `q`, or `qm`. + * - `q`: Layer 2 LQI. + * - `m`: Link Margin. + * - `r`: RSSI. + * . + * The additional `r` is optional and only used for reference devices. When this option + * is specified, Type/Average Enum of each Type Id Flags is set to reserved. This is + * used to verify that the Probing Subject correctly handles invalid Type Id Flags, and + * only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. + * @par + * Sends a Link Metrics Management Request to register an Enhanced-ACK Based Probing. + * @sa otLinkMetricsConfigEnhAckProbing + */ else if (aArgs[2] == "register") { enhAckFlags = OT_LINK_METRICS_ENH_ACK_REGISTER; @@ -5884,8 +6257,28 @@ template <> otError Interpreter::Process(Arg aArgs[]) #endif #if OPENTHREAD_FTD +/** + * @cli joinerport + * @code + * joinerport + * 1000 + * Done + * @endcode + * @par api_copy + * #otThreadGetJoinerUdpPort + */ template <> otError Interpreter::Process(Arg aArgs[]) { + /** + * @cli joinerport (set) + * @code + * joinerport 1000 + * Done + * @endcode + * @cparam joinerport @ca{udp-port} + * @par api_copy + * #otThreadSetJoinerUdpPort + */ return ProcessGetSet(aArgs, otThreadGetJoinerUdpPort, otThreadSetJoinerUdpPort); } #endif