> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

源码与访问日期：2026年10月27日。固定仓库 `will-cogley/Coglet`，提交 `31f3c61b05a88980d0bf56b397ffea473e79c0da`，提交时间 2026-10-24T10:40:11Z。本轮复核默认分支仍指向此提交。本文解释该版本自身的代码组织、对象关系、执行与通信，不将外部集成建议画成项目现有架构。

# 架构结论与系统边界

Coglet 的基本方案是**ESP32 负责联网语音与会话，RP2040 负责机械表达与本地仲裁，外接 Grove Vision AI V2 负责视觉推理**。前两者分别运行 ESP-IDF C++ 固件与 MicroPython 脚本，通过简单的 UART 文本行连接。视觉模块另走 RP2040 的第二路 UART。它没有把所有功能放进一个机器人操作系统，也没有为每种表情创建独立任务或进程。

ESP32 一侧沿用小智的 `Application`、`AudioService`、`Protocol` 和 MCP 工具结构。Coglet 的产品定制主要落在板级类、UART 桥和 RP2040 动画程序。RP2040 一侧以 `main.py` 的单循环为调度中心，调用过程式 `animation` 模块和 `EyeFollower`、`Servo` 等对象。校准、临时动作、表情、视觉与口部动画依照固定优先级争用同一组舵机目标。

**必须区分两个摄像头／计算路径。** ESP32 板级代码初始化的 GC0308 摄像头服务于该侧相机工具。Grove Vision AI V2 自己推理，RP2040 读取检测框。所读路径没有显示先把 ESP32 图像送入 RP2040，再由 RP2040 运行检测模型。这里的“视觉跟随”是检测框到舵机角度的规则控制，模型推理不在这四份 MicroPython 文件中。

