检测 · 识别 · Demo 运行 API

给调用方（平台、脚本、别人写的程序）的一份独立文档：从"看一眼画面"到"让小车自己追过去 把东西夹起来"这一整条链的 HTTP 接口。全部在板上实测过，坐标单位一律是原图像素。

想一次看全部接口（电机/机械臂/OTA/WiFi/系统）见 API 文档；这篇只讲 摄像头 → 推理 → 跑动作这条链，覆盖 /api/camera/*、/api/detect、/api/models/* 与 /api/demo/*。

一分钟上手

IP=<板子IP>

# ① 开摄像头（检测的前提；不开会回 "camera not available"）
curl -X POST http://$IP/api/camera/open

# ② 看一眼识别结果（框的四个角，原图像素）
curl "http://$IP/api/detect?model=tennis"
# → {"ok":true,"count":1,"boxes":[{"x1":2,"x2":172,"y1":0,"y2":360}]}

# ③ 跑一次 demo：用 tennis 模型做"接近瞄准"，框宽到 320px 就算到位
curl -X POST http://$IP/api/demo/init -H 'Content-Type: application/json' \
     -d '{"action":"approach","model":"tennis","target_size":320,"speed":30,"turn_speed":25}'
# → {"completed":true}          ← 默认等它跑完再返回（下面的"wait"一节）

③ 里没有建任何卡片：action + model + 参数凑齐就是一次完整请求。车会真的动。

1. 摄像头（检测的前提）

snapshot 的响应（实测 640x360 q70 约 46KB JSON）：

{"image":"/9j/4AAhQVZ...", "format":"jpeg", "width":640, "height":360, "m":0.05, "c":-2.82}

m / c 是像素→实际距离的标定系数（config.toml 的 [camera] calib_m/calib_c）， 用来自算"这个框离我多远"。不需要就算着玩，detect 不用它们。

分辨率/帧率/画质都在 config.toml 的 [camera]（width/height/fps/jpeg_quality）， 接口里不能改。stream 默认直通摄像头原始 MJPEG（服务端零解码零编码），所以带宽约 4~7 Mbps；嫌大就调低 jpeg_quality。

2. 检测 / 识别：GET /api/detect

"检测"和"识别"在这个系统里是同一件事：把一帧送进模型，拿回几个框。模型认什么由它自己 训练决定（网球、方块、橘子…），接口不管语义 —— 它只把框给你。

GET /api/detect?model=<模型名>[&conf=0.25][&iou=0.45]

成功（HTTP 200）：

{"ok": true, "count": 1, "boxes": [{"x1": 2, "x2": 172, "y1": 0, "y2": 360}]}

框宽 = x2 - x1，中心 = (x1+x2)/2, (y1+y2)/2 —— REST 版只给四角，宽高/中心/面积 自己算。脚本里的 detect() 会多给 w/h/cx/cy/area（见 §5）。

坐标是原图（如 640x360），不是页面上 stream 缩放后的尺寸 —— 两个尺寸不一致时 别拿标尺去量屏幕。

失败：

要"连续看"就轮询这个接口（车上一帧推理约 100~340ms，取决于有没有同时写着屏）； 要高帧率画面用 /api/camera/stream，它不跑模型。

conf 给错值直接报错而不是悄悄用默认 —— 调参时最怕"以为生效了其实没生效"。

3. 模型（"认什么"）

模型就是 $AKA_HOME/demo/models/<名字>.cvimodel 一个文件，文件名去掉后缀就是 model 参数的值。 GET /api/demo/list 的 models 字段能拿到板上现有的清单：

curl http://$IP/api/demo/list
# → {"demos":[…], "actions":[{"id":"approach","name":"接近瞄准"},…], "models":["block","orange","tennis"]}

上传

curl --data-binary @orange.cvimodel "http://$IP/api/models/upload?name=orange"
# → {"ok":true,"name":"orange","path":"/root/AKA-00/demo/models/orange.cvimodel","size":12864632}

curl -F "file=@orange.cvimodel" -F "name=orange" "http://$IP/api/model/upload"
# → {"status":"ok","name":"orange","size":12864632,"path":"…"}

同名覆盖，且覆盖即生效（下一次 /api/detect 就用新模型，不用重启）。校验：文件头必须是 CviModel（挡"传错文件"）、大小上限 32MB；先落 .part 再原子换入，传一半断了不会毁掉 正在用的那颗。

删除

curl -X POST http://$IP/api/models/delete -H 'Content-Type: application/json' -d '{"name":"orange"}'
# → {"ok":true,"name":"orange","cards":["追橘子"]}      ← cards = 正在用它的卡片名

只删这一个文件。用它建过的卡片不会跟着删，只是变成 ready:false、点开始报 模型文件缺失 —— 重传一个同名模型就原地复活。删完记得 GET /api/demo/list 刷新清单。

4. Demo 运行

概念：一张卡片 = 动作 × 模型

• 动作 = demo/<动作>.lua 脚本（预定义、与模型无关：approach 接近瞄准、grab 追到就夹）；
• 模型 = demo/models/<模型>.cvimodel；
• 卡片 = 用户起的名字 + 上面两者 + 四个参数，存 demo/configs/<卡片名>.json。

卡片不是必需的：action + model + 参数 直接发就是一次完整请求（不落盘、页面不留卡片）。 卡片只是"存下来反复用"的壳。

跑一次：POST /api/demo/init

两种形状，二选一：

// ① 跑存下来的卡片（界面上点"开始"就是这条）
{"name": "追网球接近"}

// ② 临时组装一次（不用建卡）
{"action": "approach", "model": "tennis",
 "target_size": 320, "speed": 30, "turn_speed": 25, "mode": "once"}

响应：

// 默认（wait=true）：等这次跑完再返回，只给一个完成标志
{"completed": true}
{"completed": false, "error": "目标丢失（1595ms 没看到目标）"}     // 跑完了但没成功
{"completed": false, "error": "timeout: 到最大执行时间（5 分钟）"}   // 到时限被宿主收工

// wait=false：立刻返回"起来了"
{"status":"started","name":"approach","script":"approach","action":"approach",
 "model":"tennis","pid":682,"pgid":682,"completed":false}

wait 的语义（最容易被误解的一条）：

• 它只决定这一个 HTTP 请求等不等，不是脚本的时限。
• once 默认等 → 一次请求拿到结论；loop 默认不等（循环不会自己结束，等下去就是挂死 连接），显式传 "wait": true 直接 400。
• 请求最多等 310 秒；而脚本自身在 once 模式下最多跑 5 分钟（到点宿主收工、 状态落 aborted、error 写明"到最大执行时间"）。所以正常情况是先由脚本收工、请求拿到 真实原因。
• 想自己轮询就传 "wait": false，然后看 /api/demo/status。

失败响应：

一次只能跑一个：脚本驱动电机是独占的，第二个请求 409。要换就 stop 再起。

最底层那条：POST /api/demo/run

{"script": "grab", "params": {"model": "tennis", "target_size": 300, "mode": "once"}}

和 init 的区别：不校验模型/卡片，params 原样交给脚本（调试、一次性用）。响应字段与 init 一致（{ok,state,script,mode} / 等跑完时 {completed:…}）。

看状态：GET /api/demo/status

{"state":"running","script":"approach","model":"tennis","card":"追网球接近","mode":"once",
 "round":1,"calls":92,"action":"forward","message":"",
 "notes":{"box_w":"298","offset":"28"}}

停：POST /api/demo/stop

立刻刹车、不等脚本配合；脚本会在下一次调原语时被中断，状态转 aborted。 没在跑时返回 {"status":"already_stopped"}（不报错）。

卡片管理

ready:false 表示动作脚本或模型文件缺了 —— 卡片照样列出来（点开始会明确报错），不会凭空消失。

5. 动作脚本（要加新动作时）

动作就是 $AKA_HOME/demo/<动作名>.lua 一个文件，宿主内置 Lua 解释器跑它。 第一行的约定注释给显示名（界面上的"接近瞄准"就是这么来的）：

-- name: 我的动作
local p = params() or {}
local model = p.model                      -- 宿主注入：卡片/请求里配的模型
local target = tonumber(p.target_size) or 300

while true do
    local d, err = detect(model)           -- 取一帧跑一次推理
    if not d then fail("推理失败：" .. tostring(err)) end
    local best = nil
    for _, b in ipairs(d.boxes) do
        if not best or b.area > best.area then best = b end
    end
    if not best then standby(); sleep_ms(50)
    elseif best.x2 - best.x1 >= target then brake(); return "到位了"
    else forward(p.speed or 20); sleep_ms(600); standby() end
end

能用的原语（全部只有这些）

有 math/string/table 标准库；没有 io / os / package / coroutine / debug，也没有 pcall （脚本吞掉宿主的打断就糟了）。内存预算 4MB。

板上现成两个动作：approach（-- name: 接近瞄准，只靠近不夹）、grab（-- name: 追到就夹）。 别改这两个文件 —— 它们是仓库里的代码、OTA 会按包覆盖；想调参请改卡片配置或另写一个 动作脚本（demo/<新名字>.lua，OTA 不会删你新加的）。

6. 安全边界（宿主强制，脚本和调用方都绕不过去）

7. 一条龙例子（可直接复制）

IP=<板子IP>; MODEL=tennis

# 1) 传一颗模型（同名覆盖、覆盖即生效）
curl --data-binary @orange.cvimodel "http://$IP/api/models/upload?name=orange"

# 2) 开摄像头，看它在哪、框多大（据此定 target_size）
curl -X POST http://$IP/api/camera/open
curl "http://$IP/api/detect?model=$MODEL&conf=0.5"

# 3) 跑一次：不建卡，直接组装；默认等跑完
curl -X POST http://$IP/api/demo/init -H 'Content-Type: application/json' \
     -d "{\"action\":\"approach\",\"model\":\"$MODEL\",\"target_size\":320,\"speed\":30,\"turn_speed\":25}"

# 4) 想边跑边看：wait=false + 轮询 status（notes 里有 box_w/offset，调参就看它）
curl -X POST http://$IP/api/demo/init -H 'Content-Type: application/json' \
     -d "{\"action\":\"approach\",\"model\":\"$MODEL\",\"target_size\":320,\"wait\":false}"
while true; do curl -s http://$IP/api/demo/status; echo; sleep 1; done

# 5) 停
curl -X POST http://$IP/api/demo/stop

8. 常见坑（都是踩过的）