espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2026-08-21 01:49:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

[api] update descriptions of the radio platform power APIs (#10839)

Browse Source 
Current radio platform defines three power related APIs:
`otPlatRadioSetTransmitPower()`, `otPlatRadioSetChannelMaxTransmitPower()`
and `otPlatRadioSetChannelTargetPower()`. However, the descriptions of
these APIs do not clearly define the relationship between them, which
causes a lot of confusion for radio platform developers.

https://github.com/orgs/openthread/discussions/10761
https://github.com/orgs/openthread/discussions/10611
https://github.com/orgs/openthread/discussions/9899

This commit updates the descriptions these APIs to clearly define
the relationship between these power APIs.
This commit is contained in:
Zhanglong Xia
2024-10-21 22:50:49 +01:00
committed by GitHub
parent 5bd9de5f30
commit c519aa4534
2 changed files with 9 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openthread/instance.h
+1 -1
View File
@@ -52,7 +52,7 @@ extern "C" {
*
* @note This number versions both OpenThread platform and user APIs.
*/
#define OPENTHREAD_API_VERSION (455)
#define OPENTHREAD_API_VERSION (456)
/**
* @addtogroup api-instance
include/openthread/platform/radio.h
+8 -3
View File
@@ -533,10 +533,10 @@ void otPlatRadioSetShortAddress(otInstance *aInstance, otShortAddress aShortAddr
otError otPlatRadioGetTransmitPower(otInstance *aInstance, int8_t *aPower);
/**
* Set the radio's transmit power in dBm.
* Set the radio's transmit power in dBm for all channels.
*
* @note The real transmit power will be no larger than the power specified in the max power table for
* the current channel.
* the current channel that was configured by `otPlatRadioSetChannelMaxTransmitPower()`.
*
* @param[in] aInstance The OpenThread instance structure.
* @param[in] aPower The transmit power in dBm.
@@ -1185,6 +1185,9 @@ uint8_t otPlatRadioGetCslUncertainty(otInstance *aInstance);
/**
* Set the max transmit power for a specific channel.
*
* @note This function will be deprecated in October 2027. It is recommended to use the function
* `otPlatRadioSetChannelTargetPower()`.
*
* @param[in] aInstance The OpenThread instance structure.
* @param[in] aChannel The radio channel.
* @param[in] aMaxPower The max power in dBm, passing OT_RADIO_RSSI_INVALID will disable this channel.
@@ -1300,7 +1303,9 @@ otError otPlatRadioClearCalibratedPowers(otInstance *aInstance);
* Set the target power for the given channel.
*
* @note This API is an optional radio platform API. It's up to the platform layer to implement it.
* If this API is implemented, the function `otPlatRadioSetTransmitPower()` should be disabled.
* If this function and `otPlatRadioSetTransmitPower()` are implemented at the same time:
* - If neither of these two functions is called, the radio outputs the platform-defined default power.
* - If both functions are called, the last one to be called takes effect.
*
* The radio driver should set the actual output power to be less than or equal to the @p aTargetPower and as close
* as possible to the @p aTargetPower. If the @p aTargetPower is lower than the minimum output power supported