ESP-IDF ADC 校准驱动程序实战指南：从原始采样到精确电压-港品优选

ESP-IDF ADC 校准驱动程序实战指南：从原始采样到精确电压

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

导读

本文基于 ESP-IDF 官方文档《模数转换器 (ADC) 校准驱动程序》展开，系统讲解 ADC 校准的原理、两种内置校准方案（线性拟合与曲线拟合）的创建与销毁流程、原始结果到电压（mV）的转换方法，并结合 components/esp_adc 组件源码深入剖析其底层实现。读完本文，你将能够在自己的 ESP32 系列项目中使用adc_cali_*API 消除芯片间参考电压差异带来的测量误差，获得准确、可复现的 ADC 电压读数。

为什么需要 ADC 校准：参考电压的芯片间差异

在 ESP32 系列芯片中，模数转换器（ADC）的工作方式是比较输入模拟电压与内部参考电压，从而逐位确定数字输出结果。芯片设计时 ADC 参考电压为1100 mV，但受半导体工艺波动影响，不同芯片的真实参考电压会有差异，范围约在1000 mV 到 1200 mV之间。

如果不做校准，同一输入电压在不同芯片上会得到不同的原始读数，导致测量精度无法保证。ADC 校准驱动程序的作用正是利用每颗芯片在出厂时烧录于 eFuse 中的校准参数，对这一偏差进行补偿，从而获得更准确的电压输出。

从源码看，线性拟合方案（ESP32）正是围绕参考电压范围 1000~1200 mV 设计查找表（Lookup Table）的，见 components/esp_adc/esp32/adc_cali_line_fitting.c 中的LUT_VREF_LOW、LUT_VREF_HIGH宏。

功能概述与使用流程

校准驱动的基本使用步骤如下：

创建校准方案（Scheme）——获取一个校准方案句柄adc_cali_handle_t；
结果转换——调用adc_cali_raw_to_voltage()将原始 ADC 结果转换为以 mV 为单位的校准电压；
线程安全注意——了解哪些 API 可跨 RTOS 任务安全调用；
减少噪声——必要时通过硬件电容与多次采样降低噪声；
（ESP32）Kconfig 选项——按需裁剪代码体积。

创建校准方案（Scheme）

每个 ADC 校准方案对应一个校准句柄adc_cali_handle_t。它本质上是接口层定义的方案表adc_cali_scheme_t的指针，该结构体包含一个函数指针raw_to_voltage和自定义上下文ctx，定义于 components/esp_adc/interface/adc_cali_interface.h。

struct adc_cali_scheme_t { esp_err_t (*raw_to_voltage)(void *arg, int raw, int *voltage); void *ctx; };

查询芯片支持的校准方案

使用adc_cali_check_scheme()可以查询当前芯片支持的校准方案：

esp_err_t adc_cali_check_scheme(adc_cali_scheme_ver_t *scheme_mask);

其实现位于 components/esp_adc/adc_cali.c。它通过编译期宏ADC_CALI_SCHEME_LINE_FITTING_SUPPORTED/ADC_CALI_SCHEME_CURVE_FITTING_SUPPORTED决定向scheme_mask置入ADC_CALI_SCHEME_VER_LINE_FITTING（BIT(0)）还是ADC_CALI_SCHEME_VER_CURVE_FITTING（BIT(1)）。若没有任何方案，返回ESP_ERR_NOT_SUPPORTED。

若你已清楚所用芯片支持的方案，可以跳过此步骤直接调用对应的创建函数。若使用自定义校准方案，可以自行调整adc_cali_check_scheme()（源码中留有 "Add your custom ADC calibration scheme here" 的扩展注释），或跳过它直接调用自定义的创建函数。

方案一：线性拟合校准方案（Line Fitting）

适用于ESP32、ESP32-S2、ESP32-C2。该方案假设 ADC 原始读数与电压之间近似呈线性关系，通过 eFuse 中烧录的校准点拟合出系数。

创建前需配置结构体adc_cali_line_fitting_config_t，其成员见 components/esp_adc/include/esp_adc/adc_cali_scheme.h：

成员	说明
`unit_id`	ADC 原始结果来自哪个 ADC 单元（`adc_unit_t`）
`atten`	ADC 原始结果的衰减程度（`adc_atten_t`）
`bitwidth`	ADC 原始结果的位宽（`adc_bitwidth_t`）
`default_vref`	仅 ESP32 可用，默认参考电压估计值，通常置 0

其中default_vref的语义需要特别注意：通常默认设置为 0，不影响校准过程。但若线性拟合方案所需的 eFuse 位未烧录到板子上，驱动程序会退化为根据default_vref校准，此时必须为其提供有效值。

创建与销毁句柄：

