diff --git a/include/openthread/child_supervision.h b/include/openthread/child_supervision.h index 5c0172165..3d47ba1d6 100644 --- a/include/openthread/child_supervision.h +++ b/include/openthread/child_supervision.h @@ -55,7 +55,7 @@ extern "C" { */ /** - * Get the child supervision interval (in seconds). + * Gets the child supervision interval (in seconds). * * Child supervision feature provides a mechanism for parent to ensure that a message is sent to each sleepy child * within the supervision interval. If there is no transmission to the child within the supervision interval, @@ -69,7 +69,7 @@ extern "C" { uint16_t otChildSupervisionGetInterval(otInstance *aInstance); /** - * Set the child supervision interval (in seconds). + * Sets the child supervision interval (in seconds). * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aInterval The supervision interval (in seconds). Zero to disable supervision on parent. @@ -78,7 +78,7 @@ uint16_t otChildSupervisionGetInterval(otInstance *aInstance); void otChildSupervisionSetInterval(otInstance *aInstance, uint16_t aInterval); /** - * Get the supervision check timeout interval (in seconds). + * Gets the supervision check timeout interval (in seconds). * * If the device is a sleepy child and it does not hear from its parent within the specified check timeout, it initiates * the re-attach process (MLE Child Update Request/Response exchange with its parent). @@ -91,7 +91,7 @@ void otChildSupervisionSetInterval(otInstance *aInstance, uint16_t aInterval); uint16_t otChildSupervisionGetCheckTimeout(otInstance *aInstance); /** - * Set the supervision check timeout interval (in seconds). + * Sets the supervision check timeout interval (in seconds). * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aTimeout The check timeout (in seconds). Zero to disable supervision check on the child. diff --git a/include/openthread/instance.h b/include/openthread/instance.h index e065d0666..5eee72d99 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 (237) +#define OPENTHREAD_API_VERSION (238) /** * @addtogroup api-instance diff --git a/include/openthread/thread.h b/include/openthread/thread.h index 451035ba9..0eb4d2f86 100644 --- a/include/openthread/thread.h +++ b/include/openthread/thread.h @@ -305,7 +305,7 @@ otError otThreadSetJoinerAdvertisement(otInstance * aInstance, #define OT_JOINER_ADVDATA_MAX_LENGTH 64 ///< Maximum AdvData Length of Joiner Advertisement /** - * Get the Thread Child Timeout used when operating in the Child role. + * Gets the Thread Child Timeout (in seconds) used when operating in the Child role. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -317,7 +317,7 @@ otError otThreadSetJoinerAdvertisement(otInstance * aInstance, uint32_t otThreadGetChildTimeout(otInstance *aInstance); /** - * Set the Thread Child Timeout used when operating in the Child role. + * Sets the Thread Child Timeout (in seconds) used when operating in the Child role. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aTimeout The timeout value in seconds. diff --git a/include/openthread/thread_ftd.h b/include/openthread/thread_ftd.h index ea052deed..6cb3ddc3d 100644 --- a/include/openthread/thread_ftd.h +++ b/include/openthread/thread_ftd.h @@ -122,7 +122,7 @@ typedef struct otCacheEntryIterator } otCacheEntryIterator; /** - * Get the maximum number of children currently allowed. + * Gets the maximum number of children currently allowed. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -134,7 +134,7 @@ typedef struct otCacheEntryIterator uint16_t otThreadGetMaxAllowedChildren(otInstance *aInstance); /** - * Set the maximum number of children currently allowed. + * Sets the maximum number of children currently allowed. * * This parameter can only be set when Thread protocol operation has been stopped. * @@ -451,7 +451,7 @@ uint8_t otThreadGetRouterSelectionJitter(otInstance *aInstance); void otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter); /** - * The function retains diagnostic information for an attached Child by its Child ID or RLOC16. + * Gets diagnostic information for an attached Child by its Child ID or RLOC16. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aChildId The Child ID or RLOC16 for the attached child. @@ -645,7 +645,7 @@ int8_t otThreadGetParentPriority(otInstance *aInstance); otError otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority); /** - * This function gets the maximum number of IP addresses that each MTD child may register with this device as parent. + * Gets the maximum number of IP addresses that each MTD child may register with this device as parent. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -657,11 +657,15 @@ otError otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority) uint8_t otThreadGetMaxChildIpAddresses(otInstance *aInstance); /** - * This function sets/restores the maximum number of IP addresses that each MTD child may register with this + * Sets or restores the maximum number of IP addresses that each MTD child may register with this * device as parent. * - * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness - * to limit the address registrations of the reference parent in order to test the MTD DUT reaction. + * Pass `0` to clear the setting and restore the default. + * + * Available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. + * + * @note Only used by Thread Test Harness to limit the address registrations of the reference + * parent in order to test the MTD DUT reaction. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMaxIpAddresses The maximum number of IP addresses that each MTD child may register with this diff --git a/src/cli/cli.cpp b/src/cli/cli.cpp index c0e258fe9..5217b79e8 100644 --- a/src/cli/cli.cpp +++ b/src/cli/cli.cpp @@ -1715,6 +1715,20 @@ template <> otError Interpreter::Process(Arg aArgs[]) { uint16_t maxChildren; + /** + * @cli child table + * @code + * child table + * | ID | RLOC16 | Timeout | Age | LQ In | C_VN |R|D|N|Ver|CSL|QMsgCnt| Extended MAC | + * +-----+--------+------------+------------+-------+------+-+-+-+---+---+-------+------------------+ + * | 1 | 0xc801 | 240 | 24 | 3 | 131 |1|0|0| 3| 0 | 0 | 4ecede68435358ac | + * | 2 | 0xc802 | 240 | 2 | 3 | 131 |0|0|0| 3| 1 | 0 | a672a601d2ce37d8 | + * Done + * @endcode + * @par + * Prints a table of the attached children. + * @sa otThreadGetChildInfoByIndex + */ if (isTable) { static const char *const kChildTableTitles[] = { @@ -1757,6 +1771,17 @@ template <> otError Interpreter::Process(Arg aArgs[]) OutputExtAddress(childInfo.mExtAddress); OutputLine(" |"); } + /** + * @cli child list + * @code + * child list + * 1 2 3 6 7 8 + * Done + * @endcode + * @par + * Returns a list of attached Child IDs. + * @sa otThreadGetChildInfoByIndex + */ else { OutputFormat("%d ", childInfo.mChildId); @@ -1770,6 +1795,25 @@ template <> otError Interpreter::Process(Arg aArgs[]) SuccessOrExit(error = aArgs[0].ParseAsUint16(childId)); SuccessOrExit(error = otThreadGetChildInfoById(GetInstancePtr(), childId, &childInfo)); + /** + * @cli child (id) + * @code + * child 1 + * Child ID: 1 + * Rloc: 9c01 + * Ext Addr: e2b3540590b0fd87 + * Mode: rn + * Net Data: 184 + * Timeout: 100 + * Age: 0 + * Link Quality In: 3 + * RSSI: -20 + * Done + * @endcode + * @cparam child @ca{child-id} + * @par api_copy + * #otThreadGetChildInfoById + */ OutputLine("Child ID: %d", childInfo.mChildId); OutputLine("Rloc: %04x", childInfo.mRloc16); OutputFormat("Ext Addr: "); @@ -1792,6 +1836,17 @@ template <> otError Interpreter::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; + /** + * @cli childip + * @code + * childip + * 3401: fdde:ad00:beef:0:3037:3e03:8c5f:bc0c + * Done + * @endcode + * @par + * Gets a list of IP addresses stored for MTD children. + * @sa otThreadGetChildNextIp6Address + */ if (aArgs[0].IsEmpty()) { uint16_t maxChildren = otThreadGetMaxAllowedChildren(GetInstancePtr()); @@ -1818,11 +1873,31 @@ template <> otError Interpreter::Process(Arg aArgs[]) } } } + /** + * @cli childip max + * @code + * childip max + * 4 + * Done + * @endcode + * @par api_copy + * #otThreadGetMaxChildIpAddresses + */ else if (aArgs[0] == "max") { #if !OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE error = ProcessGet(aArgs + 1, otThreadGetMaxChildIpAddresses); #else + /** + * @cli childip max (set) + * @code + * childip max 2 + * Done + * @endcode + * @cparam childip max @ca{count} + * @par api_copy + * #otThreadSetMaxChildIpAddresses + */ error = ProcessGetSet(aArgs + 1, otThreadGetMaxChildIpAddresses, otThreadSetMaxChildIpAddresses); #endif } @@ -1834,8 +1909,28 @@ template <> otError Interpreter::Process(Arg aArgs[]) return error; } +/** + * @cli childmax + * @code + * childmax + * 5 + * Done + * @endcode + * @par api_copy + * #otThreadGetMaxAllowedChildren + */ template <> otError Interpreter::Process(Arg aArgs[]) { + /** + * @cli childmax (set) + * @code + * childmax 2 + * Done + * @endcode + * @cparam childmax @ca{count} + * @par api_copy + * #otThreadSetMaxAllowedChildren + */ return ProcessGetSet(aArgs, otThreadGetMaxAllowedChildren, otThreadSetMaxAllowedChildren); } #endif // OPENTHREAD_FTD @@ -1845,13 +1940,56 @@ template <> otError Interpreter::Process(Arg aArgs[]) { otError error = OT_ERROR_INVALID_ARGS; + /** + * @cli childsupervision checktimeout + * @code + * childsupervision checktimeout + * 30 + * Done + * @endcode + * @par api_copy + * #otChildSupervisionGetCheckTimeout + */ if (aArgs[0] == "checktimeout") { + /** @cli childsupervision checktimeout (set) + * @code + * childsupervision checktimeout 30 + * Done + * @endcode + * @cparam childsupervision checktimeout @ca{timeout-seconds} + * @par api_copy + * #otChildSupervisionSetCheckTimeout + */ error = ProcessGetSet(aArgs + 1, otChildSupervisionGetCheckTimeout, otChildSupervisionSetCheckTimeout); } #if OPENTHREAD_FTD + /** + * @cli childsupervision interval + * @code + * childsupervision interval + * 30 + * Done + * @endcode + * @par + * This command can only be used with FTD devices. + * @par api_copy + * #otChildSupervisionGetInterval + */ else if (aArgs[0] == "interval") { + /** + * @cli childsupervision interval (set) + * @code + * childsupervision interval 30 + * Done + * @endcode + * @cparam childsupervision interval @ca{interval-seconds} + * @par + * This command can only be used with FTD devices. + * @par api_copy + * #otChildSupervisionSetInterval + */ error = ProcessGetSet(aArgs + 1, otChildSupervisionGetInterval, otChildSupervisionSetInterval); } #endif @@ -1860,8 +1998,26 @@ template <> otError Interpreter::Process(Arg aArgs[]) } #endif // OPENTHREAD_CONFIG_CHILD_SUPERVISION_ENABLE +/** @cli childtimeout + * @code + * childtimeout + * 300 + * Done + * @endcode + * @par api_copy + * #otThreadGetChildTimeout + */ template <> otError Interpreter::Process(Arg aArgs[]) { + /** @cli childtimeout (set) + * @code + * childtimeout 300 + * Done + * @endcode + * @cparam childtimeout @ca{timeout-seconds} + * @par api_copy + * #otThreadSetChildTimeout + */ return ProcessGetSet(aArgs, otThreadGetChildTimeout, otThreadSetChildTimeout); }