BMW CarData

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

Voraussetzungen: ein aktives BMW Konto mit dem zugeordneten Fahrzeug, 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 ca. 2017 mit ConnectedDrive Ausstattung. Die BMW CarData API erlaubt maximal 50 Datenabfragen pro Tag und Fahrzeug.

Inhaltsverzeichnis

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

Konfiguration↑

Ersteinrichtung

Führen Sie diese Schritte der Reihe nach aus:
1. Öffnen Sie in einem Desktop-Browser (die mobile MyBMW App bietet dies nicht) bmw.com/mybmw und melden Sie sich mit Ihrem BMW Konto an.
2. Wählen Sie Ihr Fahrzeug aus und navigieren Sie dann: BMW CarData → Technical Access to BMW CarData → CarData API. Aktivieren Sie 'Request access to CarData API' 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 'BMW CarData' Plugin 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. Wählen Sie das Plugin BMW CarData im Peripheriebaum (unter Netzwerkperipherie) aus und klicken Sie oben in der Leiste auf 'Gerät hinzufügen', um ein 'BMW Vehicle' hinzuzufügen. Geben Sie die FIN ein — die 17-stellige Fahrzeug-Identifizierungsnummer. Die FIN befindet sich im Fahrzeugschein, am unteren Rand der Windschutzscheibe sowie in MyBMW → Vehicle overview, wenn Sie das Fahrzeug auswählen.
5. Verbinden Sie den Eingang Poll Trigger mit einem Signal, das eine Datenaktualisierung auslösen soll — für einen kurzen Test genügt ein Taster; im Produktivbetrieb sind typische Quellen ein zeitgesteuerter Trigger (zum Beispiel mehrmals täglich), ein Ereignis bei verbundener Wallbox oder eine Änderung des Ladezustands. Ohne einen verbundenen Poll Trigger ruft das Plugin keine Daten ab.
6. Speichern Sie die Konfiguration in den Miniserver.
7. Wenn der Poll Trigger zum ersten Mal auslöst, erscheint in der Loxone App (und in Loxone Config) eine Systemmeldung. Tippen Sie auf 'BMW Anmeldung öffnen' (nicht auf 'OK'), melden Sie sich mit Ihrem BMW Konto an und bestätigen Sie — der Code ist bereits enthalten, ein Tipp plus Bestätigung genügt. Falls Sie versehentlich auf 'OK' getippt haben, lösen Sie den Poll Trigger erneut aus.
8. Das Plugin ruft nun bei jedem Poll Trigger-Impuls Fahrzeugdaten ab. Das Zugriffstoken wird auf dem Miniserver gespeichert und automatisch erneuert; 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 (Desktop-Browser erforderlich — die mobile MyBMW App verfügt nicht über dieses Menü) unter Vehicle overview → BMW CarData → Technical Access to BMW CarData → CarData API erstellt. 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.

Koordinaten des Zuhauses

Der Ausgang Entfernung von Zuhause wird als Großkreisentfernung zwischen den Koordinaten des Miniservers und der aktuellen GPS-Position des Fahrzeugs berechnet. Stellen Sie den Standort des Miniservers in Loxone Config entweder in den Projekteigenschaften oder in den Miniserver-Einstellungen (Standort) ein.

Abruf

Das Plugin ruft Daten nicht automatisch ab — es holt Daten nur dann, wenn der Eingang Poll Trigger eine steigende Flanke erhält. Verbinden Sie ihn mit einem beliebigen Signal, das die Fahrzeugdaten aktualisieren soll. Für einen kurzen Test verwenden Sie einen Taster; im Produktivbetrieb einen zeitgesteuerten Trigger (mehrmals täglich), das Verbinden einer Wallbox oder eine Änderung des Ladezustands. Beachten Sie das Limit von 50 Anfragen pro Tag und Fahrzeug (siehe Anfragelimit und Fehlermeldungen weiter unten).

Autorisierung

Jedes Fahrzeug wird einmalig mit Ihrem BMW Konto autorisiert — am einfachsten über die Loxone App. Nachdem Sie das Fahrzeug hinzugefügt, in den Miniserver gespeichert und den Poll Trigger einmal ausgelöst haben, erscheint in der Loxone App (und in Loxone Config) eine Systemmeldung; der Ausgang Autorisierung erforderlich ist dabei 1. Tippen Sie in dieser Meldung auf 'BMW Anmeldung öffnen' — nicht auf 'OK'. Der Button öffnet die BMW-Anmeldung mit bereits enthaltenem Code, sodass Sie sich nur anmelden und bestätigen. Das Plugin ruft dann Daten ab und Autorisierung erforderlich kehrt auf 0 zurück. Falls Sie versehentlich auf 'OK' getippt haben oder die Autorisierung fehlschlug, lösen Sie den Poll Trigger erneut aus. Danach wird das Zugriffstoken automatisch erneuert; eine erneute Anmeldung ist nur nötig, wenn Sie den Zugriff im MyBMW Portal widerrufen.

