REST untuk integrasi, WebSocket MAVLink mentah untuk data waktu nyata, topik MQTT berversi untuk relai jarak jauh, dan SDK Python untuk driver serta ekstensi. Bagian ini menetapkan port, endpoint, izin, dan contoh antarmuka milik KairOS yang ditargetkan.
API dan SDK dijelaskan sebagai kontrak yang ditargetkan KairOS; versi stabil dan jaminan kompatibilitas belum dirilis.
Repositori KairOS ↗Pada halaman ini +
Delapan endpoint inti
Antarmuka kendali mendengarkan port 8080 dan mengembalikan JSON. Sebagian besar permintaan memerlukan header X-KairOS-Key. Setiap kunci memiliki tingkat izin sehingga pembacaan telemetri dapat dipisahkan dari perintah penerbangan, unggahan misi, dan operasi administratif.
| Metode | Endpoint | Data atau tindakan |
|---|---|---|
| GET | /api/status | Kesehatan, waktu aktif, koneksi FC, peran, versi agen |
| GET | /api/telemetry | Sikap, GPS, baterai, kanal RC, mode penerbangan |
| GET | /api/params | Cache parameter FC dengan penyaringan awalan |
| POST | /api/commands | Lepas landas, mendarat, goto, RTL, arm, disarm |
| GET | /api/config | Konfigurasi agen saat ini dalam JSON |
| PUT | /api/config | Ubah kunci dan muat ulang layanan terkait tanpa berhenti |
| GET | /api/services | running, stopped, atau failed untuk layanan yang dikelola |
| GET | /api/logs | Peristiwa terstruktur dengan penyaring layanan dan tingkat |
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 }
}Baca telemetri dan kirim perintah dari 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}},
)Satu aliran MAVLink, beberapa transportasi
| Antarmuka | Port atau topik | Tujuan |
|---|---|---|
| REST | :8080 | Status, telemetri, konfigurasi, layanan, perintah |
| MAVLink WebSocket | :8765 | MAVLink v2 biner dua arah |
| WebRTC WHEP | :8889 | Video lokal |
| Status | kairos/v1/agents/{agent_id}/status | Kesehatan dan ketersediaan agen yang disimpan |
| Telemetri | kairos/v1/agents/{agent_id}/telemetry | Aliran keadaan wahana |
| Peristiwa | kairos/v1/agents/{agent_id}/events | Peristiwa dan peringatan yang dapat dipantau |
| Perintah | kairos/v1/agents/{agent_id}/commands | Perintah ke agen dengan QoS 1 |
| ACK | kairos/v1/agents/{agent_id}/acks/{command_id} | Hasil perintah tertentu |
| Pensinyalan WebRTC | kairos/v1/agents/{agent_id}/video/webrtc/offer | Penawaran SDP untuk video P2P |
Router menerima satu aliran dari FC dan mendistribusikannya ke beberapa konsumen sekaligus: GCS peramban melalui WebSocket 8765, klien SITL/rekayasa melalui TCP 5760, dan alat lama melalui UDP 14550. WebSocket tidak memiliki pembungkus JSON: isinya adalah bingkai MAVLink v2 biner yang kompatibel pada tingkat protokol.
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));Kontrak untuk driver dan logika di wahana
| Kelas | Tujuan |
|---|---|
| CameraDriver | Kamera CSI, USB UVC, IP, dan SDK vendor |
| GimbalDriver | Pan, tilt, roll, dan telemetri gimbal |
| LidarDriver | Perangkat LiDAR dan pengukur jarak |
| GpsDriver | Penerima GPS/GNSS |
| EscDriver | Driver ESC dan telemetri balik |
| VisionClient | Bingkai dan deteksi dari bus visi di wahana |
Izin kunci API membatasi ruang tindakan
| Tingkat | Operasi yang diizinkan |
|---|---|
| read | Telemetri, status, konfigurasi, log, dan parameter tanpa perubahan keadaan |
| command | Perintah penerbangan; mencakup read |
| mission | Unggah dan jalankan berkas misi; mencakup command |
| config | Ubah konfigurasi agen dan FC; mencakup read |
| admin | Pembaruan, mulai ulang layanan, pengelolaan kunci, dan akses penuh |
Jaga kerahasiaan kunci dan jangan memasukkannya ke log publik, tangkapan layar, atau bundel klien. Integrasi peramban sebaiknya menggunakan kredensial berjangka pendek dengan lingkup terbatas, bukan kunci admin permanen.
Penandatanganan MAVLink v2 tanpa menyimpan kunci pada agen
Stasiun darat membuat kunci 32 byte dan menyimpannya di peramban sebagai kunci Web Crypto yang tidak dapat diekstrak. Endpoint kemampuan memeriksa firmware dan ketersediaan parameter penandatanganan. Setelah pendaftaran satu kali, pengendali penerbangan memverifikasi tag HMAC-SHA256 pada setiap bingkai keluar. Agen tetap menjadi saluran transparan dan tidak menyimpan kunci penandatanganan.
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
}