AP3216C：读取环境光与接近数据

本课对应《DNESP32S3 使用指南（IDF 版）》第 25 章。配套完整工程：examples/20-ap3216c。

环境与验收边界： DNESP32S3 V1.2，ESP-IDF v5.5.5；本机 macOS 构建通过。Ubuntu 26、外设接线、屏幕效果和实际测量仍待实板验收。下文输出均为预期格式，不能当作已采集的硬件日志。

本课完成后能做什么

无遮挡和遮挡时观察 ALS、PS 的趋势以及 valid 标志。
解释 IR/PS 掩码，能区分通信错误与无效测量。
用错误地址实验时得到明确错误，恢复地址后可重新测量。

硬件连接与资源

信号或资源	对应关系
I²C0	SDA GPIO41，SCL GPIO42
AP3216C	地址 0x1e，板载
中断输出	接 XL9555 IO0_0，本课轮询不用
外加接线	无，直接观察板载 ALS&PS 区域

以下为正点原子 DNESP32S3 V1.2 原理图的相关页，保留原厂标识；表格用于快速定位，遇到板卡版本差异以实际原理图为准。点击图片可查看引脚与网络名。

DNESP32S3 原理图第 2 页

DNESP32S3 原理图第 3 页

本课信号与数据处理流程

一个芯片提供三类读数

ALS 是环境光通道，PS 是接近检测通道，IR 是红外通道。本课读出原始数值并观察变化，不把 PS 的整数说成厘米，也不在没有量程配置依据时把 ALS 直接写成 lux。

芯片地址为 0x1e。向系统配置寄存器 0 写 0x04 复位，等待 10 ms，再写 0x03 启用测量，等待首轮转换。初始化后每 200 ms 读取一次，不用紧密循环向还没完成转换的器件索要“新数据”。

寄存器不是每两个字节就能直接拼接

从 0x0A 连续读取 6 字节：

通道	组装方式	有效性
IR	高字节左移 2 位，低字节取 bit1..0	低字节 bit7 为无效标志
ALS	高字节左移 8 位，再或低字节	16 位原始值
PS	高字节取低 6 位左移 4，低字节取低 4 位	低字节 bit6 为无效标志

这些掩码把状态位从数据位里去掉。把整个低字节拼入 PS，会把无效标志当成测量数值。

“读失败”和“读到了无效状态”分别处理

I²C 超时是通信错误；通信成功但 IR/PS 有效位未满足，是传感器状态。这两层不能合并成一个数字 0，因为真实暗环境或远离物体也可能给出很小的读数。

BSP 先读入临时数组，确认事务成功后才更新输出结构。应用打印原始值及 valid 标志；通信失败会降低重试频率到 1 秒，并重新初始化。遮挡、强光或距离变化的具体数值依赖现场，不能照抄示例数字作为验收门槛。

工程如何组织

驱动放在 components/BSP/，应用放在 main/main.c。本工程包含 BUS、AP3216C 模块。项目根目录的 components/BSP 会被 ESP-IDF 自动发现，main 的 PRIV_REQUIRES BSP 声明组件依赖；INCLUDE_DIRS 导出头文件搜索路径，不是运行时查找文件。

应用代码：入口与处理流程

下面代码直接取自配套工程的 main/main.c，头文件和 BSP 实现在仓库中一并提供。初学时先看 app_main()，再追踪它调用的模块。

 1#include <stdio.h>
 2#include <stdint.h>
 3#include <stdbool.h>
 4#include <string.h>
 5#include <stdlib.h>
 6#include <assert.h>
 7#include "esp_err.h"
 8#include "esp_log.h"
 9#include "esp_timer.h"
10#include "freertos/FreeRTOS.h"
11#include "freertos/task.h"
12#include "ap3216c.h"
13void app_main(void)
14{
15    i2c_master_bus_handle_t bus;
16    ESP_ERROR_CHECK(bus_init(0,CONFIG_LESSON_I2C_SDA,CONFIG_LESSON_I2C_SCL,&bus));
17    ESP_ERROR_CHECK(light_open(bus));
18    bool ready=false;
19    while(1) {
20        esp_err_t err=ESP_OK;
21        if(!ready) { err=light_reset(); ready=(err==ESP_OK); }
22        light_sample_t s;
23        if(ready) err=light_read(&s);
24        if(err==ESP_OK) ESP_LOGI("light","ALS=%u IR=%u valid=%d PS=%u valid=%d",
25            s.als,s.ir,s.ir_valid,s.ps,s.ps_valid);
26        else { ready=false; ESP_LOGW("light","%s",esp_err_to_name(err)); }
27        vTaskDelay(pdMS_TO_TICKS(ready ? 200 : 1000));
28    }
29}

