范围与证据日期:2026-10-27。本文解释 Petoi 自身公开代码的构建方式、对象和状态、控制链路及运行边界;覆盖 BiBoard 固件与 Python 命令客户端两个独立运行域。本轮为固定提交源码阅读,未新运行整机、Arduino 构建、Ollama 模型或无线连接测试。
一、版本与产品边界
| 公开代码 | 本文固定版本 | 对应范围 |
|---|---|---|
| OpenCatEsp32-Quadruped-Robot | f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef,提交时间 2026-10-24 07:29:17 UTC | 当前公开 BiBoard / ESP32 控制程序;默认编译选择 BITTLE、BiBoard_V1_0,源码日期宏为 261024 |
| opencat-gemma | 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;这是客户端配置事实,不等于本轮已完成“本地大模型运行”验证。固件编译入口、固件版本宏、模型客户端
Quaddle 的公开边界必须单列。 固件 README 明确写着其源码尚未公开。CLI 的 contract/quaddle.json 已公开模型识别字段、命令、眼睛表达和鼠标模式指令,BLE 代码也包含适配 ESP32-S3 握手的处理;这些只证明宿主协议支持,不能据此推导 Quaddle 内部任务、四舵机协调、显示或反馈架构。本文下文的固件机制均指所固定的 OpenCatEsp32,而非 Quaddle 私有固件。未公开声明、Quaddle 合约、S3 握手兼容处理
还存在明确的版本错位:CLI README 的 Bittle 硬件验证对象是 B10_260527,转向策略的注释也引用这一固件;当前阅读固件的日期宏已经是 261024,其中带参数的转向和延迟回执有实际实现。因此“旧固件上角度转向不停止”只能作为 CLI 设计动机,不能当作当前固定提交的实测结论。作者测试范围、runner 的历史依据、当前转向实现
二、代码如何组成可运行系统
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 等实现。模块边界主要是文件与自由函数,不是每个模块各持有独立上下文的对象服务。包含顺序让后面的实现直接读取前面定义的全局变量和函数,这也解释了为何理解一个命令需要跨几个头文件追踪。入口及宏、实现组装顺序
README 给出的编译环境是 Arduino IDE 的 ESP32 Dev Module,240 MHz、4 MB Flash、Default 4MB with spiffs 分区、禁用 PSRAM。仓库根目录还保留模块测试、技能资料和配置目录;这些不参与本文主链的对象建模。公开构建说明给出板级选项,但本文没有执行构建或确认外部 Arduino 核心与库的实际安装组合。即使分区名称含 SPIFFS,所追踪的机器人配置持久化实际走 Preferences / 可选 EEPROM,不能把分区选项误写成已经使用文件系统保存所有参数。README 构建选项、Preferences 定义
机型宏改变 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 条件不同的输出路径。机型选择、板级引脚、逻辑自由度、舵机映射及初始化
模块存在“编进程序”和“运行时启用”两个层次。入口的 VOICE、CAMERA、GESTURE 等宏并不意味着这些模块都在每一轮主循环工作;moduleActivatedQ 保存运行选择,readSignal() 在空闲分支中再按条件调用已启用传感器。编译裁剪用于硬件差异,运行状态用于当前模块选择。模块开关与默认数组、输入和模块读取
2. 宿主是同步命令管道,外加传输辅助线程
Python 入口 _main() 处理 CLI 参数、设备识别、合约加载及链路生命周期,handle() 串行调用 ask → parse → run。Contract 持有允许命令、正则、schema 和 prompt;runner 是模块函数,负责把命令变成带超时的计划;三个 Link 类以同名 send()、close() 供 runner 调用,没有公共父类。WebSocket 的心跳线程与 BLE 的 asyncio 线程只是传输辅助,不是让多个模型计划并行执行的任务系统。CLI 控制流、合约对象、计划执行、WebSocket 心跳、BLE 事件循环