| **版本与范围依据** | **直接入口** |
|---|---|
| 固定代码、许可及整机资料 | [仓库固定版本](https://github.com/will-cogley/Coglet/tree/31f3c61b05a88980d0bf56b397ffea473e79c0da)、[README](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/README.md) |
| ESP32 程序入口与会话主干 | [main.cc](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/main.cc#L16)、[Application::Start](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/application.cc#L355) |
| RP2040 程序入口与视觉实现 | [main.py 主循环](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/main.py#L415)、[vision.py](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/vision.py#L210) |

# 仓库、构建与部署单元

| **目录或文件** | **职责** | **产物与边界** |
|---|---|---|
| `CogletESP/CMakeLists.txt`、`sdkconfig` | ESP-IDF 工程及板型选择 | `PROJECT_VER` 为 2.0.5，工程名仍为 xiaozhi；这是固件版本字段，不是 Coglet 整机上市版本 |
| `CogletESP/main/application.{h,cc}` | 会话状态、调度、音频与网络事件协调 | 同一个 ESP32 固件中的 C++ 对象与 FreeRTOS 任务，不是服务端 |
| `main/audio/`、`main/protocols/` | 音频队列与网络协议抽象 | 本轮补读头文件及调用方，没有宣称逐行核查所有编解码器、网络传输实现 |
| `main/boards/bread-compact-wifi-s3cam/` | Coglet 板型的相机、音频、按键、LED、五项机械工具 | 当前选中的板级目录名称来自小智通用板型；类的实际定制应读实现，不能只看目录名 |
| `main/uart_component.{h,cc}` | ESP32 向 RP2040 发送状态与动作文本 | 串口驱动与发送函数，无独立设备会话协议服务 |
| `CogletESP/RP2040/main.py` | 串口接收、所有权仲裁、物理开关、睡眠输出门控 | 部署到 RP2040 文件系统，由 MicroPython 启动执行 |
| `RP2040/animation.py` | 九路 Servo 实例、姿态表、表情函数、眨眼／口部／临时动作计时 | 以模块全局状态和函数为主，没有名为 AnimationController 的实际类 |
| `RP2040/vision.py` | Grove Vision 串口驱动、检测框处理、眼睛／颈部／底座协调 | `GroveVisionAI` 与 `EyeFollower` 是实际类；检测模型内部不在此文件 |
| `RP2040/servoclass.py` | PWM 驱动、全局输出使能、每路速度／加速度插值 | `Servo` 使用共享的 `_PCA9685` 实例，经 I²C 写执行器 |

当前固定树中的 `CogletESP` 是普通目录，本轮不再沿用旧资料中“先初始化该子模块”的假设。ESP-IDF 编译与 MicroPython 文件部署是两个更新单元。读到 ESP32 OTA，不代表 RP2040 动画文件、Grove Vision 模型和整机结构会原子更新。硬件树中有 V3 工程，而脚本启动日志仍标记 PCB V2.0，这些命名本身不足以确认任意版本混装兼容。

| **构建／版本问题** | **代码依据** |
|---|---|
| ESP-IDF 工程版本、组件与板型分支 | [顶层 CMake](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/CMakeLists.txt)、[组件 CMake](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/CMakeLists.txt)、[sdkconfig](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/sdkconfig) |
| 板级实现与引脚定义 | [板级类](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/boards/bread-compact-wifi-s3cam/compact_wifi_board_s3cam.cc)、[config.h](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/boards/bread-compact-wifi-s3cam/config.h) |
| ESP32 固件升级边界 | [ota.cc](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/ota.cc) |

# 组件关系与运行位置

下图按真实处理器分组。框内是逻辑模块，不表示每个框都是一个线程。云端内部没有取得对应完整源码，图中只保留所读协议边界。

![Coglet 组件关系](<%E5%9B%BE/Coglet%20%E7%BB%84%E4%BB%B6.png>)

```mermaid
flowchart TB
  CLOUD[小智兼容服务端\n音频与 JSON / MCP] <-->|网络协议| PROTO
  subgraph ESP[ESP32-S3 · ESP-IDF 固件]
    PROTO[Protocol\nMQTT 或 WebSocket]
    APP[Application\n状态与主事件循环]
    AUDIO[AudioService\n音频处理与队列]
    BOARD[CompactWifiBoardS3Cam\n相机与机械 MCP 工具]
    UART[uart_component\n文本行发送]
    CAM[Esp32Camera / GC0308]
    PROTO <--> APP
    APP <--> AUDIO
    BOARD --> CAM
    BOARD --> UART
    APP --> UART
  end
  subgraph RP[RP2040 · MicroPython 单循环]
    MAIN[main.py\n接收与优先级仲裁]
    ANIM[animation 模块\n姿态和临时动作]
    FOLLOW[EyeFollower\n检测框到角度]
    DRIVER[GroveVisionAI\nAT 与 JSON 驱动]
    SERVO[九个 Servo 对象\n速度与加速度插值]
    PCA[共享 _PCA9685\nI2C / PWM / nOE]
    MAIN --> ANIM
    MAIN --> FOLLOW
    FOLLOW --> DRIVER
    ANIM --> SERVO
    FOLLOW --> SERVO
    MAIN --> SERVO
    SERVO --> PCA
  end
  UART -->|UART1 · 115200 · 换行分帧| MAIN
  DRIVER <-->|UART0 · 921600 · AT / JSON| VISION[Grove Vision AI V2\n外部检测推理模块]
  PCA --> HW[九路机械执行器]
```

RP2040 接收的是 `idle`、`listening`、`speaking`、情绪名及 `action:xxx`，不是连续音频或音素。ESP32 的音频服务自行处理音频包。由此可以解释：口部会随“说话中”标记运动，但不能据此认定它与每个音素或实际扬声器响度同步。

# ESP32 对象关系与启动链

## 实际类与状态所有者

`Application` 是单例，持有一个 `AudioService` 值对象和一个 `unique_ptr<Protocol>`。`Protocol` 是协议抽象，启动时依据 OTA 返回配置创建 `MqttProtocol` 或 `WebsocketProtocol`。网络回调、音频事件与会话状态不是同一个抽象层。

`Application::Schedule` 在互斥锁下向 `main_tasks_` 加入闭包，再置 `MAIN_EVENT_SCHEDULE` 位。主事件循环被唤醒后处理任务。该模式把需要串行协调的会话修改集中在主事件循环，同时音频服务和协议底层继续异步运行。不能把 `Schedule` 画成新进程，也不能因为存在队列就认为全部共享状态都已证明没有竞态。

![Coglet ESP32 核心类](<%E5%9B%BE/Coglet%20ESP32%20%E7%B1%BB%E5%9B%BE.png>)

```mermaid
classDiagram
  class Application {
    -DeviceState device_state_
    -deque main_tasks_
    -mutex mutex_
    +GetInstance() Application
    +Start()
    +Schedule(callback)
    +MainEventLoop()
    +SetDeviceState(state)
    +AbortSpeaking(reason)
  }
  class AudioService {
    +Initialize(codec)
    +Start()
    +PushPacketToDecodeQueue(packet)
    +PopPacketFromSendQueue()
    +ResetDecoder()
  }
  class Protocol {
    <<abstract>>
    +Start()
    +SendAudio(packet)
    +OnIncomingJson(callback)
    +OnIncomingAudio(callback)
  }
  class MqttProtocol
  class WebsocketProtocol
  class CompactWifiBoardS3Cam {
    -SendCogletAction(action)
    +GetAudioCodec()
    -InitializeTools()
    -InitializeCamera()
  }
  class WifiBoard
  class McpServer {
    +GetInstance() McpServer
    +AddTool(tool)
    +ParseMessage(payload)
  }
  Application *-- AudioService : audio_service_
  Application *-- Protocol : protocol_
  Protocol <|-- MqttProtocol
  Protocol <|-- WebsocketProtocol
  WifiBoard <|-- CompactWifiBoardS3Cam
  Application ..> McpServer : 转交 MCP 消息
  CompactWifiBoardS3Cam ..> McpServer : 注册五个工具
  Application ..> CompactWifiBoardS3Cam : 经 Board 接口访问
```

图中派生协议关系由 `Application` 创建类型和 `Protocol` 接口共同支撑，本轮没有对两种协议的每个传输函数做等深分析。板级工具通过捕获 `this` 的回调调用 `SendCogletAction`，不是 `Application` 自己实现了五种机械运动。

## 启动过程

`app_main` 先初始化 UART，然后创建默认 ESP 事件循环，再初始化 NVS。仅在 NVS 空间不足或版本不兼容的特定错误下擦除并重建，随后调用 `Application::GetInstance().Start()`。

`Start` 取得 Board，把状态设为 Starting，初始化并启动音频服务，注册音频回调，创建优先级为 3 的 `main_event_loop` 任务并启动一秒时钟。接着等待网络、检查资源和固件信息、注册通用 MCP 工具，再根据配置选择传输协议。注册完连接、音频、JSON 等回调后启动协议，最后进入 Idle。**板级构造还会注册 Coglet 的五个动作工具，因此通用工具和产品专用工具是两个注册位置。**

TTS 的 `start` 消息将 Speaking 状态修改排入主循环。TTS `stop` 根据 ListeningMode 回到 Idle 或 Listening。`llm.emotion` 也进入 `Schedule`，既更新显示接口又向 UART 发送情绪名。`mcp` 消息则交给 `McpServer::ParseMessage`。这是同一网络输入分发出的多条路径，不能把情绪、音频和工具调用视为一种完整的动作事务。

| **ESP32 机制** | **固定源码定位** |
|---|---|
| 单例、任务队列、协议对象、音频对象和句柄 | [application.h](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/application.h#L37) |
| 启动顺序、网络配置和 JSON 分发 | [Start 与回调](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/application.cc#L355) |
| 加锁排队及主事件循环 | [Schedule](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/application.cc#L555)、[MainEventLoop](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/application.cc#L566) |
| 音频处理器、Opus 及发送／解码／播放队列声明 | [audio_service.h](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/audio/audio_service.h#L25) |
| 协议回调契约 | [protocol.h](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/protocols/protocol.h) |

# RP2040 的对象与过程式模块

RP2040 并非完全面向对象。`animation.py` 创建全局 `servos` 字典，保存各路限位、速度、加速度及姿态表。大量情绪函数通过 `new_state_flag` 完成一次性进入动作，再以毫秒计时执行持续动作。`main.py` 持有 `speech_active`、接收缓冲、开关边沿、睡眠输出标记，并拥有全局 `eye_follower`。

真实类关系主要集中在视觉与舵机层。`EyeFollower` 内部创建 `GroveVisionAI`，同时引用外部传入的 Servo 字典。所有 Servo 共享模块级 `_pca`，不是每个舵机各自构造一块 PCA9685。Servo 保存的是软件估计的 `pos`、`vel` 和 `target`，这些字段没有来自舵机编码器的回读。

![Coglet RP2040 核心类](<%E5%9B%BE/Coglet%20RP2040%20%E7%B1%BB%E5%9B%BE.png>)

```mermaid
classDiagram
  class EyeFollower {
    +dict servos
    +GroveVisionAI vision
    +bool has_target
    +float filtered_x
    +float filtered_y
    +update(now,state_name,enabled)
    +release_to_home()
    -_accept_new_frame(now)
    -_set_eye_targets(left,right)
    -_set_pitch_target(angle)
    -_set_base_target(angle)
  }
  class GroveVisionAI {
    +int frame_id
    +get_best_box()
    +set_enabled(enabled,now)
    +update(now)
    -_read_uart()
    -_handle_line(line)
    -_handle_event(name,code,data)
  }
  class Servo {
    +float pos
    +float vel
    +float target
    +float min_angle
    +float max_angle
    +set_target(angle)
    +set_immediate(angle)
    +update(dt)
    -_write_pwm(angle)
  }
  class _PCA9685 {
    +write_us(channel,pulse_us)
  }
  EyeFollower *-- GroveVisionAI : 自行创建
  EyeFollower o-- Servo : 引用外部 servos
  Servo ..> _PCA9685 : 使用模块共享 _pca
```

这里不把 `main.py`、`animation.py` 伪造为类。它们的关键关系是调用顺序与共享变量，应看下面的所有权与时序图。类图采用聚合箭头表示 EyeFollower 对现有 Servo 的引用，避免暗示销毁 EyeFollower 就会销毁所有执行器对象。

# 主循环、优先级与正交状态

## 启动和每轮执行

导入 `animation` 时创建 Servo 对象，PCA9685 输出门控初始关闭。主程序检查 PCA 是否就绪，若没有检测到，则进入一秒循环并保持输出关闭。若就绪，先在关闭 PWM 时预写眼睑校准角度，再使能输出、建立校准 home 表，进入主循环。

每轮先计算实际经过的 `dt`，读取串口并逐行解释。即使校准正在接管执行器，普通情绪和说话标记仍然可以更新。然后依次判断校准、临时动作、普通行为，最后统一更新所有 Servo 并检查睡眠释放。循环末尾 `sleep_ms(1)` 是让步，不是保证每轮总周期为 1ms。串口解析、视觉处理、打印和 I²C 写入都会占用时间，当前 `dt` 未做上界截断。

## 谁可以写执行器

| **层级** | **真实执行规则** | **恢复或结束** |
|---|---|---|
| 校准 | GPIO20 低电平使后续持续更新优先进入校准分支；GPIO12 仅在校准中启动以 home 为中心的摆动。接收阶段动作初始化仍可能提前写 PWM | 退出时重置 `new_state_flag`，重新进入最新表情。摆动释放时立即命令回 home |
| MCP 临时动作 | 一个全局动作槽，优先于普通表情、随机眨眼、视觉和说话口部动画；新请求替换旧请求 | 实际窗口为 2000ms。超时的同一轮恢复最新普通状态，不等待云端确认 |
| 普通状态／表情 | `apply_state` 先写该状态需要的目标，再更新随机眨眼 | 状态变化时恢复默认速度／加速度并重新进入；重复状态不重置动画时钟 |
| 视觉跟随 | 普通行为阶段再调用 EyeFollower，仅在支持的状态及开关使能时写目标 | Sad 保留对 PIT 的所有权，视觉不覆盖该轴；关闭跟随后仅释放跟随相关轴 |
| 独立口部动画 | 普通阶段最后根据 `speech_active` 更新 MOU | 情绪 happy／sad 不清掉说话标记。neutral／idle／listening／thinking／state_startup 才明确停止 |
| Servo 积分与 PWM 门控 | 所有上层设置完目标后统一 `update(dt)`，最后按睡眠条件控制 nOE | 软件位置与速度均进入容差并保持 500ms 才关闭 PWM，不切断舵机 5V |

下图是按主循环分支重建的**行为仲裁状态图**，不是代码中存在同名枚举或统一 FSM 类。说话标记、当前情绪、MCP 动作槽和 PWM 门控是几个独立变量，不能合并为一个“当前机器人状态”。

![Coglet 行为仲裁](<%E5%9B%BE/Coglet%20%E8%B0%83%E5%BA%A6%E7%8A%B6%E6%80%81.png>)

```mermaid
stateDiagram-v2
  [*] --> Normal : PCA ready / 输出使能
  state "普通表情、眨眼、视觉、口部" as Normal
  state "持续更新进入校准分支" as Calibration
  state "持续更新进入 MCP 动作分支" as Action
  Normal --> Calibration : 校准开关低电平
  Action --> Calibration : 校准开关低电平
  Calibration --> Normal : 退出且动作窗口已结束
  Calibration --> Action : 退出且动作窗口仍有效
  Normal --> Action : 收到合法 action
  Action --> Action : 新 action 替换当前动作
  Action --> Normal : 2000ms 窗口到期
  note right of Normal
    情绪和 speech_active 分别保存
    idle 软件收敛保持 500ms 后禁用 PWM
    禁用 PWM 不会退出主循环
  end note
  note right of Calibration
    串口仍接收最新状态
    接收阶段动作初始化可提前写 PWM
    动作时钟仍按真实时间流逝
  end note
```

视觉驱动被逻辑暂停时仍会读取 UART，避免已有回复卡在接收缓冲。校准和 MCP 并没有为这些后台模块新建线程，它们在持续更新阶段禁止相关模块再写竞争目标。

**校准优先不是完整的硬件写入互斥。** 串口接收位于校准分支之前，收到 action 时同步调用 `start_mcp_action`。其 `_freeze_all_servos_for_mcp` 对各轴调用 `set_immediate`，blink 初始化还立即写眼睑。因此校准期间收到新动作，仍可能在同轮进入校准更新前写 PWM。上图只重建后续持续更新的仲裁，不把代码注释中的“absolute priority”当成整个循环已保证的性质。

| **仲裁与状态证据** | **固定源码定位** |
|---|---|
| 说话标记、睡眠输出门控及校准 | [main.py 标记与门控](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/main.py#L39)、[主循环完整分支](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/main.py#L415) |
| 临时动作的名称、时长、启动与结束 | [动作常量](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/animation.py#L443)、[start_mcp_action](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/animation.py#L506)、[结束与更新](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/animation.py#L614) |
| 九路对象、默认运动参数及状态函数表 | [Servo 字典](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/animation.py#L385)、[state_map](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/animation.py#L1333) |

# 工具调用、UART 与完成语义

板级 `InitializeTools` 注册 shake_head、blink、left_ear、right_ear、ears 五种动作。工具回调将请求转换为 `action:名字`，调用 `uart_send_string` 后立即返回 `true`。RP2040 随后才在自己的下一轮收包并执行。**该返回值不是动作已完成，也不是下位机已确认接受。**

![Coglet 动作调用时序](<%E5%9B%BE/Coglet%20%E5%8A%A8%E4%BD%9C%E6%97%B6%E5%BA%8F.png>)

```mermaid
sequenceDiagram
  participant Net as Protocol / MCP 输入
  participant MCP as McpServer
  participant Board as 板级工具回调
  participant Uart as uart_component
  participant RP as RP2040 main.py
  participant Anim as animation 模块
  participant Servo as Servo / PCA9685
  Net->>MCP: ParseMessage(payload)
  MCP->>Board: self.coglet.shake_head
  Board->>Board: SendCogletAction(shake_head)
  Board->>Uart: uart_send_string(action:shake_head)
  Uart-->>RP: action:shake_head + CRLF
  Board-->>MCP: true（尚无下位机确认）
  Note over RP,Anim: 接收与执行不由 ESP32 返回值同步
  RP->>Anim: start_mcp_action(name, now)
  Anim->>Servo: 初始化冻结各轴，部分动作立即写 PWM
  loop 每轮且未被校准覆盖
    RP->>Anim: update_mcp_action(now)
    Anim->>Servo: 设置动作目标
    RP->>Servo: update(dt)
  end
  RP->>Anim: 时间窗到期 / 恢复最新普通状态
  Note over RP,Net: 所读桥接路径没有动作 ID、ACK 或完成消息回传
```

工具描述写“一次三回合”，下位机则以两秒窗口控制。某个动作的循环节奏可能在窗口内重复，但协议没有以“完成三次并回执”的形式实现该描述。动作被新请求替换、被校准抢占时也没有对应的取消结果消息。

| **UART 层** | **ESP32 ↔ RP2040** | **RP2040 ↔ Grove Vision** |
|---|---|---|
| 物理设置 | ESP UART1 TX17/RX18；RP UART1 TX4/RX5；115200、8N1 | RP UART0 TX0/RX1；921600、8N1 |
| 消息格式 | 字符串加 CRLF，RP 按 LF 拆分后 decode、strip | AT 命令和 JSON 行，驱动区分操作回复与推理事件 |
| 状态 | 最新表情、说话布尔值、单个临时动作 | 初始化阶段、待响应命令、推理请求、frame_id 与最新检测框 |
| 关联与完成 | 所读链路无请求 ID、ACK、完成结果；打印日志不是反向协议 | 驱动使用命令／推理等待和超时管理，但不提供云工具动作完成语义 |
| 异常边界 | 该 RP 接收缓冲未见长度上限，也没有在 decode 周围单独捕获非法 UTF-8 | 视觉驱动有 8192 接收缓冲限制、解析防护及超时逻辑，两条 UART 不能混写为相同健壮性 |

`uart_component` 还定义了发送 `[SPEAK_START]`／`[SPEAK_STOP]` 的辅助函数。当前已追踪的主动路径是 `Application::SetDeviceState` 发送 idle／listening／speaking 等词，以及情绪回调发送情绪名。不能只因为辅助函数存在，就把方括号协议画成当前口部控制主链。

| **通信证据** | **固定源码定位** |
|---|---|
| 五项工具、立即返回 true | [SendCogletAction 与 InitializeTools](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/boards/bread-compact-wifi-s3cam/compact_wifi_board_s3cam.cc#L201) |
| 串口设置、换行发送、辅助函数 | [uart_component.cc](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/uart_component.cc#L6)、[引脚定义](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/uart_component.h) |
| RP 接收与状态解析 | [main.py 接收分支](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/main.py#L420) |
| 当前设备状态向 UART 的映射 | [SetDeviceState](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/application.cc#L677) |

# 视觉检测、滤波与执行器分工

## 从推理事件到舵机目标

`GroveVisionAI` 打开 UART，逐步查询设备、版本、模型及传感器，再发送 INVOKE 请求。`update` 每轮推进协议工作，不阻塞等待整次推理。代码分别处理命令与推理超时，读入 JSON 后更新最新检测框与 `frame_id`。`EyeFollower` 每当看到新的 frame_id，选最高 score 的框中心作为目标，排除越界坐标。

目标坐标先经过 X、Y 各五帧中值窗口，再分别做自适应指数平滑。目标变化大时 alpha 增大以加快响应，小变化时减小以抑制抖动。随后应用像素死区、角度滞回、每次最大角度步长与关节限位，最终仍由 Servo 插值，而不是把检测框直接写成 PWM。

![Coglet 视觉跟随时序](<%E5%9B%BE/Coglet%20%E8%A7%86%E8%A7%89%E6%97%B6%E5%BA%8F.png>)

```mermaid
sequenceDiagram
  participant Main as RP2040 主循环
  participant Follow as EyeFollower
  participant Driver as GroveVisionAI
  participant Vision as Grove Vision AI V2
  participant Servo as Servo 对象
  Main->>Follow: update(now, state, enabled)
  Follow->>Driver: set_enabled / update
  Driver->>Vision: 初始化 AT 或 INVOKE
  Vision-->>Driver: JSON 操作回复 / 检测框事件
  Driver->>Driver: 缓冲拆行、解析、frame_id 更新
  alt 跟随启用且状态允许
    Follow->>Driver: get_best_box()
    Follow->>Follow: 中值 + 自适应 EMA
    Follow->>Follow: 死区、滞回、步长与轴所有权
    Follow->>Servo: eyes / pitch / base 目标
  else 暂停
    Note over Driver,Vision: 仍收已有回复，暂停新请求
  end
  Main->>Servo: update(dt) 后输出 PWM
  Note over Follow,Servo: 目标超时后，眼睛与允许的 PIT 渐回中
```

| **参数／机制** | **固定实现与含义** |
|---|---|
| 图像坐标 | 代码按 240×240 及中心 120 解释返回框；不代表任意模型输出都兼容 |
| X 平滑 | 五帧中值；稳定 alpha=0.10，移动 alpha=0.50，切换阈值 14px |
| Y 平滑 | 五帧中值；稳定 alpha=0.08，移动 alpha=0.35，切换阈值 16px |
| 控制节拍 | 25ms 的控制更新门槛；是代码节流条件，未测得整机稳定 40Hz |
| 眼睛／颈部 | X 主要写 EYL/EYR，Y 写 PIT；Sad 状态保留 PIT，不被视觉重写 |
| 底座 YAW | 眼睛目标溢出达到 3° 后，每步最多 1° 调整 base_command，并限于 30°～150° |
| 目标丢失 | 最新目标超过 650ms 后，眼睛和允许跟踪的 PIT 逐步归中；底座并非同时自动归中 |

**代码注释与实现有冲突。** 文件头、构造日志及 `_set_base_target` 周围保留“不写 YAW”的旧描述，但 `update` 实际向 `servos["YAW"]` 写 `base_command`，后半段还有眼睛溢出向底座转移的分支。这里按执行语句解释，不能照注释把该轴漏掉。关闭跟随时 `release_to_home` 只立即归中 EYL、EYR、PIT，没有同时归中 YAW。

| **视觉证据** | **固定源码定位** |
|---|---|
| 参数、控制间隔和允许状态 | [vision.py 常量区](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/vision.py#L79) |
| AT / JSON 状态、解析与暂停 | [GroveVisionAI](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/vision.py#L210) |
| 检测框选择、五帧中值与 EMA | [EyeFollower._accept_new_frame](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/vision.py#L728) |
| 轴所有权、时限、YAW 实际写入及溢出转移 | [EyeFollower.update](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/vision.py#L827) |

# 舵机插值、睡眠与运动边界

`Servo.set_target` 将目标限制到该关节的 min_angle／max_angle。`update(dt)` 根据当前位置、速度及到目标的距离，比较停止距离 `v²/(2a)` 后选择加速或减速，限制速度，再积分软件位置。角度映射为 500～2500μs，经共享 PCA9685 输出。它属于逐轴轨迹逼近，不是多关节逆运动学、碰撞规划或基于编码器的闭环位置控制。

需要单独指出：当前 `update` 对积分后的 `pos` 只限制到全局 0～180°，没有再次限制到该实例的关节范围。RP 主循环又没有限制过大的 dt。前轮从原文件提取 Servo 类进行无硬件计算，复现 PIT 范围 1～80°、pos=50、target=80、dt=0.5s 时得到 pos=150°。这是数学状态和 PWM 请求的反例，未在真机上执行。初始化同样先用 90° 预载所有 Servo，主程序只特别修正 LID，不能从 target 限位存在推导出所有启动角度已符合关节范围。

睡眠判断使用相同软件 pos／vel 的误差容差，不是传感器确认机械已到位。满足 Idle、无高优先级所有者、全部启用 Servo 收敛并持续 500ms 后，把 nOE 拉高以禁用 PWM。串口、视觉、主循环仍运行，舵机 5V 仍在。非 Idle 状态、临时动作或校准会先恢复输出。

| **运动与口部依据** | **固定源码／验证材料** |
|---|---|
| Servo 初始化、target 限位、积分与 PWM | [servoclass.py](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/servoclass.py#L196) |
| 软件收敛、延时与 nOE | [main.py](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/main.py#L79) |
| 与音频波形无关的随机口部目标 | [animation.py 口部实现](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/animation.py#L152) |
| 已有原类无硬件验证与反例，未新增真机验证 | 验证脚本（研究底稿，未随本专区发布）、验证结果（研究底稿，未随本专区发布） |

# 配置、持久化与异常传播

ESP32 的 `Settings` 用 RAII 封装 NVS namespace。写入函数标脏，析构时在可写且 dirty 的条件下 commit，再 close。OTA 代码可以读取 OTA URL，并保存返回的 MQTT／WebSocket 配置。这类配置与 RP2040 动画常量不是一套存储。

RP2040 的姿态、角度、速度与滤波参数主要是 Python 文件常量。当前情绪、说话标记、MCP 计时、检测框与软件位置保存在 RAM。所读四份 RP 文件没有显示校准参数写入持久配置文件的流程。物理“校准模式”是把执行器移动到校准姿态及摆动检查，并不自动意味着它会测量误差、保存标定结果。

| **边界** | **当前实现能说明什么** | **未取得的保证** |
|---|---|---|
| 网络错误 | Protocol 网络错误回调保存错误并置主事件位；声道关闭会调度回到 Idle | 未对全部重连、断网时长、服务端顺序异常做运行验证 |
| 跨 MCU 发送 | ESP 写出文本，RP 后续按行接收 | 没有读到动作请求 ID、幂等、下位机错误回传或完成确认 |
| RP 接收异常 | 当前解析是直接 decode、strip，再匹配状态／动作 | 没有把非法编码、超长未换行输入的隔离作为已实现能力 |
| 视觉超时 | Grove 驱动有等待超时、缓冲上限和启用控制 | 不证明外部视觉固件自身可靠，也不保证始终有有效目标 |
| 机械执行 | 软件插值、逐轴 target 限制、PWM 禁用 | 无机械到位反馈；积分及启动角度存在上述边界 |
| 升级 | ESP32 OTA、RP 脚本和视觉模块各有不同部署边界 | 没有已核实的三者一致性版本协商与整体回滚协议 |

| **配置证据** | **固定源码定位** |
|---|---|
| NVS 读写与析构提交 | [settings.cc](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/settings.cc)、[settings.h](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/settings.h) |
| OTA 信息与 MQTT／WebSocket 配置 | [ota.cc](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/ota.cc#L44) |

# 该项目采用的基本架构方案

**双 MCU 分工**把音频联网与机械表达放在不同运行环境，RP 可以继续处理物理开关和本地动画。代价是跨板契约很薄，发送、接受、执行、结束没有统一事务语义，版本兼容也需要独立管理。视觉模块构成第三个计算边界，不能把“双 MCU”理解为整机只有两处运行软件。

**ESP32 事件集中调度**让网络输入、音频队列通知与会话状态通过主循环协调。它保留小智现有抽象和驱动生态，产品定制集中在板级桥接。代价是理解 Coglet 时必须同时读小智基础链路与定制位置，单看五个 MCP 工具会漏掉音频和情绪路径。

**RP2040 合作式主循环和固定优先级仲裁**减少了线程同步，执行顺序直接表达轴所有权。代价是时序受循环负载影响，同一 Servo 的覆盖依赖代码顺序而非显式资源锁，新增行为必须认真检查每个轴在各分支的写入。

**状态表加时间函数动画**将表情归结为姿态、计时和参数变化。它便于构造有辨识度的机械动作，但这些状态不是模型理解出的完整情感，也没有自动生成安全轨迹。独立 speech_active 是必要的正交状态设计，避免一个 happy 情绪事件意外终止说话口部运动。

**检测框到角度的分层滤波控制**把视觉推理与机械响应解耦，包含中值、EMA、死区、滞回和逐步更新，适合降低噪声。其目标是视觉上的平滑跟随，不等于跨关节运动规划或闭环机械安全保证。

# 本轮阅读深度与仍不可见的部分

本轮沿固定 GitHub 提交重新核对 ESP32 启动、Application 状态与事件、UART 桥、板级工具、RP 主循环、动画仲裁、视觉驱动及 Servo 数学路径，并补读 Application／AudioService／Protocol／Settings／MCP 的公开头文件或实现。音频编解码器、全部小智板型、外部视觉模型与其固件、ESP-IDF 驱动并未全部逐文件深读。图中这些部分保留接口边界，没有补造内部类。

| **阅读层级** | **材料与可支持的结论** |
|---|---|
| 实现与调用链 | main.cc、application.cc、uart_component、板级类、RP2040 四文件；可追踪网络状态／工具如何落到 PWM |
| 类型与接口补读 | application.h、audio_service.h、protocol.h、mcp_server.h、settings.h；可说明对象拥有关系、队列和回调契约，不等于完整实现已执行 |
| 配置与部署 | 两层 CMake、sdkconfig、Kconfig、config.h、ota.cc、settings.cc；可区分编译板型、网络配置、NVS 与不同更新单元 |
| 已有无硬件验证 | Servo 原类提取的计算测试，包含已复现反例；不宣称 MicroPython 整机测试、串口联调或 PWM 实测通过 |
| 无法由当前代码确认 | Grove Vision 检测模型内部、硬件闭环反馈、各板版本兼容、完整出厂固件与最终硬件组合 |

原始固定文件及 blob 记录见 首次源码清单（研究底稿，未随本专区发布） 与 本轮补读清单（研究底稿，未随本专区发布）。这些本地材料用于研究复核，对外阅读依赖表内 GitHub 固定链接。图的可编辑源文件与同名 PNG／SVG 同目录保存。

根许可对自有材料标记 CC BY-NC，`CogletESP/LICENSE` 为沿用小智的 MIT 文本。该差异影响代码采用边界，不能把一个子目录的许可推广成整机全部可商用。许可明细保留在 [机械表情源码研究](<../Coglet%20%E6%9C%BA%E6%A2%B0%E8%A1%A8%E6%83%85%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6.md>)，本篇以现有架构解释为主。
