两条命令确认机器人真的联网可用
配网向导走完、断电重启后,机器人应连上家里 2.4 GHz Wi-Fi,OLED 显示就绪状态和局域网 IP。官方在这一步给的两条验证命令是:
curl http://tiny-engineer.local/health curl -X POST "http://tiny-engineer.local/anim?name=ring"
第一条做健康探活,不驱动任何硬件,返回的 JSON 里 ok 为 true 就算通过。第二条请求敲铃动画:机器人先摆出蓄力姿态,右手快速敲下并播放一次 bell.wav,随后回到空闲姿态。只要舵机动了,就证明 Wi-Fi、HTTP 服务、PCA9685、动画引擎整条链路都通了;铃声音频在 LittleFS 分区里,Web Flash 的官方镜像自带,出现「有动作没声音」时重刷同一版本镜像即可补上。
官方给这一步的验收标准是 /health 返回 OK 且 ring 能跑。若 .local 解析慢或连不上,用官方给的两个补救办法:直接把 OLED 上显示的 IP 替换主机名(跳过 DNS 解析),或给 curl 加 -4 强制走 IPv4。固件本身同时应答 mDNS 的 A 与 AAAA 记录,个别客户端仍会卡一下,这两个办法都能绕开。注意三种地址各管一段:tiny-engineer.local 是 mDNS 名(仅 2.4 GHz 网络有效),192.168.4.1 只在 setup AP 配网阶段有效,OLED 上显示的才是机器人当前所在的局域网 IP。
health 返回里值得逐项看的字段
| 字段 | 含义 |
|---|---|
version |
固件版本字符串,编译期由 git describe 生成 |
uptime_ms |
开机至今的毫秒数 |
free_heap / heap_size
|
可用堆内存与堆总量(字节) |
cpu_temp_c |
ESP32-C3 片上温度(非环境温度),传感器不可用时为 null |
wifi.ip / wifi.rssi
|
当前 STA 的 IPv4 地址与信号强度 dBm |
wifi.hostname |
mDNS 名,默认 tiny-engineer.local
|
provisioning |
是否正处在 setup AP 配网模式 |
oled |
OLED 是否探测并初始化成功 |
version 是编译期 git describe 的产物:正式 tag 上形如 v0.1.0;开发构建形如 v0.1.0-82-g7c79b83,结尾还可能带 -dirty;取不到时为 unknown。它标的是固件构建,npm 上的 CLI 版本是另一条独立版本线,对照版本关系请看版本辨识页。另外 /health 用的是实时的 WiFi.status(),比开机时保存的标志更能反映当前网络状况。
十三种内置动画与典型事件映射
POST /anim 只收一个 name 参数,合法取值就是这 13 个动画状态。机器人不解析事件语义,哪个事件配哪个动画完全由发送方决定,下表是官方文档给出的典型用途:
| name | 类型 | 典型用途(对应助手事件) |
|---|---|---|
reading |
连续 | 助手在读文件、读上下文 |
typing |
连续 | 助手在写码、编辑、跑工具 |
thinking |
连续 | 助手在推理或等待长步骤 |
talking |
连续 | 说话姿态;也是 /play 播放语音时的默认姿态 |
ring |
单次 | 回合结束、任务完成的提示铃 |
welcome |
单次 | 会话开始打招呼;开机连上 Wi-Fi 后自动播放 |
attention |
单次+等待循环 | 需要用户输入或确认 |
error |
单次+受阻循环 | 任务失败、遇到障碍 |
abort |
单次 | 任务被取消 |
dead |
保持 | 没电/资源耗尽:播完 dead.wav 后保持 X 眼直到新的动画请求 |
wakeup |
单次 | 从睡眠唤醒,仅在睡着或入睡过程中生效 |
sleep |
单次 | 强制入睡:闭眼、OLED 熄屏 |
none |
空闲 | 清姿态、回中位;开机默认值 |
用 GET /anim 可随时查询当前动画名。ring、welcome 这类单次动画播完后查询会回到 none;dead 例外,播完保持 X 眼不自动返回。想逐个感受姿态,把上面第二条命令里的 name=ring 换成其余 12 个名字各发一遍即可。
姿态最短保持、防刷与两级超时回落
-
最短保持 1 秒:每个姿态至少跑满 1 s 才允许切换;保持期内收到的新请求只保留最新一个,其余丢弃(官方称 spam-safe,怎么刷都不会把动画引擎刷乱)。响应里的
animation可能仍是旧动画名,等保持期结束才切换成最新请求。 -
连续动画超时:
typing / reading / thinking / talking连续运行超过continuous_timeout(默认 5 分钟)后,固件自动切到attention,约 1 分钟后回到空闲;同名重发不打断动作,只刷新这个计时。 -
空闲熄屏:
none持续超过sleep_timeout(默认 10 分钟)后 OLED 熄屏;任何非空闲动画都会唤醒设备并重置计时,其他 API 调用不影响这个计时器。
两个超时都能用 POST /settings 修改,取值范围都是 1–1440 分钟。这些规则合起来意味着脚本可以放心地在每个事件上发一次请求:发多了设备自己会节流,忘了发连续动画也会自己回落,不会卡死在一个姿态里。
这一步没过的三个常见症状
- OLED 显示热点地址或
192.168.4.1:Wi-Fi 没保存成功,回配网向导(总装第二十节)重走一遍再看。 -
ring有动作没声音:重刷同一版本的官方镜像(stock 镜像含音频),仍无声音再查喇叭接线与供电。 -
.local连不上或很慢:换 OLED 上显示的 IP,或加-4强制 IPv4。
这三条之外的症状(启动红闪、舵机抖动重启、hook 装了不动)归排障页逐症状定位;验证通过后,下一页把整套 HTTP 接口和动作绑定摊开讲。