项目>Tiny Engineer>故障排查:刷机、配网、舵机、供电与助手 hook 逐症状定位

故障排查:刷机、配网、舵机、供电与助手 hook 逐症状定位

摘要:按症状定位刷机红闪、配网失败或屏幕显示热点地址、舵机抖动重启、有动作没声音、hook 不动和 mDNS 连不上,每条都有可执行的下一步和该回看的官方页。

排障入口:先看板上信号,再按症状定位

这一页按「现象、原因、下一步」组织,每条给可执行命令与该回看的官方页,固件以 v0.2.0、CLI 以 0.4.1(2026-11-16 抓取时点的 latest)为准。上电后排障先看两个板上信号:板载 RGB 初始化成功为暗绿色,致命失败为红色闪烁,数长间隔前的闪烁次数;再看 OLED 文案。两者都定位不了再接串口读日志(115200),致命挂起时固件一定会在串口打印 HALT: … 和 LED blinks: N,即使串口日志开关关闭也会打印,没线缆时红闪码就是唯一信号。

官方 Stuck? 速查表

官方快速上手页的 Stuck? 表把常见卡点映射到对应文档,先给全表索引,后面各节展开技术性最强的几类:

症状 下一步 回看的官方页
板子不支持的额外模块 采购前查购物页的额外模块小节;接线按接线规则;装配阶段再装模块 采购官方页、接线官方页
不知道买什么 按官方默认购物车核对:主控板、ESP32-C3-Zero、5 只同型号舵机、0.91 英寸 OLED、8Ω/1W 喇叭、M2 紧固件、5V/2A 电源、USB-C 数据线 采购官方页
板子怎么插 通电前检查:喇叭只接 SPK+ / SPK− 一种方式;舵机插头对丝印;ESP32 方向对齐 PCB USB 丝印 主控板说明官方页
打印什么 按舵机型号选打印件目录,先打测试件再打整机 三维打印件说明官方页
打印件怎么装 装配指南 §1–§19;居中在总装前,每居中一步拔一根舵机线 装配指南官方页
刷机或安装卡住 回浏览器 Web Flash 重装,细节看下一节 刷机指南官方页
.local 慢或解析失败 用 OLED 上显示的 IP,或 curl -4 强制 IPv4 快速上手官方页
OLED 显示 join AP 或 192.168.4.1 Wi-Fi 未保存或 STA 连接失败,回装配指南 §20 完成配网向导 装配指南官方页
welcome / ring 无声(舵机会动) 从 Web Flash 重装同一版本镜像(自带音频);PlatformIO 用户补 pio run -t uploadfs 刷机指南官方页
hooks 从不动机器人 Node 18 及以上;npx -y tiny-engineer doctor;hook 超时给到 30 秒以上 集成指南官方页
舵机抖动或动作时板子重启 供电预算问题,换 5V/2A 以上电源 供电官方页
其他启动 / I2C / 音频失败 按硬件测试页的 Failures 表逐行对照 硬件测试官方页

启动红闪码:数闪烁次数定位初始化失败

致命的初始化失败会挂起启动并让板载 WS2812 红闪:每闪 300 毫秒亮、300 毫秒灭,重复之间隔 3 秒,从周期起点数长间隔前的闪烁次数。

闪烁次数 含义 常见原因 下一步
1 闪 PCA9685 未在 I2C 地址 0x40 上找到 ESP32 没坐在主控板上,或接线、地址问题 断电后把 ESP32-C3-Zero 对准丝印坐回主控板;散接路线检查 PCA9685 的 VCC 接 3V3、共地、SDA/SCL 与地址焊桥;串口确认 Checking PCA9685 at 0x40... 是否成功
2 闪 MAX98357A / I2S 初始化失败 I2S 引脚接线问题 检查 GPIO2/3/4 是否短到 5V 或 GND,三根线对应 BCLK/LRC/DIN;串口读 ERROR: I2S initialization failed 所在行

两种情况看着像刷机失败,其实都正常:裸 C3-Zero 不上主控板单独刷能刷成功,随后固件因找不到 PCA9685 挂起(1 闪、约 3 秒间隔)且不会出现热点,插回主控板即恢复;首次启动串口可能打印 Preferences NOT_FOUND(NVS 为空),走完启动即正常。OLED 缺失与 Wi-Fi 连不上是软失败,固件会继续跑;PCA9685 与 I2S 失败才会挂死。串口监视(advanced 场景)用 pio device monitor(115200)。回看:硬件测试官方页。

刷机卡住:数据线、端口与分区版本坑

Web Flash 按顺序排查:浏览器用 Chrome 或 Edge;线用 USB-C 数据线,纯充电线必失败;数据线插主控板 USB-C,不插 ESP32 模块上的口;ESP32 先坐在主控板排针上再刷。装完的完成标志:板载 RGB 初始化为暗绿色、出现 TinyEngineer-XXXX 热点,连上后在 http://192.168.4.1/config 选 Assembly support、按 Move all to 90° 舵机会动。此时官方原话是 Stop here:不要完成 Wi-Fi 向导,等总装完到装配指南 §20 再配网。

