REST para integração, WebSocket MAVLink em bruto para dados em tempo real, tópicos MQTT versionados para retransmissão remota e SDK Python para controladores e extensões. Aqui estão definidos portas, endpoints, permissões e exemplos previstos da interface própria KairOS.
API e SDK estão descritos como contrato previsto KairOS; a versão estável e a compatibilidade ainda não foram lançadas.
Repositório KairOS ↗Nesta página +
Oito endpoints principais
A superfície de controlo escuta na porta 8080 e devolve JSON. A maioria dos pedidos requer o cabeçalho X-KairOS-Key. Cada chave tem um nível de permissões, permitindo separar leitura de telemetria, comandos de voo, carregamento de missões e operações administrativas.
| Método | Endpoint | Dados ou ação |
|---|---|---|
| GET | /api/status | Saúde, tempo ativo, ligação do FC, papel e versão do agente |
| GET | /api/telemetry | Atitude, GPS, bateria, canais RC e modo de voo |
| GET | /api/params | Cache de parâmetros do FC com filtro por prefixo |
| POST | /api/commands | Descolar, aterrar, ir para, RTL, armar e desarmar |
| GET | /api/config | Configuração atual do agente em JSON |
| PUT | /api/config | Alteração de chaves e recarregamento em funcionamento dos serviços afetados |
| GET | /api/services | running, stopped ou failed para os serviços geridos |
| GET | /api/logs | Eventos estruturados com filtros de serviço e nível |
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 }
}Ler telemetria e enviar comandos a partir de 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}},
)Um fluxo MAVLink, vários transportes
| Interface | Porta ou tópico | Finalidade |
|---|---|---|
| REST | :8080 | Estado, telemetria, configuração, serviços e comandos |
| MAVLink WebSocket | :8765 | MAVLink v2 binário bidirecional |
| WebRTC WHEP | :8889 | Vídeo local |
| Estado | kairos/v1/agents/{agent_id}/status | Saúde retida e disponibilidade do agente |
| Telemetria | kairos/v1/agents/{agent_id}/telemetry | Fluxo de estado do veículo |
| Eventos | kairos/v1/agents/{agent_id}/events | Eventos e avisos observáveis |
| Comandos | kairos/v1/agents/{agent_id}/commands | Comandos para o agente com QoS 1 |
| ACK | kairos/v1/agents/{agent_id}/acks/{command_id} | Resultado de um comando concreto |
| Sinalização WebRTC | kairos/v1/agents/{agent_id}/video/webrtc/offer | Oferta SDP para vídeo P2P |
O encaminhador recebe um único fluxo do FC e distribui-o simultaneamente a vários consumidores: GCS no navegador por WebSocket 8765, SITL ou cliente de engenharia por TCP 5760 e ferramentas antigas por UDP 14550. O WebSocket não contém invólucro JSON: transmite tramas binárias MAVLink v2 compatíveis com o protocolo de transmissão.
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 e lógica a bordo
| Classe | Finalidade |
|---|---|
| CameraDriver | Câmaras CSI, USB UVC, IP e com SDK do fabricante |
| GimbalDriver | Rotação horizontal, inclinação, rolamento e telemetria do gimbal |
| LidarDriver | Dispositivos LiDAR e telémetros |
| GpsDriver | Recetores GPS/GNSS |
| EscDriver | Controladores ESC e telemetria de retorno |
| VisionClient | Fotogramas e deteções do barramento de visão a bordo |
As permissões da chave API limitam o âmbito de atuação
| Nível | O que é permitido |
|---|---|
| read | Telemetria, estado, configuração, registos e parâmetros sem alterar o estado |
| command | Comandos de voo; inclui read |
| mission | Carregamento e execução de ficheiros de missão; inclui command |
| config | Alteração da configuração do agente e do FC; inclui read |
| admin | Atualizações, reinício de serviços, gestão de chaves e acesso completo |
A chave deve ser guardada como segredo e não colocada em registos públicos, capturas de ecrã ou pacote do cliente. Para integração no navegador, recomenda-se uma credencial de âmbito limitado e curta duração em vez de uma chave administrativa permanente.
Assinatura MAVLink v2 sem guardar a chave no agente
A estação terrestre cria uma chave de 32 bytes e guarda-a no navegador como chave Web Crypto não extraível. O endpoint de capacidades verifica o firmware e a existência dos parâmetros de assinatura. Após uma inscrição inicial única, o controlador de voo verifica a etiqueta HMAC-SHA256 de cada trama de saída. O agente mantém-se um canal transparente e não guarda a chave de assinatura.
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
}