From 176be056446c14e6c724cedc7485cfeebdf8e431 Mon Sep 17 00:00:00 2001 From: jrhodie <139580534+jrhodie@users.noreply.github.com> Date: Wed, 31 Jan 2024 11:07:51 -0800 Subject: [PATCH] [cli] commissioner commands (#9798) --- src/cli/cli_commissioner.cpp | 228 +++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) diff --git a/src/cli/cli_commissioner.cpp b/src/cli/cli_commissioner.cpp index d8fa14a09..b7c04d3b7 100644 --- a/src/cli/cli_commissioner.cpp +++ b/src/cli/cli_commissioner.cpp @@ -40,6 +40,24 @@ namespace ot { namespace Cli { +/** + * @cli commissioner announce + * @code + * commissioner announce 0x00050000 2 32 fdde:ad00:beef:0:0:ff:fe00:c00 + * Done + * @endcode + * @cparam commissioner announce @ca{mask} @ca{count} @ca{period} @ca{destination} + * * `mask`: Bitmask that identifies channels for sending MLE `Announce` messages. + * * `count`: Number of MLE `Announce` transmissions per channel. + * * `period`: Number of milliseconds between successive MLE `Announce` transmissions. + * * `destination`: Destination IPv6 address for the message. The message may be multicast. + * @par + * Sends an Announce Begin message. + * @note Use this command only after successfully starting the %Commissioner role + * with the `commissioner start` command. + * @csa{commissioner start} + * @sa otCommissionerAnnounceBegin + */ template <> otError Commissioner::Process(Arg aArgs[]) { otError error; @@ -59,6 +77,27 @@ exit: return error; } +/** + * @cli commissioner energy + * @code + * commissioner energy 0x00050000 2 32 1000 fdde:ad00:beef:0:0:ff:fe00:c00 + * Done + * Energy: 00050000 0 0 0 0 + * @endcode + * @cparam commissioner energy @ca{mask} @ca{count} @ca{period} @ca{scanDuration} @ca{destination} + * * `mask`: Bitmask that identifies channels for performing IEEE 802.15.4 energy scans. + * * `count`: Number of IEEE 802.15.4 energy scans per channel. + * * `period`: Number of milliseconds between successive IEEE 802.15.4 energy scans. + * * `scanDuration`: Scan duration in milliseconds to use when + * performing an IEEE 802.15.4 energy scan. + * * `destination`: Destination IPv6 address for the message. The message may be multicast. + * @par + * Sends an Energy Scan Query message. Command output is printed as it is received. + * @note Use this command only after successfully starting the %Commissioner role + * with the `commissioner start` command. + * @csa{commissioner start} + * @sa otCommissionerEnergyScan + */ template <> otError Commissioner::Process(Arg aArgs[]) { otError error; @@ -88,6 +127,20 @@ template <> otError Commissioner::Process(Arg aArgs[]) const otExtAddress *addrPtr = nullptr; otJoinerDiscerner discerner; + /** + * @cli commissioner joiner table + * @code + * commissioner joiner table + * | ID | PSKd | Expiration | + * +-----------------------+----------------------------------+------------+ + * | * | J01NME | 81015 | + * | d45e64fa83f81cf7 | J01NME | 101204 | + * | 0x0000000000000abc/12 | J01NME | 114360 | + * Done + * @endcode + * @par + * Lists all %Joiner entries in table format. + */ if (aArgs[0] == "table") { uint16_t iter = 0; @@ -152,6 +205,29 @@ template <> otError Commissioner::Process(Arg aArgs[]) SuccessOrExit(error); } + /** + * @cli commissioner joiner add + * @code + * commissioner joiner add d45e64fa83f81cf7 J01NME + * Done + * @endcode + * @code + * commissioner joiner add 0xabc/12 J01NME + * Done + * @endcode + * @cparam commissioner joiner add @ca{eui64}|@ca{discerner pksd} [@ca{timeout}] + * * `eui64`: IEEE EUI-64 of the %Joiner. To match any joiner, use `*`. + * * `discerner`: The %Joiner discerner in the format `number/length`. + * * `pksd`: Pre-Shared Key for the joiner. + * * `timeout`: The %Joiner timeout in seconds. + * @par + * Adds a joiner entry. + * @note Use this command only after successfully starting the %Commissioner role + * with the `commissioner start` command. + * @csa{commissioner start} + * @sa otCommissionerAddJoiner + * @sa otCommissionerAddJoinerWithDiscerner + */ if (aArgs[0] == "add") { uint32_t timeout = kDefaultJoinerTimeout; @@ -171,6 +247,27 @@ template <> otError Commissioner::Process(Arg aArgs[]) { error = otCommissionerAddJoiner(GetInstancePtr(), addrPtr, aArgs[2].GetCString(), timeout); } + /** + * @cli commissioner joiner remove + * @code + * commissioner joiner remove d45e64fa83f81cf7 + * Done + * @endcode + * @code + * commissioner joiner remove 0xabc/12 + * Done + * @endcode + * @cparam commissioner joiner remove @ca{eui64}|@ca{discerner} + * * `eui64`: IEEE EUI-64 of the joiner. To match any joiner, use `*`. + * * `discerner`: The joiner discerner in the format `number/length`. + * @par + * Removes a %Joiner entry. + * @note Use this command only after successfully starting the %Commissioner role + * with the `commissioner start` command. + * @csa{commissioner start} + * @sa otCommissionerRemoveJoiner + * @sa otCommissionerRemoveJoinerWithDiscerner + */ } else if (aArgs[0] == "remove") { @@ -192,6 +289,25 @@ exit: return error; } +/** + * @cli commissioner mgmtget + * @code + * commissioner mgmtget locator sessionid + * Done + * @endcode + * @cparam commissioner mgmtget [locator] [sessionid] [steeringdata] [joinerudpport] [-x @ca{TLVs}] + * * `locator`: Border Router RLOC16. + * * `sessionid`: Session ID of the %Commissioner. + * * `steeringdata`: Steering data. + * * `joinerudpport`: %Joiner UDP port. + * * `TLVs`: The set of TLVs to be retrieved. + * @par + * Sends a `MGMT_GET` (Management Get) message to the Leader. + * Variable values that have been set using the `commissioner mgmtset` command are returned. + * @sa otCommissionerSendMgmtGet + */ template <> otError Commissioner::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -239,6 +355,25 @@ exit: return error; } +/** + * @cli commissioner mgmtset + * @code + * commissioner mgmtset joinerudpport 9988 + * Done + * @endcode + * @cparam commissioner mgmtset [locator @ca{locator}] [sessionid @ca{sessionid}] [steeringdata @ca{steeringdata}] [joinerudpport @ca{joinerudpport}] [-x @ca{TLVs}] + * * `locator`: Border Router RLOC16. + * * `sessionid`: Session ID of the %Commissioner. + * * `steeringdata`: Steering data. + * * `joinerudpport`: %Joiner UDP port. + * * `TLVs`: The set of TLVs to be retrieved. + * @par + * Sends a `MGMT_SET` (Management Set) message to the Leader, and sets the + * variables to the values specified. + * @sa otCommissionerSendMgmtSet + */ template <> otError Commissioner::Process(Arg aArgs[]) { otError error; @@ -301,6 +436,25 @@ exit: return error; } +/** + * @cli commissioner panid + * @code + * commissioner panid 0xdead 0x7fff800 fdde:ad00:beef:0:0:ff:fe00:c00 + * Done + * Conflict: dead, 00000800 + * @endcode + * @cparam commissioner panid @ca{panid} @ca{mask} @ca{destination} + * * `paind`: PAN ID to use to check for conflicts. + * * `mask`; Bitmask that identifies channels to perform IEEE 802.15.4 + * Active Scans. + * * `destination`: IPv6 destination address for the message. The message may be multicast. + * @par + * Sends a PAN ID query. Command output is returned as it is received. + * @note Use this command only after successfully starting the %Commissioner role + * with the `commissioner start` command. + * @csa{commissioner start} + * @sa otCommissionerPanIdQuery + */ template <> otError Commissioner::Process(Arg aArgs[]) { otError error; @@ -318,6 +472,17 @@ exit: return error; } +/** + * @cli commissioner provisioningurl + * @code + * commissioner provisioningurl http://github.com/openthread/openthread + * Done + * @endcode + * @cparam commissioner provisioningurl @ca{provisioningurl} + * @par + * Sets the %Commissioner provisioning URL. + * @sa otCommissionerSetProvisioningUrl + */ template <> otError Commissioner::Process(Arg aArgs[]) { // If aArgs[0] is empty, `GetCString() will return `nullptr` @@ -325,6 +490,17 @@ template <> otError Commissioner::Process(Arg aArgs[]) return otCommissionerSetProvisioningUrl(GetInstancePtr(), aArgs[0].GetCString()); } +/** + * @cli commissioner sessionid + * @code + * commissioner sessionid + * 0 + * Done + * @endcode + * @par + * Gets the current %Commissioner session ID. + * @sa otCommissionerGetSessionId + */ template <> otError Commissioner::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs); @@ -334,6 +510,22 @@ template <> otError Commissioner::Process(Arg aArgs[]) return OT_ERROR_NONE; } +/** + * @cli commissioner id (get,set) + * @code + * commissioner id OpenThread Commissioner + * Done + * @endcode + * @code + * commissioner id + * OpenThread Commissioner + * Done + * @endcode + * @cparam commissioner id @ca{name} + * @par + * Gets or sets the OpenThread %Commissioner ID name. + * @sa otCommissionerSetId + */ template <> otError Commissioner::Process(Arg aArgs[]) { otError error; @@ -351,6 +543,20 @@ template <> otError Commissioner::Process(Arg aArgs[]) return error; } +/** + * @cli commissioner start + * @code + * commissioner start + * Commissioner: petitioning + * Done + * Commissioner: active + * @endcode + * @par + * Starts the Thread %Commissioner role. + * @note The `commissioner` commands are available only when + * `OPENTHREAD_CONFIG_COMMISSIONER_ENABLE` and `OPENTHREAD_FTD` are set. + * @sa otCommissionerStart + */ template <> otError Commissioner::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs); @@ -422,6 +628,16 @@ void Commissioner::HandleJoinerEvent(otCommissionerJoinerEvent aEvent, OutputNewLine(); } +/** + * @cli commissioner stop + * @code + * commissioner stop + * Done + * @endcode + * @par + * Stops the Thread %Commissioner role. + * @sa otCommissionerStop + */ template <> otError Commissioner::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs); @@ -429,6 +645,18 @@ template <> otError Commissioner::Process(Arg aArgs[]) return otCommissionerStop(GetInstancePtr()); } +/** + * @cli commissioner state + * @code + * commissioner state + * active + * Done + * @endcode + * @par + * Returns the current state of the %Commissioner. Possible values are + * `active`, `disabled`, or `petition` (petitioning to become %Commissioner). + * @sa otCommissionerState + */ template <> otError Commissioner::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs);