排障入口:先看板上信号,再按症状定位
这一页按「现象、原因、下一步」组织,每条给可执行命令与该回看的官方页,固件以 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 从不动机器人
按顺序过四件事:
- Node 版本:CLI 要求 Node 18 及以上,
node -v确认。 - 机器人可达:先
curl http://tiny-engineer.local/health,不通就按配网一节排网络。 - 自检与冒烟测试:
npx -y tiny-engineer doctor查配置与连接;再手动喂一个 hook 事件验证链路:echo '{"hook_event_name":"stop"}' | npx -y tiny-engineer hook cursor - 超时:冷启动的 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
回看:集成指南官方页。