查看 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、initRobot
IMU 收敛等待有上限:等待首次数据后检查角速度/姿态变化,最多迭代 500 次,达到上限会打印提示并继续。它不是“未收敛则禁止运行”的硬门槛。初始化过程中也包含提示输入、延时、质量检查等路径,因此不能把 setup 描述成固定时长的无阻塞启动。收敛等待与超时继续
2. 主循环安排输入、异常与运动,IMU 在另一个任务更新
主循环先做条件性的低电量检查,再读环境和处理 IMU 异常;随后检查任务队列。只要 cleared() 不成立,就调用 popTask(),否则才走 readSignal() 和 quickDemo;再执行灯效、reaction() 和 WebServerLoop()。因此队列的待执行项以及上一任务仍未到期的延时,都会优先于主循环里的普通串口读取。这里并不是用 RTOS 队列把所有输入公平排队。主循环、cleared / popTask
imuSetup() 创建固定在 Core 0 的 taskIMU,任务从 updateGyroQ 指针读取运行标志;距上次读取超过 5 ms 时执行 readIMU() 与 getImuException(),否则让出调度。Arduino 主循环消费 ypr、xyzReal、imuUpdated 和 imuException。这只是目标检查间隔,不是经过测量保证的 200 Hz 控制周期;I²C 等待、传感器读取及调度都影响实际周期。IMU 任务及创建、imuSetup
readIMU() 用 camera / gesture / EEPROM 的布尔锁标志协调总线访问,等待有 500 ms 上限;读取失败时可以保留上一份数据。这里看到的是共享标志和共享数组,并非统一 mutex 保护下的不可变快照;本文不据此断言已经发生竞态,但不能画成各组件经线程安全消息总线隔离。I²C 等待与共享数据写入、共享锁标志
3. 哪些数据实际由谁持有
| 状态 | 实际持有位置 | 运行含义 |
|---|---|---|
| 当前输入及命令来源 | OpenCat.h 的 token/newCmd/newCmdIdx/cmdLen/lastCmd |
多入口汇入同一缓冲;newCmdIdx 表示有待处理输入,队列写 5,Web 写 4,串口/BLE 写 2。全局定义、队列写入、Web 写入 |
| 当前动作元数据 | 全局 Skill *skill 对象 |
period、frameSize、比例、预期姿态等属于 Skill;帧号 frame 和计数模式仍是全局状态。Skill 字段、帧与计数 |
| 当前动作角度数据 | 全局 newCmd 的尾部,Skill.dutyAngles 只指向它 |
新输入占前部,动作占尾部;可用输入空间随动作大小改变。inplaceShift |
| IMU / 舵机命令状态 | OpenCat.h 和 imu.h 的共享数组与标志 | currentAng 在发送 PWM 前更新,正常播放链中的值主要是已发命令角度;不能把它当作所有关节的实时测量。currentAng、calibratedPWM |
| Web 事务 | webTasks map、currentWebTaskId/webTaskActive |
和 TaskQueue 分开;跟踪连接、命令组、结果、超时。WebTask |
| Python 本次请求 | 局部 commands / plan / replies;Contract 和 Link 保留在 CLI 会话 | 没有对话记忆库、持久任务恢复或设备状态镜像。handle/chat、run |

