CogletESP-camera-version/Coglet项目分析与开发指南.md

Coglet 项目分析与开发指南

一、项目简介

Coglet 是 YouTube 创作者 Will Cogley（原 Nilheim Mechatronics）开发的 DIY 桌面 AI 伴侣机器人，目前在 Kickstarter 众筹中。项目包含 3D 打印外壳、PCB 电路板和双 MCU 软件系统。

系统架构

采用双 MCU 架构，三个核心模块通过 UART 串联：

ESP32-S3 ←── UART 115200 ──→ RP2040 (Pico) ←── UART 921600 ──→ Grove Vision AI V2
 (AI/语音/网络)                (舵机/动画)                         (摄像头/人脸检测)

芯片	职责
ESP32-S3	AI 对话、语音识别/合成、WiFi 网络、MCP 协议（基于小智 XiaoZhi 固件）
RP2040 (Raspberry Pi Pico)	9 个舵机控制、动画表情、人脸追踪（MicroPython）
Grove Vision AI V2	摄像头人脸检测

ESP32 固件核心功能

• 连接方式：WiFi / ML307 Cat.1 4G
• 语音交互：流式 ASR + LLM（Qwen/DeepSeek）+ TTS
• 离线唤醒：ESP-SR 本地语音唤醒
• 通信协议：WebSocket 或 MQTT+UDP
• 音频编码：OPUS
• 显示：OLED/LCD + 表情动画
• 多语言：中文/英文/日文
• MCP 协议：设备端 MCP（控制扬声器、LED、舵机、GPIO）+ 云端 MCP（智能家居）

RP2040 控制的舵机（共 9 个）

舵机代号	功能
EYL / EYR	左右眼水平转动
PIT	头部俯仰
YAW	头部偏航
MOU	嘴巴开合
LID	眼睑眨眼
其他	耳朵舵机等

RP2040 状态机

idle → speaking → listening → thinking → happy → neutral → calibration

---

二、GitHub 仓库总览

核心仓库

仓库	地址	Stars	说明
Coglet 主仓库	https://github.com/will-cogley/Coglet	135	3D 打印件、PCB 原理图、文档
CogletESP 固件	https://github.com/will-cogley/CogletESP	5	ESP32 固件 + RP2040 代码（fork 自小智）

相关参考仓库

仓库	地址	说明
小智上游原版	https://github.com/78/xiaozhi-esp32	CogletESP 的上游项目
EyeMech_Epsilon	https://github.com/will-cogley/EyeMech_Epsilon	Coglet 眼球机构的技术前身，RP2040 + MicroPython

CogletESP 分支列表

分支名	Commits	说明
main	789	上游同步的主分支
CogletESP	758	Coglet 专用分支（无 ESP32 摄像头版本，保留 LCD 显示）
camera-version	755	ESP32 OV3660 摄像头版本（需 PCB 飞线，禁用 LCD）
esp32_camera	-	ESP32 摄像头分支
v1	669	v1 稳定版
bed-operator	-	功能分支
fix_resampler	-	重采样器修复
fix_rndis	-	RNDIS 修复
listening_wakeword	-	唤醒词监听
nt26_board	-	NT26 开发板适配

CogletESP 分支 vs camera-version 分支（关键区别）

重要区分：这里的"摄像头"指 ESP32-S3 上直连的 OV3660 DVP 摄像头（小智 AI 视觉功能），不是 Grove Vision AI V2。Grove Vision AI V2 是独立模块接在 RP2040 上，两个分支都支持它。

两个分支仅 2 个文件不同，都在 main/boards/bread-compact-wifi-s3cam/ 目录下：

对比项	CogletESP 分支	camera-version 分支
ESP32 摄像头(OV3660)	默认引脚，与 PSRAM 冲突	飞线后的新引脚映射
LCD 显示	正常支持	禁用（引脚被摄像头占用，用 DummyDisplay 替代）
PCB 改动	无需飞线	需要 3 根飞线（35→14, 36→41, 37→42）
摄像头画面	-	设置 HMirror + VFlip 翻转
JTAG 引脚(GPIO 39-42)	默认用途	释放给摄像头使用
Grove Vision AI V2	支持	支持

GPIO 引脚映射差异（部分关键引脚）

功能	CogletESP 分支	camera-version 分支
MIC_WS	GPIO 1	GPIO 4
MIC_SCK	GPIO 2	GPIO 5
MIC_DIN	GPIO 42	GPIO 6
SPK_DOUT	GPIO 39	GPIO 7
SPK_BCLK	GPIO 40	GPIO 15
SPK_LRCK	GPIO 41	GPIO 16
LED	GPIO 48	GPIO 3
CAMERA D7	GPIO 16	GPIO 14（飞线 35→14）
CAMERA VSYNC	GPIO 6	GPIO 41（飞线 36→41）
CAMERA HREF	GPIO 7	GPIO 42（飞线 37→42）

