八步链与硬顺序
官方快速上手文档(Getting started)把整条链路定为八步:Shop → print → connect → flash → assemble(一次跑完)→ setup wizard → prove → agent hooks。每一步打开对应的官方页,做完达到退出条件再回来走下一步。顺序是硬性的,不可颠倒:
- 先在桌面上把电子件接好、通电前自检,再刷机。
- 刷机后先用 setup 热点把舵机居中到 90 度,然后才总装入壳。
- 配网向导只在总装完成后走(assembly.md 第二十节)。官方在刷机页写明「Stop here. Do not complete the setup wizard」——刷完机不要连家里 Wi-Fi。
动手前的三条安全线
- 电源用 5 V / ≥2 A 的 USB 电源加 USB-C 数据线:1 A 充电头会带不动舵机导致欠压重启,纯充电线刷机必败。
- 喇叭只接 SPK+ 和 SPK− 两个焊点,SPK− 不是地;连接器与焊盘二选一,不可同时接。
- ESP32-C3-Zero 的陶瓷天线前方避开金属件和密集的塑料、线束。
第 1 步:Shop,备齐购物车
做什么:打开官方 Shop 页或 shopping 文档,按默认购物车采购——主控板 ×1、Waveshare ESP32-C3-Zero ×1(需焊两条 1×9 排针,或买预焊好的 -M 版)、Tower Pro SG90 舵机 ×5、Adafruit Mini Oval Speaker 8Ω 1W ×1、Waveshare 0.91 寸 OLED(SSD1306 128×32 I2C)×1,加 M2 螺丝螺母、约 7–12 cm 的公母跳线、5 V/≥2 A 电源与 USB-C 数据线,以及打印途径(自己打印或找代打)。主控板是开源 PCB,从任意板厂下单,Shop 页可下载 Gerber、BOM 与贴片坐标文件,不需要装 KiCad。
做完的标志:购物车在手——电子件、紧固件、电源线材齐备,打印途径已定。
卡住:舵机四种预设与两条硬件路线的取舍,翻「采购清单」页。
第 2 步:Print,打出结构件
做什么:按你买的舵机型号选对应打印件目录(默认 SG90 对应 parts/sg90/),先打测试件验证孔位配合,再打整机全套;材料用 PLA 或 PETG;没有打印机走官方的代打路径。
做完的标志:与你的舵机型号匹配的一整套打印件就绪。
卡住:目录怎么选、测试件先打哪个,翻「打印件与测试件」页。
第 3 步:Connect,桌面接线与通电前自检
做什么:ESP32、舵机、OLED、喇叭全部插在主控板上,按官方主控板文档逐项自检:喇叭只接一种方式且在 SPK+/SPK− 上、舵机插头方向与丝印一致、ESP32 方向与 PCB 上的 USB 丝印对齐。此时电子件全部留在桌面,先不入壳。
做完的标志:通电前自检全过,板子可以上电。
卡住:两条电压域、接线细节与分模块路线,翻「接线与上电前检查」页。
第 4 步:Flash,浏览器刷机(此时不配网)
做什么:ESP32 坐在主控板上,USB-C 数据线插在主控板的 USB-C 口(不是 ESP32 模块上的口);用 Chrome 或 Edge 打开官方 Web flash 页,按页面提示准备好板子,选 latest release(本 wiki 抓取时为固件 v0.2.0),点 Connect & install。整包镜像含固件与音频文件,无需装 PlatformIO、无需克隆仓库。
做完的标志:板载 RGB 初始化时为暗绿色(不是反复红闪);出现 TinyEngineer-XXXX 开头的 setup 热点;手机或电脑连上它后打开 http://192.168.4.1/config,选 Assembly support,按 Move all to 90°,舵机转动。
此时不要往下走 Wi-Fi 向导。官方原话「Stop here. Do not complete the setup wizard」——配网留到总装后的第二十节,电子件继续留在桌面。
卡住:红闪含义、裸模块刷机后的正常表现、分区与版本细节,翻「浏览器 Web 刷机」页。
第 5 步:Assemble,居中加总装
做什么:按 assembly.md 第一节到第十九节总装:头帽、居中、接合、走线槽、手臂、灯。居中在桌面阶段做:连 setup 热点,用 Assembly support 的 Move all to 90°(可用 Identify 逐关节抖动确认),每居中完一个舵机就拔掉该舵机线,再继续下一个。M2 螺丝直接攻入塑料,不用胶水,也不用热熔铜螺母。
做完的标志:全部机械接合完成,舵机与 OLED 排线按指南插好。
卡住:居中节奏与逐节装配要点,翻「90 度居中与总装」页。
第 6 步:Setup wizard,配网
做什么:走 assembly.md 第二十节的配网向导:选家里 Wi-Fi、保存、断电重启。机器人要上 2.4 GHz 频段的网络。
做完的标志:机器人连上家用 Wi-Fi,OLED 上显示局域网 IP。
卡住:向导细节与 mDNS 名、热点地址、屏幕 IP 三种地址的区别,翻「配网向导与首次联网」页。
第 7 步:Prove,验证
做什么:跑两条命令确认机器人在线、可动:
curl http://tiny-engineer.local/health curl -X POST "http://tiny-engineer.local/anim?name=ring"
做完的标志:/health 返回正常,ring 动画执行——舵机动;铃响需要音频分区在位(Web 刷机的整包镜像默认已含)。.local 域名慢或连不上,改用 OLED 上显示的 IP,或给 curl 加 -4 参数强制走 IPv4。
卡住:十三种内置动画与超时行为,翻「验证与第一个动作」页。
第 8 步:Agent hooks,接入 AI 编程助手(可选)
做什么:跑 npx -y tiny-engineer setup 装默认 hook,或用 REST 接口给其他工具做自定义映射。这一步是可选的——不做它,机器人也能手动触发动画。
做完的标志:助手的一个事件触发了一次动画,比如回合结束敲铃。
卡住:哪家 IDE 能一键装、配置落在哪、超时怎么给,翻「接入 AI 编程助手」页。
Stuck 速查表
官方 Getting started 的 Stuck 表逐症状给出去处,对应到本 wiki 的页:
| 症状 | 翻哪页 |
|---|---|
| 不知道买什么 | 采购清单 |
| 不知道打什么 | 打印件与测试件 |
| 板子怎么插 | 接线与上电前检查 |
| 刷机或安装卡住 | 浏览器 Web 刷机 |
| 打印件怎么装 | 90 度居中与总装 |
| .local 慢或失败 | 配网向导与首次联网(用 OLED IP 或 curl -4) |
| OLED 显示 192.168.4.1(Wi-Fi 没存上) | 配网向导与首次联网(回第二十节重走向导) |
| 有动作没声音 | 浏览器 Web 刷机(重刷同一 release 补音频) |
| hook 不动机器人 | 接入 AI 编程助手(Node 18+、doctor、超时 ≥30) |
| 舵机抖动、动起来就复位 | 故障排查(供电预算) |
| 其他启动、I2C、音频故障 | 故障排查 |