模数转换器 (ADC) 单次转换模式驱动

下文将分节概述安装和运行 ADC 的基本步骤：

资源分配 - 介绍获取 ADC 句柄所需设置的参数，以及如何在 ADC 完成工作后回收资源。

配置 ADC 单元实例 - 介绍配置 ADC 单元所需设置的参数，用于获取 ADC 转换的原始结果。

读取转换结果 - 介绍如何获取 ADC 转换的原始结果。

硬件限制 - 介绍与 ADC 相关的硬件限制。

电源管理 - 介绍电源管理的相关内容。

IRAM 安全 - 介绍在禁用 cache 时，如何读取 ADC 转换的原始结果。

线程安全 - 介绍由驱动程序认证为线程安全的 API。

Kconfig 选项 - 介绍支持的 Kconfig 选项，不同选项对驱动程序的操作会产生不同影响。

ADC 单次转换模式驱动基于 ESP32 SAR ADC 模块实现，不同的 ESP 芯片可能拥有不同数量的独立 ADC。对于单次转换模式驱动而言，ADC 实例以 adc_oneshot_unit_handle_t 表示。

请设置所需的初始配置结构体 adc_oneshot_unit_init_cfg_t 安装 ADC 实例，具体如下：

adc_oneshot_unit_init_cfg_t::unit_id 选择 ADC。请参阅 技术规格书，了解对应 ADC 的专用模拟 IO 管脚。

adc_oneshot_unit_init_cfg_t::clk_src 选择 ADC 的时钟源。设置为 0 时，驱动程序将使用默认时钟源，详情请参阅 adc_oneshot_clk_src_t。

adc_oneshot_unit_init_cfg_t::ulp_mode 设置是否支持 ADC 在 ULP 模式下工作。

完成 ADC 初始配置后，使用已设置的初始配置结构体 adc_oneshot_unit_init_cfg_t 调用 adc_oneshot_new_unit()。如果分配成功，该函数将返回 ADC 单元实例句柄。

该函数可能因参数无效、内存不足等原因返回错误代码。比如，当要分配的 ADC 实例已经注册时，该函数会返回 ESP_ERR_NOT_FOUND 错误。可用 ADC 数量可通过 SOC_ADC_PERIPH_NUM 查看。

如果不再需要先前创建的 ADC 单元实例，请调用 adc_oneshot_del_unit() 回收该实例，相关的硬件和软件资源也会回收。

创建 ADC 单元实例后，请设置 adc_oneshot_chan_cfg_t 配置 ADC IO 以测量模拟信号，具体如下：

adc_oneshot_chan_cfg_t::atten，ADC 衰减。请参阅 技术参考手册 > 片上传感器与模拟信号处理。

adc_oneshot_chan_cfg_t::bitwidth，原始转换结果的位宽。

备注

ADC IO 及其对应的 ADC 通道编号，请参阅 技术规格书。

此外，可以使用 adc_continuous_io_to_channel() 和 adc_continuous_channel_to_io() 了解 ADC 通道和 ADC IO。

为使以上设置生效，请使用上述配置结构体调用 adc_oneshot_config_channel()，并指定要配置的 ADC 通道。函数 adc_oneshot_config_channel() 支持多次调用，以配置不同的 ADC 通道。驱动程序将在内部保存每个通道的配置。

完成上述配置后，ADC 即可测量来自配置好的 ADC 通道的模拟信号。调用 adc_oneshot_read() 可以获取 ADC 通道的原始转换结果。

adc_oneshot_read() 可安全使用。ADC 由其他驱动程序/外设共享，请参阅 硬件限制。函数 adc_oneshot_read() 使用互斥锁，避免与其他函数同时使用硬件，因此该函数不应在 ISR 上下文中使用。当 ADC 由其他驱动程序/外设占用时，该函数可能出错，并返回 ESP_ERR_TIMEOUT 错误。此时，ADC 原始结果无效。

该函数可能因参数无效而调用失败。

通过该函数获取的 ADC 转换结果为原始数据。可以使用以下公式，根据 ADC 原始结果计算电压：

其中：

Vout

数字输出结果，代表电压。

Dout

ADC 原始数字读取结果。

Vmax

可测量的最大模拟输入电压，与 ADC 衰减相关，请参考 技术参考手册 > 片上传感器与模拟信号处理。

Dmax

输出 ADC 原始数字读取结果的最大值，即 2^位宽，位宽即之前配置的 adc_digi_pattern_config_t::bit_width。

若需进一步校准，将 ADC 原始结果转换为以 mV 为单位的电压数据，请参考校准文档 模数转换器 (ADC) 校准驱动程序。

随机数生成器 (RNG) 以 ADC 为输入源。使用 ADC 单次转换模式驱动从 RNG 生成随机数时，随机性会减弱。

一个 ADC 单元每次只能在一种操作模式下运行，可以是连续模式或单次模式。adc_oneshot_start() 提供了保护措施。

Wi-Fi 也使用 ADC2，adc_oneshot_read() 提供了 Wi-Fi 驱动与 ADC 单次转换模式驱动间的保护。

ESP32-DevKitC：GPIO0 已用于自动烧录功能，不能用于 ADC 单次转换模式。

ESP-WROVER-KIT：GPIO0、GPIO2、GPIO4 和 GPIO15 已有其他用途，不能用于 ADC 单次转换模式。

启用电源管理，即启用 CONFIG_PM_ENABLE 时，系统在空闲状态下可能会调整系统时钟频率。然而，ADC 单次转换模式驱动以轮询例程运行，adc_oneshot_read() 会不断检查 CPU 是否完成读取，直到函数返回。在此期间，ADC 单次转换模式驱动程序所在的任务不会受阻塞。因此，在读取时时钟频率保持稳定。

flash 写入/擦除、OTA 等原因都可能导致 cache 禁用，此时，默认不应运行任何 ADC 单次转换模式驱动 API。如果在禁用 cache 时执行了 ADC 单次转换模式驱动 API，可能会出现类似 Illegal Instruction 或 Load/Store Prohibited 的错误。

adc_oneshot_new_unit()

adc_oneshot_config_channel()

adc_oneshot_read()

上述函数均为线程安全，使用时，可以直接从不同的 RTOS 任务中调用以上函数，无需额外锁保护。

adc_oneshot_del_unit() 非线程安全。此外，与上文中线程安全的函数一起调用该函数时，可能导致线程安全函数的调用出错。

CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM 决定了放置 ADC 快速读取函数的位置，即 IRAM 或 flash 中，详情请参阅 IRAM 安全。