ADC 两点校准方案
========================

:link_to_translation:`en:[English]`

.. important:: 当前 ADC 两点校准方案仅适用于 ESP32 与 ESP32-S2 芯片

ESP32 出厂时默认采用参考电压进行 ADC 校准。如果用户希望进一步提高 ADC 测量结果的一致性，可以将 eFuse 中的校准方案更改为两点校准方法。

同样，对于 ESP32-S2 芯片，出厂默认使用的是两点校准法（方法一）。然而，这种方法并未考虑不同 ADC 衰减下的数据进行校准。如果用户希望使用不同衰减下的数据进行校准，可以将 eFuse 中的校准方案更改为两点校准方法（方法二）。

需要注意的是，上述两种方法都需要用户使用 espefuse 工具来修改 eFuse 中的校准方案，并输入相应的校准数据。这个过程需要格外谨慎，一旦烧录了错误的校准数据，将无法再次修改。这是由于 eFuse 中的数据是不可逆的，一旦写入就无法更改。因此，在进行这些操作时，请确保数据的准确性，以避免不必要的损失。

为避免上述修改 eFuse 带来的风险，``adc_tp_calibration`` 组件提供了一种允许用户在应用层进行校准的方法，具备以下特点：

- 支持在应用层填入校准参数，用户可自行将校准存储到 NVS、SD 卡等存储介质中
- 支持 ESP32 使用两点校准方案，ESP32-S2 使用两点校准方案（方法二），且不影响现有 ESP-IDF 的校准方案

ESP32 两点校准原理
--------------------

ESP32 两点校准需要分别向 ADC1 通道与 ADC2 通道施加稳定的 150 mV 与 850 mV 电压，使用 ADC 获取原始数据接口获取当前电压下的稳定 ADC 原始数据：

+---------------+---------------+---------------+
| Input Voltage | ADC1 (ATTEN0) | ADC2 (ATTEN0) |
+===============+===============+===============+
| 150 mV        | A1            | A2            |
+---------------+---------------+---------------+
| 850 mV        | B1            | B2            |
+---------------+---------------+---------------+

.. note:: 获取 150 mV 与 850 mV 下的 ADC 原始数据时，需要配置 ADC 驱动的衰减为 ``ADC_ATTEN_DB_0``

ESP32 ADC 两点校准计算公式为：

.. math:: y=\frac{coeff_{a} \ast x + coeff_{around}}{coeff_{scale}} + coeff_{b}

* :math:`coeff_{a}`：:math:`\frac{(850-150)*atten_{scale}[atten]+(B-A)/2}{B-A}`
* :math:`coeff_{b}`：:math:`850-\frac{(850-150)*B+(B-A)/2}{B-A} +atten_{offset}[atten]`
* :math:`coeff_{scale}`：65536
* :math:`coeff_{around}`： :math:`\frac{coeff_{scale}}{2}`

+------------------------+--------+-----------+---------+----------+
| ADC1                   | ATTEN0 | ATTEN_2_5 | ATTEN_6 | ATTEN_12 |
+========================+========+===========+=========+==========+
| :math:`atten_{scale}`  | 65504  | 86975     | 120389  | 224310   |
+------------------------+--------+-----------+---------+----------+
| :math:`atten_{offset}` | 0      | 1         | 27      | 54       |
+------------------------+--------+-----------+---------+----------+

+------------------------+--------+-----------+---------+----------+
| ADC2                   | ATTEN0 | ATTEN_2_5 | ATTEN_6 | ATTEN_12 |
+========================+========+===========+=========+==========+
| :math:`atten_{scale}`  | 65467  | 86861     | 120416  | 224708   |
+------------------------+--------+-----------+---------+----------+
| :math:`atten_{offset}` | 0      | 9         | 26      | 66       |
+------------------------+--------+-----------+---------+----------+

ESP32-S2 两点校准（方法二）原理
--------------------------------

ESP32-S2 两点校准（方法二）需要分别向 ADC1 通道与 ADC2 通道施加稳定的 600 mV、800 mV、1000 mV 与 2000 mV 电压，使用 ADC 获取原始数据接口获取当前电压下的稳定 ADC 原始数据，以 ADC1 为例：

+---------------+-----------+-----------------+
| Input Voltage | ATTEN     | ADC1 Raw Value  |
+===============+===========+=================+
| 600 mV        | ATTEN_0   | High[ATTEN_0]   |
+---------------+-----------+-----------------+
| 800 mV        | ATTEN_2_5 | High[ATTEN_2_5] |
+---------------+-----------+-----------------+
| 1000 mV       | ATTEN_6   | High[ATTEN_6]   |
+---------------+-----------+-----------------+
| 2000 mV       | ATTEN_12  | High[ATTEN_12]  |
+---------------+-----------+-----------------+

.. note:: ESP32-S2 两点校准（方法二）的校准点选取需要分别在对应的衰减与标定电压下获取稳定的 ADC 原始数据，以确保校准的准确性。其中 High 用于存储不同衰减与标定电压下的 ADC 原始数据

ESP32-S2 ADC 两点校准（方法二）计算公式为：

.. math:: y=\frac{x \ast coeff_{a} / (coeff_{ascaling}/coeff_{bscaling}) + coeff_{b} }{coeff_{bscaling}} 

* :math:`coeff_{a}`：:math:`coeff_{ascaling} \ast v_{high}[atten] / High[atten]`
* :math:`coeff_{b}`：0
* :math:`coeff_{ascaling}`：65536
* :math:`coeff_{bscaling}`：1024

+------------------+--------+-----------+---------+----------+
|                  | ATTEN0 | ATTEN_2_5 | ATTEN_6 | ATTEN_12 |
+==================+========+===========+=========+==========+
| :math:`v_{high}` | 600    | 800       | 1000    | 2000     |
+------------------+--------+-----------+---------+----------+

API 参考
------------

.. include-build-file:: inc/adc_tp_calibration.inc