BMW CarData

Das BMW CarData Plugin ruft Fahrzeugdaten über die BMW CarData API ab und stellt diese als Eingänge in LOXONE Config bereit. Jedes Fahrzeug wird als eigenständiges untergeordnetes Gerät konfiguriert.

Voraussetzungen: ein aktives BMW-Konto, dem das Fahrzeug zugeordnet ist, ein LOXONE Miniserver Gen.2 mit Internetzugang sowie ein Desktop-Browser für die einmalige Aktivierung. Der CarData API-Schalter ist nur im MyBMW Webportal unter bmw.com/mybmw verfügbar — er ist NICHT in der mobilen MyBMW-App vorhanden.

Kompatible Fahrzeuge: In der Regel BMW Modelle ab etwa 2017 mit ConnectedDrive Ausstattung. Die BMW CarData API erlaubt maximal 50 Datenabfragen pro Tag und BMW Konto. Dieses Anfragelimit gilt gemeinsam für alle Fahrzeuge des Kontos.

Inhaltsverzeichnis

• Konfiguration
• Anfragelimit und Fehlermeldungen
• Sensoren und Aktoren
• Eingänge, Ausgänge, Eigenschaften

Konfiguration↑

Ersteinrichtung

Führen Sie die folgenden Schritte der Reihe nach aus:
1. Öffnen Sie in einem Desktop-Browser (die mobile MyBMW-App bietet diese Funktion nicht) die Seite bmw.com/mybmw und melden Sie sich mit Ihrem BMW-Konto an.
2. Wählen Sie Ihr Fahrzeug aus und navigieren Sie zu: BMW CarData → Technischer Zugang zu BMW CarData → CarData API. Aktivieren Sie 'Zugang zur CarData API beantragen' und akzeptieren Sie die CarData-Datenfreigabebedingungen von BMW. Das Portal zeigt anschließend eine Kennung im Format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx an — kopieren Sie diese in die Zwischenablage.
3. Fügen Sie in LOXONE Config das Plugin 'BMW CarData' zur Netzwerkperipherie hinzu. Öffnen Sie die Plugin-Einstellungen über das Zahnrad-Symbol und fügen Sie die Kennung in das Feld Client-ID ein. (Eine Kennung wird für alle unter diesem Plugin konfigurierten Fahrzeuge gemeinsam verwendet.)
4. Klicken Sie mit der rechten Maustaste auf das Plugin und fügen Sie ein untergeordnetes 'BMW Fahrzeug' hinzu. Geben Sie die VIN ein — die 17-stellige Fahrzeug-Identifikationsnummer. Die VIN finden Sie auf dem Fahrzeugschein, am unteren Rand der Windschutzscheibe sowie in MyBMW → Fahrzeugübersicht, wenn Sie das Fahrzeug auswählen.
5. Verbinden Sie den Eingang 'Abruf-Trigger' mit einem Signal, das eine Datenaktualisierung auslösen soll — für einen Schnelltest reicht ein Taster; im Produktivbetrieb sind typische Quellen ein Ereignis bei verbundener Wallbox, Änderungen des Ladezustands oder ein beliebiges anderes Automatisierungsereignis. Ohne einen verbundenen 'Abruf-Trigger' ruft das Plugin keine Daten ab.
6. Speichern Sie die Konfiguration in den Miniserver.
7. Wenn der 'Abruf-Trigger' zum ersten Mal auslöst, erscheint in LOXONE Config und in der LOXONE App eine Systemmeldung mit einem Autorisierungslink. Öffnen Sie den Link im Browser, melden Sie sich mit Ihrem BMW-Konto an und bestätigen Sie — der Benutzercode ist bereits im Link enthalten, sodass BMW nur um Bestätigung bittet.
8. Das Plugin ruft nun bei jedem 'Abruf-Trigger'-Impuls Fahrzeugdaten ab. Das Zugriffstoken wird auf dem Miniserver gespeichert und automatisch aktualisiert; Sie müssen sich nicht erneut anmelden, sofern Sie den Zugriff nicht im MyBMW Portal widerrufen.

Client-ID

Die Client-ID wird einmal pro BMW-Konto im MyBMW Webportal unter bmw.com/mybmw erstellt (Desktop-Browser erforderlich — die mobile MyBMW App verfügt nicht über dieses Menü) unter: Fahrzeugübersicht → BMW CarData → Technischer Zugang zu BMW CarData → CarData API. Das Akzeptieren der CarData-Datenfreigabebedingungen von BMW ist bei der ersten Aktivierung verpflichtend. Eine Client-ID wird für alle unter diesem Plugin konfigurierten Fahrzeuge gemeinsam verwendet und bleibt gültig, bis der Zugriff im selben Portal widerrufen wird.

Heimkoordinaten