Woher der Autorisierungscode kommt

Sie erzeugen diesen Code nie selbst — weder im MyBMW-Portal noch auf den BMW-API- oder Swagger-Seiten. Wenn der Poll Trigger auslöst, fordert das Plugin automatisch einen Einmal-Code von BMW an und zeigt ihn an zwei Stellen: in der Systemmeldung der Loxone App und im Ausgang Autorisierungs-URL als Parameter user_code des Links (https://customer.bmwgroup.com/oneid/link?user_code=...). Normalerweise tippen Sie ihn nie ein: Der Button 'BMW Anmeldung öffnen' und der Autorisierungs-URL-Link enthalten den Code bereits, sodass BMW Sie nur zur Anmeldung und Bestätigung auffordert. Der Klartext-Code ist nur ein Rückfall, falls eine Anmeldeseite ausdrücklich danach fragt. Der Code ist einige Minuten gültig; läuft er ab, lösen Sie den Poll Trigger erneut aus, um einen neuen zu erhalten.

Anfragelimit und Fehlermeldungen↑

Die BMW CarData API erlaubt maximal 50 Datenabfragen pro Tag und Fahrzeug. Der Zähler wird um Mitternacht UTC zurückgesetzt. Eine normale Datenaktualisierung verbraucht 1 Anfrage. Die allererste Aktualisierung nach der Einrichtung verbraucht einmalig ein oder zwei zusätzliche Anfragen, um das Fahrzeugmodell zu erkennen und den Datenkanal vorzubereiten — rechnen Sie am Tag der Ersteinrichtung mit ca. 3 Anfragen.

Lösen Sie nicht mehr als ca. 45 Abrufe pro Tag und Fahrzeug aus, um Spielraum für die Anfragen des ersten Abrufs und Ad-hoc-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.

Sensoren und Aktoren↑

Dieser Abschnitt erklärt, wofür jedes Signal dient. Einheiten und Wertebereiche stehen in den Tabellen Sensoren und Aktoren.

Sensoren

FIN — die 17-stellige Fahrzeug-Identifizierungsnummer; zum Unterscheiden mehrerer Fahrzeuge oder fürs Logging.
Modell — die von BMW gemeldete Modellbezeichnung; für Anzeige und Beschriftung.
Batterie-Ladezustand (%) — Ladezustand der Hochvoltbatterie; Laderegelung, Niedrigstand-Benachrichtigung, Visualisierung.
Elektrische Reichweite (km) — verbleibende elektrische Reichweite; Reichweitenwarnung, Tourenplanung.
Kilometerstand (km) — Kilometerstand des Fahrzeugs; Service-Intervall-Überwachung, Protokollierung.
Lädt (0/1) — 1, während das Fahrzeug aktiv lädt; PV-Überschuss-Logik, Benachrichtigungen, Innenraumlüftung im Sommer.
Restladezeit (min) — geschätzte Zeit bis voll (nur während des Ladens aussagekräftig); 'Fertig-um'-Anzeige, Abfahrtsplanung.
Kabel verbunden (0/1) — 1, während das Ladekabel verbunden ist; Erinnerung ans Einstecken, Freigabe von Lade-Automationen.
Ladeleistung (kW) — aktuelle Ladeleistung; Energiemonitoring, Lastmanagement.
Autorisierung erforderlich (0/1) — 1, während das Plugin auf die Autorisierung wartet; Hinweis auslösen.
Autorisierungs-URL (Text) — der Anmeldelink; in der Loxone App anzeigen, damit der Nutzer autorisieren kann.
Entfernung von zuhause (km) — Luftlinie zwischen Miniserver-Standort und GPS-Position des Fahrzeugs. Als grober 'Ist das Auto zuhause?'-Indikator nutzbar, z.B. zusammen mit Lädt, um zu bestätigen, dass das Auto zuhause lädt. Nicht geeignet für Echtzeit-Ankunfts-Automationen (etwa Garagentor öffnen), da dafür nahezu permanent gepollt werden müsste — die API ist auf 50 Anfragen pro Tag begrenzt und das Plugin ruft nur bei einem Poll Trigger ab.

Aktoren

Abruf-Trigger — eine steigende Flanke ruft einmalig aktuelle Fahrzeugdaten ab. Das Plugin pollt nie von selbst; steuern Sie ihn über einen zeitgesteuerten Trigger (z.B. mehrmals täglich), ein 'Wallbox verbunden'-Ereignis oder einen Taster.

Sensoren↑

Aktoren↑

Diagnose-Eingänge↑

Eigenschaften↑