烧录与首次初始化
本页承接 Arduino IDE 环境一页：板卡包、sdkconfig、依赖库与目录命名都已就绪，从这里开始改宏、烧录、走完首次初始化问答，并给出卡住时的应急手段。主线是 Bittle X V2（BiBoard V1）；老款 Bittle X（BiBoard V0）的宏与分区差异在前一页已分表，本页不再重复。
烧录前：改对主 sketch 的宏
打开 OpenCatEsp32.ino，头部先改两处宏。机型宏二选一：
#define BITTLE // Petoi 9 DOF robot dog: 1 on head + 8 on legBittle X V2 属于 9 DOF 机器狗（1 个头部关节加 8 个腿部关节），保持 BITTLE 启用；Nybble 与 Nybble Q 才改用 NYBBLE。主板宏按板选：
// #define BiBoard_V0_1
// #define BiBoard_V0_2
#define BiBoard_V1_0Bittle X V2（BiBoard V1）保持 BiBoard_V1_0；老款 Bittle X（BiBoard V0）按手头板卡选 V0_1 或 V0_2。ROBOT_ARM 只有带机械臂的 Bittle X+Arm 才启用，否则保持注释。再往下是一组模块宏，默认启用的有：
- VOICE、ULTRASONIC、PIR
- DOUBLE_TOUCH、DOUBLE_LIGHT、DOUBLE_INFRARED_DISTANCE
- GESTURE、CAMERA、QUICK_DEMO
AUTO_INIT 与 ROBOT_ARM 在默认源码里是注释掉的状态；串口以 Serial.begin(115200) 打开。不动这组宏直接烧，得到的就是带语音功能的 Standard 模式。
连接与烧录
USB 必须用数据线直连 BiBoard 主板上的 Type-C 口，不能接到电池的外部充电口——电池上的 Type-C 是充电口，不参与烧录。如果电池正在给主板供电，先长按电池按钮 3 秒以上关机，让主板只由 USB 供电、只亮蓝灯，再开始烧录。Windows 设备管理器里没有串口就装 WCH 的 CH343SER；Mac 在 /dev 下找 tty.wchusbserial 或 cu.wchusbserial；macOS Sequoia 15.1 及之后装完驱动还要在 Login Items & Extensions 的 Driver Extensions 里启用。宏改完、串口选对，点 Upload 上传 OpenCatEsp32.ino，改动会自动保存。
会不会进初始化：版本日期说了算
烧完是否进入 Initialization Startup Mode，不靠手动选择，而是由版本日期机制决定：当前上传 sketch 的版本日期新于主板固件的版本日期时，上传完成后自动进入初始化模式。查两边日期的方法：
- sketch 侧：看 OpenCatEsp32/src/OpenCat.h 里的 #define DATE "250218" // YYMMDD
- 主板侧：串口监视器发送 ? 查询主板固件版本日期
串口监视器设 115200 波特率、No line ending。烧完打开监视器看不到启动信息，短按主板上的 Reset 按钮即可。
首次初始化的三个 Y/n 问题
| 问题 | 答 Y 的含义 | 操作建议 |
|---|---|---|
| Reset the joints' calibration offsets? (Y/n) | 所有舵机修正清零 | 想保留已有关节校准数据就答 n |
| Calibrate the IMU? (Y/n) | 校准陀螺仪与加速度计 | 先把 BiBoard 平放在桌面、校准期间不要碰；想保留旧 IMU 数据答 n |
| Run factory quality assurance program? (Y/n) | 跑出厂质检程序 | 输 n 回车继续；不动它也会在 5 秒后自动跳过 |
串口输出 Ready! 即进入 regular startup mode。主板每次上电会比较 EEPROM 里的 BIRTHMARK 判断程序是否初始化过，已完成初始化就不会再进初始化模式；两种模式的开机旋律完全不同，不开监视器也能靠旋律分辨。程序若卡在连接阶段，关掉再重开串口监视器，或按主板上的 Reset 键；IMU 校准会在旋律播放 6 次后开始。
卡住时的三个应急手段
- ? ：查主板固件版本日期，先确认主板现在跑的是哪一版
- ! ：重置 EEPROM 里的 birthmark，机器人重启后重新走初始化——想清掉舵机校准参数重新校准、或重校 IMU 时用它
- BOOT：连不上、烧不进去时用。烧录被意外中断到再也烧不进，先给主板断电，按住 BOOT 不放，重新上电强制 ESP32 进入 Download mode，烧完再上电
另有一个官方 FAQ 场景：Windows 11 加 AMD CPU 的电脑烧录报 Wrong boot mode detected(0x13) 时，可改用 USB hub 连接；或点 Download/Flash 后按住 BOOT、短按 RESET 后松开，看到进度条出现再松开 BOOT。
别拿 ChangeLog 当最新版本依据
判断固件新旧有一个坑：两个仓库的 ChangeLog.md 各有 44 个日期条目，最新一条都停在 Mar6, 2023；但源码里存在 #define DATE "250218"，两个仓库 2026 年也仍在推送提交。所以 ChangeLog 已停更，不能当最新版本的依据；判断当前固件新旧，以源码里的 DATE 与串口 ? 查询为准。DATE 是 YYMMDD 格式的版本日期，官方只把它用于「上传的 sketch 与主板固件谁更新」的比较，没有把它定义成发布日期，也不反映任何发布节奏。
不用 IDE 的另一条烧录通道
Petoi Desktop App 的 Firmware Uploader 也能给 BiBoard 烧固件，底层调 esptool（NyBoard 才是 avrdude）。Board version 一项选 BiBoard_V1_0，对应 Bittle X V2。要注意 1.0 版软件不能配合 Joint Calibrator、Skill Composer 与其他 API 使用。官方还明确过：主板（硬件）版本与代码（软件）版本之间没有对应关系，不要拿软件版本号反推板卡代次。