OKAI IoT-Integration

Levy Fleets bietet umfassende Unterstuetzung fuer OKAI ZK-Serie IoT-Geraete und implementiert 100% des @Track Air Interface Protocol v80.56. Diese Anleitung behandelt die vollstaendige Integration, einschliesslich unterstuetzter Befehle, Telemetrieverarbeitung und Fehlerbehebung.

Ueberblick

OKAI IoT-Geraete kommunizieren mit Levy Fleets ueber einen sicheren API-Endpunkt, der Telemetriedaten, Standortberichte und Fahrzeugsteuerbefehle verarbeitet. Die Integration unterstuetzt:

• Echtzeit-GPS-Tracking mit Standortverlauf
• Batterieueberwachung einschliesslich Ladestatus
• Sperr-/Entsperrsteuerung mit Statusbestaetigung
• Geschwindigkeitsbegrenzung fuer Zonendurchsetzung
• Alarm- und Warnungsbehandlung fuer Sicherheitsereignisse
• Diagnosedaten fuer Wartung und Fehlerbehebung

Geraetekonfiguration

Servereinstellungen

Konfigurieren Sie Ihr OKAI-Geraet fuer die Kommunikation mit Levy Fleets mit diesen Einstellungen:

Authentifizierung

OKAI-Geraete authentifizieren sich per API-Schluessel. Stellen Sie sicher, dass Ihre IoT-Geraete mit dem korrekten API-Schluessel im x-api-key-Header konfiguriert sind.

Geraeteidentifikation

Geraete werden durch ihre IMEI-Nummer identifiziert. Wenn ein Geraet eine Verbindung herstellt:

1. Die IMEI wird aus der Nachricht extrahiert
2. Das System sucht das mit dieser IMEI verknuepfte Fahrzeug
3. Telemetrie wird dem korrekten Fahrzeug zugeordnet
4. Wenn kein Fahrzeug gefunden wird, wird die Nachricht als "nicht zugeordnet" protokolliert

Unterstuetzte Befehle

Levy Fleets implementiert vollstaendige Abdeckung des OKAI-Protokolls. Befehle sind in funktionale Kategorien organisiert:

Standort & Telemetrie

Status & Informationen

Batteriemanagement

ECU (Elektronische Steuereinheit)

Sperrvorgaenge

Bewegung & Alarme

Geschwindigkeit & Geofencing

System & Netzwerk

Stromereignisse

Konfiguration

NFC & Service

Bindung & Bluetooth

Datenerfassung

Telemetrieverarbeitung

Standortberichte

Wenn das Geraet einen Standortbericht sendet (GTFRI, GTERI oder GTRTO), fuehrt Levy Fleets folgendes aus:

1. Parsen der GPS-Koordinaten (Breitengrad, Laengengrad)
2. Extrahieren von Geschwindigkeit, Richtung und Hoehe
3. Aktualisierung der aktuellen Position des Fahrzeugs
4. Falls eine aktive Fahrt existiert, Speicherung des Standorts im Fahrtverlauf
5. Ausloesen der Zonendurchsetzung, wenn sich die Koordinaten geaendert haben

Batterie-Updates

Batteriestatus-Nachrichten beinhalten:

• Batteriestand - Prozentsatz (0-100%)
• Batteriespannung - Tatsaechlicher Spannungswert
• Ladestatus - Ob das Fahrzeug laedt
• IoT-Batterie - Backup-/IoT-Modul-Batterie (falls separat)

Das System verwendet den Batteriestand, um:

• Die Fahrzeugverfuegbarkeit zu aktualisieren (niedrige Batterie = nicht verfuegbar)
• Fahrzeuge im Dashboard nach Batteriestatus zu filtern
• Warnungen bei niedriger Batterie auszuloesen

Sperrstatus

Sperrzustandsaenderungen aktualisieren den Fahrzeugdatensatz:

Zonendurchsetzung

Nach der Verarbeitung von Standort-Updates waehrend einer aktiven Fahrt:

1. Die Koordinaten des Fahrzeugs werden gegen alle Zonen geprueft
2. Wenn das Fahrzeug eine Geschwindigkeitsbegrenzungszone betritt, wird ein Gasgriffbefehl gesendet
3. Wenn das Fahrzeug eine Verbotszone betritt, wird der Gasgriff deaktiviert
4. Wenn das Fahrzeug das Servicegebiet verlaesst, wird eine Warnung ausgeloest
5. Fahrtstatistiken werden neu berechnet

Fahrzeugidentitaetsaufloesung

Die OKAI-Integration verwendet intelligentes Caching fuer Fahrzeugabfragen:

Abfrageprozess

1. Cache pruefen - Zuerst im Fahrzeugidentitaets-Cache nach IMEI suchen
2. Cache-Treffer - Gecachte Fahrzeug-UUID und -Nummer zurueckgeben
3. Cache-Fehler - Datenbank nach Fahrzeug mit passender iot_imei abfragen
4. Im Cache speichern - Ergebnis fuer 1 Stunde cachen
5. Identitaet zurueckgeben - Fahrzeug-UUID fuer Telemetrie-Zuordnung bereitstellen

Nicht zugeordnete Geraete

Wenn kein Fahrzeug fuer eine IMEI gefunden wird:

1. Die Nachricht wird trotzdem fuer die Protokollierung verarbeitet
2. Das Geraet wird in der Tabelle "nicht zugeordnete Geraete" erfasst
3. Betreiber koennen nicht zugeordnete Geraete im Dashboard anzeigen
4. Sobald das Geraet registriert ist, werden zukuenftige Nachrichten korrekt zugeordnet

Aktive Fahrterkennung

