ESP-IDF 模数转换器ADC驱动完全指南oneshot、continuous 与校准原理详解【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf导读本文以 ESP-IDF 官方 ADC 编程指南docs/en/api-reference/peripherals/adc/index.rst为主线系统讲解 Espressif SoC 上 ADC模数转换器的核心概念——转换原理、原始数据分辨率、参考电压与衰减并深入剖析其两大驱动模式oneshot 模式单次按需采样与continuous 模式DMA 高速连续采样以及用于提升精度的ADC 校准驱动。阅读完本文你将掌握 ADC 通道的配置方法、原始读数与电压的换算公式、两种模式各自的资源管理与读取流程并能通过 Kconfig 选项与 IRAM-safe、电源管理等机制在实际项目中正确选型与调优。一、ADC 核心概念从模拟电压到数字量ADCAnalog to Digital Converter负责将输入模拟电压转换为数字值。ESP-IDF 的 ADC 驱动 API 返回的均是原始数据raw data它以数字形式表征模拟输入信号。1.1 分辨率与原始数据位宽默认情况下ADC 原始结果的位宽为12 位这意味着输入电压范围被划分为 2¹² 4096 个离散电平由此决定了可检测的最小输入信号变化量。原始 ADC 结果data对应的电压Vdata计算公式为Vdata data / (2^bitwidth − 1) × Vref其中dataADC 原始结果bitwidthADC 结果分辨率如 12 位VrefADC 参考电压。1.2 参考电压 Vref 的制造偏差按设计Vref为1100 mV。但由于芯片制造工艺差异不同芯片的实际参考电压可能落在1000 mV ~ 1200 mV之间。这一偏差正是需要 ADC 校准驱动的原因——要获得经过校准的精确电压值请使用 adc_calibration.rst 中介绍的校准驱动依据芯片实际的Vref对原始结果进行修正。从源码角度adc_cali_handle_t校准句柄与adc_cali_raw_to_voltage()等接口定义在 components/esp_adc/include/esp_adc/adc_cali.h校准方案接口表adc_cali_scheme_t位于 components/esp_adc/interface/adc_cali_interface.h其实现分布在 components/esp_adc/adc_cali.c、components/esp_adc/adc_cali_curve_fitting.c 等文件中。1.3 衰减Attenuation扩大测量范围ADC 只能直接测量0 V ~ Vref范围内的模拟电压。要测量更高电压可在信号进入 ADC 之前先进行衰减。支持的衰减档位如下表衰减档位比例系数 k约0 dBk ≈ 100%2.5 dBk ≈ 75%6 dBk ≈ 50%12 dBk ≈ 25%衰减档位越高ADC 能测量的输入电压上限越高。施加衰减后的电压计算公式为Vdata (Vref / k) × (data / (2^bitwidth − 1))其中k是对应衰减档位的比例值其余变量含义同前。每个衰减档位对应的具体输入电压范围请查阅目标芯片数据手册datasheet中的 Electrical Characteristics ADC CharacteristicsESP32 则为 Function Description Analog Peripherals Analog-to-Digital Converter (ADC)章节。二、ADC 驱动模式总览ESP-IDF 的 ADC 驱动按使用场景分为两种工作模式oneshot 模式适用于单次、按需采样一次只对一个通道采样实现简单、资源占用低continuous 模式适用于需要周期性或高频连续采集的场景ADC 自动对一组通道依次采样或对单个通道连续采样并通过 DMA 将结果高效搬运到内存。其中 continuous 模式需要芯片支持 DMA即SOC_ADC_DMA_SUPPORTED。同一 ADC 单元在同一时刻只能工作于一种模式下驱动内部已提供互斥保护详见各模式的硬件限制章节。两种模式对应的官方实现分别是 components/esp_adc/adc_oneshot.c 与 components/esp_adc/adc_continuous.c头文件分别为 components/esp_adc/include/esp_adc/adc_oneshot.h 与 components/esp_adc/include/esp_adc/adc_continuous.h。三、ADC Oneshot 模式驱动详解oneshot 模式适合采样频率低、按需触发的应用例如读取电位器电压、电池电量检测等低频测量任务。3.1 资源分配创建与回收 ADC 单元在 oneshot 驱动视角下一个 ADC 实例由句柄adc_oneshot_unit_handle_t表示。安装 ADC 实例前需设置初始化配置结构体adc_oneshot_unit_init_cfg_t定义于 adc_oneshot.hunit_id选择 ADC 单元ADC_UNIT_1 / ADC_UNIT_2对应芯片上具体的模拟 IO可查数据手册或使用adc_oneshot_io_to_channel()反查clk_srcADC 时钟源置 0 时驱动回退到默认时钟源见adc_oneshot_clk_src_tulp_mode是否在 ULP 模式下使用 ADC。配置完成后调用adc_oneshot_new_unit()创建单元成功则返回 ADC 单元句柄。该函数可能因参数非法、内存不足等失败特别地当目标 ADC 实例已被占用时会返回ESP_ERR_NOT_FOUND可用SOC_ADC_PERIPH_NUM宏获知芯片可用 ADC 数量。不再使用时调用adc_oneshot_del_unit()回收实例及其软硬件资源。adc_oneshot_unit_handle_t adc1_handle; adc_oneshot_unit_init_cfg_t init_config1 { .unit_id ADC_UNIT_1, .ulp_mode ADC_ULP_MODE_DISABLE, }; ESP_ERROR_CHECK(adc_oneshot_new_unit(init_config1, adc1_handle)); // ... 使用完毕后回收 ESP_ERROR_CHECK(adc_oneshot_del_unit(adc1_handle));3.2 通道配置设置衰减与位宽创建实例后通过adc_oneshot_chan_cfg_t见 adc_oneshot.h配置要测量的 IOattenADC 衰减档位取值范围为上文提到的 0 / 2.5 / 6 / 12 dBbitwidth原始转换结果位宽。调用adc_oneshot_config_channel()使配置生效该函数可多次调用以配置不同通道驱动会在内部保存每个通道的配置。adc_oneshot_chan_cfg_t config { .bitwidth ADC_BITWIDTH_DEFAULT, .atten ADC_ATTEN_DB_12, }; ESP_ERROR_CHECK(adc_oneshot_config_channel(adc1_handle, EXAMPLE_ADC1_CHAN0, config)); ESP_ERROR_CHECK(adc_oneshot_config_channel(adc1_handle, EXAMPLE_ADC1_CHAN1, config));3.3 读取转换结果调用adc_oneshot_read()获取指定通道的原始转换结果int adc_raw[2][2]; ESP_ERROR_CHECK(adc_oneshot_read(adc1_handle, EXAMPLE_ADC1_CHAN0, adc_raw[0][0])); ESP_LOGI(TAG, ADC%d Channel[%d] Raw Data: %d, ADC_UNIT_1 1, EXAMPLE_ADC1_CHAN0, adc_raw[0][0]);该函数使用互斥锁避免并发访问硬件因此不可以在 ISR 上下文调用当 ADC 正被其他驱动/外设占用时可能返回ESP_ERR_TIMEOUT此时读到的原始结果无效。原始结果换算电压的公式Vout Dout × Vmax / Dmax符号含义Vout数字输出结果代表电压DoutADC 原始数字读数Vmax最大可测输入模拟电压与 ADC 衰减相关参考 TRM On-Chip Sensor and Analog Signal Processing 章节DmaxADC 原始数字读数最大值即 2^bitwidth其中 bitwidth 为配置的通道位宽若要获得以 mV 为单位的精确电压推荐使用校准驱动见本文第五章或直接使用便捷函数adc_oneshot_get_calibrated_result()——它一步完成读取原始结果 校准为电压该函数同样声明于 adc_oneshot.h。3.4 oneshot 模式的其他要点电源管理启用CONFIG_PM_ENABLE后系统空闲时系统时钟频率可能被调整。oneshot 驱动以轮询方式工作adc_oneshot_read()会持续占用 CPU 直到返回期间任务不会阻塞因此读取时时钟频率保持稳定。IRAM Safe默认情况下所有 oneshot API 不允许在 Cache 禁用时运行如 Flash 写入/擦除、OTA 期间否则可能出现Illegal Instruction或Load/Store Prohibited错误。线程安全adc_oneshot_new_unit、adc_oneshot_config_channel、adc_oneshot_read、adc_oneshot_del_unit均保证线程安全可在不同 RTOS 任务中直接调用无需额外加锁。Kconfig 选项CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM控制 ADC 快速读取函数放置在 IRAM 还是 Flash见 components/esp_adc/Kconfig。四、ADC Continuous 模式驱动详解continuous 模式下ADC 对一路或多路模拟输入通道执行自动高速采样结果通过 DMA 高效传输到内存适用于音频采集、波形监测、电力计量等高频/周期性数据采集场景。4.1 转换帧Conversion Frame与转换结果continuous 模式以转换帧为单位组织数据转换帧Conversion Frame一个帧包含多个转换结果帧大小由adc_continuous_new_handle()按字节配置转换结果Conversion Result一个结果由多个字节组成字节数由宏SOC_ADC_DIGI_RESULT_BYTES定义其结构为adc_digi_output_data_t包含 ADC 单元、ADC 通道与原始数据。例如conv_frame_size 100表示一个转换帧包含100 / SOC_ADC_DIGI_RESULT_BYTES个转换结果。该概念在 adc_continuous.h 头部注释中有完整图示说明。4.2 资源分配创建与回收驱动句柄创建驱动前设置adc_continuous_handle_cfg_t见 adc_continuous.hmax_store_buf_size内部缓冲池最大字节数驱动将转换结果保存到该池conv_frame_size转换帧大小字节应为SOC_ADC_DIGI_DATA_BYTES_PER_CONV的倍数flags.flush_pool当缓冲池满时自动冲刷旧数据并写入新数据否则新转换结果将丢失。adc_continuous_handle_t handle NULL; adc_continuous_handle_cfg_t adc_config { .max_store_buf_size 1024, .conv_frame_size 256, }; ESP_ERROR_CHECK(adc_continuous_new_handle(adc_config, handle));adc_continuous_new_handle()可能因参数非法、内存不足等失败。特殊地返回ESP_ERR_NOT_FOUND的含义因芯片而异ESP32 表示 I2S0 外设已被占用ESP32-S2 表示 SPI3 已被占用支持 GDMA 的芯片则代表没有空闲的 GDMA 通道。不再使用驱动时调用adc_continuous_deinit()反初始化。4.3 通道与采样配置初始化后通过adc_continuous_config_t配置要采样的 IO见 adc_continuous.hpattern_num使用的 ADC 通道数量adc_pattern每个通道的配置列表类型为adc_digi_pattern_config_t包含atten衰减、channel通道号、unit所属 ADC 单元、bit_width原始结果位宽sample_freq_hz期望的采样频率Hz可用的采样频率范围见soc/soc_caps.hconv_mode连续转换模式format转换输出格式已标记 deprecated。调用adc_continuous_config()使配置生效。若返回ESP_ERR_INVALID_STATE说明驱动已启动此时不应再调用该 API。4.4 启动与停止ESP_ERROR_CHECK(adc_continuous_start(handle)); // 开始转换 ESP_ERROR_CHECK(adc_continuous_stop(handle)); // 停止转换4.5 注册事件回调通过adc_continuous_register_event_callbacks()可将用户函数挂接到驱动 ISR支持的回调定义于adc_continuous_evt_cbs_ton_conv_done一个转换帧完成时触发on_pool_ovf内部缓冲池已满时触发此时新转换结果将被丢弃通常因为adc_continuous_read()读取速度远慢于 ADC 转换速度。回调在ISR 上下文中执行因此回调内不能包含阻塞逻辑。事件数据adc_continuous_evt_data_t提供转换帧缓冲区指针conv_frame_buffer与大小size注意该缓冲区由驱动自行维护切勿手动 free。可通过user_data参数向回调传递用户上下文。当启用CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE时回调及回调调用的函数须放置在 IRAM涉及的变量也应放在内部 RAM。4.6 读取与解析转换结果adc_continuous_start()之后调用adc_continuous_read()获取转换结果可请求读取指定长度的结果若实际可用结果不足函数仍会将内部池中的数据搬运到用户缓冲区实际搬运长度通过out_length返回若内部池中暂无结果函数会阻塞timeout_ms毫秒直到至少产生一个结果超时仍未产生则返回ESP_ERR_TIMEOUT若结果填满内部池导致新结果丢失下次调用将返回ESP_ERR_INVALID_STATE。continuous 模式读出的原始数据需进一步解析为结构化结果。ESP-IDF 提供两种方式方式一adc_continuous_parse_data()手动解析uint32_t ret_num 0; esp_err_t ret adc_continuous_read(handle, result, EXAMPLE_READ_LEN, ret_num, 0); if (ret ESP_OK) { adc_continuous_data_t parsed_data[ret_num / SOC_ADC_DIGI_RESULT_BYTES]; uint32_t num_parsed_samples 0; esp_err_t parse_ret adc_continuous_parse_data(handle, result, ret_num, parsed_data, num_parsed_samples); if (parse_ret ESP_OK) { for (int i 0; i num_parsed_samples; i) { if (parsed_data[i].valid) { ESP_LOGI(TAG, ADC%d, Channel: %d, Value: %PRIu32, parsed_data[i].unit 1, parsed_data[i].channel, parsed_data[i].raw_data); } } } }注意raw_data_size必须是SOC_ADC_DIGI_RESULT_BYTES的整数倍且raw_data缓冲区需足够容纳raw_data_size字节数据解析函数内置了防缓冲区溢出与整数溢出的边界检查。方式二adc_continuous_read_parse()一步读取并解析adc_continuous_data_t parsed_data[64]; // 用户指定最大样本数 uint32_t num_samples 0; esp_err_t ret adc_continuous_read_parse(handle, parsed_data, 64, num_samples, 1000); if (ret ESP_OK) { for (int i 0; i num_samples; i) { if (parsed_data[i].valid) { ESP_LOGI(TAG, ADC%d, Channel: %d, Value: %PRIu32, parsed_data[i].unit 1, parsed_data[i].channel, parsed_data[i].raw_data); } } }解析后的结构体adc_continuous_data_t见 adc_continuous.h包含unitADC 单元ADC_UNIT_1 或 ADC_UNIT_2channelADC 通道号0-9raw_dataADC 原始数据值valid数据是否有效。与 oneshot 模式相同原始结果换算电压的公式为Vout Dout × Vmax / Dmax其中Dmax中的 bitwidth 对应adc_digi_pattern_config_t::bit_width。4.7 IIR 滤波器与 Monitor 监视器IIR 滤波器支持SOC_ADC_DIG_IIR_FILTER_SUPPORTED的芯片在 continuous 模式下提供两个 IIR 滤波器。创建时需设置adc_continuous_iir_filter_config_t包含unit、channel、coeff系数调用adc_new_continuous_iir_filter()创建adc_del_continuous_iir_filter()回收。在部分芯片上滤波器按 ADC 单元绑定SOC_ADC_DIG_IIR_FILTER_UNIT_BINDED一旦启用会对该单元所有已启用通道滤波建议使用滤波功能时每单元只启用一个通道避免滤波结果混合启用/停用分别调用adc_continuous_iir_filter_enable()/adc_continuous_iir_filter_disable()。Monitor 监视器支持SOC_ADC_MONITOR_SUPPORTED的芯片可创建监视器数量见SOC_ADC_DIGI_MONITOR_NUM对工作通道设置一个或两个阈值当转换结果超出阈值时在每个采样周期触发中断。配置结构体adc_monitor_config_t包含adc_unit、channel、h_threshold高阈值不用时置 -1、l_threshold低阈值不用时置 -1。操作 API 包括adc_continuous_monitor_enable/disable、adc_continuous_monitor_register_event_callbacks、adc_del_continuous_monitor。monitor 的典型应用是过零检测由于 ADC 无法直接处理负输入信号需先通过电路叠加DC 偏置把负信号平移进 ADC 量程——例如叠加 1 V 偏置可将 -1 V ~ 1 V 的信号变换为 0 V ~ 2 V。随后设置合适的上下阈值即可检测输入信号是否逼近零点从而识别信号相位变化adc_monitor_handle_t adc_monitor_handle NULL; adc_monitor_config_t zero_crossing_config { .adc_unit EXAMPLE_ADC_UNIT_1, // 指定要监视的 ADC 单元 .channel EXAMPLE_ADC_CHANNEL_0, // 指定要监视的 ADC 通道 .h_threshold 1100, // 高阈值接近 DC 偏置值可按需调整 .l_threshold 900, // 低阈值接近 DC 偏置值可按需调整 }; ESP_ERROR_CHECK(adc_new_continuous_monitor(zero_crossing_config, adc_monitor_handle)); adc_monitor_evt_cbs_t zero_crossing_cbs { .on_over_high_thresh example_on_exceed_high_thresh, .on_below_low_thresh example_on_below_low_thresh, }; ESP_ERROR_CHECK(adc_continuous_monitor_register_event_callbacks(adc_monitor_handle, zero_crossing_cbs, NULL)); ESP_ERROR_CHECK(adc_continuous_monitor_enable(adc_monitor_handle)); // ... 使用完毕后停用并删除 ESP_ERROR_CHECK(adc_continuous_monitor_disable(adc_monitor_handle)); ESP_ERROR_CHECK(adc_del_continuous_monitor(adc_monitor_handle));4.8 continuous 模式的其他要点电源管理启用CONFIG_PM_ENABLE后系统空闲时 APB 时钟频率可能被调整从而影响连续转换行为。continuous 驱动通过获取ESP_PM_APB_FREQ_MAX类型的电源管理锁来阻止该变化——锁在adc_continuous_start()后获取、adc_continuous_stop()后释放因此两者必须成对出现否则电源管理将失效。IRAM Safe默认所有 continuous API 均非 IRAM-safe。启用CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE后驱动内部 ISR 处理器变为 IRAM-safe即使 Cache 被禁用也能将转换结果保存到内部池。线程安全continuous 模式 API 不保证线程安全但驱动提供共享硬件互斥保护。五、ADC 校准驱动详解由于不同芯片的实际参考电压存在 1000 mV ~ 1200 mV 的制造偏差直接解读原始读数会产生较大误差。ADC 校准驱动通过软件修正偏差输出更精确的结果。5.1 校准方案Scheme的选择与创建从校准驱动视角看校准方案创建后得到一个校准句柄adc_cali_handle_t。可使用adc_cali_check_scheme()查询芯片支持的校准方案若已知支持方案可跳过此步直接调用对应创建函数。芯片支持的方案由宏标识ADC_CALI_SCHEME_VER_LINE_FITTING直线拟合ESP32、ESP32-S2、ESP32-C2ADC_CALI_SCHEME_VER_CURVE_FITTING曲线拟合ESP32-C3、ESP32-S3、ESP32-C6、ESP32-H2、ESP32-C5、ESP32-P4 等。Line Fitting 方案配置结构体adc_cali_line_fitting_config_t包含unit_id原始结果来源 ADC、atten所用衰减、bitwidth原始结果位宽。ESP32 上还有default_vref配置项通常置 0 即可——Line Fitting 方案并不依赖该值但若板子上未烧录方案所需的 eFuse 位驱动将依赖该值完成校准。可用adc_cali_scheme_line_fitting_check_efuse()检查 eFuse 位状态正常为ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP两点值或ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF参考电压值当为ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF时需设置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)); // ... 使用完毕后 ESP_ERROR_CHECK(adc_cali_delete_scheme_line_fitting(handle));Curve Fitting 方案配置结构体adc_cali_curve_fitting_config_t同样包含unit_id、atten、bitwidth以及为扩展性保留的chan字段。在 ESP32-C3 / ESP32-S3 上校准只与衰减相关、与通道无关而在 ESP32-C6 / ESP32-H2 / ESP32-C5 / ESP32-P4 上校准不仅随衰减变化、还与通道相关因此chan需填写原始结果来源通道。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)); // ... 使用完毕后 ESP_ERROR_CHECK(adc_cali_delete_scheme_curve_fitting(handle));eFuse 相关失败当创建函数返回ESP_ERR_NOT_SUPPORTED说明校准方案所需的 eFuse 位未正确烧录。ESP-IDF 的校准方案基于片上特定 ADC 校准 eFuse 位Espressif 保证这些位在模组制造时已烧录用户无需自行烧录。若遇到此类错误请联系官方技术支持渠道。若想使用自定义校准方案可参照 components/esp_adc/interface/adc_cali_interface.h 中的函数表adc_cali_scheme_t实现创建函数。5.2 结果换算raw → mV校准特性设置完成后调用adc_cali_raw_to_voltage()将原始结果转换为以 mV 为单位的校准结果int voltage[2][2]; 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_STATE说明校准方案句柄尚未创建需先创建方案句柄或用adc_cali_check_scheme()确认支持方案。注意ESP32-C2该校准仅支持ADC_ATTEN_DB_0与ADC_ATTEN_DB_12两种衰减。0 dB 下衰减为 0 dB不支持高于 950 mV 的输入电压12 dB 下实际衰减为 11 dB不支持高于 2800 mV 的输入电压。5.3 线程安全工厂函数adc_cali_check_scheme()及esp_adc_cali_new_scheme()由驱动保证线程安全其他以adc_cali_handle_t为首参的函数不保证线程安全应避免从多个任务同时调用。5.4 降低噪声Minimize NoiseADC 对噪声敏感可能导致读数偏差较大。根据使用场景可在使用的 ADC 输入引脚上连接旁路电容例如 100 nF 陶瓷电容来抑制噪声此外多次采样multisampling也是一种有效的降噪手段。上图展示了 ESP32 上通过旁路电容与 64 次多次采样组合后的噪声抑制效果。ESP32 上还可通过 Kconfig 选项裁剪校准代码体积CONFIG_ADC_CALI_EFUSE_TP_ENABLE、CONFIG_ADC_CALI_EFUSE_VREF_ENABLE、CONFIG_ADC_CALI_LUT_ENABLE若不用 12 dB 衰减下的校准可关闭查找表。上述校准选项定义于 components/esp_adc/Kconfig。六、硬件限制与注意事项汇总芯片限制说明通用同一 ADC 单元同一时刻只能工作于一种模式oneshot 或 continuous驱动已提供保护RNG 随机数发生器以 ADC 为输入源ADC 工作时 RNG 随机性下降差分芯片SOC_ADC_DIFF_SUPPORTED单端模式下若以 N 侧通道作为输入接口其原始数据极性反转-2 V ~ 2 V 输入对应 N 侧原始码 4393 ~ 0请使用校准 API 转换ESP32 / ESP32-S2 / ESP32-S3ADC2 同时被 Wi-Fi 使用驱动已提供两者间的互斥保护ESP32-C3ADC2 oneshot 模式因硬件限制不再支持结果不稳定见芯片勘误表可启用CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3强制使用ESP32-C3 / ESP32-S3ADC2 DMA 功能因硬件限制不再支持可启用CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3强制使用ESP32continuous 驱动使用 I2S0 外设作为 DMA FIFOI2S0 被占用时adc_continuous_new_handle()返回ESP_ERR_NOT_FOUNDESP32-DevKitC 的 GPIO0 因自动下载电路不可用ESP-WROVER-KIT 的 GPIO 0/2/4/15 不可用ESP32-S2continuous 驱动使用 SPI3 外设作为 DMA FIFO被占用时同样返回ESP_ERR_NOT_FOUND相关 Kconfig 选项集中在 components/esp_adc/KconfigCONFIG_ADC_DISABLE_DAC_OUTPUTADC2 使用时默认禁用 DAC 输出、CONFIG_ADC_ENABLE_DEBUG_LOG等。七、示例工程与 API 参考examples/peripherals/adc/oneshot_read演示使用 oneshot 驱动从 GPIO 读取单次 ADC 读数并调用校准函数获得以 mV 为单位的校准结果examples/peripherals/adc/continuous_read演示在开发板上使用 continuous 模式DMA从 GPIO 引脚持续读取 ADC 数据。两个示例均为可直接编译运行的完整工程是学习两种驱动模式配置流程的最佳起点。完整 API 参考类型、配置结构体与函数文档可进一步阅读oneshot 模式 API实现见 adc_oneshot.ccontinuous 模式 API实现见 adc_continuous.c校准驱动 API实现见 adc_cali.c总结ESP-IDF 的 ADC 驱动体系以原始数据 校准换算为设计核心oneshot 模式以极简 API 覆盖低频按需采样场景continuous 模式借助 DMA、转换帧、事件回调、IIR 滤波与阈值监视器等机制支撑高频连续采集而校准驱动则通过 Line Fitting / Curve Fitting 两种方案将制造偏差修正到 mV 级精度。实际选型时只需根据采样频率需求确定模式、依据信号幅度选择衰减档位并牢记各芯片特有的硬件限制与电源管理、IRAM-safe 等约束即可在 ESP32 全系列芯片上稳定、精确地完成模拟信号采集。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP-IDF 模数转换器（ADC）驱动完全指南：oneshot、continuous 与校准原理详解
ESP-IDF 模数转换器ADC驱动完全指南oneshot、continuous 与校准原理详解【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf导读本文以 ESP-IDF 官方 ADC 编程指南docs/en/api-reference/peripherals/adc/index.rst为主线系统讲解 Espressif SoC 上 ADC模数转换器的核心概念——转换原理、原始数据分辨率、参考电压与衰减并深入剖析其两大驱动模式oneshot 模式单次按需采样与continuous 模式DMA 高速连续采样以及用于提升精度的ADC 校准驱动。阅读完本文你将掌握 ADC 通道的配置方法、原始读数与电压的换算公式、两种模式各自的资源管理与读取流程并能通过 Kconfig 选项与 IRAM-safe、电源管理等机制在实际项目中正确选型与调优。一、ADC 核心概念从模拟电压到数字量ADCAnalog to Digital Converter负责将输入模拟电压转换为数字值。ESP-IDF 的 ADC 驱动 API 返回的均是原始数据raw data它以数字形式表征模拟输入信号。1.1 分辨率与原始数据位宽默认情况下ADC 原始结果的位宽为12 位这意味着输入电压范围被划分为 2¹² 4096 个离散电平由此决定了可检测的最小输入信号变化量。原始 ADC 结果data对应的电压Vdata计算公式为Vdata data / (2^bitwidth − 1) × Vref其中dataADC 原始结果bitwidthADC 结果分辨率如 12 位VrefADC 参考电压。1.2 参考电压 Vref 的制造偏差按设计Vref为1100 mV。但由于芯片制造工艺差异不同芯片的实际参考电压可能落在1000 mV ~ 1200 mV之间。这一偏差正是需要 ADC 校准驱动的原因——要获得经过校准的精确电压值请使用 adc_calibration.rst 中介绍的校准驱动依据芯片实际的Vref对原始结果进行修正。从源码角度adc_cali_handle_t校准句柄与adc_cali_raw_to_voltage()等接口定义在 components/esp_adc/include/esp_adc/adc_cali.h校准方案接口表adc_cali_scheme_t位于 components/esp_adc/interface/adc_cali_interface.h其实现分布在 components/esp_adc/adc_cali.c、components/esp_adc/adc_cali_curve_fitting.c 等文件中。1.3 衰减Attenuation扩大测量范围ADC 只能直接测量0 V ~ Vref范围内的模拟电压。要测量更高电压可在信号进入 ADC 之前先进行衰减。支持的衰减档位如下表衰减档位比例系数 k约0 dBk ≈ 100%2.5 dBk ≈ 75%6 dBk ≈ 50%12 dBk ≈ 25%衰减档位越高ADC 能测量的输入电压上限越高。施加衰减后的电压计算公式为Vdata (Vref / k) × (data / (2^bitwidth − 1))其中k是对应衰减档位的比例值其余变量含义同前。每个衰减档位对应的具体输入电压范围请查阅目标芯片数据手册datasheet中的 Electrical Characteristics ADC CharacteristicsESP32 则为 Function Description Analog Peripherals Analog-to-Digital Converter (ADC)章节。二、ADC 驱动模式总览ESP-IDF 的 ADC 驱动按使用场景分为两种工作模式oneshot 模式适用于单次、按需采样一次只对一个通道采样实现简单、资源占用低continuous 模式适用于需要周期性或高频连续采集的场景ADC 自动对一组通道依次采样或对单个通道连续采样并通过 DMA 将结果高效搬运到内存。其中 continuous 模式需要芯片支持 DMA即SOC_ADC_DMA_SUPPORTED。同一 ADC 单元在同一时刻只能工作于一种模式下驱动内部已提供互斥保护详见各模式的硬件限制章节。两种模式对应的官方实现分别是 components/esp_adc/adc_oneshot.c 与 components/esp_adc/adc_continuous.c头文件分别为 components/esp_adc/include/esp_adc/adc_oneshot.h 与 components/esp_adc/include/esp_adc/adc_continuous.h。三、ADC Oneshot 模式驱动详解oneshot 模式适合采样频率低、按需触发的应用例如读取电位器电压、电池电量检测等低频测量任务。3.1 资源分配创建与回收 ADC 单元在 oneshot 驱动视角下一个 ADC 实例由句柄adc_oneshot_unit_handle_t表示。安装 ADC 实例前需设置初始化配置结构体adc_oneshot_unit_init_cfg_t定义于 adc_oneshot.hunit_id选择 ADC 单元ADC_UNIT_1 / ADC_UNIT_2对应芯片上具体的模拟 IO可查数据手册或使用adc_oneshot_io_to_channel()反查clk_srcADC 时钟源置 0 时驱动回退到默认时钟源见adc_oneshot_clk_src_tulp_mode是否在 ULP 模式下使用 ADC。配置完成后调用adc_oneshot_new_unit()创建单元成功则返回 ADC 单元句柄。该函数可能因参数非法、内存不足等失败特别地当目标 ADC 实例已被占用时会返回ESP_ERR_NOT_FOUND可用SOC_ADC_PERIPH_NUM宏获知芯片可用 ADC 数量。不再使用时调用adc_oneshot_del_unit()回收实例及其软硬件资源。adc_oneshot_unit_handle_t adc1_handle; adc_oneshot_unit_init_cfg_t init_config1 { .unit_id ADC_UNIT_1, .ulp_mode ADC_ULP_MODE_DISABLE, }; ESP_ERROR_CHECK(adc_oneshot_new_unit(init_config1, adc1_handle)); // ... 使用完毕后回收 ESP_ERROR_CHECK(adc_oneshot_del_unit(adc1_handle));3.2 通道配置设置衰减与位宽创建实例后通过adc_oneshot_chan_cfg_t见 adc_oneshot.h配置要测量的 IOattenADC 衰减档位取值范围为上文提到的 0 / 2.5 / 6 / 12 dBbitwidth原始转换结果位宽。调用adc_oneshot_config_channel()使配置生效该函数可多次调用以配置不同通道驱动会在内部保存每个通道的配置。adc_oneshot_chan_cfg_t config { .bitwidth ADC_BITWIDTH_DEFAULT, .atten ADC_ATTEN_DB_12, }; ESP_ERROR_CHECK(adc_oneshot_config_channel(adc1_handle, EXAMPLE_ADC1_CHAN0, config)); ESP_ERROR_CHECK(adc_oneshot_config_channel(adc1_handle, EXAMPLE_ADC1_CHAN1, config));3.3 读取转换结果调用adc_oneshot_read()获取指定通道的原始转换结果int adc_raw[2][2]; ESP_ERROR_CHECK(adc_oneshot_read(adc1_handle, EXAMPLE_ADC1_CHAN0, adc_raw[0][0])); ESP_LOGI(TAG, ADC%d Channel[%d] Raw Data: %d, ADC_UNIT_1 1, EXAMPLE_ADC1_CHAN0, adc_raw[0][0]);该函数使用互斥锁避免并发访问硬件因此不可以在 ISR 上下文调用当 ADC 正被其他驱动/外设占用时可能返回ESP_ERR_TIMEOUT此时读到的原始结果无效。原始结果换算电压的公式Vout Dout × Vmax / Dmax符号含义Vout数字输出结果代表电压DoutADC 原始数字读数Vmax最大可测输入模拟电压与 ADC 衰减相关参考 TRM On-Chip Sensor and Analog Signal Processing 章节DmaxADC 原始数字读数最大值即 2^bitwidth其中 bitwidth 为配置的通道位宽若要获得以 mV 为单位的精确电压推荐使用校准驱动见本文第五章或直接使用便捷函数adc_oneshot_get_calibrated_result()——它一步完成读取原始结果 校准为电压该函数同样声明于 adc_oneshot.h。3.4 oneshot 模式的其他要点电源管理启用CONFIG_PM_ENABLE后系统空闲时系统时钟频率可能被调整。oneshot 驱动以轮询方式工作adc_oneshot_read()会持续占用 CPU 直到返回期间任务不会阻塞因此读取时时钟频率保持稳定。IRAM Safe默认情况下所有 oneshot API 不允许在 Cache 禁用时运行如 Flash 写入/擦除、OTA 期间否则可能出现Illegal Instruction或Load/Store Prohibited错误。线程安全adc_oneshot_new_unit、adc_oneshot_config_channel、adc_oneshot_read、adc_oneshot_del_unit均保证线程安全可在不同 RTOS 任务中直接调用无需额外加锁。Kconfig 选项CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM控制 ADC 快速读取函数放置在 IRAM 还是 Flash见 components/esp_adc/Kconfig。四、ADC Continuous 模式驱动详解continuous 模式下ADC 对一路或多路模拟输入通道执行自动高速采样结果通过 DMA 高效传输到内存适用于音频采集、波形监测、电力计量等高频/周期性数据采集场景。4.1 转换帧Conversion Frame与转换结果continuous 模式以转换帧为单位组织数据转换帧Conversion Frame一个帧包含多个转换结果帧大小由adc_continuous_new_handle()按字节配置转换结果Conversion Result一个结果由多个字节组成字节数由宏SOC_ADC_DIGI_RESULT_BYTES定义其结构为adc_digi_output_data_t包含 ADC 单元、ADC 通道与原始数据。例如conv_frame_size 100表示一个转换帧包含100 / SOC_ADC_DIGI_RESULT_BYTES个转换结果。该概念在 adc_continuous.h 头部注释中有完整图示说明。4.2 资源分配创建与回收驱动句柄创建驱动前设置adc_continuous_handle_cfg_t见 adc_continuous.hmax_store_buf_size内部缓冲池最大字节数驱动将转换结果保存到该池conv_frame_size转换帧大小字节应为SOC_ADC_DIGI_DATA_BYTES_PER_CONV的倍数flags.flush_pool当缓冲池满时自动冲刷旧数据并写入新数据否则新转换结果将丢失。adc_continuous_handle_t handle NULL; adc_continuous_handle_cfg_t adc_config { .max_store_buf_size 1024, .conv_frame_size 256, }; ESP_ERROR_CHECK(adc_continuous_new_handle(adc_config, handle));adc_continuous_new_handle()可能因参数非法、内存不足等失败。特殊地返回ESP_ERR_NOT_FOUND的含义因芯片而异ESP32 表示 I2S0 外设已被占用ESP32-S2 表示 SPI3 已被占用支持 GDMA 的芯片则代表没有空闲的 GDMA 通道。不再使用驱动时调用adc_continuous_deinit()反初始化。4.3 通道与采样配置初始化后通过adc_continuous_config_t配置要采样的 IO见 adc_continuous.hpattern_num使用的 ADC 通道数量adc_pattern每个通道的配置列表类型为adc_digi_pattern_config_t包含atten衰减、channel通道号、unit所属 ADC 单元、bit_width原始结果位宽sample_freq_hz期望的采样频率Hz可用的采样频率范围见soc/soc_caps.hconv_mode连续转换模式format转换输出格式已标记 deprecated。调用adc_continuous_config()使配置生效。若返回ESP_ERR_INVALID_STATE说明驱动已启动此时不应再调用该 API。4.4 启动与停止ESP_ERROR_CHECK(adc_continuous_start(handle)); // 开始转换 ESP_ERROR_CHECK(adc_continuous_stop(handle)); // 停止转换4.5 注册事件回调通过adc_continuous_register_event_callbacks()可将用户函数挂接到驱动 ISR支持的回调定义于adc_continuous_evt_cbs_ton_conv_done一个转换帧完成时触发on_pool_ovf内部缓冲池已满时触发此时新转换结果将被丢弃通常因为adc_continuous_read()读取速度远慢于 ADC 转换速度。回调在ISR 上下文中执行因此回调内不能包含阻塞逻辑。事件数据adc_continuous_evt_data_t提供转换帧缓冲区指针conv_frame_buffer与大小size注意该缓冲区由驱动自行维护切勿手动 free。可通过user_data参数向回调传递用户上下文。当启用CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE时回调及回调调用的函数须放置在 IRAM涉及的变量也应放在内部 RAM。4.6 读取与解析转换结果adc_continuous_start()之后调用adc_continuous_read()获取转换结果可请求读取指定长度的结果若实际可用结果不足函数仍会将内部池中的数据搬运到用户缓冲区实际搬运长度通过out_length返回若内部池中暂无结果函数会阻塞timeout_ms毫秒直到至少产生一个结果超时仍未产生则返回ESP_ERR_TIMEOUT若结果填满内部池导致新结果丢失下次调用将返回ESP_ERR_INVALID_STATE。continuous 模式读出的原始数据需进一步解析为结构化结果。ESP-IDF 提供两种方式方式一adc_continuous_parse_data()手动解析uint32_t ret_num 0; esp_err_t ret adc_continuous_read(handle, result, EXAMPLE_READ_LEN, ret_num, 0); if (ret ESP_OK) { adc_continuous_data_t parsed_data[ret_num / SOC_ADC_DIGI_RESULT_BYTES]; uint32_t num_parsed_samples 0; esp_err_t parse_ret adc_continuous_parse_data(handle, result, ret_num, parsed_data, num_parsed_samples); if (parse_ret ESP_OK) { for (int i 0; i num_parsed_samples; i) { if (parsed_data[i].valid) { ESP_LOGI(TAG, ADC%d, Channel: %d, Value: %PRIu32, parsed_data[i].unit 1, parsed_data[i].channel, parsed_data[i].raw_data); } } } }注意raw_data_size必须是SOC_ADC_DIGI_RESULT_BYTES的整数倍且raw_data缓冲区需足够容纳raw_data_size字节数据解析函数内置了防缓冲区溢出与整数溢出的边界检查。方式二adc_continuous_read_parse()一步读取并解析adc_continuous_data_t parsed_data[64]; // 用户指定最大样本数 uint32_t num_samples 0; esp_err_t ret adc_continuous_read_parse(handle, parsed_data, 64, num_samples, 1000); if (ret ESP_OK) { for (int i 0; i num_samples; i) { if (parsed_data[i].valid) { ESP_LOGI(TAG, ADC%d, Channel: %d, Value: %PRIu32, parsed_data[i].unit 1, parsed_data[i].channel, parsed_data[i].raw_data); } } }解析后的结构体adc_continuous_data_t见 adc_continuous.h包含unitADC 单元ADC_UNIT_1 或 ADC_UNIT_2channelADC 通道号0-9raw_dataADC 原始数据值valid数据是否有效。与 oneshot 模式相同原始结果换算电压的公式为Vout Dout × Vmax / Dmax其中Dmax中的 bitwidth 对应adc_digi_pattern_config_t::bit_width。4.7 IIR 滤波器与 Monitor 监视器IIR 滤波器支持SOC_ADC_DIG_IIR_FILTER_SUPPORTED的芯片在 continuous 模式下提供两个 IIR 滤波器。创建时需设置adc_continuous_iir_filter_config_t包含unit、channel、coeff系数调用adc_new_continuous_iir_filter()创建adc_del_continuous_iir_filter()回收。在部分芯片上滤波器按 ADC 单元绑定SOC_ADC_DIG_IIR_FILTER_UNIT_BINDED一旦启用会对该单元所有已启用通道滤波建议使用滤波功能时每单元只启用一个通道避免滤波结果混合启用/停用分别调用adc_continuous_iir_filter_enable()/adc_continuous_iir_filter_disable()。Monitor 监视器支持SOC_ADC_MONITOR_SUPPORTED的芯片可创建监视器数量见SOC_ADC_DIGI_MONITOR_NUM对工作通道设置一个或两个阈值当转换结果超出阈值时在每个采样周期触发中断。配置结构体adc_monitor_config_t包含adc_unit、channel、h_threshold高阈值不用时置 -1、l_threshold低阈值不用时置 -1。操作 API 包括adc_continuous_monitor_enable/disable、adc_continuous_monitor_register_event_callbacks、adc_del_continuous_monitor。monitor 的典型应用是过零检测由于 ADC 无法直接处理负输入信号需先通过电路叠加DC 偏置把负信号平移进 ADC 量程——例如叠加 1 V 偏置可将 -1 V ~ 1 V 的信号变换为 0 V ~ 2 V。随后设置合适的上下阈值即可检测输入信号是否逼近零点从而识别信号相位变化adc_monitor_handle_t adc_monitor_handle NULL; adc_monitor_config_t zero_crossing_config { .adc_unit EXAMPLE_ADC_UNIT_1, // 指定要监视的 ADC 单元 .channel EXAMPLE_ADC_CHANNEL_0, // 指定要监视的 ADC 通道 .h_threshold 1100, // 高阈值接近 DC 偏置值可按需调整 .l_threshold 900, // 低阈值接近 DC 偏置值可按需调整 }; ESP_ERROR_CHECK(adc_new_continuous_monitor(zero_crossing_config, adc_monitor_handle)); adc_monitor_evt_cbs_t zero_crossing_cbs { .on_over_high_thresh example_on_exceed_high_thresh, .on_below_low_thresh example_on_below_low_thresh, }; ESP_ERROR_CHECK(adc_continuous_monitor_register_event_callbacks(adc_monitor_handle, zero_crossing_cbs, NULL)); ESP_ERROR_CHECK(adc_continuous_monitor_enable(adc_monitor_handle)); // ... 使用完毕后停用并删除 ESP_ERROR_CHECK(adc_continuous_monitor_disable(adc_monitor_handle)); ESP_ERROR_CHECK(adc_del_continuous_monitor(adc_monitor_handle));4.8 continuous 模式的其他要点电源管理启用CONFIG_PM_ENABLE后系统空闲时 APB 时钟频率可能被调整从而影响连续转换行为。continuous 驱动通过获取ESP_PM_APB_FREQ_MAX类型的电源管理锁来阻止该变化——锁在adc_continuous_start()后获取、adc_continuous_stop()后释放因此两者必须成对出现否则电源管理将失效。IRAM Safe默认所有 continuous API 均非 IRAM-safe。启用CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE后驱动内部 ISR 处理器变为 IRAM-safe即使 Cache 被禁用也能将转换结果保存到内部池。线程安全continuous 模式 API 不保证线程安全但驱动提供共享硬件互斥保护。五、ADC 校准驱动详解由于不同芯片的实际参考电压存在 1000 mV ~ 1200 mV 的制造偏差直接解读原始读数会产生较大误差。ADC 校准驱动通过软件修正偏差输出更精确的结果。5.1 校准方案Scheme的选择与创建从校准驱动视角看校准方案创建后得到一个校准句柄adc_cali_handle_t。可使用adc_cali_check_scheme()查询芯片支持的校准方案若已知支持方案可跳过此步直接调用对应创建函数。芯片支持的方案由宏标识ADC_CALI_SCHEME_VER_LINE_FITTING直线拟合ESP32、ESP32-S2、ESP32-C2ADC_CALI_SCHEME_VER_CURVE_FITTING曲线拟合ESP32-C3、ESP32-S3、ESP32-C6、ESP32-H2、ESP32-C5、ESP32-P4 等。Line Fitting 方案配置结构体adc_cali_line_fitting_config_t包含unit_id原始结果来源 ADC、atten所用衰减、bitwidth原始结果位宽。ESP32 上还有default_vref配置项通常置 0 即可——Line Fitting 方案并不依赖该值但若板子上未烧录方案所需的 eFuse 位驱动将依赖该值完成校准。可用adc_cali_scheme_line_fitting_check_efuse()检查 eFuse 位状态正常为ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP两点值或ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF参考电压值当为ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF时需设置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)); // ... 使用完毕后 ESP_ERROR_CHECK(adc_cali_delete_scheme_line_fitting(handle));Curve Fitting 方案配置结构体adc_cali_curve_fitting_config_t同样包含unit_id、atten、bitwidth以及为扩展性保留的chan字段。在 ESP32-C3 / ESP32-S3 上校准只与衰减相关、与通道无关而在 ESP32-C6 / ESP32-H2 / ESP32-C5 / ESP32-P4 上校准不仅随衰减变化、还与通道相关因此chan需填写原始结果来源通道。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)); // ... 使用完毕后 ESP_ERROR_CHECK(adc_cali_delete_scheme_curve_fitting(handle));eFuse 相关失败当创建函数返回ESP_ERR_NOT_SUPPORTED说明校准方案所需的 eFuse 位未正确烧录。ESP-IDF 的校准方案基于片上特定 ADC 校准 eFuse 位Espressif 保证这些位在模组制造时已烧录用户无需自行烧录。若遇到此类错误请联系官方技术支持渠道。若想使用自定义校准方案可参照 components/esp_adc/interface/adc_cali_interface.h 中的函数表adc_cali_scheme_t实现创建函数。5.2 结果换算raw → mV校准特性设置完成后调用adc_cali_raw_to_voltage()将原始结果转换为以 mV 为单位的校准结果int voltage[2][2]; 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_STATE说明校准方案句柄尚未创建需先创建方案句柄或用adc_cali_check_scheme()确认支持方案。注意ESP32-C2该校准仅支持ADC_ATTEN_DB_0与ADC_ATTEN_DB_12两种衰减。0 dB 下衰减为 0 dB不支持高于 950 mV 的输入电压12 dB 下实际衰减为 11 dB不支持高于 2800 mV 的输入电压。5.3 线程安全工厂函数adc_cali_check_scheme()及esp_adc_cali_new_scheme()由驱动保证线程安全其他以adc_cali_handle_t为首参的函数不保证线程安全应避免从多个任务同时调用。5.4 降低噪声Minimize NoiseADC 对噪声敏感可能导致读数偏差较大。根据使用场景可在使用的 ADC 输入引脚上连接旁路电容例如 100 nF 陶瓷电容来抑制噪声此外多次采样multisampling也是一种有效的降噪手段。上图展示了 ESP32 上通过旁路电容与 64 次多次采样组合后的噪声抑制效果。ESP32 上还可通过 Kconfig 选项裁剪校准代码体积CONFIG_ADC_CALI_EFUSE_TP_ENABLE、CONFIG_ADC_CALI_EFUSE_VREF_ENABLE、CONFIG_ADC_CALI_LUT_ENABLE若不用 12 dB 衰减下的校准可关闭查找表。上述校准选项定义于 components/esp_adc/Kconfig。六、硬件限制与注意事项汇总芯片限制说明通用同一 ADC 单元同一时刻只能工作于一种模式oneshot 或 continuous驱动已提供保护RNG 随机数发生器以 ADC 为输入源ADC 工作时 RNG 随机性下降差分芯片SOC_ADC_DIFF_SUPPORTED单端模式下若以 N 侧通道作为输入接口其原始数据极性反转-2 V ~ 2 V 输入对应 N 侧原始码 4393 ~ 0请使用校准 API 转换ESP32 / ESP32-S2 / ESP32-S3ADC2 同时被 Wi-Fi 使用驱动已提供两者间的互斥保护ESP32-C3ADC2 oneshot 模式因硬件限制不再支持结果不稳定见芯片勘误表可启用CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3强制使用ESP32-C3 / ESP32-S3ADC2 DMA 功能因硬件限制不再支持可启用CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3强制使用ESP32continuous 驱动使用 I2S0 外设作为 DMA FIFOI2S0 被占用时adc_continuous_new_handle()返回ESP_ERR_NOT_FOUNDESP32-DevKitC 的 GPIO0 因自动下载电路不可用ESP-WROVER-KIT 的 GPIO 0/2/4/15 不可用ESP32-S2continuous 驱动使用 SPI3 外设作为 DMA FIFO被占用时同样返回ESP_ERR_NOT_FOUND相关 Kconfig 选项集中在 components/esp_adc/KconfigCONFIG_ADC_DISABLE_DAC_OUTPUTADC2 使用时默认禁用 DAC 输出、CONFIG_ADC_ENABLE_DEBUG_LOG等。七、示例工程与 API 参考examples/peripherals/adc/oneshot_read演示使用 oneshot 驱动从 GPIO 读取单次 ADC 读数并调用校准函数获得以 mV 为单位的校准结果examples/peripherals/adc/continuous_read演示在开发板上使用 continuous 模式DMA从 GPIO 引脚持续读取 ADC 数据。两个示例均为可直接编译运行的完整工程是学习两种驱动模式配置流程的最佳起点。完整 API 参考类型、配置结构体与函数文档可进一步阅读oneshot 模式 API实现见 adc_oneshot.ccontinuous 模式 API实现见 adc_continuous.c校准驱动 API实现见 adc_cali.c总结ESP-IDF 的 ADC 驱动体系以原始数据 校准换算为设计核心oneshot 模式以极简 API 覆盖低频按需采样场景continuous 模式借助 DMA、转换帧、事件回调、IIR 滤波与阈值监视器等机制支撑高频连续采集而校准驱动则通过 Line Fitting / Curve Fitting 两种方案将制造偏差修正到 mV 级精度。实际选型时只需根据采样频率需求确定模式、依据信号幅度选择衰减档位并牢记各芯片特有的硬件限制与电源管理、IRAM-safe 等约束即可在 ESP32 全系列芯片上稳定、精确地完成模拟信号采集。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考