章节导航#

• 本章重要 API 函数（仅 ADC Oneshot 相关）
• 学习前后依赖
• 一、理解 ADC——从电压到数字的桥梁
  • 1.1 模数转换的核心流程
  • 1.2 Oneshot vs Continuous：两种采样哲学
  • 1.3 为什么本项目选 Oneshot
• 二、运行链路树
• 三、ADC Oneshot 数据读取流程
  • 3.1 单次转换时序
  • 3.2 双通道采样不是真正”同时”
  • 3.3 数据格式
• 四、重点行注释
  • [#[myadc.c L8-12|myadc.c L8-12]]
  • [#[myadc.c L13|myadc.c L13]]
  • [#[myadc.c L15-18|myadc.c L15-18]]
  • [#[myadc.c L19-20|myadc.c L19-20]]
  • [#[main.c L20-21|main.c L20-21]]
  • [#[main.c L22-23|main.c L22-23]]
• 五、整体架构
• 六、模块实现说明
  • 6.1 MYADC 组件
  • 6.2 main 模块
• 七、文件简单注释
  • [#[myadc.c|myadc.c]]
  • [#[main.c|main.c]]
• 容易踩坑
• 八、关键要点总结
• 九、扩展思路
• Tips
  • 低速 vs 连续：何时选用哪种模式
  • ADC 衰减器的深层意义
  • 踩坑实录
  • 知识衔接

1.1 模数转换的核心流程#

ADC（Analog-to-Digital Converter，模数转换器）负责把模拟电压信号转换成数字量，让 MCU 能够读取和处理。ESP32-S3 片上集成的 SAR ADC（逐次逼近型）是这个项目唯一的模拟输入通道：

12 bit 分辨率意味着数字量范围是 0 ~ 4095，对应电压换算：

1
电压 = (ADC值 / 4095) × 量程电压

SAR ADC 工作过程分四步：

1
1. 采样保持 → 电容阵列捕获输入电压瞬间值（纳秒级）
2
2. 逐次逼近 → DAC 产生参考电压，与采样电压逐位比较
3
              ┌─ bit11: DAC输出 = 2.5V, 输入=1.8V → 1.8 < 2.5 → bit11=0, 参考电压折半
4
              ├─ bit10: DAC输出 = 1.25V, 输入=1.8V → 1.8 > 1.25 → bit10=1, 参考电压增加
5
              ├─ bit9:  DAC输出 = 1.875V, 输入=1.8V → 1.8 < 1.875 → bit9=0
6
              └─ ... 重复 12 次得到最终值
7
3. 数字输出 → 12 bit 结果写入寄存器
8
4. 函数返回 → 调用 adc_oneshot_read() 拿到 int 型原始值

关键理解：12 bit SAR ADC 每次转换需要 12 个时钟周期逐位逼近。这意味着 Conversion Time = 12 / ADC_Clock，在低速场景（如 500ms 刷新一次 LCD）下几乎感知不到延迟，但高速场景（如 20 kHz 波形采样）就开始吃力了。

1.2 Oneshot vs Continuous：两种采样哲学#

ESP32-S3 的 ADC 驱动在 ESP-IDF 中分为两套 API：adc_oneshot 和 adc_continuous。本项目使用 Oneshot（单次转换） 模式。

Oneshot 模式不涉及 DMA：每次调用 adc_oneshot_read()，CPU 都要进入驱动，等待当前通道转换完成，然后拿到一个值。流程更直接，但 CPU 参与度高。

而 Continuous 模式下 DMA 的工作流程如下：

1
ADC 硬件连续采样
2
        │
3
        ▼
4
SAR 转换完成，产生数据
5
        │
6
        ▼
7
DMA 控制器把数据搬到内存环形缓冲区
8
        │
9
        ▼
10
累积到一帧（如 8 字节）后触发 on_conv_done 回调
11
        │
12
        ▼
13
CPU 在回调里解析数据

Continuous 模式下 CPU 不用一次次地发起转换请求，只需要在 DMA 搬够一帧数据后处理一次。采样和搬运由硬件完成，CPU 开销小，适合高速场景。

1.3 为什么本项目选 Oneshot#

• 只需要每 500 ms 刷新一次 LCD，速率很低。
• 无需 DMA 环形缓冲区和回调，代码更直观。
• 直接得到 int 型 ADC 值，不需要像 Continuous 那样从原始字节中拼出 12 bit 数据。

两种模式的数据形态差异一目了然：

Oneshot 一次读取直接拿到结果：

1
adc_oneshot_read(handle, CH3, &adc1_value)
2
           │
3
           ▼
4
    adc1_value = 0 ~ 4095   (12 bit 原始值)

Continuous 则需要 DMA 搬运并解析帧：

1
ADC 连续采样 → DMA 搬运到缓冲区
2
           │
3
           ▼
4
    on_conv_done 回调
5
           │
6
           ▼
7
    data_value = edata->conv_frame_buffer   (原始字节数组)
8
           │
9
           ▼
10
    adc_value = ((data_value[1] & 0x0F) << 8) | data_value[0]

本项目采用 Oneshot，因此没有 DMA、帧格式、缓冲区、conv_frame_size 等概念。

3.1 单次转换时序#

Oneshot 模式下，CPU 每次调用 adc_oneshot_read() 都会触发一次完整的 SAR 转换：

1
CPU 调用 adc_oneshot_read()
2
           │
3
           ▼
4
    选择 ADC1 目标通道（CH3 或 CH4）
5
           │
6
           ▼
7
    SAR 转换核心开始逐次逼近
8
           │
9
           ▼
10
    转换完成，得到 12 bit 数字量
11
           │
12
           ▼
13
    结果写入 &adc1_value / &adc2_value
14
           │
15
           ▼
16
    函数返回，CPU 继续执行

3.2 双通道采样不是真正”同时”#

ESP32-S3 的 ADC1 内部只有一个 SAR 转换核心：

1
GPIO4(CH3) ─┐
2
            ├─> ADC1 MUX ─> SAR 核心 ─> raw
3
GPIO5(CH4) ─┘
4

5
raw 为 12 bit 原始值，范围 0 ~ 4095。

1
atten 越大，可测输入范围越高：
2

3
DB_0   -> 低电压范围，精度较细
4
DB_2_5 -> 范围略增
5
DB_6   -> 范围继续增大
6
DB_11  -> 本项目使用，约 0 ~ 2.6 V

1
Oneshot:
2
CPU 调用 read -> 等待转换 -> 直接得到 int raw
3

4
Continuous:
5
ADC 连续采样 -> DMA 缓冲区 -> 回调解析帧

1
adc_init()
2
  │ 配置 unit/channel/atten
3
  ▼
4
adc_oneshot_read()
5
  │ 触发一次 SAR 转换
6
  ▼
7
raw 结果
8
  │ 可换算为电压
9
  ▼
10
LCD 显示

3.3 数据格式#

Oneshot 模式直接返回一个 int 类型的 12 bit 原始值，范围 0 ~ 4095，无需像 Continuous 模式那样解析字节帧。

myadc.c L8-12#

1
adc_oneshot_unit_init_cfg_t oneshot_structure = {
2
    .clk_src = ADC_RTC_CLK_SRC_DEFAULT,
3
    .ulp_mode = ADC_ULP_MODE_DISABLE,
4
    .unit_id = ADC_UNIT_1,
5
};

作用：配置 ADC oneshot 单元级别的参数。

myadc.c L13#

1
adc_oneshot_new_unit(&oneshot_structure, &adc_unit_handle);

作用：根据上面的配置创建 ADC oneshot 单元句柄，后续所有通道配置和读取都需要使用该句柄。

myadc.c L15-18#

1
adc_oneshot_chan_cfg_t oneshot_chan_structure = {
2
    .atten = ADC_ATTEN_DB_11,
3
    .bitwidth = ADC_BITWIDTH_12,
4
};

作用：配置每个 ADC 通道的衰减和分辨率。

myadc.c L19-20#

1
adc_oneshot_config_channel(adc_unit_handle, ADC_CHANNEL_3, &oneshot_chan_structure);
2
adc_oneshot_config_channel(adc_unit_handle, ADC_CHANNEL_4, &oneshot_chan_structure);

作用：将 CH3 和 CH4 都应用上述配置。

• ADC_CHANNEL_3 对应 GPIO4。
• ADC_CHANNEL_4 对应 GPIO5。

main.c L20-21#

1
adc_oneshot_read(adc_unit_handle, ADC_CHANNEL_3, &adc1_value);
2
adc_oneshot_read(adc_unit_handle, ADC_CHANNEL_4, &adc2_value);

作用：触发单次转换并读取结果。

说明：adc_oneshot_read() 是阻塞调用，内部会等待转换完成并将结果写入第三个参数指向的变量。

main.c L22-23#

1
lcd_show_num(1, 6, adc1_value, 4, YELLOW, BLACK);
2
lcd_show_num(2, 6, adc2_value, 4, YELLOW, BLACK);

作用：在第 1 行第 6 列、第 2 行第 6 列分别显示 adc1_value 和 adc2_value，显示宽度为 4 位。

总览图：Oneshot 软件到硬件链路#

1
main/main.c
2
  │ 初始化 LCD、ADC，循环读取并显示
3
  ▼
4
components/MYADC/myadc.c
5
  │ 封装 ADC oneshot 初始化
6
  │ 导出 adc_unit_handle
7
  ▼
8
ESP-IDF adc_oneshot
9
  │ 创建单元、配置通道、触发转换
10
  ▼
11
ESP32-S3 ADC1
12
  │ CH3/GPIO4，CH4/GPIO5
13
  ▼
14
12 bit raw 结果

局部图：raw 到显示值#

1
raw: 0 ~ 4095
2
  │
3
  ├─ 直接显示 ADC 原始值
4
  │
5
  └─ 可换算电压：raw / 4095 × 3.3V

6.1 MYADC 组件#

文件：

• myadc.h
• myadc.c

头文件职责：

• 导出全局句柄 adc_unit_handle，供 main.c 直接调用读取。
• 导出 adc_init() 初始化函数。

源文件职责：

• 使用 adc_oneshot_unit_init_cfg_t 配置 ADC1 单元。
• 调用 adc_oneshot_new_unit() 创建句柄。
• 使用 adc_oneshot_chan_cfg_t 配置 12 bit、11 dB 衰减。
• 调用 adc_oneshot_config_channel() 配置 CH3 和 CH4。

6.2 main 模块#

文件：

• main.c

职责：

• 初始化 LCD 和 ADC。
• 在 LCD 上固定显示两行标签：adc1: 和 adc2:。
• 主循环每 500 ms 读取一次两个通道，更新显示。

myadc.c#

1
#include "myadc.h"
2
#include "esp_adc/adc_oneshot.h"
3

4
adc_oneshot_unit_handle_t adc_unit_handle;  // ADC oneshot 单元句柄
5

6
void adc_init(void)
7
{
8
    // 1. 配置并创建 ADC oneshot 单元
9
    adc_oneshot_unit_init_cfg_t oneshot_structure = {
10
        .clk_src = ADC_RTC_CLK_SRC_DEFAULT,
11
        .ulp_mode = ADC_ULP_MODE_DISABLE,
12
        .unit_id = ADC_UNIT_1,
13
    };
14
    adc_oneshot_new_unit(&oneshot_structure, &adc_unit_handle);
15

16
    // 2. 配置通道：12 bit、11 dB 衰减
17
    adc_oneshot_chan_cfg_t oneshot_chan_structure = {
18
        .atten = ADC_ATTEN_DB_11,
19
        .bitwidth = ADC_BITWIDTH_12,
20
    };
21

22
    // 3. 应用配置到 CH3 和 CH4
23
    adc_oneshot_config_channel(adc_unit_handle, ADC_CHANNEL_3, &oneshot_chan_structure);
24
    adc_oneshot_config_channel(adc_unit_handle, ADC_CHANNEL_4, &oneshot_chan_structure);
25
}

main.c#

1
#include <stdio.h>
2
#include "freertos/FreeRTOS.h"
3
#include "freertos/task.h"
4
#include "esp_adc/adc_oneshot.h"
5
#include "myadc.h"
6
#include "lcd.h"
7

8
int adc1_value = 0;
9
int adc2_value = 0;
10

11
void app_main(void)
12
{
13
    lcd_init();  // 初始化 LCD
14
    adc_init();  // 初始化 ADC oneshot
15

16
    // 显示固定标签
17
    lcd_show_string(1, 1, "adc1:", GREEN, BLACK);
18
    lcd_show_string(2, 1, "adc2:", GREEN, BLACK);
19

20
    while (1)
21
    {
22
        // 单次读取两个通道
23
        adc_oneshot_read(adc_unit_handle, ADC_CHANNEL_3, &adc1_value);
24
        adc_oneshot_read(adc_unit_handle, ADC_CHANNEL_4, &adc2_value);
25

26
        // 刷新 LCD 显示
27
        lcd_show_num(1, 6, adc1_value, 4, YELLOW, BLACK);
28
        lcd_show_num(2, 6, adc2_value, 4, YELLOW, BLACK);
29

30
        vTaskDelay(500);  // 每 500 ms 刷新一次
31
    }
32
}

低速 vs 连续：何时选用哪种模式#

这是 ADC 学习中最容易混淆的决策点。一句话总结：

Oneshot = “我需要什么数据就什么时候去问”，Continuous = “硬件持续采样，CPU 需要时来取”

一个实用准则：如果你在主循环里手动 vTaskDelay(100) 再读一次 ADC，那 Oneshot 一定够用。如果你需要知道”两次采样之间”发生了什么，必须用 Continuous。

ADC 衰减器的深层意义#

很多初学者以为衰减器只是”放大/缩小信号”，但它的原理远比这复杂：

什么是衰减器（Attenuator）？

ESP32-S3 的 ADC 输入范围由参考电压决定，但外部信号可能高达 3.3V——直接输入会烧毁 ADC 前端。衰减器就是一个电阻分压网络，把高压信号压缩到 ADC 核心可接受的范围。

1
外部输入电压 (0~3.3V)
2
       │
3
       ▼
4
 ┌─────────────┐
5
 │  衰减器      │  ← 电阻分压，把高压压低压
6
 │  (Attenuator)│
7
 └──────┬──────┘
8
        │ 压缩后的电压 (0~Vref)
9
        ▼
10
  ┌───────────┐
11
  │  ADC 核心  │  ← SAR 转换
12
  │  (12 bit) │
13
  └───────────┘

衰减档位的选择策略：

容易误解的点：衰减器是”衰减信号”不是”放大信号”。DB_11 衰减意味着”把输入的 2.6V 衰减到 ADC 核心能测量的范围”，而不是”把信号放大 11dB”。dB 值越大 → 分压越多 → 可测量范围越大 → 但分辨率（mV/LSB）越低。

实战建议：

• 测量 3.3V 系统下的普通传感器 → 用 DB_11
• 测量 1.2V 基准电压 → 用 DB_0（精度最高）
• 不确定信号范围 → 先用 DB_11 试探，再缩小档位

踩坑实录#

1. ADC 值跳变（噪声）：常见于 GPIO 引脚悬空。即使配置了内部下拉，悬空引脚的 ADC 读数仍然会随环境电磁噪声波动。解决方法：外接 100nF 电容到 GND，或并联 10kΩ 下拉电阻。

2. 读数不是 0 ~ 4095：ESP-IDF 的 adc_oneshot_read() 返回的是校准后的原始值，在没有启用校准的情况下，数值可能因为芯片差异偏离理论范围。不要惊讶于满量程不是 4095——这在未校准的 ADC 上是正常的。

3. WiFi 开启后 ADC2 读数异常：ESP32-S3 的 ADC2 与 WiFi 共用内部资源。如果项目中需要 WiFi + ADC，一定要用 ADC1（本项目已这样做）。这是一个极易犯的错误——代码跑通了单机测试，加上 WiFi 后 ADC 就不准了。

知识衔接#

• 上一章：LCD 显示驱动——本项目的 ADC 值最终显示在 LCD 上，lcd_show_num() 和 lcd_show_float() 是你已掌握的工具。
• 下一章：02_连续ADC——深入 DMA 驱动的 Continuous 模式，把采样率从”每秒几次”提升到”每秒两万次”。理解 TYPE2 帧格式后你会发现，Continuous 和 Oneshot 用的是同一套硬件，只是驱动策略不同。
• 后续硬件：BH1750（I2C 数字光传感器）是一个”不需要 ADC 的传感器”——它内部自带 ADC 和 DSP，通过 I2C 直接输出数字量。这是模拟传感器（接 ADC）和数字传感器（接 I2C/SPI）的关键分水岭。