BMW CarData

Wtyczka BMW CarData pobiera dane pojazdu z interfejsu API BMW CarData i udostępnia je jako wejścia w Loxone Config. Każdy pojazd jest konfigurowany jako oddzielne urządzenie podrzędne.

Wymagania: aktywne konto BMW z przypisanym do niego pojazdem, Loxone Miniserver Gen.2 z dostępem do internetu oraz przeglądarka na komputerze do jednorazowej aktywacji. Przełącznik CarData API jest dostępny wyłącznie w portalu internetowym MyBMW pod adresem bmw.com/mybmw — NIE jest on dostępny w aplikacji mobilnej MyBMW.

Kompatybilne pojazdy: zazwyczaj modele BMW od ok. 2017 roku wyposażone w ConnectedDrive. Interfejs API BMW CarData umożliwia maksymalnie 50 zapytań o dane dziennie na pojazd.

Spis treści

• Konfiguracja
• Limit zapytań i komunikaty o błędach
• Sensors and Actuators
• Wejścia, wyjścia, właściwości

Konfiguracja↑

Pierwsza konfiguracja

Wykonaj poniższe kroki po kolei:
1. W przeglądarce na komputerze (aplikacja mobilna MyBMW nie oferuje tej możliwości) otwórz bmw.com/mybmw i zaloguj się przy użyciu swojego konta BMW.
2. Wybierz swój pojazd, a następnie przejdź do: BMW CarData → Technical Access to BMW CarData → CarData API. Aktywuj opcję 'Request access to CarData API' i zaakceptuj warunki udostępniania danych CarData firmy BMW. Portal wyświetli wówczas identyfikator w formacie xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx — skopiuj go do schowka.
3. W Loxone Config dodaj wtyczkę 'BMW CarData' do peryferii sieciowych. Otwórz ustawienia wtyczki za pomocą ikony koła zębatego i wklej identyfikator w polu Client ID. (Jeden identyfikator jest współdzielony przez wszystkie pojazdy skonfigurowane w ramach tej wtyczki.)
4. Kliknij wtyczkę prawym przyciskiem myszy i dodaj urządzenie podrzędne 'BMW Vehicle'. Wprowadź numer VIN — 17-znakowy numer identyfikacyjny pojazdu. Numer VIN znajduje się w dowodzie rejestracyjnym pojazdu, na dolnej krawędzi przedniej szyby oraz w MyBMW → Vehicle overview po wybraniu pojazdu.
5. Połącz wejście Poll Trigger z sygnałem, który ma wyzwalać odświeżenie danych — do szybkiego testu wystarczy przycisk lub wpis Weekly Timer; w środowisku produkcyjnym typowymi źródłami są zdarzenie podłączenia do wallboxa, zmiany stanu ładowania lub dowolne inne zdarzenie automatyzacji. Bez podłączonego Poll Trigger wtyczka nie pobiera żadnych danych.
6. Zapisz konfigurację do Miniservera.
7. Przy pierwszym wyzwoleniu Poll Trigger w Loxone Config oraz w Loxone App pojawi się komunikat systemowy z linkiem autoryzacyjnym. Otwórz link w przeglądarce, zaloguj się przy użyciu swojego konta BMW i potwierdź — kod użytkownika jest już osadzony w linku, więc BMW prosi jedynie o potwierdzenie.
8. Od tej chwili wtyczka pobiera dane pojazdu przy każdym impulsie Poll Trigger. Token dostępu jest przechowywany w Miniserverze i odświeżany automatycznie; nie trzeba logować się ponownie, chyba że dostęp zostanie cofnięty w portalu MyBMW.

Client ID

Client ID jest tworzone raz na konto BMW w portalu internetowym MyBMW pod adresem bmw.com/mybmw (wymagana przeglądarka na komputerze — aplikacja mobilna MyBMW nie posiada tego menu) w sekcji Vehicle overview → BMW CarData → Technical Access to BMW CarData → CarData API. Zaakceptowanie warunków udostępniania danych CarData firmy BMW jest obowiązkowe przy pierwszej aktywacji. Jedno Client ID jest współdzielone przez wszystkie pojazdy skonfigurowane w ramach tej wtyczki i pozostaje ważne do momentu cofnięcia dostępu w tym samym portalu.

Współrzędne domu

Wyjście Odległość od domu jest obliczane jako odległość po ortodromie między współrzędnymi Miniservera a aktualną pozycją GPS pojazdu. Skonfiguruj lokalizację Miniservera w Loxone Config → ustawienia Miniservera → Lokalizacja.

Odpytywanie

Wtyczka nie odpytuje automatycznie — pobiera dane wyłącznie wtedy, gdy wejście Poll Trigger otrzyma zbocze narastające. Połącz je z dowolnym sygnałem, który ma odświeżać dane pojazdu. Do szybkiego testu użyj przycisku lub wpisu Weekly Timer; w środowisku produkcyjnym wykorzystaj zdarzenia takie jak podłączenie do wallboxa, zmiana stanu ładowania lub aktywacja sceny. Pamiętaj o limicie 50 zapytań dziennie na pojazd (patrz Limit zapytań i komunikaty o błędach poniżej).