如何选择分支？

• 带 ESP32 OV3660 摄像头 → 用 camera-version 分支 + PCB 做 3 根飞线，但没有 LCD 屏
• 不带 ESP32 摄像头 / 想保留 LCD 屏 → 用 CogletESP 分支
• 仅使用 Grove Vision AI V2 人脸追踪 → 两个分支都可以，这是 RP2040 端的功能，与 ESP32 分支无关

Coglet 主仓库目录结构

Coglet/
├── 3D Printing Files/
│   └── CogletB34Parts.3mf          # 3D 打印零件
├── PCB/
│   ├── CogNogV1_0.pdf              # 原理图 PDF
│   └── CogletESP_2026-02-24.epro   # EasyEDA 工程文件
├── CogletESP/                       # Git 子模块 → CogletESP 仓库
├── Translated Docs for XiaoZhi AI/  # 14 份小智文档英文翻译
│   ├── 固件烧录指南
│   ├── WiFi 配置
│   ├── 面包板接线
│   ├── ESP-IDF 开发环境搭建
│   └── 摄像头接线 ...
└── README.md

已知 PCB 问题（CogNog V1.0）

• USB-C 接口过紧
• 摄像头引脚与 PSRAM 冲突（GPIO 35/36/37 被 PSRAM Octal SPI 占用，详见下方飞线说明）
• 体积电容不足
• 摄像头画面水平翻转（camera-version 分支已通过 SetHMirror(true) 修正）

翻译文档索引（Translated Docs for XiaoZhi AI）

主仓库中 Translated Docs for XiaoZhi AI/ 包含 13 份小智文档英文翻译，其中与搭建相关的：

文件	内容
DIY Breadboard for Xiaozhi AI...	完整硬件清单和接线教程（最详细，18MB）
[Latest] Wiring Tutorial...Camera	带摄像头的最新接线教程
Setting up ESP IDF 5.5.2...	ESP-IDF 开发环境搭建（Windows）
Flash Tool_Web Terminal...	网页烧录工具（无需 IDF 环境）
Configure Device Wi-Fi...	WiFi 配网和设备添加
Steps for Wake Word Change...	唤醒词修改

---

三、项目状态

• 活跃度：积极开发中（最后更新 2026 年 3 月）
• 成熟度：早期阶段 / 工作进行中
  • Releases 页面为空，无预编译固件
  • PCB 存在多个已知问题
  • 没有专用的 Coglet 板级配置（使用通用 bread-compact 系列）
• 众筹：Kickstarter 进行中
• 社区：Discord + QQ 群

---

四、摄像头版本完整搭建流程（camera-version）

你使用的是带摄像头的版本，以下是从零到运行的完整操作流程。

4.1 为什么需要飞线？

这是 CogNog V1.0 PCB 的设计缺陷，不是故意的设计。

ESP32-S3 的 PSRAM 使用 Octal SPI 接口，占用了 GPIO 35/36/37。但 V1.0 PCB 把摄像头的三个信号线（D7、VSYNC、HREF）也接到了这三个引脚上。当摄像头和 PSRAM 同时工作时，引脚冲突导致摄像头无法使用。

所有使用 CogNog V1.0 PCB + 摄像头的用户都必须飞线。 目前只有 V1.0 版本的 PCB。

4.2 硬件准备清单

部件	说明
CogNog V1.0 PCB	需要飞线修改
ESP32-S3 模组	带 PSRAM（如 N16R8）
OV3660 摄像头模组	DVP 接口 + 排线 + 转接板
Grove Vision AI V2	人脸追踪模块 + 15pin 排线适配器
INMP441 麦克风	I2S 数字麦克风
扬声器	I2S 输出
9x 舵机	必须 180° 标准舵机（如 KPower M0090 或 MG90S 180° 金属齿轮版），详见下方舵机选型说明
Raspberry Pi Pico (RP2040)	舵机控制
6 Pin PicoBlade 连接线	RP2040 ↔ ESP32 UART

4.3 PCB 飞线操作（3 根线）

在 CogNog V1.0 PCB 上，切断原走线并飞线到新引脚：

原始引脚	飞线到	摄像头信号	说明
GPIO 35	GPIO 14	CAMERA_PIN_D7	数据位 7
GPIO 36	GPIO 41	CAMERA_PIN_VSYNC	垂直同步
GPIO 37	GPIO 42	CAMERA_PIN_HREF	行参考信号

注意：camera-version 分支还释放了 JTAG 引脚（GPIO 39-42）给摄像头使用，代码中通过 gpio_reset_pin() 实现。

4.4 代码下载

# 第 1 步：克隆 camera-version 分支（ESP32 固件 + RP2040 代码都在里面）
git clone -b camera-version https://github.com/will-cogley/CogletESP.git

