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.

Compatible vehicles: typically BMW models from approx. 2017 onwards with ConnectedDrive equipment. The BMW CarData API allows a maximum of 50 data requests per day per BMW account, shared across all vehicles.

Spis treści

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

Konfiguracja↑

Pierwsza konfiguracja

Wykonaj poniższe kroki w podanej kolejności:
1. W przeglądarce na komputerze (aplikacja mobilna MyBMW nie oferuje takiej możliwości) otwórz stronę bmw.com/mybmw i zaloguj się na swoje konto BMW.
2. Wybierz swój pojazd, a następnie przejdź do: BMW CarData → Dostęp techniczny do BMW CarData → CarData API. Aktywuj opcję „Poproś o dostęp do CarData API” i zaakceptuj warunki udostępniania danych CarData przez BMW. Portal wyświetli identyfikator w formacie xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx — skopiuj go do schowka.
3. W LOXONE Config dodaj wtyczkę „BMW CarData” do urządzenia peryferyjnego sieciowego. Otwórz ustawienia wtyczki za pomocą ikony koła zębatego i wklej identyfikator w polu ID klienta. (Jeden identyfikator jest wspólny dla wszystkich pojazdów skonfigurowanych w tej wtyczce).
4. Wybierz wtyczkę BMW CarData w drzewie urządzeń peryferyjnych (w sekcji Urządzenia peryferyjne sieciowe) i kliknij „Dodaj urządzenie” na pasku narzędzi u góry, aby dodać „Pojazd BMW”. 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 → Przegląd pojazdu po wybraniu pojazdu.
5. Podłącz wejście Poll Trigger do sygnału, który powinien wyzwolić odświeżenie danych — do szybkiego testu wystarczy naciśnięcie przycisku; w produkcji typowymi źródłami są zaplanowany wyzwalacz czasowy (na przykład kilka razy dziennie), zdarzenie podłączone do wallboxa lub zmiana stanu ładowania. Bez podłączonego Poll Trigger wtyczka nie pobiera żadnych danych.
6. Zapisz konfigurację na Miniserverze.
7. Przy pierwszym uruchomieniu Poll Trigger w aplikacji LOXONE (i w LOXONE Config) pojawia się komunikat systemowy. Kliknij przycisk „Otwórz logowanie BMW” (nie „OK”), zaloguj się na swoje konto BMW i potwierdź – kod jest już osadzony, więc wystarczy jedno kliknięcie i potwierdzenie. Jeśli kliknąłeś „OK” przez pomyłkę, ponownie uruchom Poll Trigger, aby uruchomić ponownie.
8. Wtyczka pobiera teraz dane pojazdu przy każdym impulsie Poll Trigger. Token dostępu jest przechowywany na Miniserverze i odświeżany automatycznie; nie musisz się ponownie logować, chyba że cofniesz dostęp 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

Wartość „Odległość od domu” jest obliczana jako odległość po wielkim kole między współrzędnymi Miniservera a aktualną pozycją GPS pojazdu. Lokalizację Miniservera należy skonfigurować w LOXONE Config → Ustawienia Miniservera → Lokalizacja.

Odpytywanie

The plugin does not poll automatically — it only fetches data when the Poll Trigger input receives a rising edge. Connect it to any signal that should refresh the vehicle data. For a quick test, use a push-button; in production use a scheduled time trigger (a few times a day), a wallbox connecting, or a charging-state change. Keep in mind the 50-requests-per-day limit per BMW account, shared across all vehicles (see Rate Limit and Error Messages below).

Autoryzacja

Każdy pojazd należy jednorazowo autoryzować za pomocą konta BMW. Zalecaną metodą jest skorzystanie z aplikacji LOXONE. Po dodaniu pojazdu należy zapisać konfigurację w Miniserverze i jednorazowo uruchomić wyzwalacz „Poll Trigger”. W aplikacji LOXONE oraz w LOXONE Config wyświetla się komunikat systemowy. Podczas gdy autoryzacja jest w toku, wyjście „Authorization Required” ma wartość 1. W tym komunikacie należy wybrać opcję „Open BMW login” (a nie przycisk „OK”). Ta czynność otwiera stronę logowania BMW z osadzonym kodem autoryzacyjnym. Użytkownik loguje się na swoje konto BMW i potwierdza dostęp. Po pomyślnej autoryzacji wtyczka pobiera dane, a wyjście „Wymagana autoryzacja” zostaje zresetowane do wartości 0. Jeśli przypadkowo wybrano opcję „OK” lub autoryzacja nie powiodła się, należy ponownie uruchomić Poll Trigger, aby ponownie wyświetlić komunikat o autoryzacji i wznowić proces. Po pomyślnej autoryzacji token dostępu jest automatycznie odświeżany. Ponowna autoryzacja jest wymagana tylko wtedy, gdy dostęp zostanie cofnięty w portalu MyBMW.

Skąd pochodzi kod autoryzacyjny

