Merge branch 'doc/RF_calibration' into 'master'

doc: add documentation for RF calibration

See merge request idf/esp-idf!3828

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
  *

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)
 {

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`.

docs/en/api-guides/index.rst

@@ -26,8 +26,9 @@ API Guides
    Application Level Tracing <app_trace>
    Console Component <console>
    ROM debug console <romconsole>
+   RF Calibration <RF_calibration>
    WiFi Driver <wifi>
    ESP-MESH <mesh>
    BluFi <blufi>
    External SPI-connected RAM <external-ram>
-   Linker Script Generation <linker-script-generation>
+   Linker Script Generation <linker-script-generation>

docs/zh_CN/api-guides/RF_calibration.rst

@@ -0,0 +1 @@
+.. include:: ../../en/api-guides/RF_calibration.rst

docs/zh_CN/api-guides/index.rst

@@ -26,6 +26,7 @@ API 指南
    Application Level Tracing <app_trace>
    控制台终端组件 <console>
    ROM debug console <romconsole>
+   RF Calibration <RF_calibration>
    WiFi Driver <wifi>
    ESP-MESH <mesh>
    BluFi <blufi>