# dfk10-bsp-cplus

**Repository Path**: genvex/dfk10-bsp-cplus

## Basic Information

- **Project Name**: dfk10-bsp-cplus
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DFRobot K10 AI Camera Board — ESP-BSP

> 为 DFRobot K10 构建的标准 esp-bsp 板级支持包，从 esp-claw YAML 声明式配置翻译为 C 代码 BSP 组件。  
> 基于 ESP-IDF v6.0（实机验证 v6.0.2）+ LVGL 9.5 + esp_lvgl_port，所有组件通过云端拉取，无本地依赖。

## 仓库原则

- `main` 分支是**最小可运行基线**，既是代码也是当前硬件能力的可执行说明书。
- `components/dfrobot_k10` 隔离板级细节，向应用暴露稳定 API。
- `main/` 承载 LVGL 应用、状态机、动画、任务，**不改动 BSP 框架**。
- `AGENTS.md` 定义 agent 工作方式；`docs/AI_HARDWARE_DEVELOPMENT_GUIDE.md` 承载完整硬件上下文与排障知识。
- **编译结果与实机结果分开报告。** 一个成功的 `idf.py build` 绝不能冒充硬件验证通过。

## Agent 入口

开始前按顺序建立上下文：

1. 阅读 `AGENTS.md`、本 README、`docs/AI_HARDWARE_DEVELOPMENT_GUIDE.md`。
2. `git status --short --branch`，保留已有改动。
3. 读 `components/dfrobot_k10/include/bsp/dfrobot_k10.h`（引脚/地址单一事实来源）和要改的实现。
4. 到 `dfk10-expansionboard-idf6/examples/<app>/` 找最接近需求的参考。复用**设计模式**，不整枝合并。
5. 把需求拆成：输入、输出、状态、并发任务、持久化、内存预算、失败降级，再决定改 `main` 还是扩 `components`。
6. 完成 `idf.py build` 最低检查，所有涉及屏/按键/音频/电池/时序的结论保留明确的实机验收项。

### 信息优先级链

```text
原理图 / PCB / 板卡修订 / 实测
    > components/dfrobot_k10/include/bsp/dfrobot_k10.h
    > BSP 实现与 docs/AI_HARDWARE_DEVELOPMENT_GUIDE.md
    > README 与示例应用
```

仓库**当前不提供**原理图、PCB、BOM、电池型号、充电芯片、板卡修订号。遇到板卡版本、极性、寄存器、未用 GPIO 未知时，必须标注"未知/待实测"并请求证据，禁止用其他 ESP32-S3 板的参数填空。

## 硬件概览

| 部件 | 型号 | 总线 | 关键引脚 |
|------|------|------|----------|
| MCU | ESP32-S3 | — | — |
| Flash | 16MB QIO @80MHz | — | — |
| PSRAM | 8MB Octal @80MHz | — | — |
| LCD | ILI9341 240×320 | SPI3 @40MHz | MOSI=21, SCLK=12, CS=14, DC=13 |
| Camera | GC2145 2MP | DVP 8-bit | VSYNC=4, DE=5, PCLK=17, XCLK=7 |
| Microphone | ES7243E | I2S0 RX + 共享 I2C 0x23（实测） | MCLK=3, BCLK=0, WS=38, DIN=39 |
| Speaker | NS4168 | I2S0 TX | DOUT=45 |
| IO Expander | TCA9555 16-bit | I2C port 1, addr 0x20 | SDA=47, SCL=48 |
| LED | 3× WS2812 | RMT TX | GPIO 46 |
| SD Card | SDHC | SPI2 @20MHz | CS=40, MOSI=42, MISO=41, SCLK=44 |

## 快速开始

### 环境要求

- ESP-IDF v6.0.x（v6.0.2 实机验证）
- 目标芯片：ESP32-S3

### 编译

```bash
cd dfk10-bsp-agent
idf.py set-target esp32s3
idf.py build
```

### 宿主机测试（无板卡）

