项目>Tiny Engineer>HTTP 接口与动作绑定:二十个端点、动作表和自定义事件

HTTP 接口与动作绑定:二十个端点、动作表和自定义事件

摘要:按目的在二十个端点里找到该用的那一个,配置设备端事件到效果的绑定表、令牌认证、波形播放和 WebSocket 订阅,并知道官方建议的短超时忽略网络错误写法。

先记三条全局规则

  • JSON HTTP 服务跑在 ESP32-C3 的 80 端口:STA 连上 Wi-Fi 后基址是板子 IP(OLED/串口显示)或 http://tiny-engineer.local(mDNS,仅 2.4 GHz);setup AP 阶段是 http://192.168.4.1/。
  • 带参数的路由(POST /anim 和 /play 除外)要求发 JSON 对象 body 并带 Content-Type: application/json,用 query 参数或表单字段会返回 400。
  • 机器人还没选过连接模式(未配网)时,控制类接口返回 503 not provisioned;设置与装配支持类路由在 setup AP 下照常可用。

二十个端点按目的分组

固件的 JSON API 共二十个端点,另有 GET / 返回一张 HTML 端点索引页,列出全部路由和参数,始终公开、无硬件副作用。按目的分组如下:

目的 端点 作用
索引 GET / HTML 端点索引页(始终公开,浏览器可直接打开)
健康 GET /auth、GET /health 查是否需要 Bearer(始终公开);健康探活(实时 Wi-Fi 状态)
动画 GET /anim、POST /anim 读当前动画名;请求切换动画(?name=…)
播放 POST /play、POST /play/{name} 流式播放 WAV 并搭配说话/思考姿态
设置 GET /settings、POST /settings、PUT /settings/wifi、GET/PUT /settings/actions、POST /settings/reset 读写 NVS 设置;替换 Wi-Fi 网络列表;读写设备端动作绑定表;恢复出厂
动作测试 POST /actions/test 模拟一个事件类型,跑匹配的 Actions 而不发布 WebSocket/串口事件
测试 POST /servos/park、POST /test/servo、POST /test/audio、POST /test/audio/bell、POST /test/screen、POST /test/movement、POST /test/led 停动画归中并保持;单舵机移动;音频、铃声、屏幕、全舵机、RGB 灯硬件自检
装配支持 POST /setup/servo、POST /setup/led、POST /setup/oled、POST /setup/audio 仅 setup AP 模式可用:0–180° 全电行程居中、LED 颜色映射预览、OLED 翻转预览、播放 welcome 音频

测试类路由全是 POST,且处理器会阻塞到测试完成,客户端要等它返回。整机总装后 POST /test/servo 被钳制在保存的最小/最大角度内;未总装想跑 0–180° 全行程,用 setup AP 的 /setup/servo。

设备端动作绑定表:Actions

机器人自己也能做「事件→效果」的本地联动:设备发出的出站事件按这张表直接触发声音或动画,不经过电脑脚本。GET /settings/actions 读表,PUT /settings/actions 整表替换,规则如下:

  • 表为 0–16 行,空表即清空;超行数或含非法行返回 400 且旧表保留。
  • 每行 on 是 1–47 字符的事件名,支持 * 通配(匹配事件类型里的任意序列);do 只能是 sound 或 anim,并带对应参数 sound(bell/click)或 anim(动画名)。
  • 一次出站事件发布时,所有匹配行按列表顺序执行;写入立即生效。
curl -X PUT "http://tiny-engineer.local/settings/actions" \
  -H "Content-Type: application/json" \
  -d '{"actions":[{"on":"button.click","do":"sound","sound":"bell"}]}'

默认固件不发出站事件,表由按钮扩展或 mod 触发。配好后用 POST /actions/test 传 {"type":"button.click"} 模拟事件验证,不用真去按按钮。

认证:access_token 与 Bearer

  • 用 POST /settings 设 access_token:0–64 个可打印 ASCII 字符,两端不能有空格;空字符串即关闭认证(默认关闭)。
  • 设了 token 后所有 JSON API 路由要求请求头 Authorization: Bearer …,缺失或错误返回 401;HTML 面板路由保持公开,由页面提示输入。
  • GET /auth 始终公开且不泄露 token,先查它确认是否需要带认证。
  • 设置或轮换非空 token 会断开当前 WebSocket 订阅者(需带新 token 重连),清空 token 不会断开。

播放:/play 的 WAV 硬要求

POST /play 边收边播,任意长度的片段都不占机器人存储,响应在播完后返回。格式不符会在任何声音播出之前报错:

项 要求
音频格式 WAV,16-bit mono PCM,采样率 22050 Hz(固件 SAMPLE_RATE)
请求头 Content-Type: audio/wav;必须有 Content-Length
姿态 /play 默认 talking;/play/{name} 可指定 talking/typing/reading/thinking/none,带自己音效的动画会被拒绝,避免两段音频重叠
播完行为 回到请求前正在跑的连续动画,否则回 none
典型错误 415 expected 16-bit mono PCM at 22050 Hz;415 not a WAV file / no audio data;400 非法 name
curl -X POST http://tiny-engineer.local/play -H 'Content-Type: audio/wav' --data-binary @clip.wav

姿态为 talking 时,固件从 PCM 流提取语音能量驱动点头、抬手等反应动作;其他姿态只播音不动。固件的 WebServer 是单线程,/play 播放期间其他请求会排队等待。

订阅出站事件:WebSocket 与串口

设备向电脑方向发事件走独立通道:WebSocket ws://<host>:81/events(与 HTTP 服务同起同停),同样的 JSON 也会以 Evt 帧走 USB 串口。要点:

  • 最多 4 个客户端;81 端口无 TLS,只能配 http: 基址用 ws:// 连。
  • 设备设了 token 时,连接串接 ?token=…(与 Bearer 同一个密钥);轮换 token 会踢掉已连订阅者,需要带新 token 重连。
  • 默认固件不发事件,通道保持可用,供按钮扩展或 mod 发布;REST 只有入站方向,WebSocket 客户端发上去的内容会被忽略。
websocat "ws://tiny-engineer.local:81/events"

脚本侧写法:短超时并忽略网络错误

官方对集成方的要求很明确:每个请求设短超时(约 2 秒),失败就吞掉网络错误继续干活,机器人离线或响应慢时不能拖住 agent 的正常流程。三种语言的官方示例:

curl -4 -sS -m 2 -X POST "http://tiny-engineer.local/anim?name=reading" >/dev/null || true
await fetch("http://tiny-engineer.local/anim?name=thinking", {
  method: "POST",
  signal: AbortSignal.timeout(2000),
}).catch(() => {});
import urllib.request
urllib.request.urlopen(
    urllib.request.Request(
        "http://tiny-engineer.local/anim?name=typing",
        method="POST",
    ),
    timeout=2,
)

给 IDE hook、插件或 CI 写触发器时照这个模板来。事件到动画的映射完全自己定,机器人只关心 name 参数,具体怎么接各家工具见接入 AI 编程助手页。

资料来源

  • 接口文档官方页
  • 集成指南官方页
  • 设置说明官方页
  • 命令行工具说明