查看 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、SkillList / Skill、HeadOverlay、QList
四、命令如何进入、排队和被解释
串口读取先选可用来源:SerialBT、被启用的 Serial2、USB Serial。首字节成为 token;大写 token 通常按二进制参数读取,以 ~ 为结束符,小写使用换行。常规串口等待是 10 ms,技能数据和部分较长消息使用 200 ms。读取完成后清理文本首尾空白、补结束符并设置 newCmdIdx。reaction() 看到新命令后按 token 分派,执行查询、配置、关节控制、技能、队列等分支。串口解析、reaction 分派入口
BLE 输入不是另一个完整解析器对象。GATT 回调 MyCallbacks::onWrite() 直接把片段写入全局 newCmd,保存 token、长度和收包时间;之后 readBle() 等待结束符或时间窗口、封口并标记新命令。Serial 与 BLE 共用后端,但收包路径的边界处理并不完全一致:串口分支显式检查 spaceAfterStoringData/BUFF_LEN,BLE 回调的复制循环没有同样检查。这是固定源码可见的实现差异,本轮没有做超长输入实验或漏洞验证。BLE 回调及封包、串口空间检查
TaskQueue 保存的不是可执行闭包,而是“token + 参数副本 + 延时”的 Task。队列取出一项时复制到全局输入状态,相当于内部合成一条命令,再由同一个 reaction 处理。延时从 loadTaskInfo() 记录的 millis() 开始计算,定义的是下一项可被取出的时间门槛,不是一个单独线程在动作完成后睡眠。若本次 reaction 阻塞超过该延时,下一项到主循环重新获得控制时就可能立即被取出。Task 数据复制、队列时序
q 命令使用 : 切分命令和延时,实际代码使用 > 切分子命令,例如 qk sit:1000>m 8 0:500>。taskQueue 顶部注释仍写 ~,而 reaction 的示例和实际 strtok 使用 >;应以解析代码为准。这套格式没有事务提交、执行回滚和持久队列语义,收到 q 的 token 回执也不代表队列中的每个动作已经完成。实际 createTask、reaction 的 q 示例
共享缓冲是这套架构最重要的内存约束。加载动作时先把 PROGMEM 字节读入 newCmd,然后 inplaceShift() 将帧数据搬到尾部,Skill.dutyAngles 指向尾部。之后清理命令只把前缀和 cmdLen 清空,并保留能让动作继续的 token。这样节省了一块独立动作缓冲,但“新输入可写多少字节”与“当前动作占多少字节”发生耦合,任何新增输入路径都必须遵守同一约定。动作加载、尾部搬移、resetCmd
指针生命周期还有一个明确的静态问题:addTask 用 new 分配 Task,Task 析构函数会释放参数;然而 popTask 只调用 QList.pop_front,而 QList.pop_front 只 delete 链表节点,没有 delete 节点保存的 Task 指针。这条常规出队路径中没有调用 Task 析构,存在任务对象及参数持续占用堆的风险。此处是逐路径源码发现,尚未测量长时间运行的内存曲线,不把它表述为已复现整机故障。分配与析构、出队、QList 删除节点
五、Skill 如何变成舵机运动
1. 动作表是紧凑数据格式,Skill 是当前数据的解释器
机型对应的 Instinct 头文件定义 PROGMEM 角度数组,以及平行的名称表和指针表。SkillList 启动时创建轻量 SkillPreview,记录名称、period 和索引;查找时支持精确名、左右镜像规则及随机动作。Skill 本身只有一份,切换动作会重新装载其元数据和缓冲视图。Bittle 预置步态、名称/指针目录、SkillList 查找
数据格式由 period 决定:period=1 是姿态,帧宽 DOF;period>1 是周期步态,帧宽 WALKING_DOF;period<0 是动作序列,帧宽 DOF+4,额外字节用于速度、停留和触发条件。正 period 使用 4 字节头,负 period 使用 7 字节头并带循环段。formatSkill 还提取预期 roll/pitch 和角度缩放比。这里的技能不是在线轨迹优化器或神经策略网络,而是解释紧凑帧数据并叠加姿态修正。dataLen / formatSkill
loadBySkillName() 找到数据后停止旧头部叠加,加载帧,处理机型变体、方向镜像和某些姿态的小幅随机偏移,再通过 transformToSkill() 进入动作。函数名 nearestFrame() 容易引发误读:当前实现返回 0,不能说它已经计算了离当前姿态最近的步态帧。装载与镜像、nearestFrame / transformToSkill
2. 姿态/步态每轮推进,动作序列可以阻塞
正 period 在 Skill.perform() 中逐关节取帧角度,先选择头部叠加、手动头部或原动作帧,再加姿态补偿,调用 calibratedPWM,最后推进 frame。到帧尾回绕时增加 completedCycles;达到 targetCycles 就清计数并加入 k up。所以计数的单位是完整步态周期,不是位置传感器测得的实际迈步距离。正 period 执行、周期完成
负 period 的行为序列在一次 perform 中遍历帧,调用 transform、等待 IMU 触发条件、按帧延时并处理 loopCycle;部分等待最长 2 秒,循环计数还允许特殊重复语义。它在帧间检查 SerialBT、语音串口、Serial2、Serial 和异常条件来决定中断,源码注释明确 BLE 尚未在这条检查中处理。由于 WebSocket.loop 位于外层 Arduino loop,行为内部持续执行时也不能假定 WebSocket 新命令会立即被泵入。这是“协议有 stop 命令”与“任何时刻都能立即抢占”之间的实际差别。行为播放及中断、主循环 Web 调度位置
当前版本增加了 HeadOverlay:当正在走 gait 而新请求对应负 period 行为时,reaction 可以只取其头部关键帧叠加到行走,而不切掉腿部步态。HeadOverlay 持有 PROGMEM 源指针、帧序号、开始时刻、起止角和 active 标志,update 按时间做余弦插值并退出;Skill.perform 每轮在头部关节优先采用它的 angles。它不是另起一个线程,也不是完整行为在并行播放;该路径的回执仍遵循当前正 period 的处理,因此不能把 k 回执解释为头部叠加动画已经播放完。叠加入口、HeadOverlay 状态和推进、头部角度优先级
3. PWM、IMU 和反馈各自闭合不同环节
transform() 当前执行分支以最大角差和 speedRatio 计算插值步数,用余弦曲线从 currentAng 过渡到目标,并在每个插值步后 delay。calibratedPWM() 裁剪 angleLimit,加入零位和校准偏移、旋转方向,再调用 ESP PWM 舵机或 PCA 输出。它在输出之前就更新 currentAng,故普通动作回执不会证明所有关节物理到位。servoSetup 会根据舵机型号设定角度和脉宽范围并载入校准。当前插值分支、限位和输出、舵机初始化
IMU 的姿态补偿读取期望与当前 roll/pitch 的差,在 adjust 中按关节系数计算、限制幅度及变化速度,叠加到动作角度;异常检测则把翻倒、被抬起、碰撞、转向到达等写成异常值,由主循环决定恢复动作或加入 up。当前带参数转向还比较归一化 yaw 目标、识别越过目标;这与日常 roll/pitch 平衡是相关但不同的控制路径。adjust、异常识别、yaw 目标判断、转向结束进入 up
固件确实有舵机反馈功能:readFeedback 发送反馈信号、detach 输出、把 PWM 引脚改为输入并测脉宽,servoFeedback 再把脉宽转换为角度;这是显式反馈/跟随路径,不应否认其存在。与此同时,普通 Skill 完成回执没有逐关节等待反馈收敛的判据。两者不能合并成“所有动作都由关节位置闭环验收”。反馈采样、反馈角度转换、回执分支