# 第 2 步：克隆主仓库（文档、PCB 原理图、3D 打印件）
git clone https://github.com/will-cogley/Coglet.git

克隆后的目录结构：

CogletESP/                    # camera-version 分支
├── main/
│   └── boards/
│       └── bread-compact-wifi-s3cam/
│           ├── config.h                      # GPIO 引脚映射（飞线后的版本）
│           └── compact_wifi_board_s3cam.cc   # 板级初始化（禁用 LCD，启用摄像头）
├── components/
├── RP2040/                   # RP2040 MicroPython 代码
│   ├── main.py               # 主控程序、舵机状态机、UART 通信（ESP32 + Grove Vision AI V2）
│   ├── servoclass.py         # 舵机驱动（PWM 50Hz，平滑运动）
│   └── animation.py          # 动画定义（思考、开心、热身等）
├── CMakeLists.txt
└── sdkconfig

4.5 编译烧录 ESP32 固件（macOS）

# 1. 进入项目目录
cd CogletESP

# 2. 激活 IDF 环境
source ~/esp/esp-idf/export.sh

# 3. 设置目标芯片
idf.py set-target esp32s3

# 4. 配置板级选项
idf.py menuconfig
# → 找到板级配置，选择 bread-compact-wifi-s3cam

# 5. 编译
idf.py build

# 6. 查看可用串口
ls /dev/cu.usb*

# 7. 烧录并监控
idf.py -p /dev/cu.usbmodem14101 flash monitor
# 串口名根据实际替换（/dev/cu.usbmodem* 或 /dev/cu.usbserial*）

# 8. 退出监视器：Ctrl + ]

4.6 烧录 RP2040（MicroPython）

第 1 步：刷入 MicroPython 固件

下载地址：https://micropython.org/download/RPI_PICO/

版本选择：下载 v1.24.x ~ v1.25.x 稳定版 .uf2 文件。代码只用基础 API（Pin、PWM、UART），v1.20+ 稳定版都兼容。不要下载 preview/nightly 预览版。

硬件说明：CogNog V1.0 PCB 上 RP2040 是直接焊接的（不是独立的 Raspberry Pi Pico 开发板），PCB 上有两个相关按键：

• SW1（Boot Switch）：位于 Flash Memory 旁，即 BOOTSEL 功能，用于进入 UF2 烧录模式
• Run Switch：位于 RP2040 旁，连接 RUN 引脚，即复位按钮。使用场景：
  • 上传新的 .py 文件后，按一下重启 RP2040 使新代码生效（等同于 mpremote reset）
  • 舵机行为异常时，按一下重启恢复到初始状态
  • 配合 SW1 进入烧录模式（见下方方式 B）

操作（macOS / Windows 通用）：

方式 A — USB 未连接时：

1. 按住 SW1（Boot Switch） → 通过 RP2040 的 USB-C 口连接电脑 → 松开 SW1
2. 电脑上出现 RPI-RP2 U 盘（macOS 在 Finder，Windows 在资源管理器）
3. 将 .uf2 文件拖入 U 盘
4. RP2040 自动重启

方式 B — USB 已连接时（更常用）：

1. 按住 SW1（Boot Switch）不松手
2. 按一下 Run Switch（复位）然后松开（只按一下，不用保持）
3. 松开 SW1 — 整个过程约 1-2 秒，关键是按 Run Switch 时 SW1 必须处于按下状态
4. 电脑上出现 RPI-RP2 U 盘
5. 将 .uf2 文件拖入 U 盘
6. RP2040 自动重启

原理：Run Switch 让 RP2040 复位重启，重启瞬间 SW1 被按着 → RP2040 检测到 BOOTSEL 为低电平 → 进入 UF2 bootloader 模式。

提示：如果 RP2040 已经刷过 MicroPython 且只需要更新 .py 文件，不需要重新进入 bootloader 模式，直接用 mpremote 上传即可（见第 2 步）。

第 2 步：上传 .py 文件

注意：CogletESP 分支有 4 个文件（含 coms.py），camera-version 分支有 3 个文件（无 coms.py）。请使用对应分支的文件。

macOS

方式 A — mpremote（推荐）：

pip install mpremote
cd CogletESP/RP2040

mpremote cp main.py :main.py
mpremote cp servoclass.py :servoclass.py
mpremote cp coms.py :coms.py          # 仅 CogletESP 分支需要
mpremote cp animation.py :animation.py

mpremote reset        # 重启运行
mpremote repl         # 查看串口输出（调试用）

mpremote 本质就是一个串口文件传输工具，把 .py 文件拷贝到 Pico 的文件系统里。Pico 上电后自动运行 main.py，不需要搭建任何 MicroPython 编译环境。

方式 B — Thonny（图形界面）：

brew install --cask thonny

