> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

范围与证据日期：2026-10-27。本文解释 Petoi 自身公开代码的构建方式、对象和状态、控制链路及运行边界；覆盖 BiBoard 固件与 Python 命令客户端两个独立运行域。本轮为固定提交源码阅读，未新运行整机、Arduino 构建、Ollama 模型或无线连接测试。

# 一、版本与产品边界

| 公开代码 | 本文固定版本 | 对应范围 |
| --- | --- | --- |
| OpenCatEsp32-Quadruped-Robot | [f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/commit/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef)，提交时间 2026-10-24 07:29:17 UTC | 当前公开 BiBoard / ESP32 控制程序；默认编译选择 BITTLE、BiBoard_V1_0，源码日期宏为 261024 |
| opencat-gemma | [60a76bc9529f7f61af9d0250d538d2cbde3d4cd5](https://github.com/PetoiCamp/opencat-gemma/commit/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5)，提交时间 2026-10-24 08:34:35 UTC | 本文深入 Python CLI、机器人命令合约及 USB / BLE / WebSocket 传输；仓库同时存在手机网页演示，本轮未将其实现纳入架构结论 |

两份代码没有组成一个单进程应用。固件负责把协议命令变成预制动作帧和舵机输出；Python 负责向外部 Ollama 服务请求命令、校验输出、形成有限计划并等待机器人回复。模型没有嵌入该 Arduino 固件。默认模型名是 `gemma4:e2b-it-qat`，默认接口是 `http://localhost:11434/api/chat`；这是客户端配置事实，不等于本轮已完成“本地大模型运行”验证。[固件编译入口](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/OpenCatEsp32.ino#L1)、[固件版本宏](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L70)、[模型客户端](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/gemma.py#L6)

**Quaddle 的公开边界必须单列。** 固件 README 明确写着其源码尚未公开。CLI 的 `contract/quaddle.json` 已公开模型识别字段、命令、眼睛表达和鼠标模式指令，BLE 代码也包含适配 ESP32-S3 握手的处理；这些只证明宿主协议支持，不能据此推导 Quaddle 内部任务、四舵机协调、显示或反馈架构。本文下文的固件机制均指所固定的 OpenCatEsp32，而非 Quaddle 私有固件。[未公开声明](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/README.md#L17)、[Quaddle 合约](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/contract/quaddle.json#L1)、[S3 握手兼容处理](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L71)

还存在明确的版本错位：CLI README 的 Bittle 硬件验证对象是 `B10_260527`，转向策略的注释也引用这一固件；当前阅读固件的日期宏已经是 `261024`，其中带参数的转向和延迟回执有实际实现。因此“旧固件上角度转向不停止”只能作为 CLI 设计动机，不能当作当前固定提交的实测结论。[作者测试范围](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/README.md#L53)、[runner 的历史依据](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L13)、[当前转向实现](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1503)

# 二、代码如何组成可运行系统

## 1. 固件是以头文件拼装的 Arduino 控制程序

`OpenCatEsp32.ino` 先定义机型、板型和模块宏，再包含 `src/OpenCat.h`。后者同时承载编译配置、全局状态、库依赖和 `initRobot()`，并按顺序包含 `taskQueue.h`、`configConstants.h`、`io.h`、`imu.h`、`motion.h`、`skill.h`、`moduleManager.h`、`webServer.h`、`reaction.h` 等实现。模块边界主要是文件与自由函数，不是每个模块各持有独立上下文的对象服务。包含顺序让后面的实现直接读取前面定义的全局变量和函数，这也解释了为何理解一个命令需要跨几个头文件追踪。[入口及宏](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/OpenCatEsp32.ino#L1)、[实现组装顺序](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L620)

README 给出的编译环境是 Arduino IDE 的 ESP32 Dev Module，240 MHz、4 MB Flash、Default 4MB with spiffs 分区、禁用 PSRAM。仓库根目录还保留模块测试、技能资料和配置目录；这些不参与本文主链的对象建模。公开构建说明给出板级选项，但本文没有执行构建或确认外部 Arduino 核心与库的实际安装组合。即使分区名称含 SPIFFS，所追踪的机器人配置持久化实际走 Preferences / 可选 EEPROM，不能把分区选项误写成已经使用文件系统保存所有参数。[README 构建选项](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/README.md#L76)、[Preferences 定义](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/configConstants.h#L33)

机型宏改变 `MODEL`、头尾关节、腿型、舵机型号和 `Instinct*.h` 动作表；板型宏改变 GPIO、PWM 通道、串口和 IMU 配置。默认 Bittle / BiBoard V1.0 使用 12 个 PWM 通道；逻辑 `DOF=16`，八个行走自由度通过映射跳过部分逻辑关节，不能直接把 16 解释成这块板上的 16 个物理舵机。V0.1 / V0.2、V1.0 和 BiBoard2 的分支分别定义不同引脚和通道；BiBoard2 分支为 16 个通道，并走与 ESP_PWM 条件不同的输出路径。[机型选择](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L100)、[板级引脚](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L144)、[逻辑自由度](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L249)、[舵机映射及初始化](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/espServo.h#L32)

模块存在“编进程序”和“运行时启用”两个层次。入口的 VOICE、CAMERA、GESTURE 等宏并不意味着这些模块都在每一轮主循环工作；`moduleActivatedQ` 保存运行选择，`readSignal()` 在空闲分支中再按条件调用已启用传感器。编译裁剪用于硬件差异，运行状态用于当前模块选择。[模块开关与默认数组](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L499)、[输入和模块读取](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/moduleManager.h#L453)

## 2. 宿主是同步命令管道，外加传输辅助线程

Python 入口 `_main()` 处理 CLI 参数、设备识别、合约加载及链路生命周期，`handle()` 串行调用 `ask → parse → run`。`Contract` 持有允许命令、正则、schema 和 prompt；`runner` 是模块函数，负责把命令变成带超时的计划；三个 Link 类以同名 `send()`、`close()` 供 runner 调用，没有公共父类。WebSocket 的心跳线程与 BLE 的 asyncio 线程只是传输辅助，不是让多个模型计划并行执行的任务系统。[CLI 控制流](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/__main__.py#L18)、[合约对象](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/contract.py#L20)、[计划执行](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L40)、[WebSocket 心跳](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L160)、[BLE 事件循环](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L22)

![](<%E5%9B%BE/Petoi%20%E7%BB%84%E4%BB%B6%E6%9E%B6%E6%9E%84.png>)

```mermaid
flowchart TB
  subgraph Host["宿主计算机：opencat-gemma Python CLI"]
    CLI["__main__: handle / chat"]
    Model["gemma.ask / parse"]
    Contract["Contract：codes / prompt / schema"]
    Runner["runner.plan / run"]
    Link["SerialLink / WsLink / BleLink"]
    CLI --> Model
    Contract --> Model
    CLI --> Runner
    Contract --> Runner
    Runner --> Link
  end
  Ollama["外部 Ollama 服务 localhost:11434"] <--> Model
  subgraph MCU["BiBoard：OpenCatEsp32 固件"]
    Input["readSignal / read_serial / readBle"]
    Web["WebServerLoop / WebTask 注册表"]
    Loop["Arduino loop"]
    Queue["TaskQueue：命令与延时"]
    Reaction["reaction：token 分派"]
    Skill["Skill / SkillList / HeadOverlay"]
    Motion["transform / adjust / calibratedPWM"]
    IMU["taskIMU：Core 0"]
    Globals["共享全局状态 newCmd / token / frame / ypr"]
    Store["Preferences config / 可选 I2C EEPROM"]
    Loop --> Queue
    Loop --> Input
    Loop --> Reaction
    Loop --> Web
    Queue --> Globals
    Input --> Globals
    Web --> Globals
    Globals --> Reaction
    Reaction --> Skill
    Skill --> Motion
    IMU --> Globals
    Globals --> Motion
    Store --> Skill
    Reaction --> Store
  end
  Link -->|"USB / BLE 文本命令"| Input
  Link -->|"WebSocket JSON 单命令 task"| Web
  Motion --> Servo["PWM 舵机输出"]
  Sensor["MPU6050 或 ICM42670"] --> IMU
```

图中的 Ollama 是外部进程，Servo 和 IMU 是硬件边界；`Globals` 是全局数据集合的图示，并非源码中叫这个名字的类。组件连线表达调用和数据流，不代表所有箭头都通过消息队列。

# 三、启动、主循环和状态所有权

## 1. setup 建立单套机器人状态

`setup()` 初始化串口后调用 `initRobot()`。后者配置 I²C，检测外设，打开 `config` 命名空间，判断是否新板并执行配置初始化，再按条件恢复 Wi-Fi、启动 IMU 和舵机、创建 `Skill` 与 `SkillList`，完成蓝牙初始化和 `TaskQueue` 创建，加载 `rest`，初始化运行模块并等待 IMU 数据趋稳。动作目录、当前动作和任务队列各是一份全局指针；不存在为每条连接分别创建的机器人实例。[setup](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/OpenCatEsp32.ino#L37)、[initRobot](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L656)

IMU 收敛等待有上限：等待首次数据后检查角速度/姿态变化，最多迭代 500 次，达到上限会打印提示并继续。它不是“未收敛则禁止运行”的硬门槛。初始化过程中也包含提示输入、延时、质量检查等路径，因此不能把 setup 描述成固定时长的无阻塞启动。[收敛等待与超时继续](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/imu.h#L739)

## 2. 主循环安排输入、异常与运动，IMU 在另一个任务更新

主循环先做条件性的低电量检查，再读环境和处理 IMU 异常；随后检查任务队列。只要 `cleared()` 不成立，就调用 `popTask()`，否则才走 `readSignal()` 和 quickDemo；再执行灯效、`reaction()` 和 `WebServerLoop()`。因此队列的待执行项以及上一任务仍未到期的延时，都会优先于主循环里的普通串口读取。这里并不是用 RTOS 队列把所有输入公平排队。[主循环](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/OpenCatEsp32.ino#L60)、[cleared / popTask](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L73)

`imuSetup()` 创建固定在 Core 0 的 `taskIMU`，任务从 `updateGyroQ` 指针读取运行标志；距上次读取超过 5 ms 时执行 `readIMU()` 与 `getImuException()`，否则让出调度。Arduino 主循环消费 `ypr`、`xyzReal`、`imuUpdated` 和 `imuException`。这只是目标检查间隔，不是经过测量保证的 200 Hz 控制周期；I²C 等待、传感器读取及调度都影响实际周期。[IMU 任务及创建](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/imu.h#L945)、[imuSetup](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/imu.h#L1010)

`readIMU()` 用 camera / gesture / EEPROM 的布尔锁标志协调总线访问，等待有 500 ms 上限；读取失败时可以保留上一份数据。这里看到的是共享标志和共享数组，并非统一 mutex 保护下的不可变快照；本文不据此断言已经发生竞态，但不能画成各组件经线程安全消息总线隔离。[I²C 等待与共享数据写入](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/imu.h#L646)、[共享锁标志](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L484)

## 3. 哪些数据实际由谁持有

| 状态 | 实际持有位置 | 运行含义 |
| --- | --- | --- |
| 当前输入及命令来源 | OpenCat.h 的 `token/newCmd/newCmdIdx/cmdLen/lastCmd` | 多入口汇入同一缓冲；`newCmdIdx` 表示有待处理输入，队列写 5，Web 写 4，串口/BLE 写 2。[全局定义](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L424)、[队列写入](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L76)、[Web 写入](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L363) |
| 当前动作元数据 | 全局 `Skill *skill` 对象 | period、frameSize、比例、预期姿态等属于 Skill；帧号 `frame` 和计数模式仍是全局状态。[Skill 字段](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L76)、[帧与计数](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L417) |
| 当前动作角度数据 | 全局 `newCmd` 的尾部，Skill.dutyAngles 只指向它 | 新输入占前部，动作占尾部；可用输入空间随动作大小改变。[inplaceShift](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L132) |
| IMU / 舵机命令状态 | OpenCat.h 和 imu.h 的共享数组与标志 | `currentAng` 在发送 PWM 前更新，正常播放链中的值主要是已发命令角度；不能把它当作所有关节的实时测量。[currentAng](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L602)、[calibratedPWM](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/motion.h#L5) |
| Web 事务 | `webTasks` map、`currentWebTaskId/webTaskActive` | 和 TaskQueue 分开；跟踪连接、命令组、结果、超时。[WebTask](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L71) |
| Python 本次请求 | 局部 commands / plan / replies；Contract 和 Link 保留在 CLI 会话 | 没有对话记忆库、持久任务恢复或设备状态镜像。[handle/chat](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/__main__.py#L18)、[run](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L40) |

![](<%E5%9B%BE/Petoi%20%E5%9B%BA%E4%BB%B6%E6%A0%B8%E5%BF%83%E7%B1%BB.png>)

```mermaid
classDiagram
  class QList~T~ {
    +push_back(T)
    +push_front(T)
    +pop_front()
    +front()
    +size()
    +get(index)
    +clear()
  }
  class Task {
    +char tkn
    +char* parameters
    +int paraLength
    +int dly
    +info()
  }
  class TaskQueue {
    +Task* lastTask
    +addTask(t,p,d)
    +addTaskToFront(t,p,d)
    +createTask()
    +cleared()
    +loadTaskInfo(t)
    +popTask()
  }
  class SkillPreview {
    +char* skillName
    +int period
    +int index
  }
  class SkillList {
    +lookUp(key,feedback)
  }
  class Skill {
    +char[] skillName
    +int period
    +int8_t* dutyAngles
    +byte frameSize
    +buildSkill()
    +buildSkill(s)
    +dataLen(p)
    +inplaceShift()
    +formatSkill()
    +transformToSkill(frame)
    +convertTargetToPosture(targetFrame)
    +perform()
  }
  class HeadOverlay {
    +bool active
    +float[] angles
    +start(progmem,mirrorHeadQ)
    +update()
    +stop()
    -beginFrame(index)
  }
  class WebTask {
    +String taskId
    +String status
    +uint8_t clientId
    +commandGroup
    +results
    +size_t currentCommandIndex
  }
  QList~T~ <|-- TaskQueue : T = Task pointer
  QList~T~ <|-- SkillList : T = SkillPreview pointer
  TaskQueue o-- Task : stores pointers
  SkillList o-- SkillPreview : stores pointers
  Skill ..> HeadOverlay : uses global headOverlay
  Skill ..> TaskQueue : queues up after cycles
  note for Skill "dutyAngles points into global newCmd tail"
  note for WebTask "Stored in global webTasks map; not a Task subclass"
```

类图保留实际类名。`QList<T>` 在源码中分别实例化为 Task 指针和 SkillPreview 指针容器；菱形只表示保存指针，不承诺析构所有权。全局自由函数 `reaction()`、`loadBySkillName()`、`calibratedPWM()` 没有被虚构为类的方法。Skill 与 HeadOverlay 是对全局对象的使用关系，不是 Skill 内的成员组合。[Task / TaskQueue](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L3)、[SkillList / Skill](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L3)、[HeadOverlay](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/headOverlay.h#L8)、[QList](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/QList/QList.h#L10)

# 四、命令如何进入、排队和被解释

串口读取先选可用来源：SerialBT、被启用的 Serial2、USB Serial。首字节成为 token；大写 token 通常按二进制参数读取，以 `~` 为结束符，小写使用换行。常规串口等待是 10 ms，技能数据和部分较长消息使用 200 ms。读取完成后清理文本首尾空白、补结束符并设置 `newCmdIdx`。`reaction()` 看到新命令后按 token 分派，执行查询、配置、关节控制、技能、队列等分支。[串口解析](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/moduleManager.h#L380)、[reaction 分派入口](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L341)

BLE 输入不是另一个完整解析器对象。GATT 回调 `MyCallbacks::onWrite()` 直接把片段写入全局 `newCmd`，保存 token、长度和收包时间；之后 `readBle()` 等待结束符或时间窗口、封口并标记新命令。Serial 与 BLE 共用后端，但收包路径的边界处理并不完全一致：串口分支显式检查 `spaceAfterStoringData/BUFF_LEN`，BLE 回调的复制循环没有同样检查。这是固定源码可见的实现差异，本轮没有做超长输入实验或漏洞验证。[BLE 回调及封包](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/bleUart.h#L48)、[串口空间检查](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/moduleManager.h#L402)

`TaskQueue` 保存的不是可执行闭包，而是“token + 参数副本 + 延时”的 `Task`。队列取出一项时复制到全局输入状态，相当于内部合成一条命令，再由同一个 reaction 处理。延时从 `loadTaskInfo()` 记录的 `millis()` 开始计算，定义的是下一项可被取出的时间门槛，不是一个单独线程在动作完成后睡眠。若本次 reaction 阻塞超过该延时，下一项到主循环重新获得控制时就可能立即被取出。[Task 数据复制](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L3)、[队列时序](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L73)

`q` 命令使用 `:` 切分命令和延时，实际代码使用 `>` 切分子命令，例如 `qk sit:1000>m 8 0:500>`。taskQueue 顶部注释仍写 `~`，而 reaction 的示例和实际 strtok 使用 `>`；应以解析代码为准。这套格式没有事务提交、执行回滚和持久队列语义，收到 q 的 token 回执也不代表队列中的每个动作已经完成。[实际 createTask](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L45)、[reaction 的 q 示例](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1546)

共享缓冲是这套架构最重要的内存约束。加载动作时先把 PROGMEM 字节读入 newCmd，然后 `inplaceShift()` 将帧数据搬到尾部，Skill.dutyAngles 指向尾部。之后清理命令只把前缀和 cmdLen 清空，并保留能让动作继续的 token。这样节省了一块独立动作缓冲，但“新输入可写多少字节”与“当前动作占多少字节”发生耦合，任何新增输入路径都必须遵守同一约定。[动作加载](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L102)、[尾部搬移](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L132)、[resetCmd](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/tools.h#L197)

指针生命周期还有一个明确的静态问题：addTask 用 new 分配 Task，Task 析构函数会释放参数；然而 popTask 只调用 QList.pop_front，而 QList.pop_front 只 delete 链表节点，没有 delete 节点保存的 Task 指针。这条常规出队路径中没有调用 Task 析构，存在任务对象及参数持续占用堆的风险。此处是逐路径源码发现，尚未测量长时间运行的内存曲线，不把它表述为已复现整机故障。[分配与析构](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L10)、[出队](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/taskQueue.h#L87)、[QList 删除节点](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/QList/QList.h#L115)

# 五、Skill 如何变成舵机运动

## 1. 动作表是紧凑数据格式，Skill 是当前数据的解释器

机型对应的 Instinct 头文件定义 PROGMEM 角度数组，以及平行的名称表和指针表。SkillList 启动时创建轻量 SkillPreview，记录名称、period 和索引；查找时支持精确名、左右镜像规则及随机动作。Skill 本身只有一份，切换动作会重新装载其元数据和缓冲视图。[Bittle 预置步态](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/InstinctBittleESP.h#L1632)、[名称/指针目录](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/InstinctBittleESP.h#L2486)、[SkillList 查找](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L18)

数据格式由 period 决定：period=1 是姿态，帧宽 DOF；period>1 是周期步态，帧宽 WALKING_DOF；period<0 是动作序列，帧宽 DOF+4，额外字节用于速度、停留和触发条件。正 period 使用 4 字节头，负 period 使用 7 字节头并带循环段。formatSkill 还提取预期 roll/pitch 和角度缩放比。这里的技能不是在线轨迹优化器或神经策略网络，而是解释紧凑帧数据并叠加姿态修正。[dataLen / formatSkill](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L122)

`loadBySkillName()` 找到数据后停止旧头部叠加，加载帧，处理机型变体、方向镜像和某些姿态的小幅随机偏移，再通过 `transformToSkill()` 进入动作。函数名 `nearestFrame()` 容易引发误读：当前实现返回 0，不能说它已经计算了离当前姿态最近的步态帧。[装载与镜像](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L462)、[nearestFrame / transformToSkill](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L257)

## 2. 姿态/步态每轮推进，动作序列可以阻塞

正 period 在 `Skill.perform()` 中逐关节取帧角度，先选择头部叠加、手动头部或原动作帧，再加姿态补偿，调用 calibratedPWM，最后推进 frame。到帧尾回绕时增加 completedCycles；达到 targetCycles 就清计数并加入 `k up`。所以计数的单位是完整步态周期，不是位置传感器测得的实际迈步距离。[正 period 执行](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L371)、[周期完成](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L437)

负 period 的行为序列在一次 perform 中遍历帧，调用 transform、等待 IMU 触发条件、按帧延时并处理 loopCycle；部分等待最长 2 秒，循环计数还允许特殊重复语义。它在帧间检查 SerialBT、语音串口、Serial2、Serial 和异常条件来决定中断，源码注释明确 BLE 尚未在这条检查中处理。由于 WebSocket.loop 位于外层 Arduino loop，行为内部持续执行时也不能假定 WebSocket 新命令会立即被泵入。这是“协议有 stop 命令”与“任何时刻都能立即抢占”之间的实际差别。[行为播放及中断](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L283)、[主循环 Web 调度位置](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/OpenCatEsp32.ino#L109)

当前版本增加了 HeadOverlay：当正在走 gait 而新请求对应负 period 行为时，reaction 可以只取其头部关键帧叠加到行走，而不切掉腿部步态。HeadOverlay 持有 PROGMEM 源指针、帧序号、开始时刻、起止角和 active 标志，update 按时间做余弦插值并退出；Skill.perform 每轮在头部关节优先采用它的 angles。它不是另起一个线程，也不是完整行为在并行播放；该路径的回执仍遵循当前正 period 的处理，因此不能把 k 回执解释为头部叠加动画已经播放完。[叠加入口](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1444)、[HeadOverlay 状态和推进](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/headOverlay.h#L8)、[头部角度优先级](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L383)

## 3. PWM、IMU 和反馈各自闭合不同环节

`transform()` 当前执行分支以最大角差和 speedRatio 计算插值步数，用余弦曲线从 currentAng 过渡到目标，并在每个插值步后 delay。`calibratedPWM()` 裁剪 angleLimit，加入零位和校准偏移、旋转方向，再调用 ESP PWM 舵机或 PCA 输出。它在输出之前就更新 currentAng，故普通动作回执不会证明所有关节物理到位。servoSetup 会根据舵机型号设定角度和脉宽范围并载入校准。[当前插值分支](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/motion.h#L170)、[限位和输出](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/motion.h#L5)、[舵机初始化](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/espServo.h#L32)

IMU 的姿态补偿读取期望与当前 roll/pitch 的差，在 adjust 中按关节系数计算、限制幅度及变化速度，叠加到动作角度；异常检测则把翻倒、被抬起、碰撞、转向到达等写成异常值，由主循环决定恢复动作或加入 up。当前带参数转向还比较归一化 yaw 目标、识别越过目标；这与日常 roll/pitch 平衡是相关但不同的控制路径。[adjust](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/motion.h#L302)、[异常识别](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/imu.h#L841)、[yaw 目标判断](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/imu.h#L901)、[转向结束进入 up](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L11)

固件确实有舵机反馈功能：readFeedback 发送反馈信号、detach 输出、把 PWM 引脚改为输入并测脉宽，servoFeedback 再把脉宽转换为角度；这是显式反馈/跟随路径，不应否认其存在。与此同时，普通 Skill 完成回执没有逐关节等待反馈收敛的判据。两者不能合并成“所有动作都由关节位置闭环验收”。[反馈采样](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/espServo.h#L177)、[反馈角度转换](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/espServo.h#L217)、[回执分支](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1574)

![](<%E5%9B%BE/Petoi%20%E5%9B%BA%E4%BB%B6%E5%8A%A8%E4%BD%9C%E7%8A%B6%E6%80%81.png>)

```mermaid
stateDiagram-v2
  [*] --> Init: setup / initRobot
  Init --> Posture: 加载 rest 并完成初始化
  Posture --> Gait: 加载 period 大于 1 的 skill
  Posture --> Behavior: 加载 period 小于 0 的 skill
  Gait --> Gait: 下一帧或 headOverlay
  Gait --> QueuedUp: 计数完成或转向异常达到目标
  QueuedUp --> Posture: popTask 加载 up
  Gait --> Posture: 外部 kbalance 或其他姿态
  Behavior --> Posture: perform 结束后 convertTargetToPosture
  Behavior --> Posture: 被可检测输入打断后加载 up
  Posture --> RestOutput: T_REST / shutServos
  Gait --> RestOutput: T_REST 被主循环处理
  RestOutput --> Posture: 新姿态命令
  note right of Gait
    token / period / frame / flags 共同决定
    这些状态名是阅读流程后的概括
    源码没有对应统一枚举
  end note
```

此状态图是依据 token、period、frame、队列和标志推导的阅读辅助，**不是源码中存在的统一状态枚举**。姿态仍可持续执行平衡补偿；RestOutput 表示停止输出的路径，不代表板卡或舵机物理电源已断开。[动作后处理](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1599)、[T_REST](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L660)、[shutServos 输出方式](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/espServo.h#L134)

# 六、Python 如何把模型回答变成有限计划

## 1. 合约同时约束提示词、schema 与运行检查

每个 `contract/<robot>.json` 给出机器人名称、识别字段、允许命令及 kind。Contract 从同一份数据生成 prompt 和 JSON schema：steps 允许 1–20 的周期数，joint 限定 −90 到 90 的角度，其他类别按允许的裸命令匹配；validate 再用正则检查每一项。这样避免手写提示词和 Python 允许列表分别维护，但约束主要是语法和命令集合，没有环境感知、碰撞判断、动作可行性证明，也没有 schema.maxItems 限制整条列表长度。[合约生成和校验](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/contract.py#L13)、[Bittle 命令类别](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/contract/bittle.json#L6)、[Quaddle joint 类别](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/contract/quaddle.json#L396)

ask 向 Ollama 发送两条 message：system prompt 和本次 user text，并设置 stream=false、think=false、temperature=0、format=schema。返回后 parse 使用 json.loads；若得到对象，会选择其中第一个列表值作为兼容处理；非列表、非法 JSON 或未允许命令均拒绝。模型可以返回空数组，意味着不发送动作。所谓 chat 只是反复读取输入，每次重新执行这条管道，没有把之前问答追加为模型上下文。[ask / parse](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/gemma.py#L10)、[chat 循环](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/__main__.py#L37)

`--dry-run` 只跳过机器人连接和发送，仍先调用 ask，所以它依赖可用 Ollama 和模型，并不是不调用模型的纯静态演练。设备识别通过 `?` 响应匹配合约中的 model；指定串口而没有显式 robot 时使用 bittle 默认，WebSocket 无法识别时也警告并默认 bittle；CLI 的这个选择与固件编译机型是两个配置层，不能视为自动证明一致。[dry-run](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/__main__.py#L18)、[模型选择与回退](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/__main__.py#L135)、[响应识别](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L61)

## 2. plan 负责语义收窄，run 负责顺序发送

plan 首先验证全部命令，然后生成 `(command, timeout_s, timed_by_us)` 列表。steps 缺少参数时补 3，等待预算为 `5 + 2 × cycles` 秒；timed 命令按原样发送，等待其加载回执后由宿主 sleep，默认 2 秒，再发 STOP；once/joint 使用 10 秒预算；final 命令后面的内容被丢弃。这里 20 是单个 steps 参数的上限，既不是总指令数也不是总运行时长上限。[plan](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L4)

run 在发送前完整构造计划，BLE 还会预先拒绝会断开蓝牙的 `XO`。随后逐项调用 Link.send，收到回复才发下一项；合约可指定 echo 覆盖默认首字符，例如 XO/Xo 等待 k。执行中任何 BaseException，包括 Ctrl+C，都会尝试再发 `kbalance`，然后重新抛出原异常；STOP 发送失败会打印失败信息。STOP 是平衡姿态命令，不是断电、硬实时急停或独立安全通道，仍依赖原链路和固件愿意处理输入。[run 与停止补偿](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L40)、[Quaddle echo 覆盖](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/contract/quaddle.json#L254)

这套管道保证的是“格式合法、顺序执行、部分无限运动由计数或宿主时间收束”，不是模型对自然语言语义必然正确。诸如把“左转 90 度”映射到 timed 的 kwkL，实际只转固定时间；这正是合约中把角度转向收窄后的可观察行为。当前固件虽已有角度参数路径，CLI 没有因此改用它。[runner 转向理由](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L13)、[Quaddle 角度请求示例](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/contract/quaddle.json#L424)、[当前固件参数解析](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1478)

![](<%E5%9B%BE/Petoi%20%E5%AE%BF%E4%B8%BB%E6%A0%B8%E5%BF%83%E7%B1%BB.png>)

```mermaid
classDiagram
  class Contract {
    +robot
    +codes
    +examples
    +pattern
    +schema
    +prompt
    +validate(commands)
  }
  class SerialLink {
    +ser
    +send(command,timeout,done,echo)
    +close()
  }
  class WsLink {
    +ws
    -_closed
    +send(command,timeout,echo)
    -_send_once(command,timeout)
    -_heartbeat(interval)
    +close()
  }
  class BleLink {
    +is_ble
    +client
    -_buf
    -_lock
    +connect()
    +send(command,timeout,done,echo)
    +close()
    -_on_notify(sender,data)
    -_lines_until(token,timeout,what,done)
  }
  class MultipleRobotsError
  class RuntimeError
  RuntimeError <|-- MultipleRobotsError
  note for Contract "Used by module functions ask, parse, plan and run"
  note for SerialLink "send/close duck typing; no common base class in source"
  note for WsLink "Heartbeat daemon thread; taskId completion"
  note for BleLink "Shared asyncio loop thread; notification buffer"
```

图中只画源码实际声明的类。ask、parse、plan、run 均为模块函数，模型客户端没有名为 Agent、Planner 或 RobotController 的常驻类。BleLink 的锁保护通知缓冲；WsLink 的 Event 控制心跳退出；它们没有提供跨链路统一事务编号。[Contract](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/contract.py#L20)、[SerialLink / WsLink](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L33)、[BleLink](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L45)

![](<%E5%9B%BE/Petoi%20%E8%AE%A1%E6%95%B0%E6%AD%A5%E6%80%81%E6%97%B6%E5%BA%8F.png>)

```mermaid
sequenceDiagram
  actor U as 用户
  participant CLI as CLI handle
  participant G as gemma.ask / Ollama
  participant C as Contract / parse
  participant R as runner.plan / run
  participant L as SerialLink
  participant F as read_serial / reaction
  participant S as Skill.perform
  participant Q as TaskQueue
  U->>CLI: 前进三周期后坐下
  CLI->>G: prompt + schema + 本次输入
  G-->>CLI: ["kwkF 3","ksit"]
  CLI->>C: parse 与 validate
  C-->>CLI: 合法命令列表
  CLI->>R: run(contract,commands,link)
  R->>R: plan：kwkF 3 超时 11 秒
  R->>L: send("kwkF 3",11)
  L->>F: kwkF 3 加换行
  F->>F: loadBySkillName / cycleCountingMode=true
  Note over F,L: deferSkillTokenEcho=true 暂不回 k
  loop 三次步态帧循环
    F->>S: perform()
    S->>S: calibratedPWM / frame wrap
  end
  S->>Q: addTask('k',"up")
  Q->>F: loadTaskInfo / newCmdIdx=5
  F->>F: 加载 up / 清除 defer
  F-->>L: 独立行 k
  L-->>R: reply text
  R->>L: send("ksit",10)
  L->>F: ksit 加换行
  F->>F: loadBySkillName / transformToSkill
  F-->>L: 独立行 k
  L-->>R: reply text
  Note over F,S: 输出及帧循环完成；不是关节物理到位测量
```

时序图用固定代码能表达的 `kwkF 3 → ksit` 演示，属于源码推演，不是本轮机器人运行记录。计数步态开始时 deferSkillTokenEcho=true，完成周期后加入 up，只有队列加载 up 才解除延迟并回 k；随后坐下。对裸步态、姿态和行为不能套用同一种等待含义。[开始计数与延迟](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1478)、[周期到达入队](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L441)、[解除延迟与回复](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1574)

# 七、串口、BLE 与 WebSocket 的“完成”分别是什么

## 1. 文本回执是固件分支选择的完成点

SerialLink.send 写入命令加换行，按短读超时累积文本，直到某个完整行等于预期 token，或命中调用方的 done 正则；识别大小写不敏感。链路不携带命令 ID，且普通每次 send 前没有重置串口输入缓冲，因此它不能从协议层区分迟到的同 token 回复属于哪一条命令。BLE 使用相同完成行规则，发送前清空本地通知缓冲，但也没有机器人端事务 ID。[SerialLink.send](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L43)、[BleLink.send](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L106)

固件的 k 并不是固定定义的“机器人完全停稳”。普通 gait 加载后就可回复，之后继续循环；姿态在装载变换后回复；负 period 行为在 perform 返回后回复并转换成当前姿态；参数 gait 用 defer 标志延迟到 up 队列步骤。HeadOverlay 又可能在回复后继续播放。printToAllPorts 将文本输出到若干活动端口，并在 Web 命令期间追加到 webResponse；这种 fan-out 也不是每条串口请求独享的响应通道。[一般回执](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1579)、[行为后回执](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1599)、[输出分发](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/io.h#L12)

Wi-Fi 配置是特例：固件连接成功后先打印 IP，再延时重启，客户端 wifi_setup 因而等待 IP 正则而不是 w 回执。USB 设备识别的 `?` 超时允许重试一次；普通运动命令没有通用重试，避免将一次执行变成无意的重复动作。[wifi_setup / 识别重试](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L68)、[固件连接后重启](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L435)

## 2. BLE 的异步收包被包成同步 send

BleLink.connect 在共享 asyncio 线程连接和订阅 NUS，然后等待可能的 ESP32 欢迎消息和强制 rest 回执，再主动发送 `?` 识别；对于 S3 则兼容不带普通换行的握手。这段代码是为已知固件连接行为作适配，不代表 Python 能控制私有固件的内部状态。发现多个候选且未指定名称时会在连接前抛 MultipleRobotsError，避免随机接入一个设备。[连接握手](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L71)、[多设备选择](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L126)

发送时 GATT write 使用 response=false，写成功只代表传输调用结束，随后仍要等待通知中的应用层 token。BLE 的异步写等待和回执等待各使用传入 timeout，因此其总耗时并不严格等于 runner 为一项填写的一段 deadline。断开或超时没有自动重连恢复计划；close 中的断开异常被吞掉，运行错误交由 runner 做停止尝试。[异步等待与取消](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L36)、[发送和关闭](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/ble.py#L106)

## 3. WebTask 是事务外壳，不是另一个运动调度器

固件在 81 端口接收 JSON command，WebTask 保存 taskId、clientId、commandGroup、results、currentCommandIndex 和字符串状态。startWebTask 把一条命令写入全局 token/newCmd，标记 running；reaction 到其回执点时调用 finishWebCommand，再由 completeWebTask 收集 webResponse、推进组内下一条，最终发送 completed 和 results 并删除任务。换言之，Web completed 继承同一固件命令回执语义，没有增加关节到位判定。[结构与入口](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L71)、[startWebTask](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L363)、[completeWebTask](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L446)

Python WsLink 每条命令独占一个 WebTask，避免在一个命令组中放入裸 gait 后被下一条立刻覆盖；它用 time_ns 构造 taskId，只接受匹配 ID 的 completed，但任何 error 都会抛出，因为固件可能返回旧任务 ID 的错误。心跳线程每 15 秒发消息；固件通常按 40 秒心跳超时判断连接，健康检查每 15 秒一次，任务执行超时常量为 45 秒。这些检查仍由外层 WebServerLoop 推进，长行为阻塞时不是独立 watchdog 截止时间。[WsLink 协议](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L160)、[超时常量](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L50)、[主循环检查](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L688)

忙碌路径比较特别：新命令到来而 webTaskActive=true 时，固件调用 errorWebTask 把**旧活动任务**标为错误并清理，本次新命令没有进入执行。WsLink 只对完全匹配 `Previous web task is still running` 的错误重试一次；这使同一连接在 Ctrl+C 后发送 STOP 时能先清旧事务，再提交停止姿态。多客户端情况下错误可能送往旧任务 clientId，不能把这个客户端补偿提升成任意多控制端公平排队或可靠抢占。[忙碌处理](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L299)、[errorWebTask](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L498)、[仅 BUSY 重试](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L180)

![](<%E5%9B%BE/Petoi%20WebSocket%20%E5%81%9C%E6%AD%A2%E9%87%8D%E8%AF%95.png>)

```mermaid
sequenceDiagram
  actor U as 用户
  participant R as runner.run
  participant W as WsLink
  participant E as handleWebSocketEvent
  participant T as webTasks / currentWebTaskId
  participant F as reaction
  Note over R,T: 同一连接已有运行中的旧任务
  U->>R: Ctrl+C
  R->>W: send("kbalance",10)
  W->>E: 新 taskId / commands=["kbalance"]
  E->>T: 发现 webTaskActive
  E->>T: errorWebTask：删除旧任务并清活动标志
  E-->>W: Previous web task is still running
  Note over E,F: 本次新命令被拒绝；旧运动未由清任务自动停止
  W->>W: 仅匹配 BUSY 文案时重试一次
  W->>E: 新 taskId / commands=["kbalance"]
  E->>T: 保存任务并 startWebTask
  T->>F: token=k / newCmd=balance / newCmdIdx=4
  F->>F: loadBySkillName / 姿态变换
  F->>T: finishWebCommand / completeWebTask
  T-->>W: 匹配 taskId 的 completed + results
  W-->>R: 返回停止命令回执
  R-->>U: 重新抛出中断
  Note over R,F: STOP 是平衡姿态命令；链路故障时可能发送失败
```

任务超时、断线和心跳错误会改变 WebTask/连接状态，但所追踪分支没有自动加入 up、发 kbalance 或调用 shutServos。超时路径甚至保留标为 error 的任务记录，而普通 complete/errorWebTask 路径会 erase。由此只能认定事务生命周期与运动生命周期分离；不能说断网必停，也不能把客户端一次重试称为通用故障恢复。[断开与清理](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L248)、[错误处理](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L498)、[任务超时路径](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L716)

# 八、参数、技能与文件如何保存

默认没有定义 I2C_EEPROM_ADDRESS，机器人用 Preferences `config` 命名空间保留配置。configSetup 为新板写入版本日期、声音状态、音量、模块开关、语言、临时技能及 Wi-Fi 启用标志；已初始化的板卡按同一组 key 恢复。配置版本比较取版本字符串末尾日期，旧于当前日期会走 resetAsNewBoard 路径，属于版本化重新初始化，而非通用数据库迁移器。[默认存储选择](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L84)、[打开命名空间](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L678)、[版本处理与配置恢复](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/configConstants.h#L549)

持久化粒度是参数和动作数据，不是运行中事务快照。校准偏移通过 saveCalib 写入 calib 并重算 calibratedZeroPosition；设备名写入 ID，改名后的广播名要到重启再生效；ICM 的加速度和陀螺偏移分别写为浮点 key。内置技能是编译在 PROGMEM 的表；收到 K 技能数据时另写 tmpLen/tmp，当前执行帧仍放 RAM。若启用外部 I²C EEPROM，相关分支改用固定地址和字节序列保存，不是两种存储在默认情况下双写。[校准](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/configConstants.h#L718)、[名称保存](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/configConstants.h#L532)、[ICM 偏移](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/imu.h#L508)、[临时技能写入](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L1400)

Wi-Fi 凭据走 ESP Wi-Fi 配置接口：connectWifi 调 WiFi.begin，后续 connectWifiFromStoredConfig 用 esp_wifi_get_config 读取保存的 STA 配置；应用自身的 WifiManager key 记录是否启用恢复连接。当前应用代码没有另建一份密码 JSON 文件。Wi-Fi 配置失败最多重试三次，成功会打印 IP 后重启；客户端抑制原始超时异常链，是因为固件输出中会包含密码末四位，短密码分支会显示全部。这是已追踪的日志行为，不将其扩大为完整安全审计结论。[Wi-Fi 连接/恢复](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/webServer.h#L554)、[配置命令与日志](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/reaction.h#L435)、[客户端异常包装](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L100)

Python 文件侧的权威数据是 contract/*.json；同目录 *.prompt.txt 和 *.schema.json 由 `python -m opencat_gemma.contract` 生成，方便其他语言消费。本轮没有执行生成命令。CLI 每次启动加载合约；命令计划、回复、串口缓冲、Web taskId 和 BLE 缓冲是进程内临时状态，没有保存失败计划以重启续跑，也没有保存聊天长期记忆。Ollama 的模型文件及运行缓存属于外部运行时，不由这套 Python 模块自行实现。[合约文件与生成入口](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/contract.py#L10)、[临时执行状态](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L49)、[模型调用边界](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/gemma.py#L10)

# 九、架构风格及其可见取舍

固件的特点是**一个当前动作解释器、共享状态、编译配置和协作式主循环**。它用紧凑 PROGMEM 数据和共用缓冲降低常驻数据占用，以统一 token 分派接入多个控制来源；IMU 单独放到 FreeRTOS 任务，使运动循环阻塞时仍可能更新姿态数据。代价是输入、动作缓冲和执行时序相互依赖：同一全局命令可以被多个来源触达，长动作影响协议服务，队列延时影响输入轮询，回执含义随动作类型变化。此结论来自调用结构和状态持有关系，不是性能基准或全仓审计。[全局与组装](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/OpenCat.h#L417)、[主循环](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/OpenCatEsp32.ino#L60)、[共享帧存储](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/src/skill.h#L132)

宿主的特点是**数据驱动合约加同步管道**。同一合约产出 prompt/schema/regex，runner 把步态、计时动作和模式切换做成不同执行规则；传输以鸭子类型替换。它保持模型与运动执行的进程边界，也因此不能依靠模型推理保证运动终止，必须理解固件回执并补充停止操作。其状态简单、容易逐请求跟踪，但没有持续规划、历史记忆、传感器回读闭环或计划持久化；这些不是被隐藏在某个 Agent 类中，而是在本次阅读的实现中没有建立。[Contract](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/contract.py#L20)、[runner](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L13)、[每次模型消息](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/gemma.py#L12)

可靠性边界落在具体代码上：QList 与 Task 的析构所有权未衔接；WebTask 错误不等于电机停止；普通 token 回执没有请求 ID；部分动作播放只检查特定输入；部分编译和运行宏改变行为。相应的结论限定在固定提交和已读分支，不能替代硬件断连、角度到达、堆内存和长时间运行验证。当前公开固件与 CLI 作者测试版本不同，也意味着不能把两个版本的观察无条件拼成一份整机能力证明。

# 十、实际阅读范围与未验证部分

| 仓库 / 路径 | 本轮实际阅读范围 |
| --- | --- |
| 固件 OpenCatEsp32.ino | setup、loop、默认机型/板型/模块宏，完整入口 |
| 固件 src/OpenCat.h | 配置、机型/板级映射、全局状态、实现包含关系和 initRobot；主要为 L66–结束 |
| 固件 src/taskQueue.h、src/QList/QList.h | Task 参数复制/析构、队列解析/时序/出队；QList 节点与删除路径，完整文件 |
| 固件 src/skill.h | SkillPreview/SkillList、Skill 格式、缓冲搬移、变换、行为与步态执行、计数和 loadBySkillName，完整核心实现 |
| 固件 src/headOverlay.h | 状态字段、start/update/stop/beginFrame，完整文件 |
| 固件 src/motion.h | L1–207 的 PWM/transform，L302–约 L335 的姿态补偿；未把可选 CPG 后半部分纳入结论 |
| 固件 src/InstinctBittleESP.h | wkF、balance、rest 数据片段及 L2486–结束名称/指针表；未逐个验证所有动作数组 |
| 固件 src/moduleManager.h | 模块激活保存、L380–结束的串口/信号/环境输入；其余传感器实现未逐一展开 |
| 固件 src/reaction.h | 异常入口、低电量相关段落、新命令分派、查询/名称/Wi-Fi/休息/校准分支、L1400–结束的 Skill/队列/回执与动作推进；未逐项审计所有控制 token |
| 固件 src/espServo.h | 舵机型号、初始化、停止、L177–约 L240 的反馈测量与转换；未验证硬件反馈精度 |
| 固件 src/imu.h | 传感器初始化及偏移保存的相关段落、L646–结束的读取/收敛/异常/任务创建；未审计底层传感器库 |
| 固件 src/configConstants.h | Preferences 与 EEPROM 选择、配置 key、版本/新板处理、名称、临时技能和校准保存；未逐项验证 NVS 调试工具 |
| 固件 src/webServer.h | WebTask、输入事件、任务启动/完成/错误、Wi-Fi恢复及 WebServerLoop，完整业务路径 |
| 固件 src/bleUart.h、src/io.h、src/tools.h、src/bluetoothManager.h | BLE 服务/接收/封包与连接管理相关路径；printToAllPorts 与 resetCmd；未把底层 BLE 库实现当已审计 |
| Gemma opencat_gemma/{__main__,contract,gemma,runner,links,ble}.py | 完整 Python 控制链、字段、异常与 Link 实现 |
| Gemma contract/{bittle,nybble,quaddle}.json | 模型识别、kind、允许命令和示例；大型命令列表按字段及相关段落阅读，没有逐动作硬件确认 |
| 两仓 README、requirements 与既有缓存材料 | 确认边界、构建说明、作者测试版本及依赖；README 测试陈述与本轮验证分开 |

新增缓存保存在 petoi-architecture（研究底稿，未随本专区发布），复用的固件源码见 PetoiCamp 缓存（研究底稿，未随本专区发布），Python 原有源码与测试材料见 petoi-gemma 缓存（研究底稿，未随本专区发布）。图的 Mermaid 源文件与 PNG 引用使用相同 basename，位于本文同目录的 [图](<%E5%9B%BE/index.html>)。

本轮只做源码与文档一致性检查，未运行模型、串口/BLE/WebSocket、固件编译或整机动作。前序报告中的纯 Python 假链路测试不等于本文两仓固定版本的硬件端到端验证；本文时序图和状态图均按代码推演。Quaddle 内部固件、手机网页演示内部机制、全部传感器插件、所有预制动作和底层库均不在本轮已验证范围。

