先记三条全局规则
- 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 编程助手页。