1. 打开 Thonny → 右下角选择 MicroPython (Raspberry Pi Pico)
2. 逐个打开 .py 文件 → 另存为 → 选择 Raspberry Pi Pico → 保存同名
3. 保存完成后 Pico 重启自动运行 main.py

Windows

方式 A — mpremote（推荐）：

# 1. 安装 mpremote（需要 Python 3.x，从 python.org 下载安装，勾选 Add to PATH）
pip install mpremote

# 2. 进入 RP2040 目录
cd CogletESP\RP2040

# 3. 上传文件（Pico 连接 USB 后 Windows 会分配 COM 口，mpremote 自动识别）
mpremote cp main.py :main.py
mpremote cp servoclass.py :servoclass.py
mpremote cp coms.py :coms.py          # 仅 CogletESP 分支需要
mpremote cp animation.py :animation.py

mpremote reset        # 重启运行
mpremote repl         # 查看串口输出（调试用，Ctrl+] 退出）

Windows 注意事项：

• 如果 mpremote 找不到设备，打开设备管理器 → 端口(COM 和 LPT)，确认 Pico 对应的 COM 口（如 COM3），然后用 mpremote connect COM3 cp main.py :main.py 指定端口
• 如果设备管理器中看不到 COM 口，需要安装驱动：MicroPython 固件刷入后 Pico 通常免驱，若未识别可尝试拔插 USB 或换 USB 口

方式 B — Thonny（图形界面，适合新手）：

1. 下载安装 Thonny：https://thonny.org/ （选择 Windows 版本）
2. 打开 Thonny → 右下角选择 MicroPython (Raspberry Pi Pico)
3. 逐个打开 .py 文件 → 文件 → 另存为 → 选择 Raspberry Pi Pico → 保存同名
4. 保存完成后 Pico 重启自动运行 main.py

4.7 配置 Grove Vision AI V2（人脸追踪）

不需要手动刷底层固件，但需要部署一个人脸检测模型。

操作步骤：

1. 用 USB-C 线将 Grove Vision AI V2 连接到电脑
2. 用 Chrome 浏览器访问 SenseCraft AI 平台：https://sensecraft.seeed.cc/
3. 模型下载地址：https://sensecraft.seeed.cc/ai/model/deploy?id=60094&uniform_type=36&name=%E4%BA%BA%E8%84%B8%E6%A3%80%E6%B5%8B&adapteds=11&adapteds=12&adapteds=14&task=1
4. 选择一个人脸检测模型（推荐 YOLO Face Detection，输入尺寸 224x224）
5. 点击部署，等待上传完成
6. 断开 USB，将模块接回 RP2040 的 UART

为什么是 224x224？ 代码中 pixel_centre = 112 即 224/2，表明模型输入分辨率为 224x224。

工作原理：

RP2040 发送 AT+INVOKE=1,0,1 (SSCMA AT 协议)
    ↓
Grove Vision AI V2 运行人脸检测推理
    ↓
返回 JSON，包含 "boxes" 字段 → [x, y, w, h, ...]
    ↓
RP2040 计算人脸偏移量：x_offset = boxes[0] - 112, y_offset = boxes[1] - 112
    ↓
驱动舵机追踪：
  - EYL/EYR（眼球左右） → 跟随 x_offset
  - PIT（头部俯仰） → 跟随 y_offset
  - YAW（底座旋转） → 眼球偏离中心 >20° 时延迟跟随
    ↓
deadzone = 20 像素（避免微小抖动触发舵机）

4.8 硬件连接

┌─────────────┐    UART 115200     ┌──────────────┐    UART 921600     ┌───────────────────┐
│  ESP32-S3   │◄──────────────────►│  RP2040      │◄──────────────────►│ Grove Vision AI V2│
│             │  TX→RX(GP5)        │  (Pico)      │  TX(GP0)→RX       │                   │
│  AI/语音    │  RX←TX(GP4)        │  舵机控制     │  RX(GP1)←TX       │  人脸检测          │
│  WiFi/网络  │  GND──GND          │  动画状态机   │                    │  YOLO 模型         │
└─────────────┘                    └──────────────┘                    └───────────────────┘
                                          │
                                    PWM 引脚 x9
                                          │
                                   ┌──────┴──────┐
                                   │  9 个舵机    │
                                   │ EYL/EYR/PIT │
                                   │ YAW/MOU/LID │
                                   │  + 耳朵等    │
                                   └─────────────┘

ESP32 通过 UART 发送状态字符串给 RP2040： neutral / idle / listening / speaking / thinking / happy → RP2040 根据状态执行对应舵机动画

4.9 舵机选型说明（重要）

实测踩坑记录：使用 MG90S 360° 连续旋转版舵机后，耳朵舵机转到目标角度后无法停止，持续堵转导致齿轮发出刺耳声音、舵机严重发烫，有烧毁风险。更换为 180° 标准舵机后问题解决。

必须使用 180° 标准舵机的原因