BSP 关键实现：AP3216C

以下是本课对应驱动的完整源文件。对外声明见 ap3216c.h。公共 BUS 模块统一使用新 I²C master API，将单次事务等待限制在 50 ms；设备 API 使用 7 位地址。

 1#include "ap3216c.h"
 2#include "freertos/FreeRTOS.h"
 3#include "freertos/task.h"
 4static i2c_master_dev_handle_t s_dev;
 5esp_err_t light_open(i2c_master_bus_handle_t bus) { return bus_device(bus, 0x1e, &s_dev); }
 6esp_err_t light_reset(void)
 7{
 8    ESP_RETURN_ON_ERROR(reg_write(s_dev, 0, 4), "light", "reset");
 9    vTaskDelay(pdMS_TO_TICKS(10));
10    ESP_RETURN_ON_ERROR(reg_write(s_dev, 0, 3), "light", "enable");
11    vTaskDelay(pdMS_TO_TICKS(120)); // 首次转换完成后才能读。
12    return ESP_OK;
13}
14esp_err_t light_read(light_sample_t *out)
15{
16    uint8_t b[6];
17    ESP_RETURN_ON_ERROR(reg_read(s_dev, 0x0a, b, 6), "light", "read");
18    light_sample_t next = {.ir=((uint16_t)b[1]<<2)|(b[0]&3),
19        .als=((uint16_t)b[3]<<8)|b[2], .ps=((b[5]&63)<<4)|(b[4]&15),
20        .ir_valid=!(b[0]&0x80), .ps_valid=!(b[4]&0x40)};
21    *out = next; // 只有整次读取成功才交付新数据。
22    return ESP_OK;
23}

CMake 与中文注释

1# 私有依赖只供本组件源码使用。
2idf_component_register(SRCS "main.c" INCLUDE_DIRS "."
3    PRIV_REQUIRES esp_timer BSP )

每个工程有自己的 project() 名称和 sdkconfig.defaults。VS Code 设置已关闭普通 CMake 自动配置，C/C++ 语言服务读取 build/compile_commands.json；首次构建前文件尚不存在，应先激活 IDF 并构建，而不是手工拼头文件路径。

编译、烧录与观察

 1# 激活 EIM 安装的 IDF；每个新终端都需要激活。
 2source ~/.espressif/tools/activate_idf_v5.5.5.sh
 3# 进入单个示例根目录，不是在 examples 总目录运行。
 4cd ~/mycode/esp32-blog/examples/20-ap3216c
 5# 首次配置目标；已有正确配置时不用每次重复 set-target。
 6idf.py set-target esp32s3
 7# 编译会生成 build/compile_commands.json，供 VS Code 使用。
 8idf.py build
 9# 把这个值换成实际连接开发板的端口；macOS 通常为 /dev/cu.*。
10PORT=/dev/ttyUSB0
11idf.py -p "$PORT" flash monitor
12# 串口监视退出：Ctrl+]。

预期输出或屏幕内容（示意；数值、日志前缀和启动时间依现场而变）：

1light: ALS=<raw> IR=<raw> valid=1 PS=<raw> valid=1

故障定位与逐项验收

先检查目标是否是 esp32s3、实际端口与供电，再按本文引脚表核对跳线。编译成功只能说明源码与工具链兼容，无法证明模块型号、物理线路或时序已经正确。

无遮挡和遮挡时观察 ALS、PS 的趋势以及 valid 标志。
解释 IR/PS 掩码，能区分通信错误与无效测量。
用错误地址实验时得到明确错误，恢复地址后可重新测量。

遇到通信错误先看错误码和对应模块，禁止简单用“错误时返回 0”掩盖异常。预期日志是阅读程序的参考，验收时应保存自己的现象、日志与接线照片。

与教材和官方实现对照

对照教材第 25 章正文：保留复位和连续寄存器读取，分别保存有效位，不再把异常统一返回零；中断脚存在但本课不使用。

本地验证记录与参考

2026-10-24：ESP-IDF v5.5.5、目标 ESP32-S3，本机 macOS idf.py build 通过。
Hugo 草稿页面、文内本地图片和课程入口已检查；draft: true 保留，实板验收后再考虑发布。
未执行本课硬件烧录、波形测量或外设现象验收，以上待办不提前勾选。
ESP-IDF v5.5.5 官方接口文档。
教材第 25 章；DNESP32S3 V1.2 原理图第 2、3、4 页。

返回课程目录