查看 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 表示停止输出的路径,不代表板卡或舵机物理电源已断开。动作后处理、T_REST、shutServos 输出方式
六、Python 如何把模型回答变成有限计划
1. 合约同时约束提示词、schema 与运行检查
每个 contract/<robot>.json 给出机器人名称、识别字段、允许命令及 kind。Contract 从同一份数据生成 prompt 和 JSON schema:steps 允许 1–20 的周期数,joint 限定 −90 到 90 的角度,其他类别按允许的裸命令匹配;validate 再用正则检查每一项。这样避免手写提示词和 Python 允许列表分别维护,但约束主要是语法和命令集合,没有环境感知、碰撞判断、动作可行性证明,也没有 schema.maxItems 限制整条列表长度。合约生成和校验、Bittle 命令类别、Quaddle joint 类别
ask 向 Ollama 发送两条 message:system prompt 和本次 user text,并设置 stream=false、think=false、temperature=0、format=schema。返回后 parse 使用 json.loads;若得到对象,会选择其中第一个列表值作为兼容处理;非列表、非法 JSON 或未允许命令均拒绝。模型可以返回空数组,意味着不发送动作。所谓 chat 只是反复读取输入,每次重新执行这条管道,没有把之前问答追加为模型上下文。ask / parse、chat 循环
--dry-run 只跳过机器人连接和发送,仍先调用 ask,所以它依赖可用 Ollama 和模型,并不是不调用模型的纯静态演练。设备识别通过 ? 响应匹配合约中的 model;指定串口而没有显式 robot 时使用 bittle 默认,WebSocket 无法识别时也警告并默认 bittle;CLI 的这个选择与固件编译机型是两个配置层,不能视为自动证明一致。dry-run、模型选择与回退、响应识别
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
run 在发送前完整构造计划,BLE 还会预先拒绝会断开蓝牙的 XO。随后逐项调用 Link.send,收到回复才发下一项;合约可指定 echo 覆盖默认首字符,例如 XO/Xo 等待 k。执行中任何 BaseException,包括 Ctrl+C,都会尝试再发 kbalance,然后重新抛出原异常;STOP 发送失败会打印失败信息。STOP 是平衡姿态命令,不是断电、硬实时急停或独立安全通道,仍依赖原链路和固件愿意处理输入。run 与停止补偿、Quaddle echo 覆盖
这套管道保证的是“格式合法、顺序执行、部分无限运动由计数或宿主时间收束”,不是模型对自然语言语义必然正确。诸如把“左转 90 度”映射到 timed 的 kwkL,实际只转固定时间;这正是合约中把角度转向收窄后的可观察行为。当前固件虽已有角度参数路径,CLI 没有因此改用它。runner 转向理由、Quaddle 角度请求示例、当前固件参数解析

