Zurück zu Guides
Roboter-API-Integrationsführer: Roboter mit Ihrem Software-Stack verbinden
Wie man Roboterhardware mit APIs, Web-Dienstleistungen und Unternehmenssoftware integriert <unk> REST-APIs, WebSocket, ROS2-Brücken und Cloud-Konnektivität.
[← Führer]
Ein Systemintegrationsleitfaden für Ingenieure, die Roboterhardware mit Unternehmenssoftware verbinden
Integrationsarchitekturoptionen
Bevor Sie einen Code schreiben, wählen Sie das richtige Integrationsmuster für Ihre Anforderungen aus.
| Pattern | Latenz | Coupling | Best For |
|---|---|---|---|
| Direct SDK | <5ms | Tight — language/platform specific | Safety-critical control loops, high-frequency motion |
| REST API | 50–200ms | Loose — language agnostic | Task dispatch, status queries, configuration |
| WebSocket | 5–50ms | Medium — long-lived connection required | Real-time telemetry, servo commands, streaming |
| ROS2 bridge | 10–100ms | Loose — uses ROS2 ecosystem | ROS2-compatible software, visualization, multi-robot |
Die meisten Produktionsintegrationen verwenden eine Kombination: REST API für Aufgaben-Dispediture und Statusanfragen (wo Latenz akzeptabel ist), WebSocket für Echtzeit-Telemetrie-Streaming und das direkte SDK nur für die Low-Level-Steuerungsschleife, die auf dem Bordcomputer des Robots ausgeführt wird.
REST API-Design für Robotersteuerung
Eine gut gestaltete REST API behandelt Roboter als Ressourcen und Aufgaben als erstklassige Objekte.
- POST /Tasks
Eine neue Aufgabe einreichen. Körper: T1 . Rückgabe: T2 . - GET /tasks/{id}
Erhalten Sie den Status der Aufgabe. Gibt den aktuellen Status (Schlange / Lauf / Erfolg / Misserfolg), die Ausführungsmessungen und Fehlerdetails zurück, wenn sie fehlen. - GET /robots/{id}/status
Erhalten Sie die Gesundheit des Robots: Gelenktemperaturen, Batterie, Fehlercodes, aktuelle Aufgabe und Posen. - DELETE /tasks/{id}
Absagen einer in der Warteschlange befindlichen oder laufenden Aufgabe. Gibt 200 zurück, wenn sie erfolgreich abgesagt wird, 409 Konflikt, wenn die Aufgabe in einem nicht ablösbaren Zustand (z.B. Mitte der Einfügung) ist. - Authentifizierung: Verwenden Sie API-Schlüssel für maschinengleich-Maschine-Integrationen (einfachere, auditierbare) oder OAuth2-Kunden-Zugeben-Fluss für mehrere Mieter-Entwicklungen.
- Rate Limiting: Eine 100 Anfragen/Sekunde-Rate-Limit pro Schlüssel, die in der API-Gateway-Schicht durchgesetzt wird, anzuwenden. 429 Zu viele Anfragen mit einem
T4 -Header zurückgeben. Die meisten Integrationen nähern sich dieser Grenze nie.
WebSocket Implementierung
WebSocket bietet den zweiseitigen, niedrig-Latenz-Kanal, der für die Echtzeit-Robotersteuerung und das Telemetrie-Streaming erforderlich ist. Zwei separate WebSocket-Kanäle werden empfohlen
- Command Stream (Robot ← Client): Der Client sendet
T5 -formatige JSON-Kommandos bei 50 100 Hz . Der Bordcontroller des Robots muss jeden Befehl innerhalb von 10 ms erkennen oder einen sicheren Stoppzustand einlegen. Benutze für Kommandoströme eine binäre Kodierung (MessagePack oder CBOR) anstelle von JSON3 5× kleinere Nutzlast, 30 50% geringere Latenz. - Telemetrie-Stream (Roboter → Client): Der Roboter sendet den gemeinsamen Zustand, die End-Effektor-Position, die Kamera-Metadaten und Fehlercodes bei 10 Hz. 10 Hz reichen für die Überwachung und Visualisierung aus; höhere Geschwindigkeiten erfordern eine binäre Codierung und eine dedizierte Netzwerkbandbreite.
- Herzschlag und Wiedereinbindung: Der Client muss alle 1 Sekunde einen Ping-Framm senden. Wenn der Roboter 3 Sekunden lang keinen Ping erhält, wird er in einen sicheren Stoppzustand eingehen.
- Botschaftsequenzierung: In jeder Nachricht eine monotonisch steigende Sequenznummer einbeziehen. Der Empfänger kann abgefallene Nachrichten erkennen und entscheiden, ob er die nächste Nachricht interpolieren oder warten soll.
ROS2 Webbrücke
Für Teams mit vorhandener ROS2-Infrastruktur stellt rosbridge_suite ROS2-Themen, Services und Aktionen über WebSocket mit JSON-Codierung dar. Dies ermöglicht es Web-Dashboards und nicht-ROS-Anwendungen, mit dem ROS2-Graph zu interagieren, ohne ROS2 selbst auszuführen.
- rosbridge_server: Installieren Sie über
T6 . Laufen Sie einen WebSocket-Server auf Port 9090 standardmäßig. Kunden verbinden sich und abonnieren/publizieren ROS2-Themen mit einem einfachen JSON-Protokoll. - roslibjs: Die JavaScript-Clientbibliothek für rosbridge. Erlaubt Web-Dashboards, sich für
T7 , T8 und benutzerdefinierte Themen zu abonnieren und ROS2-Dienste aus dem Browser zu rufen. - JSON-Codierung überhead: rosbridge verwendet JSON-Codierung, die 5
10x größer ist als die native CDR-Binärcodierung von ROS2. Für Hochfrequenzthemen (>10 Hz mit großen Nachrichten) sollten Sie vor der Überbrückung eine dedizierte binäre Brücke oder Filterthemen in Betracht ziehen. - ** Sicherheitsmerkmal:** rosbridge hat keine Authentifizierung standardmäßig. Laufen Sie es immer hinter dem WireGuard VPN, das im [Fleet Management Guide] beschrieben ist, und wird nie direkt im Internet ausgesetzt.
Unternehmenseinstimmungsmuster
Die Verbindung von Roboter mit Unternehmenssystemen (WMS, ERP, MES) erfordert Muster, die die Zuverlässigkeitsung zwischen immer aktivierten Unternehmenssystemen und gelegentlich offline-Robotern bewältigen:
- Message-Schlange für die Aufgabe des Versandes (Kafka oder RabbitMQ): WMS veröffentlicht Pick-Orders für ein Kafka-Thema. Der Roboterflottenmanager konsumiert aus dem Thema und verschickt Aufgaben an verfügbare Roboter. Wenn ein Roboter offline ist, wenn eine Aufgabe eintrifft, bleibt die Aufgabe in der Schlange, bis ein Roboter verfügbar ist. Dies entkoppelt das WMS von der Roboterverfügbarkeit.
- ERP/WMS-Webhooks für Bestellveranstaltungen: Konfigureren Sie das WMS, um einen Webhook in Ihre Roboterplattform-API zu posten, wenn neue Bestellungen bereit sind. Die Roboterplattform verarbeitet den Webhook und versendet Aufgaben. Implementieren Sie die Webhook-Signaturverifizierung (HMAC-SHA256) um eine falsche Bestell-Injektion zu verhindern.
- Zeitreihen-Datenbank für Telemetrie (InfluxDB): Speichern Sie die Roboter-Telemetrie in InfluxDB für die langfristige Analyse und Nachgiebigkeit-Berichterstattung.
Sicherheitsdurchführung
- TLS 1.3 für alle Netzwerkkommunikation: Alle REST, WebSocket und Rosbridge-Verkehr müssen TLS 1.3. Konfiguration Ihres Reverse Proxy (Nginx oder Caddy) mit
T9 und HSTS-Header. Roboter, die sich mit Cloud-Diensten verbinden, müssen das Serverzertifikat validieren. - Zertifikatsverbindung für Roboterklienten: Die Roboter-Onboard-Software sollte den erwarteten Fingerabdruck des Serverzertifikats verknüpfen und Verbindungen zu unerwarteten Zertifikaten ablehnen. Dies verhindert man-in-the-middle-Angriffe in Fabrik-/Warehouse-Netzwerkumgebungen, in denen schädliche APs vorhanden sein können.
- VPN für sensible Umgebungen: Für Einsätze in hochaufsichtlichen Umgebungen (pharmazeutische, defensive, finanzielle) verweist die gesamte Roboter-Cloud-Kommunikation über einen WireGuard VPN-Tunnel.
- Audit Logging: Loggen Sie jeden API-Anruf mit: Timestamp, API-Schlüssel-ID (nicht der Schlüssel selbst), Endpunkt, Reaktionsstatus und IP-Anfrage. Speichern Sie Audit-Logge in einem Schreib-Once-Stor (AWS CloudTrail oder GCP Cloud Audit-Logges). Dies ist für die SOC 2-Konformität und die Untersuchung von Vorfällen erforderlich.
Test und Spott
- Fake-Roboter-Server für die Entwicklung: Erstellen Sie einen Fake-HTTP/WebSocket-Server, der auf die komplette Roboter-API mit realistischen simulierten Daten reagiert. Entwickler können Integrationen gegen den Fake erstellen und testen, ohne dass ein physischer Roboter zugreifen muss. Der Fake sollte aufgezeichnete Roboter-Sitzungen für deterministische Integrationsprüfungen wiedergeben.
- Simulationsbasierte Integrationsprüfungen: Für die End-to-End-Tests des gesamten Stacks (WMS → Roboterplattform → Roboter → Telemetrie → Dashboard) verwenden Sie einen simulierten Roboter in Gazebo oder Isaac Sim. Diese Tests werden in CI bei jeder Zuganforderung durchgeführt und auf die Einheitstests fehlenden Integrationsregressionen gefangen.
- Vertragstests: Verwenden Sie Pact oder ähnliches Vertragstest-Framework, um zu überprüfen, ob der API-Produzent (eure Roboterplattform) und API-Verbraucher (WMS-Integration, Dashboard) sich auf das API-Schema einig sind. Dies verhindert, dass Änderungen bis zur Integration unentdeckt bleiben.
Integrationsarchitekturdiagramm
Eine typische End-to-End-Architektur für die Bereitstellung eines Produktionslager:
- Layer 1
Roboterhardware: Roboterarm + Bordcomputer mit ROS2, direkte SDK-Steuerungsschleife bei 500 Hz, lokale Sicherheitswache. - Layer 2
Roboterplattform (on-premise oder in der Cloud): REST API für Aufgabenmanagement, WebSocket Server für Echtzeit-Telemetrie, RCSV-Plattform für Dashboard und Policy-Deployment. - Layer 3
Enterprise-Integration: Kafka-Message-Bus, der WMS-Bestellereignisse verbraucht und auf die Roboterplattform verschickt; InfluxDB für die Telemetrie-Speicherung; Grafana-Dashboard für das Betriebsteam. - Level 4
Unternehmenssysteme: WMS (Warehouse Management), ERP (Inventar, Finanzen), MES (Fertigungsmanagementsystem)alle kommunizieren nur mit Layer 3, niemals direkt mit Robotern.
OpenArm 1 ROS2 Schnittstelle: Spezifische Themen
Der OpenArm 1 bietet einem nativen ROS2-Treiber die folgende Themenstruktur. Dies dient als Referenzimplementierung für die Integration eines beliebigen Arms über die oben beschriebenen Muster.
T10 -- Sensor_msgs/JointState bei 50 Hz. 7 Felder: 6 Gelenke + 1 Grifföffnung. Zustandsschnittstelle: Position, Geschwindigkeit, Anstrengung. T11 -- Trajektorie_msgs/JointTrajectory. Positionmodus Befehle bei bis zu 50 Hz über ros2_control JointTrajectoryController. T12 -- Geometrie_msgs/SchlüsselStempelt bei 100 Hz (wenn der F/T-Sensor angeschlossen ist). 6-Achsen-Kraft/Durchschwung an der Handgelenkflange. T13 -- std_msgs/Float64. Greiferöffnung Befehl 0.0 (geschlossen) bis 1.0 (vollständig geöffnet). T14 -- Diagnostik_msgs/DiagnosticArray. Motortemperaturen, Fehlercodes, Firmware-Version. - ROS2-Service:
T15 -- Schalter zwischen Positions-, Geschwindigkeits- und Impedanzkontrollemodi. - ROS2-Aktion:
T16 -- akzeptiert eine Ziel-End-Effektor-Pose und führt sie über MoveIt2-Planungspipeline aus.
Python-Client-Beispiel: REST-API-Integration
Ein minimaler Python-Client, der eine Aufgabe verschickt, die Fertigstellung überwacht und die Telemetrie abruft:
import requests, time
API_URL = "https://platform.roboticscenter.ai/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. Submit a task
task = requests.post(f"{API_URL}/tasks", json={
"task_type": "pick_and_place",
"robot_id": "arm-001",
"parameters": {
"pick_pose": [0.3, 0.1, 0.05, 0, 0, 0, 1],
"place_pose": [0.3, -0.2, 0.05, 0, 0, 0, 1]
},
"priority": 1
}, headers=HEADERS).json()
task_id = task["task_id"]
print(f"Task submitted: {task_id}")
# 2. Poll for completion
while True:
status = requests.get(
f"{API_URL}/tasks/{task_id}", headers=HEADERS
).json()
if status["status"] in ("succeeded", "failed"):
break
time.sleep(1.0)
print(f"Result: {status['status']}")
# 3. Get robot telemetry
health = requests.get(
f"{API_URL}/robots/arm-001/status", headers=HEADERS
).json()
print(f"Joint temps: {health['joint_temperatures']}")
print(f"Battery: {health['battery_pct']}%")
Fehlerbewältigung und Wiederversuch
- Idempotency: Alle POST/Tasks-Anfragen sollten eine vom Client generierte
T17 (UUID) enthalten. Der Server gibt die bestehende Aufgabe zurück, wenn der gleiche Schlüssel erneut eingereicht wird, wodurch duplizierte Aufgaben bei Netzwerkversuchen verhindert werden. - Retry mit exponentiellem Backoff: Für 5xx Serverfehler und Netzwerk-Timeouts, erneut mit 1s, 2s, 4s, 8s-Intervallen mit maximal 4 Wiederversuchen. Für 4xx Clientfehler, nicht erneut versuchen - die Anfrage zu beheben.
- WebSocket-Wiederverbindung: Wenn die Telemetrie WebSocket abschaltet, muss der Kunde: (1) 1 Sekunde warten, (2) erneut versuchen, sich zu verbinden, (3) alle Themen erneut abonnieren und (4) die letzten 10 Sekunden der verpassten Telemetrie über den REST-Backfill-Endpunkt
T18 beantragen. - Richtlinie des Schaltplatzes: Wenn ein Roboter bei 5 aufeinanderfolgenden API-Anrufen Fehler zurückgibt, öffnet er einen Schaltplatzeschalter für 60 Sekunden. Während dieser Zeit werden alle Anfragen an diesen Roboter einen cached-out-status zurückgeben. Nach 60 Sekunden senden Sie eine einzige Gesundheitsprüfungsanfrage. Wenn dies gelingt, schließen Sie den Schaltplatzeschalter und setzen Sie den normalen Betrieb wieder auf.
Verwandte Leitfäden
- ROS2 und MoveIt2 Integration -- ROS2 Integration auf niedriger Ebene zur Armsteuerung
- Fernflottenmanagement -- API-Integration und Überwachung im Flottenbereich
- [Politik- und Produktionsentwicklung]
T25 ) -- API-Muster für die Einführung und Überwachung von Politiken - Warehouse Deployment Checklist -- WMS und Unternehmensintegrationsplanung
- Beschätzung der Robotersicherheitsrisiken -- Sicherheitsanforderungen für API-Endpunkte
Arbeiten mit RCSV
Die RCSV-Plattform bietet Produktions-API-Programme für Robotersteuerung, Flottenmanagement und Unternehmensintegration.
- Datenplattform -- REST- und WebSocket-APIs für die Aufgabenvermittlung, Telemetrie und Flottenmanagement
- Datenerhebungssysteme -- API-gestützte Datenerhebung mit programmatischer Aufgabe und -übermittlung
- Hardware Store -- OpenArm 1 Schiffe mit einem vorgebauten ROS2-Treiber und API-Integrationspaket
- [Kontaktieren Sie uns]
T32 ) -- eine Integrationsarchitekturüberprüfung für Ihre Bereitstellung anfordern
Schneller mit der RCSV-Plattform zu integrieren
Die RCSV-Plattform bietet vorgebaute REST- und WebSocket-API, Flottenmanagement und Enterprise-Integrations-Konnektoren für Roboter-Entwicklungen.
[Erforschen Sie die Plattform]