From 9099a13015d0570f21a8988cc196899a99e619fc Mon Sep 17 00:00:00 2001 From: jrhodie <139580534+jrhodie@users.noreply.github.com> Date: Mon, 25 Sep 2023 15:42:25 -0700 Subject: [PATCH] [docs] add Doxygen tags for CLI commands (`macfilter rss add` - `macfilter rss remove`) (#9442) --- include/openthread/instance.h | 2 +- include/openthread/link.h | 19 ++++++-- src/cli/README.md | 2 +- src/cli/cli_mac_filter.cpp | 88 +++++++++++++++++++++++++++++++++++ 4 files changed, 104 insertions(+), 7 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 424cf09a7..6f2181238 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 (359) +#define OPENTHREAD_API_VERSION (360) /** * @addtogroup api-instance diff --git a/include/openthread/link.h b/include/openthread/link.h index 76b5d39eb..d48d5d498 100644 --- a/include/openthread/link.h +++ b/include/openthread/link.h @@ -788,8 +788,12 @@ void otLinkFilterClearAddresses(otInstance *aInstance); otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *aIterator, otMacFilterEntry *aEntry); /** - * Adds a fixed received signal strength (in dBm) entry for the messages from a given Extended Address in - * MAC Filter. + * Adds the specified Extended Address to the `RssIn` list (or modifies an existing + * address in the `RssIn` list) and sets the received signal strength (in dBm) entry + * for messages from that address. The Extended Address does not necessarily have + * to be in the `address allowlist/denylist` filter to set the `rss`. + * @note The `RssIn` list contains Extended Addresses whose `rss` or link quality indicator (`lqi`) + * values have been set to be different from the defaults. * * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * @@ -804,11 +808,14 @@ otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *a otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddress, int8_t aRss); /** - * Removes a MAC Filter entry for fixed received signal strength setting for a given Extended Address. + * Removes the specified Extended Address from the `RssIn` list. Once removed + * from the `RssIn` list, this MAC address will instead use the default `rss` + * and `lqi` settings, assuming defaults have been set. + * (If no defaults have been set, the over-air signal is used.) * * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * - * No action is performed if there is no existing entry in Filter matching the given Extended Address. + * No action is performed if there is no existing entry in the `RssIn` list matching the specified Extended Address. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. @@ -841,7 +848,9 @@ void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss); void otLinkFilterClearDefaultRssIn(otInstance *aInstance); /** - * Clears all the received signal strength entries (including default RSS-in) on MAC Filter. + * Clears all the received signal strength (`rss`) and link quality + * indicator (`lqi`) entries (including defaults) from the `RssIn` list. + * Performing this action means that all Extended Addresses will use the on-air signal. * * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * diff --git a/src/cli/README.md b/src/cli/README.md index 2f44e3dc8..21a3dbf0b 100644 --- a/src/cli/README.md +++ b/src/cli/README.md @@ -3954,7 +3954,7 @@ Done ``` ```bash -> macfilter rss add 0f6127e33af6b404 2 +> macfilter rss add-lqi 0f6127e33af6b404 2 Done ``` diff --git a/src/cli/cli_mac_filter.cpp b/src/cli/cli_mac_filter.cpp index 95cf1c227..547fbed5b 100644 --- a/src/cli/cli_mac_filter.cpp +++ b/src/cli/cli_mac_filter.cpp @@ -288,6 +288,26 @@ exit: return error; } +/** + * @cli macfilter rss + * @code + * macfilter rss + * 0f6127e33af6b403 : rss -95 (lqi 1) + * Default rss: -50 (lqi 3) + * Done + * @endcode + * @par + * Provides the following information: + * - Listing of all the extended addresses + * where the received signal strength (`rss`) has been set to be different from + * the default value. The link quality indicator (`lqi`) is also shown. The `rss` + * and `lqi` settings map to each other. If you set one, the value of the other + * gets set automatically. This list of addresses is called the `RssIn List`. + * Setting either the `rsi` or the `lqi` adds the corresponding extended address + * to the `RssIn` list. + * - `Default rss`: Shows the default values, if applicable, for the `rss` and `lqi` settings. + * @sa otLinkFilterGetNextRssIn + */ template <> otError MacFilter::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -298,6 +318,32 @@ template <> otError MacFilter::Process(Arg aArgs[]) { OutputFilter(kRssFilter); } + /** + * @cli macfilter rss add-lqi + * @code + * macfilter rss add-lqi * 3 + * Done + * @endcode + * @code + * macfilter rss add-lqi 0f6127e33af6b404 2 + * Done + * @endcode + * @cparam macfilter rss add-lqi @ca{extaddr} @ca{lqi} + * To set a default value for the link quality indicator for all received messages, + * use the `*` for the `extaddr` argument. The allowed range is 0 to 3. + * @par + * Adds the specified Extended Address to the `RssIn` list (or modifies an existing address in the `RssIn` list) + * and sets the fixed link quality indicator for messages from that address. + * The Extended Address + * does not necessarily have to be in the `address allowlist/denylist` filter to set the `lqi`. + * @note The `RssIn` list contains Extended Addresses whose `lqi` or + * received signal strength (`rss`) values have been set to be different from the defaults. + * The `lqi` will automatically get converted to a corresponding `rss` value. + * @par + * This is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. + * @sa otLinkConvertLinkQualityToRss + * @sa otLinkFilterSetDefaultRssIn + */ else if (aArgs[0] == "add-lqi") { uint8_t linkQuality; @@ -316,6 +362,22 @@ template <> otError MacFilter::Process(Arg aArgs[]) error = otLinkFilterAddRssIn(GetInstancePtr(), &extAddr, rss); } } + /** + * @cli macfilter rss add + * @code + * macfilter rss add * -50 + * Done + * @endcode + * @code + * macfilter rss add 0f6127e33af6b404 -85 + * Done + * @endcode + * @cparam macfilter rss add @ca{extaddr} @ca{rss} + * To set a default value for the received signal strength for all received messages, + * use the `*` for the `extaddr` argument. + * @par api_copy + * #otLinkFilterAddRssIn + */ else if (aArgs[0] == "add") { SuccessOrExit(error = aArgs[2].ParseAsInt8(rss)); @@ -330,6 +392,23 @@ template <> otError MacFilter::Process(Arg aArgs[]) error = otLinkFilterAddRssIn(GetInstancePtr(), &extAddr, rss); } } + /** + * @cli macfilter rss remove + * @code + * macfilter rss remove * + * Done + * @endcode + * @code + * macfilter rss remove 0f6127e33af6b404 + * Done + * @endcode + * @cparam macfilter rss remove @ca{extaddr} + * If you wish to remove the default received signal strength and link quality indicator settings, + * use the `*` as the `extaddr`. This unsets the defaults but does not remove + * entries from the `RssIn` list. + * @par api_copy + * #otLinkFilterRemoveRssIn + */ else if (aArgs[0] == "remove") { if (aArgs[1] == "*") @@ -342,6 +421,15 @@ template <> otError MacFilter::Process(Arg aArgs[]) otLinkFilterRemoveRssIn(GetInstancePtr(), &extAddr); } } + /** + * @cli macfilter rss clear + * @code + * macfilter rss clear + * Done + * @endcode + * @par api_copy + * #otLinkFilterClearAllRssIn + */ else if (aArgs[0] == "clear") { otLinkFilterClearAllRssIn(GetInstancePtr());