查看 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、SerialLink / WsLink、BleLink

查看 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;随后坐下。对裸步态、姿态和行为不能套用同一种等待含义。开始计数与延迟、周期到达入队、解除延迟与回复
七、串口、BLE 与 WebSocket 的“完成”分别是什么
1. 文本回执是固件分支选择的完成点
SerialLink.send 写入命令加换行,按短读超时累积文本,直到某个完整行等于预期 token,或命中调用方的 done 正则;识别大小写不敏感。链路不携带命令 ID,且普通每次 send 前没有重置串口输入缓冲,因此它不能从协议层区分迟到的同 token 回复属于哪一条命令。BLE 使用相同完成行规则,发送前清空本地通知缓冲,但也没有机器人端事务 ID。SerialLink.send、BleLink.send
固件的 k 并不是固定定义的“机器人完全停稳”。普通 gait 加载后就可回复,之后继续循环;姿态在装载变换后回复;负 period 行为在 perform 返回后回复并转换成当前姿态;参数 gait 用 defer 标志延迟到 up 队列步骤。HeadOverlay 又可能在回复后继续播放。printToAllPorts 将文本输出到若干活动端口,并在 Web 命令期间追加到 webResponse;这种 fan-out 也不是每条串口请求独享的响应通道。一般回执、行为后回执、输出分发
Wi-Fi 配置是特例:固件连接成功后先打印 IP,再延时重启,客户端 wifi_setup 因而等待 IP 正则而不是 w 回执。USB 设备识别的 ? 超时允许重试一次;普通运动命令没有通用重试,避免将一次执行变成无意的重复动作。wifi_setup / 识别重试、固件连接后重启
2. BLE 的异步收包被包成同步 send
BleLink.connect 在共享 asyncio 线程连接和订阅 NUS,然后等待可能的 ESP32 欢迎消息和强制 rest 回执,再主动发送 ? 识别;对于 S3 则兼容不带普通换行的握手。这段代码是为已知固件连接行为作适配,不代表 Python 能控制私有固件的内部状态。发现多个候选且未指定名称时会在连接前抛 MultipleRobotsError,避免随机接入一个设备。连接握手、多设备选择
发送时 GATT write 使用 response=false,写成功只代表传输调用结束,随后仍要等待通知中的应用层 token。BLE 的异步写等待和回执等待各使用传入 timeout,因此其总耗时并不严格等于 runner 为一项填写的一段 deadline。断开或超时没有自动重连恢复计划;close 中的断开异常被吞掉,运行错误交由 runner 做停止尝试。异步等待与取消、发送和关闭
3. WebTask 是事务外壳,不是另一个运动调度器
固件在 81 端口接收 JSON command,WebTask 保存 taskId、clientId、commandGroup、results、currentCommandIndex 和字符串状态。startWebTask 把一条命令写入全局 token/newCmd,标记 running;reaction 到其回执点时调用 finishWebCommand,再由 completeWebTask 收集 webResponse、推进组内下一条,最终发送 completed 和 results 并删除任务。换言之,Web completed 继承同一固件命令回执语义,没有增加关节到位判定。结构与入口、startWebTask、completeWebTask
Python WsLink 每条命令独占一个 WebTask,避免在一个命令组中放入裸 gait 后被下一条立刻覆盖;它用 time_ns 构造 taskId,只接受匹配 ID 的 completed,但任何 error 都会抛出,因为固件可能返回旧任务 ID 的错误。心跳线程每 15 秒发消息;固件通常按 40 秒心跳超时判断连接,健康检查每 15 秒一次,任务执行超时常量为 45 秒。这些检查仍由外层 WebServerLoop 推进,长行为阻塞时不是独立 watchdog 截止时间。WsLink 协议、超时常量、主循环检查
忙碌路径比较特别:新命令到来而 webTaskActive=true 时,固件调用 errorWebTask 把旧活动任务标为错误并清理,本次新命令没有进入执行。WsLink 只对完全匹配 Previous web task is still running 的错误重试一次;这使同一连接在 Ctrl+C 后发送 STOP 时能先清旧事务,再提交停止姿态。多客户端情况下错误可能送往旧任务 clientId,不能把这个客户端补偿提升成任意多控制端公平排队或可靠抢占。忙碌处理、errorWebTask、仅 BUSY 重试