Coglet 的 9 个舵机全部采用角度控制模式（代码中 set_target(角度) 命令舵机转到指定角度并保持），这只有 180° 标准舵机才能实现。

180° 标准舵机 vs 360° 连续旋转舵机的核心区别：

对比项	180° 标准舵机（如 KPower M0090）	360° 连续旋转舵机（如 MG90S 360° 改装版）
内部结构	有电位器（可变电阻），实时反馈当前角度	拆除/固定了电位器，失去角度反馈能力
PWM 信号含义	对应目标角度（1ms=0°, 1.5ms=90°, 2ms=180°）	对应旋转速度和方向（1.5ms=停止, <1.5ms=反转, >1.5ms=正转）
控制逻辑	闭环控制：收到 PWM → 对比目标与当前角度 → 自动转到位停住	开环控制：收到 PWM → 按速度持续旋转，永不停止
能否锁定位置	能，到达角度后施力保持	不能，停转后无保持力，外力可推动
旋转范围	0°~180° 精确定位	360° 无限旋转，无法精确定位

为什么 360° 舵机无法通过代码适配？

网上有"定时转动"方案（全速旋转 N 毫秒 → 发停止信号），原理是 转动时间 = (500ms / 360°) × 目标角度。但这对 Coglet 完全不可行：

1. 误差累积无法修正：没有位置反馈，每次转动误差 ±5°~10°。Coglet 的动画是高频反复运动（说话时嘴巴每 250ms 开合一次、耳朵每秒摆动），运行几分钟后累积误差可达几百度，位置完全跑飞
2. 个体差异大：每台舵机电机特性、齿轮间隙不同，无法统一校准"时间-角度"关系。换一台舵机就要重新标定
3. 无法保持位置：代码中头部俯仰、眼球等需要停在某个角度并持续施力保持。360° 舵机停转后没有保持力，手一碰就偏了
4. 实时性失效：Coglet 需要实时响应 AI 状态变化动态调整角度，定时方案无法做到实时同步
5. 负载和温度影响转速：电压波动、温度变化都会改变旋转速度，使时间估算更不准确

推荐舵机型号

型号	说明	参考价格
KPower M0090（官方推荐）	9g 模拟金属齿轮 180° 舵机	~¥8-12/个
MG90S 180° 金属齿轮版	注意必须是 180° 版，不带 "continuous/360" 字样	~¥5-8/个

购买注意：MG90S 有 180° 和 360° 两个版本，外观完全一样。购买时务必确认商品标题或参数中标注 "180°"，避免买到 360° 连续旋转版。

9 个舵机角度范围详解

代码中所有舵机的 PWM 映射为 0°180°（脉宽 500μs2500μs），各舵机通过 min_angle / max_angle 限定实际运动范围（源码：animation.py 第 14-23 行）：

舵机代号	功能	GPIO 引脚	角度范围	最大跨度	运动说明
YAW	底座旋转	GP6	10°~170°	160°	头部左右转动，人脸追踪时由 Grove Vision AI V2 驱动
ROL	颈部侧倾	GP7	30°~120°	90°	头部左右歪头，happy 状态下 70°↔110° 摆动
PIT	头部俯仰	GP8	1°~80°	79°	头部上下点头，thinking 状态下 50°↔80° 摆动
MOU	嘴巴开合	GP19	5°~150°	145°	speaking 时 70°↔130° 每 250ms 切换（张嘴/闭嘴）
EYL	左眼球	GP12	30°~150°	120°	左右看，人脸追踪时跟随 x 偏移量
EYR	右眼球	GP13	30°~150°	120°	与 EYL 同步运动
LID	眼睑	GP14	30°~160°	130°	30°=闭眼，110°~160°=睁眼，随机眨眼动画
EAL	左耳	GP15	60°~150°	90°	happy 状态下 100°↔160° 摆动
EAR	右耳	GP16	30°~120°	90°	happy 状态下 60°↔120° 摆动

注意：以上角度范围是代码中的软件限位，基于官方 3D 打印件和 KPower M0090 舵机校准。如果使用其他舵机或自制外壳，可能需要调整 animation.py 中的 min_angle / max_angle 避免堵转。

MOU 引脚差异：CogletESP 分支 MOU 使用 GP19，camera-version 分支 MOU 使用 GP9。请根据实际 PCB 版本确认。

校准模式使用方法

CogNog V1.0 PCB 上有一个 SW11（Calibration Switch） 拨动开关，连接 RP2040 的 GPIO20。代码中 GPIO20 配置了内部上拉电阻：

mode = Pin(20, Pin.IN, Pin.PULL_UP)
is_calibrating = (mode.value() == 1)  # 高电平 = 校准模式

SW11 逻辑：

SW11 状态	GPIO20 电平	模式	表现
断开（GPIO20 悬空）	高（内部上拉到 1）	校准模式	所有舵机归 90° 中位，LED 闪烁
接通（GPIO20 接 GND）	低	正常运行模式	响应 ESP32 状态指令，执行动画

