按症状排查
先对症状、再动手。本页以 Bittle X V2（BiBoard V1）为主线；涉及老款 Bittle X（BiBoard V0）或与代次相关的差异，逐条单独标注适用版本。
症状一：烧录失败
设备列表里看不到串口。适用：BiBoard V1 用 USB 线直连。按顺序查：
- 线：必须用 USB Type-C 数据线——有些 USB 线只有电源线没有数据线，优先用套件原配线，直连电脑不要经过 hub。
- Windows：设备管理器没有串口时，装 WCH 的
CH343SER驱动。 - Mac：终端进
/dev目录执行ls，找tty.wchusbserial或cu.wchusbserial开头的设备名。 - macOS Sequoia 15.1 及之后：装完驱动还要去 Settings → General → Login Items & Extensions → Driver Extensions 手动启用，否则驱动不生效。
- 还不行：关掉电池电源再看串口是否出现；分不清哪个口属于机器人时，拔插电脑端 USB 看列表增减。
报 Wrong boot mode detected(0x13)。适用：Windows 11 + AMD CPU 的电脑较常见。两招任选：换一个 USB hub 连接；或点 Download/Flash 后按住 BOOT、短按 RESET 松开，看到进度条开始滚动再松开 BOOT。
烧录被中途打断，之后再也烧不进去。适用：BiBoard V1。下一步：断电 → 按住 BOOT → 重新上电，强制 ESP32 进入 Download mode，烧完再正常上电。
症状二：编译报找不到 OpenCat.h
报错形如 OpenCat:82:10: fatal error: src/OpenCat.h: No such file or directory。适用：Arduino IDE 编译 OpenCatEsp32 源码。原因与解法只有一个：源码必须整包下载，且根目录名必须与 .ino 同名——ZIP 解压得到 OpenCatEsp32-main，必须重命名为 OpenCatEsp32 后再打开 OpenCatEsp32.ino。
症状三：供电异常
电池灯红 / 重复旋律 / 动作暂停并 beep。适用：两代 Bittle X 通用（电池均为 ZCF503060、1000mAh / 7.4Wh）。下一步：
- 短按电池按钮看灯色：蓝 = 有电，红 = 低电；耗尽过程由蓝渐红。
- 低电先充电：用 5V-1A USB 充电器，不建议快充；充电中红灯、充满绿灯。电池装在机身上时因插座空间限制无法直接充电，必须拆下来充。
- 充电时电池自动停止对外供电是正常行为——「边充边玩」不可行；Type-C 只充电、2P 2.54mm 红黑线端子才是给主板供电的口，两个口不能混。
- 供电端子不得短路；主板端子带防反插设计，但极性接反仍有损坏主板的风险。
死机 / 无响应。适用：所有机型。两步：先看电池电量，低电就充电；电量正常则拆开背盖，按主板 LED logo 旁的 reset 按钮重启。
症状四：校准走偏
校准完一退出校准态，腿又歪回去。适用：两代通用。原因：offset 没保存。下一步：校准态里发 s 保存，可以每调完一个舵机就存一次。
校准界面连不上机器人。适用：BiBoard。原因：USB 线插到了电池充电口。下一步：USB 必须直连 BiBoard 主板，不能接电池充电口；没有线也可走蓝牙。
腿装反 / 装错关节。适用：组装版套件。下一步：主控资源有限、程序分两段——第二段上传标准功能代码后，首次配置要进 joint calibration 状态并按正确方向装腿；进校准态之前不要先装头和腿，断电时舵机输出轴角度随机，先装腿会互相碰撞，长时间堵转可能损坏舵机。
症状五：语音无反应
先看代次：Bittle X V2（BiBoard V1）语音模块内置；老款 Bittle X（BiBoard V0）是外接语音扩展帽方案，要先拨扩展帽上的开关。下一步：老款查扩展帽开关是否拨对；语言被误切换不用慌——重启后自动恢复默认语言（English）。
症状六：走路不稳
| 具体表现 | 下一步 |
|---|---|
| 走得很慢 | 手机 App 里关 Gyro |
| 四脚朝天翻不回来 | 手机 App 里开 Gyro |
| 整体走不稳 | 用 L 形调角器重新校准关节；关 Gyro 让慢步态更稳；必要时 Desktop App → Tools → calibrate gyroscope 重置陀螺仪 |
| 校准后仍不对称 | 发 d、kup、kwkF 在 rest / stand / walk 之间反复验证，可能需要多轮校准；对称后装中心螺丝固定——前提是 offset 已用 s 保存 |
| 预组装版也走不稳 | 官方明说预组装版仍可能需要微调关节 |
其他已知问题
- 「play dead」反复循环：旧固件的已知 bug，升级到最新固件。
- 舵机完全不工作：官方排查顺序——重烧固件 → 校准 PWM 信号 → 交换引脚定义。
- macOS 14.1 (Sonoma) 上 Desktop App 按钮无响应：Python Tk 库与 macOS 的兼容问题，临时办法是按住按钮同时轻微拖动鼠标。