Der Ausgang 'Entfernung von Zuhause' wird als Großkreisentfernung zwischen den Koordinaten des Miniservers und der aktuellen GPS-Position des Fahrzeugs berechnet. Konfigurieren Sie den Standort des Miniservers in LOXONE Config → Gerät konfigurieren → Standort.

Abruf

Das Plugin fragt die Daten nicht automatisch ab – sie werden nur abgerufen, wenn der Eingang Poll Trigger eine steigende Flanke erhält. Verbinden Sie den Eingang mit einem beliebigen Signal, das die Fahrzeugdaten aktualisieren soll. Für einen schnellen Test kann ein Taster verwendet werden. Im laufenden Betrieb empfiehlt sich beispielsweise ein zeitgesteuerter Trigger mehrmals täglich, das Anschließen einer Wallbox oder eine Änderung des Ladezustands. Beachten Sie das Limit von 50 Anfragen pro Tag und BMW Konto, das gemeinsam für alle Fahrzeuge gilt (siehe unten Anfragelimit und Fehlermeldungen).

Autorisierung

Jedes Fahrzeug muss einmalig über ein BMW-Konto autorisiert werden. Die empfohlene Vorgehensweise erfolgt über die LOXONE App. Speichern Sie nach dem Hinzufügen des Fahrzeugs die Konfiguration auf dem Miniserver und lösen Sie den 'Abruf-Trigger' einmal aus. In der LOXONE App und in LOXONE Config wird eine Systemmeldung angezeigt. Solange die Autorisierung aussteht, ist der Ausgang 'Autorisierung erforderlich' auf 1 gesetzt. Wählen Sie in dieser Meldung 'BMW-Login öffnen' (nicht die Schaltfläche 'OK'). Dadurch wird der BMW-Login mit einem eingebetteten Autorisierungscode geöffnet. Der Benutzer meldet sich mit seinem BMW-Konto an und bestätigt den Zugriff. Nach erfolgreicher Autorisierung ruft das Plugin die Fahrzeugdaten ab und der Ausgang 'Autorisierung erforderlich' wird auf 0 zurückgesetzt. Falls versehentlich 'OK' ausgewählt wurde oder die Autorisierung fehlschlägt, lösen Sie den 'Abruf-Trigger' erneut aus, um die Autorisierungsmeldung erneut anzuzeigen und den Vorgang neu zu starten. Nach erfolgreicher Autorisierung wird das Zugriffstoken automatisch aktualisiert. Eine erneute Autorisierung ist nur erforderlich, wenn der Zugriff im MyBMW Portal widerrufen wird.

Herkunft des Autorisierungscodes