查看 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。由此只能认定事务生命周期与运动生命周期分离;不能说断网必停,也不能把客户端一次重试称为通用故障恢复。断开与清理、错误处理、任务超时路径
八、参数、技能与文件如何保存
默认没有定义 I2C_EEPROM_ADDRESS,机器人用 Preferences config 命名空间保留配置。configSetup 为新板写入版本日期、声音状态、音量、模块开关、语言、临时技能及 Wi-Fi 启用标志;已初始化的板卡按同一组 key 恢复。配置版本比较取版本字符串末尾日期,旧于当前日期会走 resetAsNewBoard 路径,属于版本化重新初始化,而非通用数据库迁移器。默认存储选择、打开命名空间、版本处理与配置恢复
持久化粒度是参数和动作数据,不是运行中事务快照。校准偏移通过 saveCalib 写入 calib 并重算 calibratedZeroPosition;设备名写入 ID,改名后的广播名要到重启再生效;ICM 的加速度和陀螺偏移分别写为浮点 key。内置技能是编译在 PROGMEM 的表;收到 K 技能数据时另写 tmpLen/tmp,当前执行帧仍放 RAM。若启用外部 I²C EEPROM,相关分支改用固定地址和字节序列保存,不是两种存储在默认情况下双写。校准、名称保存、ICM 偏移、临时技能写入
Wi-Fi 凭据走 ESP Wi-Fi 配置接口:connectWifi 调 WiFi.begin,后续 connectWifiFromStoredConfig 用 esp_wifi_get_config 读取保存的 STA 配置;应用自身的 WifiManager key 记录是否启用恢复连接。当前应用代码没有另建一份密码 JSON 文件。Wi-Fi 配置失败最多重试三次,成功会打印 IP 后重启;客户端抑制原始超时异常链,是因为固件输出中会包含密码末四位,短密码分支会显示全部。这是已追踪的日志行为,不将其扩大为完整安全审计结论。Wi-Fi 连接/恢复、配置命令与日志、客户端异常包装
Python 文件侧的权威数据是 contract/.json;同目录 .prompt.txt 和 *.schema.json 由 python -m opencat_gemma.contract 生成,方便其他语言消费。本轮没有执行生成命令。CLI 每次启动加载合约;命令计划、回复、串口缓冲、Web taskId 和 BLE 缓冲是进程内临时状态,没有保存失败计划以重启续跑,也没有保存聊天长期记忆。Ollama 的模型文件及运行缓存属于外部运行时,不由这套 Python 模块自行实现。合约文件与生成入口、临时执行状态、模型调用边界
九、架构风格及其可见取舍
固件的特点是一个当前动作解释器、共享状态、编译配置和协作式主循环。它用紧凑 PROGMEM 数据和共用缓冲降低常驻数据占用,以统一 token 分派接入多个控制来源;IMU 单独放到 FreeRTOS 任务,使运动循环阻塞时仍可能更新姿态数据。代价是输入、动作缓冲和执行时序相互依赖:同一全局命令可以被多个来源触达,长动作影响协议服务,队列延时影响输入轮询,回执含义随动作类型变化。此结论来自调用结构和状态持有关系,不是性能基准或全仓审计。全局与组装、主循环、共享帧存储
宿主的特点是数据驱动合约加同步管道。同一合约产出 prompt/schema/regex,runner 把步态、计时动作和模式切换做成不同执行规则;传输以鸭子类型替换。它保持模型与运动执行的进程边界,也因此不能依靠模型推理保证运动终止,必须理解固件回执并补充停止操作。其状态简单、容易逐请求跟踪,但没有持续规划、历史记忆、传感器回读闭环或计划持久化;这些不是被隐藏在某个 Agent 类中,而是在本次阅读的实现中没有建立。Contract、runner、每次模型消息
可靠性边界落在具体代码上: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,位于本文同目录的 图。
本轮只做源码与文档一致性检查,未运行模型、串口/BLE/WebSocket、固件编译或整机动作。前序报告中的纯 Python 假链路测试不等于本文两仓固定版本的硬件端到端验证;本文时序图和状态图均按代码推演。Quaddle 内部固件、手机网页演示内部机制、全部传感器插件、所有预制动作和底层库均不在本轮已验证范围。