改动 `bsp_pins.h` 的引脚/地址/尺寸/时钟，或 I2C 地址相关代码后，先跑：

```bash
bash tests/host/run_tests.sh
```

校验内容：引脚范围与唯一性、总线分配、尺寸/时钟参数合法性、I2C 设备地址冲突（含 `bsp_pins.h` 宏与实现的一致性检查）。

### 烧录

```bash
idf.py -p /dev/ttyACM0 flash monitor
```

烧录后：
- LCD 屏幕显示 "Hello K10!" + 蓝底白字
- 开机自动测试 SD 卡读写
- 摄像头预览显示在 LCD 上半区 (240×160)
- 下半区显示文字 + 按键控制 LED（P2=红, P3=绿, P4=蓝）

## 项目结构

```
dfk10-bsp-agent/
├── AGENTS.md                         # Agent 工作方式入口
├── CMakeLists.txt                    # 项目顶层 CMake
├── sdkconfig.defaults                # 项目级 Kconfig
├── partitions.csv                    # 分区表
├── dependencies.lock                 # 云端组件锁定版本
├── README.md                         # 本文件
├── WORK_REPORT.md                    # 工作报告
├── LCD_CAMERA_TUNING_NOTES.md        # LCD + 摄像头调试经验总结
├── main/                             # 测试程序
│   ├── CMakeLists.txt
│   ├── idf_component.yml
│   └── main.c                        # LCD + 摄像头预览 + SD卡测试 + 按键点灯
├── components/dfrobot_k10/           # BSP 组件
│   ├── CMakeLists.txt
│   ├── idf_component.yml             # 云端依赖声明
│   ├── Kconfig                       # 板卡配置菜单
│   ├── sdkconfig.defaults            # 板级 Kconfig
│   ├── dfrobot_k10.c                 # 核心实现
│   ├── src/sensors/                  # AHT20 / LTR329 / SC7A20H / 传感器任务实现
│   └── include/bsp/
│       ├── bsp_pins.h                # 引脚/地址/时序单一事实来源
│       ├── dfrobot_k10.h             # 公共 API + 能力 flags + 类型
│       ├── bsp_sensors.h             # 传感器聚合接口
│       ├── sensor_task.h             # 传感器后台任务
│       ├── config.h                  # BSP 配置
│       ├── display.h                 # 显示通用接口
│       ├── bsp_err_check.h           # 错误检查宏
│       └── sensors/                  # AHT20 / LTR329 / SC7A20H 头文件
├── docs/                             # 硬件上下文、排障知识、调试手记
└── tests/host/                       # 宿主机一致性测试（无需板卡）
```

## BSP API

```c
#include "bsp/dfrobot_k10.h"

// 显示 + LVGL
lv_display_t      *bsp_display_start(void);
void               bsp_display_lock(void);
void               bsp_display_unlock(void);
esp_lcd_panel_handle_t bsp_lcd_get_panel(void);

// I2C
esp_err_t               bsp_i2c_init(void);
i2c_master_bus_handle_t bsp_i2c_get_handle(void);

// IO 扩展器
esp_err_t             bsp_io_expander_init(void);
esp_io_expander_handle_t bsp_io_expander_get_handle(void);

// 音频
esp_err_t            bsp_audio_init(void);
esp_codec_dev_handle_t bsp_audio_codec_speaker_init(void);
esp_codec_dev_handle_t bsp_audio_codec_microphone_init(void);

// Camera (DVP)
esp_err_t            bsp_camera_init(esp_cam_ctlr_handle_t *ret_handle);

// Buttons (via TCA9555)
bool                 bsp_button_get_state(bsp_button_t btn);

// LED
esp_err_t            bsp_led_strip_init(void);
esp_err_t            bsp_led_set(int index, uint8_t r, uint8_t g, uint8_t b);
esp_err_t            bsp_led_clear(void);

// SD Card (SPI mode)
esp_err_t            bsp_sdcard_init(sdmmc_card_t **card);
esp_err_t            bsp_sdcard_deinit(void);
```

