[posix] add power calibration support (openthread#8293)

The actual output power of the Thread device may be determined by both
the Thread radio chip and the FEM. Consider the output power error of
the Thread radio chip and the gain error of the FEM, the actual output
power is inconsistent with the expected output power.  To guarantee
that the actual output power is accurate and meet the regulatory
requirements, the output power should be calibrated in the factory if
the output power is not accurate.

This commit contains the following changes:

- Adds a power calibration implementation
- Adds a config file to configure the target power for different
  countries
- Adds a tool for the factory to persist the power calibration data

.github/workflows/posix.yml

@@ -65,6 +65,10 @@ jobs:
         ulimit -c unlimited
         ./script/test prepare_coredump_upload
         OT_OPTIONS='-DOT_READLINE=OFF -DOT_FULL_LOGS=ON -DOT_LOG_OUTPUT=PLATFORM_DEFINED' VIRTUAL_TIME=0 OT_NODE_TYPE=rcp ./script/test build expect
+    - name: Run ot-fct
+      run: |
+        OT_CMAKE_NINJA_TARGET="ot-fct" script/cmake-build posix
+        tests/scripts/expect/ot-fct.exp
     - name: Check Crash
       if: ${{ failure() }}
       run: |

Android.mk

@@ -373,6 +373,7 @@ LOCAL_SRC_FILES                                                  := \
     src/core/utils/otns.cpp                                         \
     src/core/utils/parse_cmdline.cpp                                \
     src/core/utils/ping_sender.cpp                                  \
+    src/core/utils/power_calibration.cpp                            \
     src/core/utils/slaac_address.cpp                                \
     src/core/utils/srp_client_buffers.cpp                           \
     src/lib/hdlc/hdlc.cpp                                           \
@@ -384,6 +385,7 @@ LOCAL_SRC_FILES                                                  := \
     src/posix/platform/alarm.cpp                                    \
     src/posix/platform/backbone.cpp                                 \
     src/posix/platform/backtrace.cpp                                \
+    src/posix/platform/config_file.cpp                              \
     src/posix/platform/daemon.cpp                                   \
     src/posix/platform/entropy.cpp                                  \
     src/posix/platform/firewall.cpp                                 \
@@ -395,6 +397,8 @@ LOCAL_SRC_FILES                                                  := \
     src/posix/platform/misc.cpp                                     \
     src/posix/platform/multicast_routing.cpp                        \
     src/posix/platform/netif.cpp                                    \
+    src/posix/platform/power.cpp                                    \
+    src/posix/platform/power_updater.cpp                            \
     src/posix/platform/radio.cpp                                    \
     src/posix/platform/radio_url.cpp                                \
     src/posix/platform/settings.cpp                                 \
@@ -656,6 +660,43 @@ LOCAL_SRC_FILES := src/posix/client.cpp
 include $(BUILD_EXECUTABLE)
 endif # ($(USE_OTBR_DAEMON), 1)
 
+include $(CLEAR_VARS)
+
+LOCAL_MODULE := ot-fct
+LOCAL_MODULE_TAGS := eng
+
+LOCAL_CPPFLAGS                                            := \
+    -std=c++11                                               \
+    -pedantic-errors                                         \
+    $(NULL)
+
+LOCAL_CFLAGS                                              := \
+    $(OPENTHREAD_PUBLIC_CFLAGS)                              \
+    $(OPENTHREAD_PRIVATE_CFLAGS)                             \
+    $(OPENTHREAD_PROJECT_CFLAGS)                             \
+    $(NULL)
+
+LOCAL_C_INCLUDES                                         := \
+    $(OPENTHREAD_PROJECT_INCLUDES)                          \
+    $(LOCAL_PATH)/include                                   \
+    $(LOCAL_PATH)/src/                                      \
+    $(LOCAL_PATH)/src/core                                  \
+    $(LOCAL_PATH)/src/posix/platform                        \
+    $(NULL)
+
+LOCAL_SRC_FILES                                          := \
+    src/core/common/string.cpp                              \
+    src/core/utils/parse_cmdline.cpp                        \
+    src/lib/platform/exit_code.c                            \
+    src/posix/platform/config_file.cpp                      \
+    src/posix/platform/power.cpp                            \
+    tools/ot-fct/cli.cpp                                    \
+    tools/ot-fct/logging.cpp                                \
+    tools/ot-fct/main.cpp                                   \
+    $(NULL)
+
+include $(BUILD_EXECUTABLE)
+
 ifneq ($(OPENTHREAD_PROJECT_ANDROID_MK),)
 include $(OPENTHREAD_PROJECT_ANDROID_MK)
 endif

CMakeLists.txt

@@ -209,6 +209,7 @@ if(OT_PLATFORM STREQUAL "simulation")
 endif()
 
 add_subdirectory(tests)
+add_subdirectory(tools)
 
 add_custom_target(print-ot-config ALL
                   COMMAND ${CMAKE_COMMAND}

examples/platforms/simulation/openthread-core-simulation-config.h

@@ -265,4 +265,24 @@
 #define OPENTHREAD_CONFIG_DETERMINISTIC_ECDSA_ENABLE 1
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_POWER_CALIBRATION_ENABLE
+ *
+ * Define as 1 to enable power calibration support.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_POWER_CALIBRATION_ENABLE
+#define OPENTHREAD_CONFIG_POWER_CALIBRATION_ENABLE 1
+#endif
+
+/**
+ * @def OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE
+ *
+ * Define as 1 to enable platform power calibration support.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE
+#define OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE 1
+#endif
+
 #endif // OPENTHREAD_CORE_SIMULATION_CONFIG_H_

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (270)
+#define OPENTHREAD_API_VERSION (271)
 
 /**
  * @addtogroup api-instance

include/openthread/platform/radio.h

@@ -1144,6 +1144,100 @@ otError otPlatRadioConfigureEnhAckProbing(otInstance         *aInstance,
                                           otShortAddress      aShortAddress,
                                           const otExtAddress *aExtAddress);
 
+/**
+ * Add a calibrated power of the specified channel to the power calibration table.
+ *
+ * @note This API is an optional radio platform API. It's up to the platform layer to implement it.
+ *
+ * The @p aActualPower is the actual measured output power when the parameters of the radio hardware modules
+ * are set to the @p aRawPowerSetting.
+ *
+ * The raw power setting is an opaque byte array. OpenThread doesn't define the format of the raw power setting.
+ * Its format is radio hardware related and it should be defined by the developers in the platform radio driver.
+ * For example, if the radio hardware contains both the radio chip and the FEM chip, the raw power setting can be
+ * a combination of the radio power register and the FEM gain value.
+ *
+ * @param[in] aInstance               The OpenThread instance structure.
+ * @param[in] aChannel                The radio channel.
+ * @param[in] aActualPower            The actual power in 0.01dBm.
+ * @param[in] aRawPowerSetting        A pointer to the raw power setting byte array.
+ * @param[in] aRawPowerSettingLength  The length of the @p aRawPowerSetting.
+ *
+ * @retval OT_ERROR_NONE             Successfully added the calibrated power to the power calibration table.
+ * @retval OT_ERROR_NO_BUFS          No available entry in the power calibration table.
+ * @retval OT_ERROR_INVALID_ARGS     The @p aChannel, @p aActualPower or @p aRawPowerSetting is invalid or the
+ *                                   @p aActualPower already exists in the power calibration table.
+ * @retval OT_ERROR_NOT_IMPLEMENTED  This feature is not implemented.
+ *
+ */
+otError otPlatRadioAddCalibratedPower(otInstance    *aInstance,
+                                      uint8_t        aChannel,
+                                      int16_t        aActualPower,
+                                      const uint8_t *aRawPowerSetting,
+                                      uint16_t       aRawPowerSettingLength);
+
+/**
+ * Clear all calibrated powers from the power calibration table.
+ *
+ * @note This API is an optional radio platform API. It's up to the platform layer to implement it.
+ *
+ * @param[in]  aInstance   The OpenThread instance structure.
+ *
+ * @retval OT_ERROR_NONE             Successfully cleared all calibrated powers from the power calibration table.
+ * @retval OT_ERROR_NOT_IMPLEMENTED  This feature is not implemented.
+ *
+ */
+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.
+ *
+ * The radio driver should set the actual output power to be less than or equal to the target power and as close
+ * as possible to the target power.
+ *
+ * @param[in]  aInstance     The OpenThread instance structure.
+ * @param[in]  aChannel      The radio channel.
+ * @param[in]  aTargetPower  The target power in 0.01dBm. Passing `INT16_MAX` will disable this channel to use the
+ *                           target power.
+ *
+ * @retval  OT_ERROR_NONE             Successfully set the target power.
+ * @retval  OT_ERROR_INVALID_ARGS     The @p aChannel or @p aTargetPower is invalid.
+ * @retval  OT_ERROR_NOT_IMPLEMENTED  The feature is not implemented.
+ *
+ */
+otError otPlatRadioSetChannelTargetPower(otInstance *aInstance, uint8_t aChannel, int16_t aTargetPower);
+
+/**
+ * Get the raw power setting for the given channel.
+ *
+ * @note OpenThread `src/core/utils` implements a default implementation of the API `otPlatRadioAddCalibratedPower()`,
+ *       `otPlatRadioClearCalibratedPowers()` and `otPlatRadioSetChannelTargetPower()`. This API is provided by
+ *       the default implementation to get the raw power setting for the given channel. If the platform doesn't
+ *       use the default implementation, it can ignore this API.
+ *
+ * Platform radio layer should parse the raw power setting based on the radio layer defined format and set the
+ * parameters of each radio hardware module.
+ *
+ * @param[in]      aInstance               The OpenThread instance structure.
+ * @param[in]      aChannel                The radio channel.
+ * @param[out]     aRawPowerSetting        A pointer to the raw power setting byte array.
+ * @param[in,out]  aRawPowerSettingLength  On input, a pointer to the size of @p aRawPowerSetting.
+ *                                         On output, a pointer to the length of the raw power setting data.
+ *
+ * @retval  OT_ERROR_NONE          Successfully got the target power.
+ * @retval  OT_ERROR_INVALID_ARGS  The @p aChannel is invalid, @p aRawPowerSetting or @p aRawPowerSettingLength is NULL
+ *                                 or @aRawPowerSettingLength is too short.
+ * @retval  OT_ERROR_NOT_FOUND     The raw power setting for the @p aChannel was not found.
+ *
+ */
+extern otError otPlatRadioGetRawPowerSetting(otInstance *aInstance,
+                                             uint8_t     aChannel,
+                                             uint8_t    *aRawPowerSetting,
+                                             uint16_t   *aRawPowerSettingLength);
+
 /**
  * @}
  *

src/core/BUILD.gn

@@ -706,6 +706,8 @@ openthread_core_files = [
   "utils/parse_cmdline.hpp",
   "utils/ping_sender.cpp",
   "utils/ping_sender.hpp",
+  "utils/power_calibration.cpp",
+  "utils/power_calibration.hpp",
   "utils/slaac_address.cpp",
   "utils/slaac_address.hpp",
   "utils/srp_client_buffers.cpp",
@@ -745,6 +747,7 @@ openthread_radio_sources = [
   "radio/radio_platform.cpp",
   "thread/link_quality.cpp",
   "utils/parse_cmdline.cpp",
+  "utils/power_calibration.cpp",
 ]
 
 header_pattern = [
@@ -791,6 +794,7 @@ source_set("libopenthread_core_config") {
     "config/parent_search.h",
     "config/ping_sender.h",
     "config/platform.h",
+    "config/power_calibration.h",
     "config/radio_link.h",
     "config/sntp_client.h",
     "config/srp_client.h",

src/core/CMakeLists.txt

@@ -240,6 +240,7 @@ set(COMMON_SOURCES
     utils/otns.cpp
     utils/parse_cmdline.cpp
     utils/ping_sender.cpp
+    utils/power_calibration.cpp
     utils/slaac_address.cpp
     utils/srp_client_buffers.cpp
 )
@@ -276,6 +277,7 @@ set(RADIO_COMMON_SOURCES
     radio/radio_platform.cpp
     thread/link_quality.cpp
     utils/parse_cmdline.cpp
+    utils/power_calibration.cpp
 )
 
 set(OT_VENDOR_EXTENSION "" CACHE STRING "specify a C++ source file built as part of OpenThread core library")

src/core/Makefile.am

@@ -330,6 +330,7 @@ SOURCES_COMMON                                  = \
     utils/otns.cpp                                \
     utils/parse_cmdline.cpp                       \
     utils/ping_sender.cpp                         \
+    utils/power_calibration.cpp                   \
     utils/slaac_address.cpp                       \
     utils/srp_client_buffers.cpp                  \
     $(NULL)
@@ -366,6 +367,7 @@ RADIO_SOURCES_COMMON                       = \
     radio/radio_platform.cpp                 \
     thread/link_quality.cpp                  \
     utils/parse_cmdline.cpp                  \
+    utils/power_calibration.cpp              \
     $(NULL)
 
 EXTRA_DIST                                 = \
@@ -514,6 +516,7 @@ HEADERS_COMMON                                  = \
     config/parent_search.h                        \
     config/ping_sender.h                          \
     config/platform.h                             \
+    config/power_calibration.h                    \
     config/radio_link.h                           \
     config/sntp_client.h                          \
     config/srp_client.h                           \
@@ -649,6 +652,7 @@ HEADERS_COMMON                                  = \
     utils/otns.hpp                                \
     utils/parse_cmdline.hpp                       \
     utils/ping_sender.hpp                         \
+    utils/power_calibration.hpp                   \
     utils/slaac_address.hpp                       \
     utils/srp_client_buffers.hpp                  \
     $(NULL)

src/core/common/instance.cpp

@@ -236,6 +236,9 @@ Instance::Instance(void)
 #endif
 #if OPENTHREAD_CONFIG_DIAG_ENABLE
     , mDiags(*this)
+#endif
+#if OPENTHREAD_CONFIG_POWER_CALIBRATION_ENABLE && OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE
+    , mPowerCalibration(*this)
 #endif
     , mIsInitialized(false)
 {

src/core/common/instance.hpp

@@ -60,6 +60,7 @@
 #include "mac/link_raw.hpp"
 #include "radio/radio.hpp"
 #include "utils/otns.hpp"
+#include "utils/power_calibration.hpp"
 
 #if OPENTHREAD_FTD || OPENTHREAD_MTD
 #include "backbone_router/backbone_tmf.hpp"
@@ -618,6 +619,9 @@ class Instance : public otInstance, private NonCopyable
 #if OPENTHREAD_CONFIG_DIAG_ENABLE
     FactoryDiags::Diags mDiags;
 #endif
+#if OPENTHREAD_CONFIG_POWER_CALIBRATION_ENABLE && OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE
+    Utils::PowerCalibration mPowerCalibration;
+#endif
 
     bool mIsInitialized;
 
@@ -960,6 +964,10 @@ template <> inline Extension::ExtensionBase &Instance::Get(void) { return mExten
 template <> inline FactoryDiags::Diags &Instance::Get(void) { return mDiags; }
 #endif
 
+#if OPENTHREAD_CONFIG_POWER_CALIBRATION_ENABLE && OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE
+template <> inline Utils::PowerCalibration &Instance::Get(void) { return mPowerCalibration; }
+#endif
+
 /**
  * @}
  *

src/core/config/platform.h

@@ -158,6 +158,16 @@
 #define OPENTHREAD_CONFIG_PLATFORM_MAC_KEYS_EXPORTABLE_ENABLE 0
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE
+ *
+ * Define as 1 to enable platform power calibration support.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE
+#define OPENTHREAD_CONFIG_PLATFORM_POWER_CALIBRATION_ENABLE 0
+#endif
+
 #if OPENTHREAD_CONFIG_PLATFORM_RADIO_PROPRIETARY_SUPPORT
 #if (!defined(OPENTHREAD_CONFIG_PLATFORM_RADIO_PROPRIETARY_CHANNEL_PAGE) || \
      !defined(OPENTHREAD_CONFIG_PLATFORM_RADIO_PROPRIETARY_CHANNEL_MIN) ||  \