منظومة REST للتكامل، وMAVLink WebSocket خام للبيانات الآنية، وموضوعات MQTT ذات إصدارات للترحيل البعيد، وPython SDK لبرامج التشغيل والتوسعات. يحدد هذا القسم المنافذ ونقاط النهاية والصلاحيات والأمثلة المستهدفة لواجهة KairOS الخاصة.
وُصفت API وSDK بوصفهما مواصفات KairOS المستهدفة؛ ولم يُصدر بعد إصدار مستقر أو ضمان توافق.
مستودع KairOS ↗في هذه الصفحة +
ثماني نقاط نهاية رئيسية
تستمع واجهة التحكم على المنفذ 8080 وتعيد JSON. تتطلب معظم الطلبات ترويسة X-KairOS-Key. لكل مفتاح مستوى صلاحيات، مما يتيح فصل قراءة القياس عن بُعد عن أوامر الطيران وتحميل المهمات والعمليات الإدارية.
| الطريقة | نقطة النهاية | البيانات أو الإجراء |
|---|---|---|
| GET | /api/status | الصحة ومدة التشغيل واتصال FC والدور وإصدار الوكيل |
| GET | /api/telemetry | الاتجاه وGPS والبطارية وقنوات RC ووضع الطيران |
| GET | /api/params | ذاكرة معلمات FC المؤقتة مع تصفية بالبادئة |
| POST | /api/commands | الإقلاع والهبوط والانتقال والعودة RTL والتسليح وإلغاء التسليح |
| GET | /api/config | إعدادات الوكيل الحالية بصيغة JSON |
| PUT | /api/config | تغيير المفاتيح وإعادة التحميل الفوري للخدمات المتأثرة |
| 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 واحد، ووسائط نقل متعددة
| الواجهة | المنفذ أو الموضوع | الغرض |
|---|---|---|
| REST | :8080 | الحالة والقياس عن بُعد والإعدادات والخدمات والأوامر |
| MAVLink WebSocket | :8765 | MAVLink v2 ثنائي في الاتجاهين |
| WebRTC WHEP | :8889 | الفيديو المحلي |
| الحالة | kairos/v1/agents/{agent_id}/status | حالة صحة محتفظ بها وتوفر الوكيل |
| القياس عن بُعد | kairos/v1/agents/{agent_id}/telemetry | تدفق حالة المركبة |
| الأحداث | kairos/v1/agents/{agent_id}/events | أحداث وتحذيرات قابلة للمراقبة |
| الأوامر | kairos/v1/agents/{agent_id}/commands | أوامر إلى الوكيل بمستوى QoS 1 |
| ACK | kairos/v1/agents/{agent_id}/acks/{command_id} | نتيجة أمر محدد |
| إشارات WebRTC | kairos/v1/agents/{agent_id}/video/webrtc/offer | عرض SDP لفيديو P2P |
يستقبل الموجّه تدفقًا واحدًا من FC ويوزعه على عدة مستهلكين بالتزامن: محطة GCS في المتصفح عبر WebSocket 8765، وSITL أو عميل هندسي عبر TCP 5760، والأدوات القديمة عبر UDP 14550. لا يوجد غلاف JSON في WebSocket؛ بل تُنقل إطارات MAVLink v2 ثنائية متوافقة مع تنسيق النقل الأصلي.
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));عقود برمجية لبرامج التشغيل والمنطق على متن المركبة
| الصنف | الغرض |
|---|---|
| CameraDriver | كاميرات CSI وUSB UVC وIP وكاميرات SDK الخاصة بالمصنّع |
| GimbalDriver | التحريك الأفقي والميل والدوران وقياس حامل الكاميرا عن بُعد |
| LidarDriver | أجهزة LiDAR ومحددات المدى |
| GpsDriver | مستقبلات GPS/GNSS |
| EscDriver | برامج تشغيل ESC والقياس الراجع عن بُعد |
| VisionClient | الإطارات ونتائج الكشف من ناقل الرؤية على المركبة |
تحدد صلاحيات مفتاح API نطاق العمل
| المستوى | المسموح |
|---|---|
| read | القياس عن بُعد والحالة والإعدادات والسجلات والمعلمات دون تغيير الحالة |
| command | أوامر الطيران؛ وتشمل read |
| mission | تحميل ملفات المهمات وتنفيذها؛ وتشمل command |
| config | تغيير إعدادات الوكيل وFC؛ وتشمل read |
| admin | التحديثات وإعادة تشغيل الخدمات وإدارة المفاتيح والوصول الكامل |
يجب حفظ المفتاح بوصفه سرًا وعدم إدراجه في السجلات العامة أو لقطات الشاشة أو حزمة العميل. يُنصح في تكامل المتصفح ببيانات اعتماد قصيرة العمر ومحددة النطاق، بدلًا من مفتاح admin دائم.
توقيع MAVLink v2 دون تخزين المفتاح على الوكيل
تنشئ المحطة الأرضية مفتاحًا بطول 32 بايت وتحفظه في المتصفح كمفتاح Web Crypto غير قابل للاستخراج. تتحقق نقطة نهاية القدرات من البرنامج الثابت ووجود معلمات التوقيع. بعد التسجيل لمرة واحدة، تتحقق وحدة التحكم بالطيران من وسم HMAC‑SHA256 لكل إطار صادر. يظل الوكيل قناة شفافة ولا يحفظ مفتاح التوقيع.
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
}