提示：如果不确定 SW11 哪个位置对应哪种模式，两个位置都试一下，LED 闪烁的那个就是校准模式。

校准与组装流程

前提：RP2040 已刷入 MicroPython 固件并上传 .py 文件。

第 1 步：进入校准模式
   └→ 将 SW11 拨到校准位置（LED 闪烁）

第 2 步：通电
   └→ 给 RP2040 和舵机供电
   └→ 所有 9 个舵机自动转到 90° 中位（staggered startup，逐个上电避免电流冲击）

第 3 步：安装舵机臂
   └→ 在 90° 中位状态下，将舵机臂安装到需要的朝向
   └→ 拧紧舵机臂固定螺丝
   └→ ⚠️ 关键：必须在通电校准状态下安装，否则角度对不上

第 4 步：组装机械结构
   └→ 将舵机装入 3D 打印外壳
   └→ 连接所有机械连杆

第 5 步：验证
   └→ 将 SW11 拨回正常运行模式
   └→ 观察舵机是否能正常运动，无堵转
   └→ 如有堵转，调整 animation.py 中对应舵机的 min_angle / max_angle

第 6 步：连接 ESP32
   └→ 接上 ESP32 UART（TX→GP5, RX→GP4）
   └→ ESP32 发送状态指令，舵机开始响应 AI 对话动画

校准模式不需要断开 ESP32：校准模式在主循环中每帧都强制覆盖舵机状态（main.py 第 153-155 行），即使 ESP32 发送了指令也会被忽略。

4.10 camera-version 的代价与限制

项目	说明
LCD 屏被禁用	摄像头占用了原 LCD 引脚，代码用 DummyDisplay 空实现替代
音频引脚全部重映射	MIC 从 GPIO 1/2/42 移到 4/5/6，SPK 从 GPIO 39/40/41 移到 7/15/16
内存压力	摄像头 + PSRAM 同时运行可能偶发内存不足（作者提到 "appears to run out of memory sometimes"）
摄像头画面翻转	已通过代码设置 SetHMirror(true) + SetVFlip(true) 修正

---

五、无摄像头版本搭建流程（CogletESP 分支）

如果不使用 ESP32 OV3660 摄像头，想保留 LCD 显示，使用此方案。

5.1 代码下载

git clone -b CogletESP https://github.com/will-cogley/CogletESP.git
git clone https://github.com/will-cogley/Coglet.git

5.2 ESP32 编译烧录

与摄像头版本相同（参见 4.5），但 menuconfig 中的板级配置可能不同，PCB 无需飞线。

5.3 RP2040 烧录

MicroPython 固件刷入方式与摄像头版本相同（参见 4.6），但 RP2040 代码两个分支不同：

• CogletESP 分支有 4 个文件：main.py、servoclass.py、coms.py、animation.py
• camera-version 分支只有 3 个文件（无 coms.py，UART 通信集成在 main.py 中）

请使用对应分支的 RP2040 目录文件上传。

5.4 Grove Vision AI V2

与摄像头版本完全相同（参见 4.7），Grove Vision AI V2 的人脸追踪功能由 RP2040 端控制，与 ESP32 分支选择无关。

---

六、常见问题

问题	解决方案
Python 环境冲突	idf.py fullclean 后重新编译
Bootloader CMake 缓存不匹配	rm -rf build/bootloader build/bootloader-prefix
找不到串口设备	安装 CP2102/CH340 驱动，检查 USB 线是否支持数据传输
menuconfig 中找不到板级配置	确认在正确的分支（camera-version 或 CogletESP）
摄像头不工作	确认已完成 3 根飞线（35→14, 36→41, 37→42）并使用 camera-version 分支
偶发内存不足	camera-version 已知问题，摄像头 + PSRAM 同时运行时可能出现
Grove Vision AI V2 无响应	确认已通过 SenseCraft 部署人脸检测模型，UART 波特率 921600
舵机不动	检查 RP2040 是否正确上传 .py 文件（CogletESP 分支 4 个 / camera-version 分支 3 个），UART 连接是否正常
舵机堵转、发烫、齿轮刺耳声	使用了 360° 连续旋转舵机，必须更换为 180° 标准舵机（详见 4.9 舵机选型说明）
舵机持续朝一个方向旋转不停	同上，360° 舵机收到非 90° 信号会持续旋转。180° 舵机会转到目标角度后自动停住

---

六点五、Phase 01 单摄像头人脸追踪 踩坑经验（2026-04-17 ~ 04-20）

背景：尝试用 ESP32 上的 OV3660 摄像头做人脸检测，通过 UART 发送人脸坐标给 RP2040，驱动眼球/YAW 舵机追踪。详细规划/执行文档见 docs/phase-01-face-tracking/。

