diff --git a/components/esp32/include/esp_phy_init.h b/components/esp32/include/esp_phy_init.h index f06375d1a..2a1a8ec7a 100644 --- a/components/esp32/include/esp_phy_init.h +++ b/components/esp32/include/esp_phy_init.h @@ -156,6 +156,18 @@ esp_err_t esp_phy_load_cal_data_from_nvs(esp_phy_calibration_data_t* out_cal_dat */ esp_err_t esp_phy_store_cal_data_to_nvs(const esp_phy_calibration_data_t* cal_data); +/** + * @brief Erase PHY calibration data which is stored in the NVS + * + * This is a function which can be used to trigger full calibration as a last-resort remedy + * if partial calibration is used. It can be called in the application based on some conditions + * (e.g. an option provided in some diagnostic mode). + * + * @return ESP_OK on success + * @return others on fail. Please refer to NVS API return value error number. + */ +esp_err_t esp_phy_erase_cal_data_in_nvs(void); + /** * @brief Initialize PHY and RF module * diff --git a/components/esp32/phy_init.c b/components/esp32/phy_init.c index dcc3b417e..d538f93bc 100644 --- a/components/esp32/phy_init.c +++ b/components/esp32/phy_init.c @@ -471,6 +471,30 @@ esp_err_t esp_phy_store_cal_data_to_nvs(const esp_phy_calibration_data_t* cal_da } } +esp_err_t esp_phy_erase_cal_data_in_nvs(void) +{ + nvs_handle handle; + esp_err_t err = nvs_open(PHY_NAMESPACE, NVS_READWRITE, &handle); + if (err != ESP_OK) { + ESP_LOGE(TAG, "%s: failed to open NVS phy namespace (0x%x)", __func__, err); + return err; + } + else { + err = nvs_erase_all(handle); + if (err != ESP_OK) { + ESP_LOGE(TAG, "%s: failed to erase NVS phy namespace (0x%x)", __func__, err); + } + else { + err = nvs_commit(handle); + if (err != ESP_OK) { + ESP_LOGE(TAG, "%s: failed to commit NVS phy namespace (0x%x)", __func__, err); + } + } + } + nvs_close(handle); + return err; +} + static esp_err_t load_cal_data_from_nvs_handle(nvs_handle handle, esp_phy_calibration_data_t* out_cal_data) { diff --git a/docs/en/api-guides/RF_calibration.rst b/docs/en/api-guides/RF_calibration.rst new file mode 100644 index 000000000..6b8aec0bd --- /dev/null +++ b/docs/en/api-guides/RF_calibration.rst @@ -0,0 +1,59 @@ +RF calibration +============== + +ESP32 supports three RF calibration methods during RF initialization: + +1. Partial calibration + +2. Full calibration + +3. No calibration + +Partial calibration +------------------- +During RF initialization, the partial calibration method is used by default for RF calibration. +It is done based on the full calibration data which is stored in the NVS. +To use this method, please go to ``menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE`. + +Full calibration +---------------- +Full calibration is triggered in the follwing conditions: + +1. NVS does not exist. + +2. The NVS partition to store calibration data is erased. + +3. Hardware MAC address is changed. + +4. PHY library version is changed. + +5. The RF calibration data loaded from the NVS partition is broken. + +It takes about 100ms more than partial calibration. +If boot duration is not critical, it is suggested to use the full calibration method. +To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE`. +If you use the default method of RF calibration, there are two ways to add the function of triggering full calibration as a last-resort remedy. + +1. Erase the NVS partition if you don't mind all of the data stored in the NVS partition is erased. That is indeed the easiest way. + +2. Call API :cpp:func:`esp_phy_erase_cal_data_in_nvs` before initializing WiFi and BT/BLE based on some conditions (e.g. an option provided in some diagnostic mode). + In this case, only phy namespace of the NVS partition is erased. + +No calibration +--------------- +No calibration method is only used when ESP32 wakes up from deep sleep. + +PHY initialization data +----------------------- +The PHY initialization data is used for RF calibration. +There are two ways to get the PHY initialization data. + +One is the default initialization data which is located in the header file :idf_file:`components/esp32/phy_init_data.h`. +It is embedded into the application binary after compiling and then stored into read-only memory (DROM). +To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`. + +Another is the initialization data which is stored in a partition. +When using a custom partition table, make sure that PHY data partition is included (type: `data`, subtype: `phy`). +With default partition table, this is done automatically. +If initialization data is stored in a partition, it has to be flashed there, otherwise runtime error will occur. +To switch to the initialization data stored in a partition, go to ``menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`. diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 0283f555b..7302fbee4 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -26,8 +26,9 @@ API Guides Application Level Tracing Console Component ROM debug console + RF Calibration WiFi Driver ESP-MESH BluFi External SPI-connected RAM - Linker Script Generation \ No newline at end of file + Linker Script Generation diff --git a/docs/zh_CN/api-guides/RF_calibration.rst b/docs/zh_CN/api-guides/RF_calibration.rst new file mode 100644 index 000000000..83f26d7c6 --- /dev/null +++ b/docs/zh_CN/api-guides/RF_calibration.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/RF_calibration.rst diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index 5fd50af4d..fcb76cc63 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -26,6 +26,7 @@ API 指南 Application Level Tracing 控制台终端组件 ROM debug console + RF Calibration WiFi Driver ESP-MESH BluFi