REST‑контур для интеграции, сырой MAVLink WebSocket для real‑time данных, версионированные MQTT‑топики для удалённого relay и Python SDK для драйверов и расширений. Здесь зафиксированы целевые порты, endpoints, права и примеры собственного интерфейса KairOS.
API и SDK описаны как целевой контракт KairOS; стабильная версия и совместимость ещё не выпущены.
Репозиторий KairOS ↗На этой странице +
Восемь основных endpoints
Control surface слушает порт 8080 и возвращает JSON. Большинство запросов требуют заголовок X-KairOS-Key. Конкретный ключ имеет уровень разрешений, поэтому чтение телеметрии можно отделить от полётных команд, mission upload и административных операций.
| Метод | Endpoint | Данные или действие |
|---|---|---|
| GET | /api/status | Health, uptime, FC connection, роль, версия агента |
| GET | /api/telemetry | Attitude, GPS, battery, RC channels, flight mode |
| GET | /api/params | Кэш параметров FC с фильтром по prefix |
| POST | /api/commands | Takeoff, land, goto, RTL, arm, disarm |
| GET | /api/config | Текущая конфигурация агента как JSON |
| PUT | /api/config | Изменение ключей и hot reload затронутых сервисов |
| GET | /api/services | running, stopped или failed для управляемых сервисов |
| GET | /api/logs | Структурированные события с фильтрами service и level |
curl -s http://<board-ip>:8080/api/telemetry \
-H "X-KairOS-Key: <your-key>" | jq{
"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
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}},
)Один MAVLink‑поток, несколько транспортов
| Поверхность | Порт или topic | Назначение |
|---|---|---|
| REST | :8080 | Статус, телеметрия, config, services, commands |
| MAVLink WebSocket | :8765 | Binary MAVLink v2 в обе стороны |
| WebRTC WHEP | :8889 | Локальное видео |
| Status | kairos/v1/agents/{agent_id}/status | Retained health и доступность агента |
| Telemetry | kairos/v1/agents/{agent_id}/telemetry | Поток состояния аппарата |
| Events | kairos/v1/agents/{agent_id}/events | Наблюдаемые события и предупреждения |
| Commands | kairos/v1/agents/{agent_id}/commands | Команды к агенту с QoS 1 |
| ACK | kairos/v1/agents/{agent_id}/acks/{command_id} | Результат конкретной команды |
| WebRTC signaling | kairos/v1/agents/{agent_id}/video/webrtc/offer | SDP offer для P2P video |
Router принимает один поток от FC и распределяет его нескольким потребителям одновременно: browser GCS через WebSocket 8765, SITL/инженерный клиент через TCP 5760 и legacy‑инструменты через UDP 14550. В WebSocket нет JSON‑обёртки: передаются wire‑compatible binary MAVLink v2 frames.
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));Контракты для драйверов и on‑vehicle логики
| Класс | Назначение |
|---|---|
| CameraDriver | CSI, USB UVC, IP и vendor SDK камеры |
| GimbalDriver | Pan, tilt, roll и телеметрия подвеса |
| LidarDriver | LiDAR и rangefinder устройства |
| GpsDriver | GPS/GNSS‑приёмники |
| EscDriver | ESC‑драйверы и обратная телеметрия |
| VisionClient | Frames и detections из on‑vehicle vision bus |
Разрешения API key ограничивают область действия
| Уровень | Что разрешено |
|---|---|
| read | Telemetry, status, config, logs, params без изменения состояния |
| command | Flight commands; включает read |
| mission | Upload и execution mission files; включает command |
| config | Изменение agent и FC configuration; включает read |
| admin | Updates, service restart, key management и полный доступ |
Ключ нужно хранить как секрет и не вставлять в публичные логи, screenshots или клиентский bundle. Для браузерной интеграции рекомендуется короткоживущий scoped credential, а не постоянный admin key.
MAVLink v2 signing без хранения ключа на агенте
Ground station создаёт 32‑byte key и хранит его в браузере как non‑extractable Web Crypto key. Capability endpoint проверяет firmware и наличие signing parameters. После одноразового enrollment полётный контроллер проверяет HMAC‑SHA256 tag каждого outbound frame. Агент остаётся прозрачным pipe и не сохраняет signing key.
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
}