源码与访问日期: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 文件中。
| 版本与范围依据 | 直接入口 |
|---|---|
| 固定代码、许可及整机资料 | 仓库固定版本、README |
| ESP32 程序入口与会话主干 | main.cc、Application::Start |
| RP2040 程序入口与视觉实现 | main.py 主循环、vision.py |
仓库、构建与部署单元
| 目录或文件 | 职责 | 产物与边界 |
|---|---|---|
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、组件 CMake、sdkconfig |
| 板级实现与引脚定义 | 板级类、config.h |
| ESP32 固件升级边界 | ota.cc |
组件关系与运行位置
下图按真实处理器分组。框内是逻辑模块,不表示每个框都是一个线程。云端内部没有取得对应完整源码,图中只保留所读协议边界。

查看 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 画成新进程,也不能因为存在队列就认为全部共享状态都已证明没有竞态。

查看 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 |
| 启动顺序、网络配置和 JSON 分发 | Start 与回调 |
| 加锁排队及主事件循环 | Schedule、MainEventLoop |
| 音频处理器、Opus 及发送/解码/播放队列声明 | audio_service.h |
| 协议回调契约 | 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,这些字段没有来自舵机编码器的回读。

查看 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 门控是几个独立变量,不能合并为一个“当前机器人状态”。

查看 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 标记与门控、主循环完整分支 |
| 临时动作的名称、时长、启动与结束 | 动作常量、start_mcp_action、结束与更新 |
| 九路对象、默认运动参数及状态函数表 | Servo 字典、state_map |
工具调用、UART 与完成语义
板级 InitializeTools 注册 shake_head、blink、left_ear、right_ear、ears 五种动作。工具回调将请求转换为 action:名字,调用 uart_send_string 后立即返回 true。RP2040 随后才在自己的下一轮收包并执行。该返回值不是动作已完成,也不是下位机已确认接受。

查看 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 |
| 串口设置、换行发送、辅助函数 | uart_component.cc、引脚定义 |
| RP 接收与状态解析 | main.py 接收分支 |
| 当前设备状态向 UART 的映射 | SetDeviceState |
视觉检测、滤波与执行器分工
从推理事件到舵机目标
GroveVisionAI 打开 UART,逐步查询设备、版本、模型及传感器,再发送 INVOKE 请求。update 每轮推进协议工作,不阻塞等待整次推理。代码分别处理命令与推理超时,读入 JSON 后更新最新检测框与 frame_id。EyeFollower 每当看到新的 frame_id,选最高 score 的框中心作为目标,排除越界坐标。
目标坐标先经过 X、Y 各五帧中值窗口,再分别做自适应指数平滑。目标变化大时 alpha 增大以加快响应,小变化时减小以抑制抖动。随后应用像素死区、角度滞回、每次最大角度步长与关节限位,最终仍由 Servo 插值,而不是把检测框直接写成 PWM。

查看 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 常量区 |
| AT / JSON 状态、解析与暂停 | GroveVisionAI |
| 检测框选择、五帧中值与 EMA | EyeFollower._accept_new_frame |
| 轴所有权、时限、YAW 实际写入及溢出转移 | EyeFollower.update |
舵机插值、睡眠与运动边界
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 |
| 软件收敛、延时与 nOE | main.py |
| 与音频波形无关的随机口部目标 | animation.py 口部实现 |
| 已有原类无硬件验证与反例,未新增真机验证 | 验证脚本(研究底稿,未随本专区发布)、验证结果(研究底稿,未随本专区发布) |
配置、持久化与异常传播
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、settings.h |
| OTA 信息与 MQTT/WebSocket 配置 | ota.cc |
该项目采用的基本架构方案
双 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 文本。该差异影响代码采用边界,不能把一个子目录的许可推广成整机全部可商用。许可明细保留在 机械表情源码研究,本篇以现有架构解释为主。