KairOS / DRONE AGENT / 03

用于集成的 REST 链路、用于实时数据的原始 MAVLink WebSocket、用于远程中继的版本化 MQTT 主题，以及供驱动和扩展使用的 Python SDK。本页定义 KairOS 自有接口的目标端口、端点、权限和示例。

规划中

API 与 SDK 被描述为 KairOS 目标契约；稳定版本和兼容性尚未发布。

KairOS 仓库 ↗

08主要 REST 端点

JSONREST 响应

WS原始 MAVLink

KEY权限认证

本页内容 +

REST API / :8080

八个主要端点

控制界面监听端口 8080 并返回 JSON。多数请求需要 X-KairOS-Key 标头。每个密钥具有权限级别，因此可将遥测读取与飞行指令、任务上传和管理操作分开授权。

方法	端点	数据或操作
GET	/api/status	健康状态、运行时间、飞控连接、角色、代理版本
GET	/api/telemetry	姿态、GPS、电池、遥控通道、飞行模式
GET	/api/params	支持前缀筛选的飞控参数缓存
POST	/api/commands	起飞、降落、前往、RTL、解锁、锁定
GET	/api/config	JSON 格式的当前代理配置
PUT	/api/config	修改配置键并热重载受影响服务
GET	/api/services	受管理服务的 running、stopped 或 failed 状态
GET	/api/logs	按 service 和 level 筛选的结构化事件

bash通过 REST 获取遥测

curl -s http://<board-ip>:8080/api/telemetry \
  -H "X-KairOS-Key: <your-key>" | jq

KairOS 目标接口：只有相应组件发布后，命令才可执行。

jsonJSON 响应示例

{
  "armed": true,
  "mode": "GUIDED",
  "battery": { "voltage": 22.4, "pct": 78 },
  "gps": { "fix": 3, "satellites": 14, "alt": 50.2 },
  "attitude": { "roll": 0.02, "pitch": -0.01, "yaw": 182.5 }
}

客户端示例

从 Python 读取遥测并发送命令

pythonKairOS 目标客户端 — 飞行验证前仅用于仿真器

import httpx

BASE = "http://<board-ip>:8080"
headers = {"X-KairOS-Key": "<your-key>"}

telem = httpx.get(f"{BASE}/api/telemetry", headers=headers).json()
print(telem["battery"]["pct"], telem["gps"]["satellites"])

httpx.post(
    f"{BASE}/api/commands",
    headers=headers,
    json={"command": "takeoff", "params": {"alt": 10}},
)

KairOS 目标接口：只有相应组件发布后，命令才可执行。

端口与主题

一个 MAVLink 流，多种传输方式

接口	端口或主题	用途
REST	:8080	状态、遥测、配置、服务、指令
MAVLink WebSocket	:8765	双向二进制 MAVLink v2
WebRTC WHEP	:8889	本地视频
状态	kairos/v1/agents/{agent_id}/status	保留的健康信息和代理可用性
遥测	kairos/v1/agents/{agent_id}/telemetry	飞行器状态流
事件	kairos/v1/agents/{agent_id}/events	可观测事件与警告
指令	kairos/v1/agents/{agent_id}/commands	发往代理的 QoS 1 指令
ACK	kairos/v1/agents/{agent_id}/acks/{command_id}	具体指令的结果
WebRTC 信令	kairos/v1/agents/{agent_id}/video/webrtc/offer	P2P 视频的 SDP offer

路由器从飞控接收一个数据流，并同时分发给多个使用方：浏览器 GCS 通过 WebSocket 8765、SITL／工程客户端通过 TCP 5760、旧版工具通过 UDP 14550。WebSocket 不使用 JSON 包装，而是传输线格式兼容的二进制 MAVLink v2 帧。

javascriptKairOS 目标浏览器 WebSocket

const ws = new WebSocket("ws://<board-ip>:8765");
ws.binaryType = "arraybuffer";

ws.onmessage = (event) => {
  decodeMavlink(new Uint8Array(event.data));
};

ws.send(encodeCommandLong(sysid, compid, cmd, params));

KairOS 目标接口：只有相应组件发布后，命令才可执行。

PYTHON SDK

驱动与机载逻辑契约

类	用途
CameraDriver	CSI、USB UVC、IP 和厂商 SDK 相机
GimbalDriver	平移、俯仰、横滚和云台遥测
LidarDriver	LiDAR 与测距设备
GpsDriver	GPS/GNSS 接收器
EscDriver	ESC 驱动和回传遥测
VisionClient	机载视觉总线中的图像帧和检测结果

安全

API 密钥权限限制作用范围

级别	允许的操作
read	读取遥测、状态、配置、日志和参数，不改变状态
command	飞行指令；包含 read 权限
mission	上传和执行任务文件；包含 command 权限
config	修改代理与飞控配置；包含 read 权限
admin	更新、服务重启、密钥管理和完整访问

密钥应作为机密保存，不得出现在公开日志、截图或客户端构建包中。浏览器集成建议使用短期、限定权限的凭据，而非长期管理员密钥。

MCP AI 助手界面：对话式任务分析、地图、遥测、工具调用、事件日志和访问权限。 — 界面 / 视觉示例**指令、访问与审计上下文**
权限面板和工具调用日志与任务并列展示。图示将权限主题与操作员上下文连接；KairOS API 契约在正文中说明。

消息完整性

MAVLink v2 签名，无需在代理中保存密钥

地面站创建 32 字节密钥，并以不可导出的 Web Crypto 密钥形式保存在浏览器中。能力端点检查固件及签名参数是否存在。一次性注册后，飞控验证每个出站帧的 HMAC-SHA256 标签。代理保持透明管道，不保存签名密钥。

http能力检查

GET /api/mavlink/signing/capability
X-KairOS-Key: <your-key>

{
  "supported": true,
  "reason": "ok",
  "firmware_name": "ArduPilot",
  "firmware_version": "4.5.0",
  "signing_params_present": true
}

KairOS 目标接口：只有相应组件发布后，命令才可执行。