现状：代码骨架全部完成（15 个任务 T01-T15），ESP32 端 + RP2040 端端到端联通，但摄像头帧数据解析仍有问题（box 固定伪激活），未完全通过验收。

6.5.1 编译 / 配置类踩坑

#	坑	原因	解决方案
1	板级配置被重置为 BREAD_COMPACT_WIFI（无摄像头版）	idf.py fullclean / set-target 可能触发 sdkconfig 重置到 defaults	显式编辑 sdkconfig 确认 CONFIG_BOARD_TYPE_BREAD_COMPACT_WIFI_CAM=y
2	esp-dl 3.3.0 与 esp-sr 2.2.x 版本冲突	esp-dl 需要 esp-dsp 1.7.0，esp-sr 2.2 钉 esp-dsp 1.6.0	升级 esp-sr 到 ~2.3.1（已切到 esp-dsp 1.7.0）
3	Bootloader CMake 缓存不匹配，编译报 source does not match	ESP-IDF 路径历史变更（如 esp-idf/v5.4.2/esp-idf/ → esp-idf/）	rm -rf build/bootloader build/bootloader-prefix 重新编译
4	ESP_LOGI 用 %lld 输出变成字符串 "ldus"	ESP-IDF nano newlib 不完全支持 %lld	改用 %lu + (unsigned long) 强转（probe 用时 < 71 分钟，uint32 足够）
5	esp_video 1.3.1/1.4.1 的 DVP 启动报 xclk_freq is not set	esp_video 源码 dvp_video_device.c 构造 esp_cam_ctlr_dvp_config_t 时缺失 xclk_freq 字段（IDF 5.4.2 不支持 external_xtal）	升 esp_video 到 1.4.1 后手动 patch managed_components 源码，在 #else 分支加 .xclk_freq = 20000000,

6.5.2 摄像头数据链路踩坑

#	坑	原因	解决方案
6	/dev/video2 打不开，errno=2 No such file	sdkconfig 中没有启用任何 sensor driver（CONFIG_CAMERA_OV3660 默认 n）	sdkconfig 启用对应摄像头：CONFIG_CAMERA_OV3660=y + 具体分辨率/格式
7	V4L2 REQBUFS count 默认为 1（DVP 路径），DMA 饥饿陈旧数据	esp32_camera.cc 中 req.count = strcmp(...) == 0 ? 2 : 1; 对 DVP 用单 buffer	改为 req.count = 2; 让 DMA 有双缓冲持续更新
8	分区表 OTA 分区 3.94MB 容纳不下 4.23MB 固件	加了 esp-dl + human_face_detect 后固件膨胀	修改 partitions/v2/16m.csv：ota_0/ota_1 各 5MB，assets 缩到 5.875MB（16MB 模组够用）
9	摄像头输出画面全黑，Y 值只有 0~8	镜头表面出厂保护膜未撕掉	用指甲抠边缘撕掉透明保护膜（极薄不易察觉）
10	画面持续偏暗	室内光照不足 / 镜头指纹灰尘	白天窗边或明亮台灯下测试

6.5.3 esp-dl 人脸检测踩坑

#	坑	原因	解决方案
11	MSR_S8_V1 模型固定在 box=[0, y, 40, y+40] 误识别	模型输入 160×120（4:3），摄像头输出 240×240（1:1），ImagePreprocessor letterbox 填充左右各 20 列灰条，模型在灰条上产生假激活	改用输入正方形的 ESPDET_PICO_224_224_FACE（224×224）
12	ESPDET 模型仍然输出固定 box [233, 158, 94, 239]（数学上不可能：x1 > x2）	怀疑模型对 out-of-distribution 输入 fallback 到默认 anchor	尝试中：手动 YUYV→RGB888 转换 + 字节序验证
13	字节序判断反复：RGB565LE / BE / YUYV 都试过	OV3660 FORMAT_CTRL00=0x61 设置是"RGB565 byte-swapped"，但实测数据更像 YUYV	通过 frame debug 打印前 16 字节诊断，按多种格式对比解读

6.5.4 任务调度踩坑（Core 亲和 & 崩溃）

#	坑	原因	解决方案
14	唤醒词检测后触发 LED 时崩溃（Interrupt wdt timeout）	face_tracker 绑 Core 0，esp-dl 推理占 150ms，RMT LED 驱动在同核抢不到 spinlock 超 300ms	face_tracker 改绑 Core 1（音频空闲时让出 CPU）
15	GDMA ISR InstrFetchProhibited at PC=0x00000000	esp_video 1.4.1 底层 DMA 回调指针变 NULL（疑似 ESP-IDF 5.4.2 兼容性 bug）	未完全修复。降低 FPS 到 5 能推迟崩溃。待升级 ESP-IDF 或改用低级 esp_cam_ctlr API
16	弱符号 uart_send_face 链接失败	C++ 名字修饰问题	extern "C" 包裹 weak 前置声明 + strong 定义，确保 C 链接名一致

