项目>Tiny Engineer>验证与第一个动作:health 探活、敲铃动画和十三种姿态

验证与第一个动作:health 探活、敲铃动画和十三种姿态

摘要:用健康检查和一条敲铃请求确认机器人真的联网可用,认清十三种内置动画状态各自对应什么助手事件,知道姿态最短保持时间和连续超时回落。

两条命令确认机器人真的联网可用

配网向导走完、断电重启后,机器人应连上家里 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 接口和动作绑定摊开讲。

资料来源

  • 接口文档官方页
  • 快速上手官方页
  • 集成指南官方页
  • 设置说明官方页