手动刷 bin 或 PlatformIO 构建时盯住分区。当前 main 的四个镜像与偏移如下,首次刷机四个缺一不可;app 加 LittleFS 只有在 bootloader 和分区表已经在片上时才够用:

镜像 偏移
bootloader 0x0
partitions 0x8000
firmware(app0) 0x10000
littlefs(spiffs) 0x220000

版本坑:v0.1.0 是双 OTA 布局,它的 LittleFS 在 0x2B0000,与当前 main 的 0x220000 不同,官方明写不要把当前 main 的偏移复用到旧 tag;按旧 0x270000 偏移刷的镜像挂载不上。NVS 固定在 0x9000,重刷 LittleFS 不动已保存设置。PlatformIO 构建场景另需 Node.js 20.19+(20.x)或 22.12+,与 CLI 运行要求的 Node 18+ 是两个不同场景,别互相套。回看:刷机指南官方页。

OLED 显示热点地址、配网失败与 .local 连不上

OLED 显示「Join this WiFi」、热点名或 192.168.4.1,说明 Wi-Fi 没保存或 STA 连接失败,机器人处于 setup AP 模式:连上屏幕显示的热点,打开 http://192.168.4.1/config,重新走配网向导;OLED 显示 WiFi failed 同理。三种地址不要混用:

地址 是什么 什么时候用
tiny-engineer.local mDNS 主机名,仅 2.4 GHz Wi-Fi 下可用 日常访问
192.168.4.1 setup AP 模式下机器人自己的 HTTP 地址 配网向导与装配支持阶段
OLED 显示的 IP 接入家庭 Wi-Fi 后分到的局域网 IP mDNS 解析不了时的兜底

.local 慢或解析失败,用 OLED 上的 IP 直接访问,或强制 IPv4:

curl -4 http://tiny-engineer.local/health
curl -4 -X POST "http://tiny-engineer.local/anim?name=ring"

探活通了就继续下一步;路由器不回 mDNS 就长期用 IP。回看:装配指南官方页 §20、快速上手官方页。

舵机抖动、动作时重启:供电预算

舵机抖动或动作无力、OLED 闪烁或黑一下、有音频噪底或断续、I2C 报错(动作一起 PCA9685 或 OLED 就「找不到」)、多个舵机同时启动瞬间板子复位,都是供电不足的典型表现。要求 5V、2A 及以上的电源;1A 充电头会欠压重启。主控板上舵机与功放挂在 eFuse(约 2A 限流)后面,多舵机堵转会先触发限流、随后自动恢复,属设计内行为,加大电源余量即可。验证命令有硬件副作用,动作会真的动:

curl -X POST http://tiny-engineer.local/test/movement
curl -X POST http://tiny-engineer.local/test/servo -H "Content-Type: application/json" -d '{"index":0,"angle":90}'

/test/movement 让五个舵机一起动,是供电压力最大的时刻;串口恰好在这条命令运行时断开,按欠压处理,别当成 PWM 或固件 bug。SG90 堵转电流比 HD-1370A 更大,别拿 HD-1370A 的电流表当 SG90 的预算。回看:供电官方页。

有动作没声音

welcome 或 ring 时舵机动、喇叭不响:stock 镜像自带 WAV 音频,最可能是 LittleFS 没刷上。Web Flash 用户从网页重装同一版本镜像即可;PlatformIO 用户补一次文件系统上传:

pio run -t uploadfs

仍无声再查硬件:喇叭只接 SPK+ 与 SPK−(BTL 输出,SPK− 不是地),连接器或焊盘二选一、不可同时接;MAX98357A 的 Vin 走 5V。单独验证音频链路:

curl -X POST http://tiny-engineer.local/test/audio
curl -X POST http://tiny-engineer.local/test/audio/bell

回看:刷机指南官方页、硬件测试官方页。

助手 hook 从不动机器人

按顺序过四件事:

  1. Node 版本:CLI 要求 Node 18 及以上,node -v 确认。
  2. 机器人可达:先 curl http://tiny-engineer.local/health,不通就按配网一节排网络。
  3. 自检与冒烟测试:npx -y tiny-engineer doctor 查配置与连接;再手动喂一个 hook 事件验证链路:echo '{"hook_event_name":"stop"}' | npx -y tiny-engineer hook cursor
  4. 超时:冷启动的 npx 很慢,setup 写入的 hook 超时要给到 30 秒以上,否则 IDE 等不及就杀掉进程,表现就是 hook 从不触发。

配置查找:连接偏好在用户级 ~/.config/tiny-engineer/env(Windows 为 %APPDATA%\tiny-engineer\env),setup 从不写项目 .env,别翻项目目录找。写自己的脚本时,官方建议短超时加忽略网络错误,机器人离线也不拖住 agent:

curl -4 -sS -m 2 -X POST "http://tiny-engineer.local/anim?name=reading" >/dev/null || true

回看:集成指南官方页。

资料来源

  • 快速上手官方页
  • 刷机指南官方页
  • 供电官方页
  • 硬件测试官方页
  • 集成指南官方页