6.5.5 RP2040 端踩坑

#	坑	原因	解决方案
17	进入 idle 后眼球卡在最后追踪位置不回中	原 facetrack() idle 时直接 return，没有回中机制	新增 _recenter_tracking_servos()，在 grove_active 从 True→False 或首次进入 idle 时一次性回中到 90°
18	ESP32 持续发误识别坐标（-95/+40 等固定值）	眼球持续累加偏移直到撞到机械限位（30°/150°）	属 ESP32 侧 bug，但 RP2040 侧加 staticflag 去重 + 回中机制缓解
19	mpremote could not enter raw repl	Pico 主循环阻塞或端口被旧 monitor 占用	拔插 USB 复位 Pico → 立刻 mpremote cp 抢时间窗
20	两个分支 RP2040 代码不同	CogletESP 分支 4 个 .py（含 coms.py），camera-version 分支 3 个（无 coms.py）	使用时对应分支代码，不要混用

6.5.6 硬件踩坑

#	坑	原因	解决方案
21	3 根飞线（35→14, 36→41, 37→42）是否到位	CogNog V1.0 PCB 设计缺陷，PSRAM 和摄像头 D7/VSYNC/HREF 冲突	万用表测导通，确保原 GPIO 35/36/37 与摄像头断开，新 GPIO 14/41/42 接通
22	舵机堵转、发烫、齿轮刺耳声	误用 360° 连续旋转舵机（MG90S 360° 版外观和 180° 一样）	更换为 KPower M0090 或 MG90S 180° 金属齿轮版（详见 4.9 节）
23	烧录固件后 Compile time 仍是旧版	用 IDE 内置烧录工具可能烧到错误路径 / 没完整烧录	改用命令行 idf.py -p /dev/cu.usbmodemXXX flash monitor，烧完立即 monitor 看 Compile time 验证

6.5.7 调试方法论

方法	用途
frame debug 打印前 16B 字节值	按多种格式（YUYV / RGB565LE / RGB565BE）对比解读，判断 sensor 实际输出
zero_bytes 比例统计	判断画面亮度（>30% 大概率镜头遮挡或极暗；<5% 画面正常）
box 数学合法性	box[0] > box[2] 或 box[2] == width 这种异常值说明模型崩了（OOD 默认输出）
对比不同画面输入下 box 是否变化	遮住摄像头 / 白墙 / 人脸 → 如果 box 完全一致，一定是模型输入路径异常
Compile time 验证烧录生效	烧录后 monitor 看 I (xxx) app_init: Compile time: ... 必须是最新编译时间
xtensa-esp32s3-elf-addr2line	把 crash backtrace 的地址转成源码文件:行号

6.5.8 Phase 01 未解决问题（遗留）

1. ❌ box 固定伪激活：无论遮住摄像头、白墙、真实人脸，box 都稳定输出 [233, 158, 94, 239]（或 MSR 模型的 [0, *, 40, *]）。已验证：

   • pix_type 不是根因（YUYV / RGB565LE / RGB565BE / RGB888 手动转换都不行）
   • 双 buffer 修复了数据更新问题，但 box 仍固定
   • 模型切换（MSR → ESPDET）改变了 box 坐标但仍固定
   • 推断：模型对某种 out-of-distribution 输入 fallback 到默认 anchor

2. ❌ GDMA ISR 崩溃：每 ~30 秒触发一次 InstrFetchProhibited at PC=0x00000000，属 esp_video 1.4.1 / ESP-IDF 5.4.2 底层 bug

3. ⚠️ 端到端未验收：RP2040 端 Bug 3（回中机制）已修，但因 ESP32 侧 box 仍固定，整条链路的"眼球跟随真实人脸"未通过

---

七、参考资源

资源	地址
Coglet GitHub 主仓库	https://github.com/will-cogley/Coglet
CogletESP 固件仓库	https://github.com/will-cogley/CogletESP
小智 ESP32 原版	https://github.com/78/xiaozhi-esp32
眼球机构参考	https://github.com/will-cogley/EyeMech_Epsilon
Coglet 组装视频	https://www.youtube.com/watch?v=-7I-jFSNP2E
MicroPython 固件下载	https://micropython.org/download/RPI_PICO/
ESP-IDF 官方文档	https://docs.espressif.com/projects/esp-idf/zh_CN/v5.4.2/
MicroPython 官方文档	https://docs.micropython.org/en/latest/
mpremote 工具文档	https://docs.micropython.org/en/latest/reference/mpremote.html
SenseCraft AI 平台（Grove Vision AI V2 模型部署）	https://sensecraft.seeed.cc/
Grove Vision AI V2 Wiki	https://wiki.seeedstudio.com/grove_vision_ai_v2/