Fuer jede eingehende Nachricht prueft das System auf aktive Fahrten:

1. Abfrage von Fahrten mit Status active oder paused
2. Filtern nach vehicle_uuid, die dem identifizierten Fahrzeug entspricht
3. Falls gefunden, Telemetrie mit der Fahrt verknuepfen
4. Standortdaten werden dem Fahrtverlauf hinzugefuegt
5. Fahrtstatistiken (Strecke, Dauer) werden aktualisiert

Legacy-Fahrt-Unterstuetzung

Fuer Rueckwaertskompatibilitaet mit aelteren Fahrtdatensaetzen:

1. Wenn keine Fahrt per UUID gefunden wird, Suche nach vehicle_number
2. Falls eine Legacy-Fahrt gefunden wird, Kennungen normalisieren
3. Das Feld vehicle_uuid fuer zukuenftige Abfragen nachfuellen

Befehle an Geraete senden

IoT-Passwort

Befehle an OKAI-Geraete erfordern das korrekte Passwort. Stellen Sie dies ein unter:

Einstellungen > Fahrzeuge > IoT-Passwoerter > Okai

Standard-Passwort: zk200

Verfuegbare Befehle

Von der Fahrzeugdetailseite koennen Sie senden:

Befehlsablauf

1. Betreiber klickt auf Befehlsschaltflaeche im Dashboard
2. Befehl wird fuer das Geraet in die Warteschlange gestellt
3. Geraet empfaengt Befehl beim naechsten Heartbeat (oder sofort, wenn online)
4. Geraet fuehrt Befehl aus und sendet Bestaetigung
5. Dashboard aktualisiert sich mit neuem Status

Fehlerbehebung

Geraet meldet keinen Standort

Symptome: Fahrzeug zeigt keinen Standort oder veraltete Standortdaten

Loesungen:

1. Geraetestrom pruefen - sicherstellen, dass die Batterie geladen ist
2. GPS-Antenne ueberpruefen - muss freie Sicht zum Himmel haben
3. Mobilfunkverbindung pruefen - Geraet benoetigt Netzwerkzugang
4. Geraetekonfiguration ueberpruefen - Servereinstellungen verifizieren
5. Auf GPS-Fix pruefen - neue Installationen benoetigen moeglicherweise 5-10 Minuten

Sperr-/Entsperrbefehle funktionieren nicht

Symptome: Befehle gesendet, aber Fahrzeug reagiert nicht

Loesungen:

1. IoT-Passwort in den Einstellungen ueberpruefen
2. Bestaetigen, dass Geraet online ist (Zeitstempel der letzten Verbindung pruefen)
3. Auf ECU-Fehler in der Telemetrie pruefen
4. Ueberpruefen, ob Fahrzeug ausreichend Batterie hat
5. Fahrzeug aus- und wieder einschalten

Batterie aktualisiert sich nicht

Symptome: Batteriestand bleibt auf gleichem Wert

Loesungen:

1. Berichtsintervall-Konfiguration pruefen
2. Ueberpruefen, ob Geraet tatsaechlich berichtet (letzte Verbindung pruefen)
3. Einige Geraete berichten Batterie nur bei bestimmten Ereignissen
4. Telemetrieprotokolle auf GTBAT-Nachrichten ueberpruefen

Geofence loest nicht aus

Symptome: Fahrzeug betritt Zone, aber keine Durchsetzung erfolgt

Loesungen:

1. Ueberpruefen, ob Zone korrekt konfiguriert und aktiv ist
2. Pruefen, ob Zonentyp Durchsetzung unterstuetzt
3. Bestaetigen, dass Fahrt aktiv ist (Zonendurchsetzung gilt nur waehrend Fahrten)
4. Standortgenauigkeit ueberpruefen - GPS kann ungenau sein
5. Zonengrenzen auf Luecken pruefen

Geraet wird als nicht zugeordnet angezeigt

Symptome: Geraet berichtet, erscheint aber in der Liste der nicht zugeordneten Geraete

Loesungen:

1. Geraet im Bereich IoT-Geraete registrieren
2. Ueberpruefen, ob IMEI exakt uebereinstimmt (keine Leerzeichen/Bindestriche)
3. Geraet mit einem Fahrzeug verknuepfen
4. Cache loeschen, falls kuerzlich hinzugefuegt (Cache aktualisiert stuendlich)

Datenspeicherung

Telemetrietabelle

Alle OKAI-Nachrichten werden in der Tabelle vehicle_telemetry gespeichert mit:

• vehicle_uuid - Zugeordnetes Fahrzeug
• imei - Geraetekennung
• raw_payload - Vollstaendige Nachrichtendaten als JSON
• message_type - Befehlstyp (z.B. "GTFRI")
• timestamp - Nachrichten-Zeitstempel
• battery_level, speed, latitude, longitude - Extrahierte Werte

Aufbewahrung

Telemetriedaten werden gemaess der Datenaufbewahrungsrichtlinie Ihres Plans aufbewahrt. Kontaktieren Sie den Support fuer Informationen ueber erweiterte Aufbewahrungsoptionen.

API-Referenz

Endpunkt

POST /api/iot/okai

Header

x-api-key: your-iot-api-key
Content-Type: application/json

Anfragebody

{
  "imei": "867648045123456",
  "message": "+RESP:GTFRI,...",
  "timestamp": "2025-12-25T12:00:00Z"
}

Antwort

{
  "success": true,
  "imei": "867648045123456",
  "messageType": "+RESP",
  "command": "GTFRI",
  "processed": true
}

Health Check

GET /api/iot/okai

Gibt den Servicestatus und eine Liste der unterstuetzten Befehle zurueck.

---