刷机卡在整个流程的哪个位置
官方把刷机钉死在两个节点之间:接线自检通过之后、机械总装之前,原话 “Flash after connect, before assembly”。原因直接:90° 居中必须在桌面摊开、电子件未入壳的状态下完成,此时固件必须已经在 ESP32 上。刷机的完成标志与停止线要分开记:出现 setup AP 并能执行 Move all to 90° 即算完成,此时不要把 Wi-Fi 向导走完,配网留给总装结束后的装配指南 §20。
Web 刷机:默认路径
出厂固件从浏览器刷入,无需安装 PlatformIO,无需 clone 仓库,逐步照做:
- 用 Chrome 或 Edge 打开刷机入口
jamro.github.io/tiny-engineer/flash/。 - 先按页面里的 Prepare the board 引导就位:ESP32 坐在主控板上,方向对照板上 USB 丝印;USB-C 数据线插板上的接口,不插 ESP32 模块自带的 USB-C。裸模块单独刷不会开 setup AP。
- 线必须是 USB-C 数据线,纯充电线会刷机失败。
- 选一个 release(截至抓取日 2026-11-16,latest 是固件 release v0.2.0,2026-10-05 发布,选它即可),点
Connect & install。
出厂镜像同时含应用固件和 LittleFS 音频分区(WAV 文件)。网页安装器按该 release 自带的 manifest.json 自动写入偏移,不需要手动填地址。装完如果动画能动但没有声音,用网页安装器重刷同一个 release 即可补上音频。
刷完应该看到什么
以下检查都要求 ESP32 坐在主控板上(PCA9685 在位),裸模块不够:
- 上电初始化阶段板载 RGB 为暗绿,反复红闪属于故障(见下文红闪码);
- 出现
TinyEngineer-XXXXsetup 热点; - 连上该热点,打开
http://192.168.4.1/config,选 Assembly support,按 Move all to 90°,舵机转到中位。
到这一步就停,官方原话 “Stop here”:不要配家用 Wi-Fi、不要做行程校准,向导留给总装后的装配指南 §20,电子件继续留在桌面。
四个镜像与分区偏移(当前 main)
每个 release 发布四个 bin,外加一个供网页安装器读取的 manifest.json(ESP Web Tools 格式,chipFamily 为 ESP32-C3)。文件名里的版本号段就是该 release 的 tag:latest 为 v0.2.0,下表即以它为例,刷其他 tag 时把这一段换成对应版本号。截至抓取日 2026-11-16,当前 main 的偏移如下,四个文件在干净的首次刷机里缺一不可:
| 镜像文件 | 烧录偏移 | 分区 |
|---|---|---|
| tiny-engineer-v0.2.0-bootloader.bin | 0x0 | bootloader |
| tiny-engineer-v0.2.0-partitions.bin | 0x8000 | 分区表 |
| tiny-engineer-v0.2.0-firmware.bin | 0x10000 | app0 应用固件 |
| tiny-engineer-v0.2.0-littlefs.bin | 0x220000 | spiffs(WAV 音频) |
只有 bootloader 和分区表已经在芯片上时,才允许只刷应用固件加 LittleFS 两件。按当前 partitions.csv:app0 长 0x210000;spiffs 长 0x1D0000,约 1.81 MB,给音频 mod 换更长的 WAV 留了空间;NVS 固定在 0x9000,保存的设置不因刷机丢失;coredump 在 0x3F0000。
版本坑:旧 tag 不能复用当前偏移
官方明写 “Do not reuse current-main offsets for an old tag”:每个 tag 的分区布局由它自己的 partitions.csv 定义。典型例子是 v0.1.0,双 OTA 布局,它的 LittleFS 不在当前 main 的 0x220000,而在 0x2B0000(2818048):
| 对比项 | 当前 main | v0.1.0(双 OTA 布局) |
|---|---|---|
| bootloader | 0x0 | 0x0 |
| 分区表 | 0x8000 | 0x8000 |
| 应用固件 | 0x10000(app0) | 以该 tag 的 partitions.csv 为准 |
| littlefs / spiffs | 0x220000 | 0x2B0000(2818048) |
两个相关事实一并记下:按旧 0x270000 偏移刷的镜像挂载不上;网页刷机时偏移由 release 的 manifest.json 自动带,需要人工核对的场景是给历史 release 补 manifest(官方叫 backfill),此时必须从那个 tag 的 partitions.csv 取偏移,bootloader 0x0、分区表 0x8000 两个位置固定不变。
启动红闪码:先数灯
致命初始化失败会停住系统并让板载 WS2812 红闪。闪烁节奏固定:每次 300 ms 亮、300 ms 灭,两轮之间隔 3 秒,从一轮的开头数即可。红闪含义只有两种:
| 长间隔前的闪烁次数 | 含义 |
|---|---|
| 1 闪 | PCA9685 没在 I2C 总线 0x40 上找到——ESP32 没坐上主控板,或接线、地址问题 |
| 2 闪 | MAX98357A / I2S 初始化失败 |
停机前固件一定会在串口打印 HALT: … 和 LED blinks: N(115200 波特,serial_log 关着也打印),没条件接串口时红闪码本身就是判断依据。初始化阶段反复红闪说明系统停住了,暗绿才是正常。
两种看着像失败、其实正常的现象
- 裸 C3-Zero 单独刷:安装器能成功写完,但固件随后找不到 PCA9685 而停机(1 闪、约 3 秒间隔),并且不会出现 TinyEngineer-XXXX 热点。把模块插回主控板即恢复正常,这不算刷机失败。
- 首次启动串口打印 Preferences NOT_FOUND:NVS 还是空的,属正常现象。
顺带记住软硬失败的边界:OLED 找不到、Wi-Fi 连不上都只是软失败,启动流程继续走;PCA9685 与 I2S 失败才会真正停机。
进阶 PlatformIO 路线(可选)
只有从源码构建、刷音频 mod、走 OTA 或需要串口监视器时才用这条路线,刷出厂固件完全不需要它。固件是 Arduino on PlatformIO(pioarduino 平台,Arduino-ESP32 3.x)。两个易混点先钉住:
-
platformio.ini里的esp32-c3-devkitm-1只是构建目标名,物理模块始终是 Waveshare ESP32-C3-Zero,不存在另一块板。 - 构建场景需要 Node.js 20.19+(20.x 系列)或 22.12+:pio run 会用 npm 构建 ui/ 目录的网页界面并嵌进固件。这个要求与 npm 命令行工具自身的 Node 18+ 属于两个场景,别混着记。
从仓库根目录执行:
pio run # 构建
pio run -t upload # 刷固件 + LittleFS
pio device monitor # 串口监视(115200)
上传前后有官方脚本兜底,异常时只告警并继续,不会卡死流程:
| 脚本 | 时机 | 作用 |
|---|---|---|
| park_servos_before_upload.py | 上传前 | 先执行 tiny-engineer park --transport serial,让关节停在中位并保持 PWM,减少上电瞬间甩进打印件;板子没开、串口占用或未装 CLI 时告警后继续。要绝对保险,先拔掉舵机的 5 V / V+。 |
| upload_fs_after_upload.py | 固件上传后 | 自动补传 LittleFS,让 welcome、bell 等 WAV 落板;动画有动作没声音时手动跑一次 pio run -t uploadfs。 |
| resume_daemon_after_upload.py | LittleFS 上传后 | 执行 tiny-engineer daemon start,恢复串口事件响应;CLI 缺失或启动失败时自己手动跑一次。 |
音频 mod:把 platformio.ini 的 custom_audio_mod 设成某个 mod 目录名(示例 halloween),即可用该 mod 的 WAV 覆盖同名出厂文件,mod 没带的保持出厂;welcome、attention、error、abort、dead 的替换需要同级 .cue 文件标记短语时间点,bell 不需要。多个串口时用 pio device list 认板,硬件 ID 看 Espressif 的 VID:PID=303A:1001(ESP32-C3 原生 USB)或所用 USB 串口桥,列表里的蓝牙串口不算。
OTA 是另一个可选环境:拿 coredump 分区换第二固件槽,LittleFS 从约 1.81 MB 缩到 960 KB。切换布局必须先用 USB 刷一次 pio run -e ota -t upload;之后 pio run -e ota -t ota 更新固件、-t otafs 更新音频。OTA 监听 UDP/TCP 3232 端口,且只在家用 Wi-Fi 下运行,setup AP 模式不行;新固件写进非活动槽并只启动一次,连上 Wi-Fi、起 OTA 监听后才转正,没走到那步的下次复位回滚。分区布局的变更不能通过 OTA 下发,必须回到 USB 重刷。环境变量 TINY_ENGINEER_URL 指向机器人地址,设了 access_token 时 TINY_ENGINEER_TOKEN 同时作为 OTA 密码。
PlatformIO 路线的完成标志
与 Web 路线一致,都在主控板上检查:串口看到 TINY ENGINEER、PCA9685 found 等正常启动行,NVS 空相关提示不算失败;板载 RGB 初始化为暗绿;Move all to 90° 或 POST /test/servo 能让舵机动。走完同样停向导,回装配页继续。