ESP_LOGI(TAG, "calibration scheme version is %s", "Line Fitting"); adc_cali_line_fitting_config_t cali_config = { .unit_id = unit, .atten = atten, .bitwidth = ADC_BITWIDTH_DEFAULT, }; ESP_ERROR_CHECK(adc_cali_create_scheme_line_fitting(&cali_config, &handle)); // ... 使用 handle 完成校准 ... ESP_LOGI(TAG, "delete %s calibration scheme", "Line Fitting"); ESP_ERROR_CHECK(adc_cali_delete_scheme_line_fitting(handle));

函数可能因ESP_ERR_INVALID_ARG（参数非法，如空指针、非法的 unit/atten/bitwidth）或ESP_ERR_NO_MEM（堆内存不足）失败；返回ESP_ERR_NOT_SUPPORTED表示开发板缺少烧录所需的 eFuse 位（见 components/esp_adc/esp32/adc_cali_line_fitting.c 中参数校验与内存分配逻辑）。

如何检查 eFuse 校准位（ESP32）

ESP32 上可通过adc_cali_scheme_line_fitting_check_efuse()检查 eFuse 中烧录的校准参数类型，结果对应 adc_cali_scheme.h 中的枚举：

ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP—— 使用 eFuse 中烧录的两点（Two Point）校准值（150 mV 与 850 mV 两个校准点，见源码中TP_LOW_VOLTAGE、TP_HIGH_VOLTAGE宏）；
ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF—— 使用 eFuse 中烧录的参考电压 Vref（步进 7 mV，基准偏移 1100 mV，见VREF_STEP_SIZE、VREF_OFFSET宏）；
ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF——无 eFuse 校准位，此时必须在创建方案时设置default_vref，作为参考电压估计值参与校准。

该枚举类型同时指示了default_vref的使用条件：只有当 eFuse 值为ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF时才需要显式提供default_vref。

方案二：曲线拟合校准方案（Curve Fitting）

适用于ESP32-C3、ESP32-S3、ESP32-C6、ESP32-H2、ESP32-C5、ESP32-P4。该方案在芯片出厂校准数据的基础上做更精细的曲线拟合，精度更高。

创建前需配置结构体adc_cali_curve_fitting_config_t，成员见 adc_cali_scheme.h：

成员	说明
`unit_id`	ADC 原始结果来自哪个 ADC 单元
`chan`	ADC 通道。ESP32-C3 / ESP32-S3 上此选项保留供扩展，校准仅因衰减程度而异、与通道无关；ESP32-C6 / ESP32-H2 / ESP32-C5 / ESP32-P4 上校准与通道选择相关（对应芯片支持通道级补偿）
`atten`	ADC 原始结果的衰减程度
`bitwidth`	ADC 原始结果的位宽

创建与销毁句柄：

ESP_LOGI(TAG, "calibration scheme version is %s", "Curve Fitting"); adc_cali_curve_fitting_config_t cali_config = { .unit_id = unit, .atten = atten, .bitwidth = ADC_BITWIDTH_DEFAULT, }; ESP_ERROR_CHECK(adc_cali_create_scheme_curve_fitting(&cali_config, &handle)); // ... 使用 handle 完成校准 ... ESP_LOGI(TAG, "delete %s calibration scheme", "Curve Fitting"); ESP_ERROR_CHECK(adc_cali_delete_scheme_curve_fitting(handle));

与 eFuse 相关的校准故障

曲线拟合方案依赖芯片上某些与 ADC 校准相关的 eFuse 位的值。乐鑫官方模组已在出厂时完成烧录，用户无需额外烧录。若adc_cali_create_scheme_curve_fitting()返回ESP_ERR_NOT_SUPPORTED，说明开发板未烧录校准方案所需的 eFuse 位。

其判定逻辑位于 components/esp_adc/adc_cali_curve_fitting.c：读取esp_efuse_rtc_calib_get_ver()获取 eFuse 校准数据编码版本，若不在ESP_EFUSE_ADC_CALIB_VER_MIN与ESP_EFUSE_ADC_CALIB_VER_MAX范围内即判定 eFuse 未烧录。遇到此类错误，建议通过乐鑫官方技术咨询渠道反馈（文档中亦指明这一处理方式）。

曲线拟合的两步校准原理

从源码结构看，曲线拟合方案采用两步校准（见 adc_cali_curve_fitting.c）：

第一步：从 eFuse 校准数据中获取参考点（get_first_step_reference_point），据此计算线性系数coeff_a（斜率）与coeff_b（偏移），系数以 65536 缩放存储为定点数（源码coeff_a_scaling = 65536）；
第二步：通过curve_fitting_get_second_step_coeff()从各芯片专属的拟合系数表（如 components/esp_adc/esp32c3/curve_fitting_coefficients.c）中获取二阶补偿参数，用get_reading_error()对第一步的线性结果进行误差修正。

使用自定义校准方案

如需自定义校准方案，可参照接口层函数表adc_cali_scheme_t（components/esp_adc/interface/adc_cali_interface.h）自行提供创建函数，实现自己的raw_to_voltage转换逻辑与上下文结构，从而将任意校准算法接入统一的adc_cali_handle_t句柄体系。

结果转换：raw 到电压（mV）

