HTTP API 接入#
外部程序优先使用 统一 SDK 接入 中的 C++ / Python 客户端;ROS / ROS 2 复用同一 Python SDK。 本页用于解释 HTTP 契约,不要求为每种语言重新实现协议。STM32 UART 见 STM32 串口 SDK。
地址与请求约定#
设备网页与 API 共用 HTTP/1.1 的 80 端口,默认基础地址为
http://192.168.11.1,当前接口前缀统一为 /api。
不要使用历史带版本号路径,也不要根据旧测试报告推断存在兼容别名。
接口分三类:普通 JSON 查询、配置/命令写入、长连接二进制数据流。 完整操作清单、字段类型和错误响应见 接口契约与完整索引。
查询通常不需要正文。JSON 写入使用 Content-Type: application/json
和明确的 Content-Length;不使用 chunked 请求正文。
不同接口的字段和正文上限不同,禁止向配置对象随意加入自定义字段。
响应通常是直接对象,没有通用的 data 或 ok 包装。
先做只读连接检查#
以下示例使用 Python 3 标准库,不要求第三方包:
import json
import urllib.request
base = 'http://192.168.11.1'
with urllib.request.urlopen(base + '/api/vio', timeout=5) as response:
status = json.load(response)
print(status)
运行中的一种成功响应:
{"state":"running","tracking":"valid","error":null,"warning":null}
这是结构示例,不是当前设备的真实状态。running 只说明进程存在; tracking、warning 和数据新鲜度需分别判断。
命令受理、状态确认与重试#
VIO 启停等命令需要 Idempotency-Key。同一次业务尝试使用同一个键,
不同操作使用不同键。不能把每次网络重试都换成新键,否则可能创建重复操作。
各模块去重记录的寿命不同,不能假设所有键永久保存。
启动 VIO 的示例会真实改变设备状态,请在准备好运行时执行:
import json
import uuid
import urllib.error
import urllib.request
base = 'http://192.168.11.1'
request_key = str(uuid.uuid4()) # 保存该键供受控重试使用
body = json.dumps({'action': 'start'}).encode('utf-8')
request = urllib.request.Request(
base + '/api/vio', data=body, method='POST',
headers={
'Content-Type': 'application/json',
'Content-Length': str(len(body)),
'Idempotency-Key': request_key,
},
)
try:
with urllib.request.urlopen(request, timeout=5) as response:
print(response.status, json.load(response))
except urllib.error.HTTPError as error:
print(error.code, error.read().decode('utf-8', errors='replace'))
# 202 仅表示受理,后续 GET /api/vio 核对真实状态;超时先查询。
典型受理返回 202,以及 action=start、accepted=true。 配置保存可能同步返回 200,例如安装补偿,因此不能把所有 POST 按同一种异步模型处理。
配置对象往往是完整替换,不是 PATCH。先读取、只保留可写字段、修改后完整提交, 再独立回读。source、configured、尺寸或上限等只读字段不能直接随读取结果全部写回。 以各请求 schema 为准。
处理错误#
失败常见结构为:
{"error":{"code":"COMMAND_BUSY"}}
错误对象不提供通用 message 或 description。OpenAPI 中 description 是文档说明, 不是返回字段;图像流的 descriptor 则是实际解码配置,两者不同。
状态 |
建议 |
|---|---|
400 |
校对字段、类型、路径及请求头,不原样循环重试 |
409 |
查占用、配置冲突、幂等键或重启状态,条件满足后再操作 |
422 |
包或内容校验失败,按模块错误码检查 |
429 |
释放多余数据流连接 |
500 / 503 |
区分服务不可用与保存结果未确认,写入失败先回读 |
507 |
检查存储空间,备份后再清理明确的数据 |
MAVLink 异步操作、录制结束原因等还可能使用独立的原因码字段。 保留未知错误码,不因客户端没有本地翻译就将其当作成功。
实时流不是普通 JSON 响应#
请求例:GET /api/stream?channels=imu 或
GET /api/stream?channels=odometry。每条连接只选择一个通道。
Content-Type 为 application/vnd.robobaton.stream。HTTP 库先去除 chunked 传输层,
再解析 RBH1。一次 TCP read、一个 HTTP chunk、一个 RBH1 分片和一条业务消息是不同边界。
不能对整条响应调用 json.load,也不能把每次收到的字节直接当成完整图像。
RBH1 固定 40 字节小端头:
偏移 |
字节数 |
内容 |
|---|---|---|
0 |
4 |
ASCII RBH1 |
4 |
2 |
封装版本 1 |
6 |
2 |
头长 40 |
8 |
2 |
channel,0 控制,1–7 对应公开通道 |
10 |
2 |
format,决定完整消息的负载解析方式 |
12 |
4 |
flags,bit0 FIRST、bit1 LAST,其他为 0 |
16 |
8 |
连接内该 channel 的传输序号 |
24 |
4 |
完整消息字节数 |
28 |
4 |
当前分片偏移 |
32 |
4 |
分片字节数,1–65536 |
36 |
4 |
保留,必须为 0 |
按通道与传输序号重组,检查长度上限、连续偏移、FIRST/LAST 与总长度一致性。
完整消息验证后再解码,断线时丢弃半条消息。共享解析上限为
2 MiB + 8208 字节/消息,JSON 上限 128 KiB;具体通道上限可能更小。
通道名 |
channel / format |
完整消息 |
|---|---|---|
控制 |
0 / 1 |
metadata、心跳等 JSON |
preview |
1 / 6 |
RBF2 描述依赖及图像封装,不是裸视频流 |
odometry |
2 / 1 |
单条里程计 JSON |
imu |
3 / 1 |
单个 IMU 样本 JSON,不是 samples 数组 |
color |
4 / 7 |
小端 uint32 JSON 长度、JSON 帧信息、编码图像 |
gray |
5 / 8 |
小端 uint32 JSON 长度、JSON 帧信息、348160 字节 mono8 |
gray_jpeg |
6 / 7 |
小端 uint32 JSON 长度、JSON 帧信息、JPEG |
depth |
7 / 9 |
小端 uint32 JSON 长度、JSON 帧信息、589824 字节 float32 LE |
先处理连接 metadata。重新连接、编码变化或源重启时重新建立配置与解码状态, 不要拿上一次 GET 的配置替代该连接实际 metadata。H.264/H.265 从携带参数集的实际 IDR 恢复, 普通 I 帧不一定满足本接口随机访问要求。
时间、序号与坐标#
业务 header.seq 是十进制字符串,和 RBH1 的连接传输序号不同。 JavaScript 用 BigInt,Python 用 int,不能先转换成浮点数再做完整性判断。 stamp.sec 与 stamp.nanosec 组合为设备本次启动的单调时钟纳秒, 不是 Unix 时间、UTC 或网络到达时间,不能直接跨设备比较。
时间无效时可以为 null,不能补一个电脑时间冒充同步。 HTTP IMU 与里程计坐标以及安装补偿的差异见 实时视图 和 接入飞控。
订阅与算法生命周期#
订阅里程计不会启动算法,关闭订阅不会停止算法。 无算法时可能仍有传输心跳,心跳只能说明连接活着。 IMU、图像和深度按自身订阅需求管理资源,取消自己的连接不应关闭其他消费者。
客户端应设置有界缓冲和超时。实时观看断线可以重连并重新读取 metadata, 严谨录制则必须记录断点或不完整状态,不把两段断开的流悄悄拼成连续采集。
跨域与联网范围#
设备网页优先使用设备自身地址,主控程序直接连接设备 USB 网络。 不要假设公网 HTTPS 网站可以任意读取本地 HTTP API,也不要为了绕过浏览器限制 将设备控制接口直接暴露到公网。本站没有承诺额外的登录、TLS 或跨域授权机制。