### 使用示例

```c
#include "bsp/dfrobot_k10.h"
#include "lvgl.h"

void app_main(void)
{
    // 显示
    lv_display_t *disp = bsp_display_start();
    bsp_display_lock();
    lv_obj_t *label = lv_label_create(lv_scr_act());
    lv_label_set_text(label, "Hello K10!");
    lv_obj_center(label);
    bsp_display_unlock();

    // SD 卡
    sdmmc_card_t *card = NULL;
    bsp_sdcard_init(&card);
    FILE *f = fopen("/sdcard/test.txt", "w");
    fprintf(f, "Hello from K10!\n");
    fclose(f);

    // 摄像头
    esp_cam_ctlr_handle_t cam = NULL;
    bsp_camera_init(&cam);
    // ... 注册 callback + 启动
}
```

## 云端依赖

构建时自动拉取组件（`idf_component.yml`）：

| 组件 | 版本 | 用途 |
|------|------|------|
| lvgl/lvgl | 9.5.0 | LVGL 图形库 |
| espressif/esp_lvgl_port | ^2 | LVGL 移植层 |
| espressif/esp_lcd_ili9341 | ^2.0.1 | LCD 驱动 (v2.0.2) |
| espressif/esp_io_expander_tca95xx_16bit | * | TCA9555 驱动 |
| espressif/esp_codec_dev | ~1.5 | 音频编解码框架 |
| espressif/led_strip | ^3.0 | WS2812 LED 驱动 |
| espressif/esp_cam_sensor | ^1.1.0 | 摄像头传感器框架 |

## 硬件能力契约

下表描述当前 `main` 分支已实现的**应用能力**（不是芯片能做什么的清单）。每行同时列出接口与必须遵守的边界。

| 能力 | 已确认实现 | 应用接口 | 必须遵守的边界 |
| --- | --- | --- | --- |
| 显示 | ILI9341, 240×320 竖屏 RGB565, SPI3 @40 MHz | `bsp_display_*` | 无 PSRAM 大 buffer 例外：I2S/LCD DMA 走内部 RAM；需大 buffer 必须 `heap_caps_malloc(..., SPIRAM\|8BIT)`；无触摸、无屏读 |
| 输入 | TCA9555 16-bit IO expander，P2–P12 10 颗按键，低电平有效 | `bsp_button_get_state()` | 轮询模式；只有 P2/P12 两键在 `main.c` 有验证；其余按键接线需实测 |
| 摄像头 | GC2145 DVP 8-bit, 640×480 → 缩放 240×160 | `bsp_camera_init()` + 独立 SCCB 探测 | SCCB 已实测探测到 0x3c、PID=0x2145；VFLIP/HMIRROR 需实测；640×480 帧 buffer 614 KB 必须放 SPIRAM；ISR 只做通知 |
| 音频·播放 | NS4168 通过 I2S0 TX std, 16-bit mono, `SLOT_LEFT` | `bsp_audio_speaker_write*()` | 不能用 `SLOT_BOTH`（mono + BOTH = 杂音）；beep 必须在 mic open 之后 |
| 音频·录音 | ES7243E 4-slot TDM, I2S0 RX, 共享总线 0x23（2026-08-25 实机定案）, 24 kHz | `bsp_audio_codec_microphone_init()` | 4 槽中只有 slot0/slot2 有效，slot1/slot3 是噪声；增益 37.5 dB；`channel=4` 不是"4 路麦" |
| IO 扩展 | TCA9555 16-bit | `bsp_io_expander_*` | I2C1 地址 0x20；与传感器共享 I2C1 |
| LED | 3× WS2812, RMT TX GPIO 46 | `bsp_led_set/clear` | 复杂动画用独立任务，不阻塞 UI |
| SD 卡 | SDHC, SPI2 @20 MHz, FATFS | `bsp_sdcard_init()` | 无卡时返回错误，app 必须降级 |
| 传感器 | AHT20 / LTR329 / SC7A20H via `sensor_task` | `bsp_sensors_*` | 走 I2C1 共享总线，注意地址冲突 |
| 日志 | ESP32-S3 原生 USB Serial/JTAG | ESP-IDF console | GPIO18/19 保留给 USB |

