REST para integraciones, WebSocket MAVLink sin procesar para datos en tiempo real, temas MQTT versionados para retransmisión remota y SDK Python para controladores y extensiones. Aquí se definen los puertos, endpoints, permisos y ejemplos previstos de la interfaz propia de KairOS.
La API y el SDK se describen como contrato previsto de KairOS; aún no se han publicado una versión estable ni garantías de compatibilidad.
Repositorio de KairOS ↗En esta página +
Ocho endpoints principales
La superficie de control escucha en el puerto 8080 y devuelve JSON. La mayoría de las solicitudes requieren la cabecera X-KairOS-Key. Cada clave tiene un nivel de permisos, lo que permite separar la lectura de telemetría de los comandos de vuelo, la carga de misiones y las operaciones administrativas.
| Método | Endpoint | Datos o acción |
|---|---|---|
| GET | /api/status | Salud, tiempo activo, conexión del FC, rol y versión del agente |
| GET | /api/telemetry | Actitud, GPS, batería, canales RC y modo de vuelo |
| GET | /api/params | Caché de parámetros del FC con filtro por prefijo |
| POST | /api/commands | Despegar, aterrizar, ir a, RTL, armar y desarmar |
| GET | /api/config | Configuración actual del agente en JSON |
| PUT | /api/config | Modificación de claves y recarga en caliente de los servicios afectados |
| GET | /api/services | running, stopped o failed para los servicios gestionados |
| GET | /api/logs | Eventos estructurados con filtros de servicio y nivel |
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 }
}Leer telemetría y enviar comandos desde 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}},
)Un flujo MAVLink, varios transportes
| Interfaz | Puerto o tema | Finalidad |
|---|---|---|
| REST | :8080 | Estado, telemetría, configuración, servicios y comandos |
| MAVLink WebSocket | :8765 | MAVLink v2 binario bidireccional |
| WebRTC WHEP | :8889 | Vídeo local |
| Estado | kairos/v1/agents/{agent_id}/status | Salud retenida y disponibilidad del agente |
| Telemetría | kairos/v1/agents/{agent_id}/telemetry | Flujo de estado del vehículo |
| Eventos | kairos/v1/agents/{agent_id}/events | Eventos y advertencias observables |
| Comandos | kairos/v1/agents/{agent_id}/commands | Comandos al agente con QoS 1 |
| ACK | kairos/v1/agents/{agent_id}/acks/{command_id} | Resultado de un comando concreto |
| Señalización WebRTC | kairos/v1/agents/{agent_id}/video/webrtc/offer | Oferta SDP para vídeo P2P |
El enrutador recibe un único flujo del FC y lo distribuye simultáneamente a varios consumidores: GCS en el navegador por WebSocket 8765, SITL o cliente de ingeniería por TCP 5760 y herramientas heredadas por UDP 14550. WebSocket no incluye envoltorio JSON: transmite tramas binarias MAVLink v2 compatibles con el protocolo de cable.
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));Contratos para controladores y lógica a bordo
| Clase | Finalidad |
|---|---|
| CameraDriver | Cámaras CSI, USB UVC, IP y con SDK del fabricante |
| GimbalDriver | Giro horizontal, inclinación, alabeo y telemetría del gimbal |
| LidarDriver | Dispositivos LiDAR y telémetros |
| GpsDriver | Receptores GPS/GNSS |
| EscDriver | Controladores ESC y telemetría de retorno |
| VisionClient | Fotogramas y detecciones del bus de visión a bordo |
Los permisos de la clave API limitan su alcance
| Nivel | Qué se permite |
|---|---|
| read | Telemetría, estado, configuración, registros y parámetros sin cambiar el estado |
| command | Comandos de vuelo; incluye read |
| mission | Carga y ejecución de archivos de misión; incluye command |
| config | Cambios en la configuración del agente y del FC; incluye read |
| admin | Actualizaciones, reinicio de servicios, gestión de claves y acceso completo |
La clave debe guardarse como secreto y no incluirse en registros públicos, capturas de pantalla ni paquetes del cliente. Para integrar navegadores se recomienda una credencial de alcance limitado y corta duración, no una clave administrativa permanente.
Firma MAVLink v2 sin almacenar la clave en el agente
La estación terrestre crea una clave de 32 bytes y la almacena en el navegador como clave Web Crypto no extraíble. El endpoint de capacidades comprueba el firmware y la existencia de parámetros de firma. Tras una incorporación inicial única, el controlador de vuelo verifica la etiqueta HMAC-SHA256 de cada trama saliente. El agente sigue siendo un canal transparente y no guarda la clave de firma.
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
}