Diesen Code erstellen Sie nicht selbst — weder im MyBMW Portal noch in der API-Dokumentation (Swagger UI). Wenn der 'Abruf-Trigger' auslöst, fordert das Plugin automatisch einen einmaligen Code von BMW an und zeigt diesen an zwei Stellen an: in der Systemmeldung der LOXONE App (nach 'Code eingeben:') sowie im Ausgang Autorisierungs-URL als Parameter user_code des Links (https://customer.bmwgroup.com/oneid/link?user_code=...). In der Regel müssen Sie diesen Code nicht manuell eingeben: Die Schaltfläche 'BMW Anmeldung öffnen' sowie der Link im Ausgang Autorisierungs-URL enthalten den Code bereits, sodass BMW lediglich die Anmeldung und Bestätigung erfordert. Der Klartext-Code dient nur als Fallback, falls eine Login-Seite eine manuelle Eingabe verlangt. Der Code ist nur wenige Minuten gültig; wenn er vor Abschluss der Anmeldung abläuft, lösen Sie den 'Abruf-Trigger' erneut aus, um einen neuen Code zu erhalten.

Anfragelimit und Fehlermeldungen↑

Die BMW CarData API erlaubt maximal 50 Datenabfragen pro Tag und BMW Konto, die gemeinsam für alle Fahrzeuge gelten. Der Zähler wird täglich um Mitternacht (UTC) zurückgesetzt. Eine normale Aktualisierung der Fahrzeugdaten verbraucht 1 Anfrage. Bei der ersten Aktualisierung nach der Einrichtung werden einmalig ein bis zwei zusätzliche Anfragen benötigt, um das Fahrzeugmodell zu erkennen und den Datenkanal vorzubereiten. Planen Sie daher am Tag der Ersteinrichtung mit etwa 3 Anfragen.

Lösen Sie insgesamt nicht mehr als ca. 45 Abrufe pro Tag für alle Fahrzeuge des BMW Kontos aus, um ausreichend Reserve für die zusätzlichen Anfragen beim ersten Abruf und für spontane Aktualisierungen zu lassen.

Systemmeldungen

Das Plugin erzeugt in LOXONE Config und in der LOXONE App Systemmeldungen für die folgenden Situationen: Autorisierung erforderlich — siehe den Abschnitt Autorisierung weiter oben. Anfragelimit erreicht — das Kontingent von 50 Anfragen/Tag wurde überschritten; die Meldung zeigt die Zeit bis Mitternacht UTC an, zu der der Zähler zurückgesetzt wird. Verbindungsfehler — der Miniserver kann die BMW CarData API nicht erreichen; überprüfen Sie die Internetverbindung. Client-ID fehlt — in den Plugin-Einstellungen wurde keine Client-ID konfiguriert. Fahrzeug nicht gefunden — die konfigurierte VIN ist dem BMW-Konto nicht zugeordnet oder existiert nicht; überprüfen Sie die VIN und die Fahrzeugberechtigungen im MyBMW Portal.

Bekannter BMW-seitiger Fehler (kein Plugin-Fehler): Bei der Autorisierung kann BMW einen internen Synchronisierungsfehler zurückgeben – zunächst einen HTTP 500 'Invalid Access Token' (keymanagement.service.invalid_access_token), unmittelbar gefolgt von access_denied ('The user has declined authorization'). Dies kann auch auftreten, wenn Sie Hauptnutzer des Fahrzeugs sind und der Datenfreigabe zugestimmt haben. Laut BMW Kundenservice betrifft der Fehler überwiegend neu erstellte CarData Clients. Workaround im MyBMW Webportal (bmw.com/mybmw): Löschen Sie den CarData Client, warten Sie ca. 30 Sekunden und erstellen Sie einen neuen Client. Warten Sie erneut ca. 30 Sekunden, aktivieren Sie die CarData API, warten Sie nochmals ca. 30 Sekunden und aktivieren Sie anschließend CarData Streaming. Kopieren Sie die neue Client ID in die Plugin-Einstellungen und lösen Sie den Poll Trigger erneut aus. Besteht der Fehler auch nach dem erneuten Erstellen des Clients, liegt die Ursache vollständig auf BMW-Seite. Wenden Sie sich in diesem Fall direkt an BMW. BMW stellt LOXONE keinen Partner- oder Entwicklerzugang zur Verfügung, über den der Fehler behoben werden könnte.

Sensoren und Aktoren↑

Dieser Abschnitt erklärt, wofür die einzelnen Signale verwendet werden. Einheiten und Wertebereiche sind in den oben aufgeführten Tabellen für Sensoren und Aktoren angegeben.

Sensoren

FIN — Die 17-stellige Fahrzeugidentifikationsnummer; dient zur Unterscheidung mehrerer Fahrzeuge oder zur Protokollierung.
Modell — Der von BMW gemeldete Modellname; zur Anzeige und Beschriftung
Batterie-Ladezustand (%) — Ladezustand der Hochvoltbatterie; für Lademanagement, Warnungen bei niedrigem Ladezustand und Visualisierung.
Elektrische Reichweite (km) — verbleibende elektrische Reichweite; für Reichweitenwarnungen und Routenplanung.
Kilometerstand (km) — Stand des Kilometerzählers; für Wartungsintervalle und Protokollierung.
Lädt (0/1) — 1, während das Fahrzeug aktiv lädt; für PV-Überschusslogik, Benachrichtigungen und z. B. automatisierte Sommerlüftung.
Restladezeit (min) — geschätzte Zeit bis zur vollständigen Ladung (nur während des Ladevorgangs relevant); für 'bereit um'-Anzeige und Abfahrtsplanung.
Kabel verbunden (0/1) — 1, wenn das Ladekabel angeschlossen ist; für Erinnerungen zum Anstecken sowie Steuerung von Ladeautomationen.
Ladeleistung (kW) — aktuelle Ladeleistung; für Energiemonitoring und Lastmanagement.
Autorisierung erforderlich (0/1) — 1, wenn das Plugin auf eine Autorisierung wartet; für Hinweis- und Erinnerungslogik.
Autorisierungs-URL (Text) — Anmeldelink zur Autorisierung; zur Anzeige in der LOXONE App für die Benutzerfreigabe.
Entfernung von Zuhause (km) — Großkreisentfernung zwischen den Koordinaten des Miniservers und der aktuellen GPS-Position des Fahrzeugs. Dient als grober Indikator, ob sich das Fahrzeug zu Hause befindet (z. B. in Kombination mit 'Lädt'). Nicht geeignet für Echtzeit-Automationen wie das Öffnen der Garage, da hierfür eine kontinuierliche Abfrage erforderlich wäre, während die API auf 50 Anfragen pro Tag begrenzt ist und das Plugin ausschließlich über den 'Abruf-Trigger' aktualisiert wird.

Aktoren

Abruf-Trigger — Bei einer steigenden Flanke werden die aktuellen Fahrzeugdaten einmalig abgerufen. Das Plugin führt keine eigenständige Abfrage durch; der Trigger sollte über einen Zeitplan (z. B. mehrmals täglich), ein Ereignis 'Ladegerät angeschlossen' oder eine Schaltfläche ausgelöst werden.

Sensoren↑

Aktoren↑

Diagnose-Eingänge↑

Eigenschaften↑