## 不属于当前契约的能力

仓库**目前没有足够证据**保证：触摸、屏读、外部按键唤醒、充电控制、USB 插入检测、精确电池电量、未用 GPIO 复用、音频功率/失真、麦克风与喇叭之间是否存在物理回声路径。ESP32-S3 芯片支持这些能力不代表板卡已连接、供电正常或已验证。

涉及这些能力的需求必须先获取原理图、板卡修订、器件数据手册或实测数据，然后才能扩展 BSP 与验收项。

## 交付格式（必须）

每次涉及硬件的 agent 交付必须分开报告，**绝不让"编译通过"冒充"硬件验证通过"**：

```text
Build:        PASS / FAIL / NOT RUN
Host tests:   PASS / FAIL / NOT RUN    # bash tests/host/run_tests.sh
Device tests: PASS / FAIL / NOT RUN
Unverified:   仍需板卡 / 仪器 / 用户确认的项
```

通用上板验收项：

- USB Serial/JTAG 启动日志稳定，无重启循环、assert、watchdog reset。
- LCD 竖屏 240×320 显示正确，彩色、边缘、刷新、背光正常。
- 开机 beep 880 Hz 音调正常。
- 麦克风波形（绿=左麦/红=右麦）独立对声音响应，无毛边；确认只取 slot0 + slot2。
- 摄像头预览 240×160 无拉伸/错位。
- SD 卡读写回读一致；无卡时 app 优雅降级。
- 反复进出页面 / 并发操作无持续堆下降、对象悬挂、任务泄漏。

按修改类型追加验收：

| 修改类型 | 必须观察的实机结果 |
| --- | --- |
| 引脚 / I2C | 所有设备扫描、启动冲突、USB 日志 |
| LCD 方向 / 颜色 | RGB565 顺序、`swap_bytes`、`mirror_y`、边缘裁切 |
| 音频 TX | 1 kHz 音调正确、无 mono + SLOT_BOTH 杂音 |
| 音频 RX | 波形四槽画出来确认 slot0/slot2 有效、增益是否削顶 |
| 摄像头 | VFLIP/HMIRROR、DVP 时钟 6 MHz、帧率 |
| SD 卡 | 无卡降级、大小文件读写回读 |
| 内存 / DMA | build 内存报告、largest free block、音频与刷屏并发稳定性 |

## 调试经验文档

详细 LCD 方向 / 摄像头栅格 / 颜色字节序等踩坑记录见 [LCD_CAMERA_TUNING_NOTES.md](LCD_CAMERA_TUNING_NOTES.md)。

核心经验：
- **LCD 方向**: 在 `disp_cfg.rotation.mirror_y=true` 里设，不是 `esp_lcd_panel_mirror()`
- **摄像头栅格**: DVP `h_res`/`v_res` 必须匹配传感器实际输出 (640×480)
- **摄像头颜色**: S3 不支持硬件 `byte_swap_en`，靠 LCD `swap_bytes=true` 自动处理
- **ISR callback**: 只发 task notification，画屏在独立 task 做

## 数据来源

K10 硬件定义提取自 [espressif/esp-claw](https://github.com/espressif/esp-claw/tree/master/application/edge_agent/boards/dfrobot/dfrobot_k10) 的 5 个文件：

| 文件 | 内容 |
|------|------|
| `board_info.yaml` | 板卡元信息 |
| `board_devices.yaml` | LCD/Camera/Audio/IO Expander/LED |
| `board_peripherals.yaml` | I2C/I2S/SPI/RMT 引脚 |
| `sdkconfig.defaults.board` | Flash/PSRAM/Audio Kconfig |
| `setup_device.c` | TCA9555 复位序列 |

## License

Apache-2.0