Nie jest to kod, który użytkownik tworzy samodzielnie — ani w portalu MyBMW, ani na stronach BMW API czy Swagger. Gdy uruchamia się wyzwalacz Poll Trigger, wtyczka automatycznie żąda od BMW kodu jednorazowego i wyświetla go w dwóch miejscach: w komunikacie systemowym aplikacji LOXONE (po napisem „wprowadź kod:”) oraz w adresie URL autoryzacji jako parametr user_code linku (https://customer.bmwgroup.com/oneid/link?user_code=...). Zazwyczaj nie trzeba go wpisywać: przycisk „Otwórz logowanie BMW” oraz link do adresu URL autoryzacji zawierają już ten kod, więc BMW prosi jedynie o zalogowanie się i potwierdzenie. Kod w postaci zwykłego tekstu służy jedynie jako rozwiązanie awaryjne na wypadek, gdyby strona logowania wymagała ręcznego wprowadzenia danych. Kod jest ważny przez kilka minut; jeśli wygaśnie, zanim zakończysz, uruchom ponownie wyzwalacz Poll Trigger, aby uzyskać nowy kod.

Limit zapytań i komunikaty o błędach↑

The BMW CarData API allows a maximum of 50 data requests per day per BMW account, shared across all vehicles. The counter resets at midnight UTC. A normal data refresh consumes 1 request. The very first refresh after setup consumes one or two additional requests once to detect the vehicle model and prepare the data channel — plan for ~3 requests on the initial setup day.

Do not trigger more than ~45 polls per day in total across all vehicles on the account to leave headroom for the first-poll requests and ad-hoc updates.

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.

Known BMW-side error (not a plugin fault): during authorization BMW may return an internal synchronization error — an HTTP 500 'Invalid Access Token' (keymanagement.service.invalid_access_token) immediately followed by access_denied ('The user has declined authorization'), even though you are the vehicle's main user and accepted the data sharing. BMW customer service has confirmed this affects mostly newly created CarData clients. Workaround, all in the MyBMW web portal (bmw.com/mybmw): delete the CarData client, wait ~30 seconds, create a new client, wait ~30 seconds, activate the CarData API, wait ~30 seconds, then activate CarData Streaming. Copy the new Client ID into the plugin settings and fire the Poll Trigger again. If the error persists after recreating the client it is entirely on BMW's side — please contact BMW directly (BMW does not offer LOXONE any partner or developer access to resolve it for you).

Czujniki i aktory↑

W niniejszym rozdziale wyjaśniono, do czego służy każdy sygnał. Jednostki miary i zakresy wartości podano w tabelach „Czujniki” i „Aktory” powyżej.

Czujniki

VIN — 17-znakowy numer identyfikacyjny pojazdu; używaj go do rozróżniania kilku pojazdów lub do rejestrowania.
Model — nazwa modelu podawana przez BMW; do wyświetlania i etykietowania.
Stan naładowania akumulatora (%) — stan naładowania akumulatora wysokonapięciowego; kontrola ładowania, powiadomienia o niskim poziomie naładowania akumulatora, wizualizacja.
Zasięg elektryczny (km) — pozostały zasięg elektryczny; ostrzeżenia o zasięgu, planowanie podróży.
Przebieg (km) — odczyt licznika kilometrów; śledzenie interwałów serwisowych, rejestrowanie.
Ładowanie (0/1) — 1, gdy pojazd jest aktywnie ładowany; logika nadwyżki energii fotowoltaicznej, powiadomienia, letnia wentylacja kabiny.
Pozostały czas ładowania (min) — szacowany czas do naładowania (istotny tylko podczas ładowania); wyświetlanie „gotowy do”, planowanie wyjazdu.
Podłączony kabel ładowania (0/1) — 1, gdy podłączony jest kabel ładowania; przypomnij użytkownikowi o podłączeniu, automatyzacja ładowania bram.
Moc ładowania (kW) — aktualna moc ładowania; monitorowanie energii, zarządzanie obciążeniem.
Wymagana autoryzacja (0/1) — 1, gdy wtyczka oczekuje na autoryzację; wyzwól przypomnienie.
Adres URL autoryzacji (tekst) — link logowania; wyświetl go w aplikacji LOXONE, aby użytkownik mógł dokonać autoryzacji.
Odległość od domu (km) — odległość ortogonalna między lokalizacją Miniservera a pozycją GPS pojazdu. Użyj jej jako wskaźnika „czy samochód jest w domu?”, np. razem z ładowaniem, aby potwierdzić, że samochód ładuje się w domu. Nie nadaje się do automatyzacji przyjazdów w czasie rzeczywistym (takich jak otwieranie garażu), ponieważ wymagałoby to niemal ciągłego sondowania, podczas gdy API jest ograniczone do 50 żądań dziennie, a wtyczka pobiera dane tylko po wyzwoleniu.

Aktory

Pool Trigger — narastające zbocze pobiera aktualne dane pojazdu jednorazowo. Wtyczka nigdy nie przeprowadza odpytywania z własnej inicjatywy; należy ją uruchomić zgodnie z harmonogramem (na przykład kilka razy dziennie), w odpowiedzi na zdarzenie „podłączono ładowarkę” lub za pomocą przycisku.

Czujniki↑

Aktory↑

Wejścia diagnostyczne↑

Właściwości↑