Autoryzacja

Przy pierwszym użyciu wtyczka wymaga jednorazowej autoryzacji za pomocą Twojego konta BMW. Gdy Poll Trigger zostanie wyzwolony po raz pierwszy, wyjście Wymagana autoryzacja przechodzi w stan 1 i pojawia się komunikat systemowy z linkiem autoryzacyjnym. Otwórz link w przeglądarce, zaloguj się przy użyciu swojego konta BMW i potwierdź — kod użytkownika jest już osadzony w linku, więc BMW prosi jedynie o potwierdzenie. Ten sam komunikat wyświetla również kod użytkownika w postaci tekstowej jako rozwiązanie zapasowe; wprowadź go ręcznie tylko wtedy, gdy strona logowania o niego poprosi (rzadkie). Po pomyślnym zalogowaniu wtyczka pobiera dane, a Wymagana autoryzacja wraca do stanu 0. Token dostępu jest następnie odświeżany automatycznie; ponowne logowanie jest wymagane tylko w przypadku cofnięcia dostępu w portalu MyBMW.

Where the authorization code comes from

You never create this code yourself — not in the MyBMW portal and not on the BMW API or Swagger pages. When the Poll Trigger fires, the plugin automatically requests a one-time code from BMW and shows it to you in two places: in the Loxone App system message (after 'enter the code:'), and in the Authorization URL output as the user_code parameter of the link (https://customer.bmwgroup.com/oneid/link?user_code=...). You normally never type it: the 'Open BMW login' button and the Authorization URL link already contain the code, so BMW only asks you to sign in and confirm. The plain-text code is only a fallback if a login page ever asks for it manually. The code is valid for a few minutes; if it expires before you finish, fire the Poll Trigger again to get a fresh one.

Limit zapytań i komunikaty o błędach↑

Interfejs API BMW CarData umożliwia maksymalnie 50 zapytań o dane dziennie na pojazd. Licznik jest resetowany o północy UTC. Normalne odświeżenie danych zużywa 1 zapytanie. Pierwsze odświeżenie po konfiguracji zużywa jednorazowo jedno lub dwa dodatkowe zapytania w celu wykrycia modelu pojazdu i przygotowania kanału danych — w dniu pierwszej konfiguracji uwzględnij ~3 zapytania.

Nie wyzwalaj więcej niż ~45 odpytań dziennie na pojazd, aby pozostawić zapas na zapytania pierwszego odpytania oraz aktualizacje doraźne.

Komunikaty systemowe

Wtyczka generuje komunikaty systemowe w Loxone Config oraz w Loxone App w następujących sytuacjach: Wymagana autoryzacja — patrz sekcja Autoryzacja powyżej. Osiągnięto limit zapytań — przekroczono limit 50 zapytań/dzień; komunikat pokazuje czas pozostały do północy UTC, kiedy licznik zostanie zresetowany. Błąd połączenia — Miniserver nie może połączyć się z interfejsem API BMW CarData; sprawdź połączenie internetowe. Brak Client ID — w ustawieniach wtyczki nie skonfigurowano Client ID. Nie znaleziono pojazdu — skonfigurowany numer VIN nie jest przypisany do konta BMW lub nie istnieje; sprawdź numer VIN oraz uprawnienia pojazdu w portalu MyBMW.

Sensors and Actuators↑

This section explains what each signal is for. Units and value ranges are listed in the Sensors and Actuators tables above.

Sensors

VIN — the 17-character vehicle identification number; use it to tell several vehicles apart or for logging.
Model — the model name reported by BMW; for display and labeling.
Battery SOC (%) — high-voltage battery state of charge; charge control, low-battery notifications, visualization.
Electric Range (km) — remaining electric range; range warnings, trip planning.
Mileage (km) — odometer reading; service-interval tracking, logging.
Charging (0/1) — 1 while the vehicle is actively charging; PV-surplus logic, notifications, summer cabin ventilation.
Remaining Charge Time (min) — estimated time until full (only meaningful while charging); 'ready by' display, departure planning.
Cable Connected (0/1) — 1 while the charge cable is connected; remind the user to plug in, gate charging automations.
Charging Power (kW) — current charging power; energy monitoring, load management.
Authorization Required (0/1) — 1 while the plugin is waiting for authorization; trigger a reminder.
Authorization URL (Text) — the login link; display it in the Loxone App so the user can authorize.
Distance from Home (km) — air-line distance between the Miniserver location and the vehicle's GPS position. Use it as a coarse 'is the car at home?' indicator, e.g. together with Charging to confirm the car is charging at home. It is not suitable for real-time arrival automations (such as opening the garage), because that would require near-constant polling while the API is limited to 50 requests per day and the plugin only fetches on a Poll Trigger.

Actuators

Poll Trigger — a rising edge fetches fresh vehicle data once. The plugin never polls on its own; drive this from a scheduled time trigger (for example a few times a day), a 'wallbox connected' event, or a button.

Czujniki↑

Aktory↑

Wejścia diagnostyczne↑

Właściwości↑