espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2026-08-07 11:17:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

[docs] add Doxygen tags for CLI commands (macfilter - macfilter addr) (#9424)

Browse Source
This commit is contained in:
jrhodie
2023-09-20 14:43:18 -07:00
committed by GitHub
parent 753b305207
commit 390500639f
3 changed files with 141 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openthread/instance.h
+1 -1
View File
@@ -53,7 +53,7 @@ extern "C" {
* @note This number versions both OpenThread platform and user APIs.
*
*/
#define OPENTHREAD_API_VERSION (358)
#define OPENTHREAD_API_VERSION (359)
/**
* @addtogroup api-instance
include/openthread/link.h
+14 -14
View File
@@ -714,7 +714,7 @@ void otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRe
/**
* Gets the address mode of MAC filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
*
@@ -726,7 +726,7 @@ otMacFilterAddressMode otLinkFilterGetAddressMode(otInstance *aInstance);
/**
* Sets the address mode of MAC filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
* @param[in] aMode The address mode to set.
@@ -737,7 +737,7 @@ void otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aM
/**
* Adds an Extended Address to MAC filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
* @param[in] aExtAddress A pointer to the Extended Address (MUST NOT be NULL).
@@ -751,7 +751,7 @@ otError otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAd
/**
* Removes an Extended Address from MAC filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* 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.
*
@@ -764,7 +764,7 @@ void otLinkFilterRemoveAddress(otInstance *aInstance, const otExtAddress *aExtAd
/**
* Clears all the Extended Addresses from MAC filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
*
@@ -774,7 +774,7 @@ void otLinkFilterClearAddresses(otInstance *aInstance);
/**
* Gets an in-use address filter entry.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
* @param[in,out] aIterator A pointer to the MAC filter iterator context. To get the first in-use address filter
@@ -791,7 +791,7 @@ otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *a
* Adds a fixed received signal strength (in dBm) entry for the messages from a given Extended Address in
* MAC Filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @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.
@@ -806,7 +806,7 @@ otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddr
/**
* Removes a MAC Filter entry for fixed received signal strength setting for a given Extended Address.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* 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.
*
@@ -819,7 +819,7 @@ void otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddr
/**
* Sets the default received signal strength (in dBm) on MAC Filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry
* in the Filter list (added using `otLinkFilterAddRssIn()`).
@@ -833,7 +833,7 @@ void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss);
/**
* Clears any previously set default received signal strength (in dBm) on MAC Filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
*
@@ -843,7 +843,7 @@ void otLinkFilterClearDefaultRssIn(otInstance *aInstance);
/**
* Clears all the received signal strength entries (including default RSS-in) on MAC Filter.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
*
@@ -853,7 +853,7 @@ void otLinkFilterClearAllRssIn(otInstance *aInstance);
/**
* Gets an in-use RssIn filter entry.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @param[in] aInstance A pointer to an OpenThread instance.
* @param[in,out] aIterator A pointer to the MAC filter iterator context. MUST NOT be NULL.
@@ -871,7 +871,7 @@ otError otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIt
/**
* Enables/disables IEEE 802.15.4 radio filter mode.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* The radio filter is mainly intended for testing. It can be used to temporarily block all tx/rx on the 802.15.4 radio.
* When radio filter is enabled, radio is put to sleep instead of receive (to ensure device does not receive any frame
@@ -887,7 +887,7 @@ void otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled);
/**
* Indicates whether the IEEE 802.15.4 radio filter is enabled or not.
*
* Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
*
* @retval TRUE If the radio filter is enabled.
* @retval FALSE If the radio filter is disabled.
src/cli/cli_mac_filter.cpp
+126 -2
View File
@@ -137,10 +137,49 @@ template <> otError MacFilter::Process<Cmd("addr")>(Arg aArgs[])
otError error = OT_ERROR_NONE;
otExtAddress extAddr;
/**
* @cli macfilter addr
* @code
* macfilter addr
* Allowlist
* 0f6127e33af6b403 : rss -95 (lqi 1)
* 0f6127e33af6b402
* Done
* @endcode
* @par
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
* @par
* Provides the following information:
* - Current mode of the MAC filter list: Either `AllowList`, `DenyList,` or `Disabled`
* - A list of all the extended addresses in the filter. The received signal strength (rss) and
* link quality indicator (lqi) are listed next to the address if these values have been set to be
* different from the default values.
* @sa otLinkFilterGetAddressMode
*/
if (aArgs[0].IsEmpty())
{
OutputFilter(kAddressFilter);
}
/**
* @cli macfilter addr add
* @code
* macfilter addr add 0f6127e33af6b403 -95
* Done
* @endcode
* @code
* macfilter addr add 0f6127e33af6b402
* Done
* @endcode
* @cparam macfilter addr add @ca{extaddr} [@ca{rss}]
* @par
* Is available only when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
* @par
* Adds an IEEE 802.15.4 Extended Address to the MAC filter list.
* If you specify the optional `rss` argument, this fixes the received signal strength for messages from the
* address. If you do not use the `rss` option, the address will use whatever default value you have set.
* If you have not set a default, the signal strength will be the over-air signal.
* @sa otLinkFilterAddAddress
*/
else if (aArgs[0] == "add")
{
SuccessOrExit(error = aArgs[1].ParseAsHexString(extAddr.m8));
@@ -156,11 +195,39 @@ template <> otError MacFilter::Process<Cmd("addr")>(Arg aArgs[])
SuccessOrExit(error = otLinkFilterAddRssIn(GetInstancePtr(), &extAddr, rss));
}
}
/**
* @cli macfilter addr remove
* @code
* macfilter addr remove 0f6127e33af6b402
* Done
* @endcode
* @cparam macfilter addr remove @ca{extaddr}
* @par
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
* @par
* This command removes the specified extended address from the MAC filter list.
* @note No action is performed if the specified extended address does not match an entry in the MAC filter list.
* @sa otLinkFilterRemoveAddress
*/
else if (aArgs[0] == "remove")
{
SuccessOrExit(error = aArgs[1].ParseAsHexString(extAddr.m8));
otLinkFilterRemoveAddress(GetInstancePtr(), &extAddr);
}
/**
* @cli macfilter addr clear
* @code
* macfilter addr clear
* Done
* @endcode
* @par
* Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
* @par
* This command clears all the extended addresses from the MAC filter list.
* @note This command does not affect entries in the `RssIn` list. That list contains extended addresses where the
* `rss` has been set to a fixed value that differs from the default.
* @sa otLinkFilterClearAddresses
*/
else if (aArgs[0] == "clear")
{
otLinkFilterClearAddresses(GetInstancePtr());
@@ -168,9 +235,40 @@ template <> otError MacFilter::Process<Cmd("addr")>(Arg aArgs[])
else
{
static const char *const kModeCommands[] = {
"disable", // (0) OT_MAC_FILTER_ADDRESS_MODE_DISABLED
/**
* @cli macfilter addr disable
* @code
* macfilter addr disable
* Done
* @endcode
* @par
* Disables MAC filter modes.
*/
"disable", // (0) OT_MAC_FILTER_ADDRESS_MODE_DISABLED
/**
* @cli macfilter addr allowlist
* @code
* macfilter addr allowlist
* Done
* @endcode
* @par
* Enables the `allowlist` MAC filter mode, which means that only the MAC addresses in the MAC filter list
* will be allowed access.
* @sa otLinkFilterSetAddressMode
*/
"allowlist", // (1) OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST
"denylist", // (2) OT_MAC_FILTER_ADDRESS_MODE_DENYLIST
/**
* @cli macfilter addr denylist
* @code
* macfilter addr denylist
* Done
* @endcode
* @par
* Enables the `denylist` MAC filter mode, which means that all MAC addresses in the MAC filter list
* will be denied access.
* @sa otLinkFilterSetAddressMode
*/
"denylist", // (2) OT_MAC_FILTER_ADDRESS_MODE_DENYLIST
};
for (size_t index = 0; index < OT_ARRAY_LENGTH(kModeCommands); index++)
@@ -276,6 +374,32 @@ otError MacFilter::Process(Arg aArgs[])
otError error = OT_ERROR_INVALID_COMMAND;
const Command *command;
/**
* @cli macfilter
* @code
* macfilter
* Address Mode: Allowlist
* 0f6127e33af6b403 : rss -95 (lqi 1)
* 0f6127e33af6b402
* RssIn List:
* 0f6127e33af6b403 : rss -95 (lqi 1)
* Default rss: -50 (lqi 3)
* Done
* @endcode
* @par
* Provides the following information:
* - `Address Mode`: Current mode of the MAC filter: Either `AllowList`, `DenyList,` or `Disabled`
* - A list of all the extended addresses in the MAC filter list. The received signal strength (rss) and
* link quality indicator (lqi) are listed next to the address if these values have been set to be
* different from the default values.
* - A separate list (`RssIn List`) that shows all the extended addresses where the `rss` has been set to
* be different from the default value.
* - `Default rss`: Shows the default values, if applicable, for the `rss` and `lqi` settings.
* @note An extended address can be in the `RssIn` list without being in the MAC filter list.
* @sa otLinkFilterSetAddressMode
* @sa otLinkFilterGetNextAddress
* @sa otLinkFilterGetNextRssIn
*/
if (aArgs[0].IsEmpty())
{
OutputFilter(kAddressFilter | kRssFilter);