REST pour l’intégration, WebSocket MAVLink brut pour le temps réel, sujets MQTT versionnés pour le relais distant et SDK Python pour pilotes et extensions. Cette section fixe les ports, points d’accès, droits et exemples de l’interface propre à KairOS.
API et SDK constituent un contrat cible KairOS ; aucune version stable ni garantie de compatibilité n’est encore publiée.
Dépôt KairOS ↗Sur cette page +
Huit points d’accès principaux
La surface de commande écoute sur le port 8080 et renvoie du JSON. La plupart des requêtes exigent l’en-tête X-KairOS-Key. Chaque clé possède un niveau de droits, séparant lecture de télémétrie, commandes de vol, envoi de missions et administration.
| Méthode | Point d’accès | Donnée ou action |
|---|---|---|
| GET | /api/status | Santé, durée de fonctionnement, connexion FC, rôle, version d’agent |
| GET | /api/telemetry | Attitude, GPS, batterie, canaux RC, mode de vol |
| GET | /api/params | Cache des paramètres FC avec filtrage par préfixe |
| POST | /api/commands | Décollage, atterrissage, déplacement, RTL, armement, désarmement |
| GET | /api/config | Configuration actuelle de l’agent en JSON |
| PUT | /api/config | Modifier les clés et recharger à chaud les services concernés |
| GET | /api/services | running, stopped ou failed pour les services gérés |
| GET | /api/logs | Événements structurés avec filtres service et 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 }
}Lire la télémétrie et envoyer une commande en 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 flux MAVLink, plusieurs transports
| Surface | Port ou sujet | Fonction |
|---|---|---|
| REST | :8080 | État, télémétrie, configuration, services, commandes |
| MAVLink WebSocket | :8765 | MAVLink v2 binaire bidirectionnel |
| WebRTC WHEP | :8889 | Vidéo locale |
| État | kairos/v1/agents/{agent_id}/status | Santé conservée et disponibilité de l’agent |
| Télémétrie | kairos/v1/agents/{agent_id}/telemetry | Flux d’état de l’appareil |
| Événements | kairos/v1/agents/{agent_id}/events | Événements et avertissements observables |
| Commandes | kairos/v1/agents/{agent_id}/commands | Commandes à l’agent avec QoS 1 |
| ACK | kairos/v1/agents/{agent_id}/acks/{command_id} | Résultat d’une commande donnée |
| Signalisation WebRTC | kairos/v1/agents/{agent_id}/video/webrtc/offer | Offre SDP pour vidéo P2P |
Le routeur reçoit un flux du FC et le distribue simultanément à plusieurs clients : GCS navigateur par WebSocket 8765, client SITL/ingénierie par TCP 5760 et outils anciens par UDP 14550. WebSocket n’ajoute pas d’enveloppe JSON : il transporte des trames MAVLink v2 binaires compatibles avec le protocole.
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));Contrats pour les pilotes et la logique embarquée
| Classe | Fonction |
|---|---|
| CameraDriver | Caméras CSI, USB UVC, IP et à SDK constructeur |
| GimbalDriver | Panoramique, inclinaison, roulis et télémétrie de nacelle |
| LidarDriver | Appareils LiDAR et télémètres |
| GpsDriver | Récepteurs GPS/GNSS |
| EscDriver | Pilotes ESC et télémétrie de retour |
| VisionClient | Images et détections du bus de vision embarqué |
Les droits des clés API limitent le périmètre d’action
| Niveau | Opérations autorisées |
|---|---|
| read | Télémétrie, état, configuration, journaux et paramètres sans modification d’état |
| command | Commandes de vol ; inclut read |
| mission | Envoi et exécution de fichiers de mission ; inclut command |
| config | Modification de la configuration de l’agent et du FC ; inclut read |
| admin | Mises à jour, redémarrage de services, gestion des clés et accès complet |
Conservez la clé secrète, hors journaux publics, captures d’écran et paquets clients. Les intégrations navigateur devraient utiliser des identifiants limités et éphémères plutôt que des clés administrateur permanentes.
Signature MAVLink v2 sans stockage de clé sur l’agent
La station sol crée une clé de 32 octets et la conserve dans le navigateur comme clé Web Crypto non extractible. Le point d’accès des capacités vérifie micrologiciel et paramètres de signature. Après enrôlement unique, le contrôleur vérifie l’étiquette HMAC-SHA256 de chaque trame sortante. L’agent reste un conduit transparent et ne stocke pas la clé.
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
}