完成校准方案创建后，调用adc_cali_raw_to_voltage()将原始 ADC 结果转换为校准电压，单位 mV：

esp_err_t adc_cali_raw_to_voltage(adc_cali_handle_t handle, int raw, int *voltage);

使用示例：

ESP_ERROR_CHECK(adc_cali_raw_to_voltage(adc_cali_handle, adc_raw[0][0], &voltage[0][0])); ESP_LOGI(TAG, "ADC%d Channel[%d] Cali Voltage: %d mV", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN0, voltage[0][0]);

该函数可能因参数无效（空指针）返回ESP_ERR_INVALID_ARG。若返回ESP_ERR_INVALID_STATE，说明校准方案尚未创建（handle->ctx为空），此时需先通过adc_cali_check_scheme()查询支持的方案并创建对应句柄，或提供自定义方案。其实现见 components/esp_adc/adc_cali.c。

转换的底层逻辑

底层转换通过方案句柄注册的raw_to_voltage函数指针完成。以线性拟合方案为例（esp32/adc_cali_line_fitting.c）：

若位宽小于 12 位，先将原始值左移扩展到 12 位分辨率（并钳位到最大值 4095）；
常规区间使用一次线性式voltage = raw * coeff_a + coeff_b计算；
当衰减为ADC_ATTEN_DB_12且读数进入非线性区（raw ≥ 2880）时，改用 20 点的查找表（覆盖 ADC 读数 2880~4096，步进 64，低/高 Vref 各一组曲线），并在线性区与非线性区的过渡窗口内做两点线性插值平滑衔接。

ESP32-C2 的衰减限制

ESP32-C2 上 ADC 校准仅在ADC_ATTEN_DB_0和ADC_ATTEN_DB_12两种衰减下受支持：

ADC_ATTEN_DB_0（0 dB）：仅支持低于950 mV的输入电压；
ADC_ATTEN_DB_12（12 dB）：仅支持低于2800 mV的输入电压。

线程安全

驱动程序保证工厂函数（创建方案的函数）的线程安全，可直接从不同的 RTOS 任务中调用，无需额外加锁。例如adc_cali_create_scheme_*系列创建函数可视为线程安全的工厂入口。

其他以adc_cali_handle_t作为第一个位置参数的函数均非线程安全，例如adc_cali_raw_to_voltage()、adc_cali_delete_scheme_*()。在没有互斥锁保护的情况下，应避免从多个任务同时调用这类函数。

Kconfig 选项（ESP32）

ESP32 上可通过以下 Kconfig 选项按需裁剪代码体积（定义于 components/esp_adc/Kconfig，默认均启用）：

CONFIG_ADC_CALI_EFUSE_TP_ENABLE—— 是否使用 eFuse 中烧录的两点校准值。若你的芯片 eFuse 校准值不是ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP，可禁用以减小代码体积；
CONFIG_ADC_CALI_EFUSE_VREF_ENABLE—— 是否使用 eFuse 中烧录的Vref。若 eFuse 校准值不是ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF，可禁用以减小代码体积；
CONFIG_ADC_CALI_LUT_ENABLE—— 是否使用查找表校正 11 dB 衰减下的非线性行为。若校准原始结果时衰减未设为ADC_ATTEN_DB_12（11 dB），可禁用以减小代码体积。

源码中这三个宏直接控制特性开关：EFUSE_TP_ENABLED、EFUSE_VREF_ENABLED、LUT_ENABLED。其中 LUT 仅在atten == ADC_ATTEN_DB_12时被装载（见 esp32/adc_cali_line_fitting.c），印证了该选项的裁剪条件。此外，禁用 LUT 后代码同样会跳过非线性区的查表与插值路径，直接走线性计算。

减少噪声

ADC 对噪声敏感，噪声可能导致读数出现较大偏差。根据不同使用场景，可采取以下措施：

硬件旁路电容：在 ADC 使用的输入管脚连接旁路电容（如 100 nF 陶瓷电容），滤除高频噪声；
多次采样：通过多次采样并取平均，进一步减轻随机噪声的影响。

进一步阅读

校准驱动的公共 API 头文件：components/esp_adc/include/esp_adc/adc_cali.h（句柄与方案版本枚举）、components/esp_adc/include/esp_adc/adc_cali_scheme.h（两类方案配置结构体）；
核心实现：components/esp_adc/adc_cali.c、components/esp_adc/adc_cali_curve_fitting.c、components/esp_adc/esp32/adc_cali_line_fitting.c；
接口抽象层（自定义方案扩展点）：components/esp_adc/interface/adc_cali_interface.h；
各芯片专属拟合系数：components/esp_adc/esp32c3/curve_fitting_coefficients.c 等；
校准驱动的测试用例：components/esp_adc/test_apps/adc/main/test_common_adc.c 中包含了方案查询、句柄创建与 raw-to-voltage 转换的完整验证流程，可作为上手参考；
ADC 单次采样（oneshot）驱动：components/esp_adc/adc_oneshot.c，负责产生校准所需的原始 ADC 读数。

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析