BMW CarData

De BMW CarData plugin haalt voertuiggegevens op via de BMW CarData API en stelt deze beschikbaar als ingangen in LOXONE Config. Elk voertuig wordt geconfigureerd als een afzonderlijk onderliggend apparaat.

Vereisten: een actief BMW-account waaraan het voertuig is toegewezen, een LOXONE Miniserver Gen.2 met internettoegang en een desktopbrowser voor de eenmalige activering. De CarData API-schakelaar is alleen beschikbaar in het MyBMW-webportaal op bmw.com/mybmw — deze is NIET aanwezig in de mobiele MyBMW-app.

Geschikte voertuigen: doorgaans BMW-modellen vanaf circa 2017 met ConnectedDrive-uitrusting. De BMW CarData API staat maximaal 50 gegevensverzoeken per dag per BMW-account toe, verdeeld over alle voertuigen.

Inhoudsopgave

• Configuratie
• Aanvraaglimiet en foutmeldingen
• Sensoren en Actoren
• Ingangen, uitgangen, eigenschappen

Configuratie↑

Eerste configuratie

Volg deze stappen in de aangegeven volgorde:
1. Open in een browser op je computer (de mobiele MyBMW-app biedt deze functie niet) de pagina bmw.com/mybmw en log in met je BMW-account.
2. Selecteer je auto en ga vervolgens naar: BMW CarData → Technische toegang tot BMW CarData → CarData API. Schakel ‘Toegang tot CarData API aanvragen’ in en ga akkoord met de voorwaarden van BMW voor het delen van CarData-gegevens. Het portaal toont vervolgens een identificatiecode in het formaat xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx — kopieer deze naar het klembord.
3. Voeg in LOXONE Config de plug-in 'BMW CarData' toe aan de netwerkperiferie. Open de instellingen van de plug-in via het tandwielpictogram en plak de identificatiecode in het veld ‘Client-ID’. (Eén identificatiecode geldt voor alle voertuigen die onder deze plug-in zijn geconfigureerd.)
4. Klik met de rechtermuisknop op de plug-in en voeg een onderliggend element ‘BMW-voertuig’ toe. Voer het VIN in — het 17-cijferige voertuigidentificatienummer. Het VIN staat op het kentekenbewijs, aan de onderrand van de voorruit en in MyBMW → Voertuigoverzicht wanneer je het voertuig selecteert.
5. Koppel de Poll Trigger-ingang aan een signaal dat een gegevensvernieuwing moet activeren — voor een snelle test volstaat een drukknop; in de praktijk zijn typische bronnen een gebeurtenis die is gekoppeld aan een wallbox, wijzigingen in de laadstatus of een andere automatiseringsgebeurtenis. Zonder een aangesloten Poll Trigger haalt de plug-in geen gegevens op.
6. Sla de configuratie op in de Miniserver.
7. De eerste keer dat de Poll Trigger wordt geactiveerd, verschijnt er een systeembericht in LOXONE Config en in de LOXONE-app met een autorisatielink. Open de link in een browser, log in met je BMW-account en bevestig — de gebruikerscode is al in de link opgenomen, dus BMW vraagt alleen om bevestiging.
8. De plug-in haalt nu bij elke 'Poll Trigger'-puls voertuiggegevens op. Het toegangstoken wordt opgeslagen op de Miniserver en automatisch vernieuwd; je hoeft niet opnieuw in te loggen, tenzij je de toegang intrekt in het MyBMW-portaal.

Client ID

De Client ID wordt eenmaal per BMW-account aangemaakt in het MyBMW-webportaal op bmw.com/mybmw (desktopbrowser vereist — de mobiele MyBMW-app heeft dit menu niet) onder Vehicle overview → BMW CarData → Technical Access to BMW CarData → CarData API. Het accepteren van de voorwaarden van BMW voor het delen van CarData-gegevens is verplicht bij de eerste activering. Eén Client ID wordt gedeeld door alle voertuigen die onder deze plugin zijn geconfigureerd en blijft geldig totdat de toegang in hetzelfde portaal wordt ingetrokken.

Thuiscoördinaten

De waarde voor ‘Afstand tot woning’ wordt berekend als de grootcirkelafstand tussen de coördinaten van de Miniserver en de huidige GPS-positie van het voertuig. Stel de locatie van de Miniserver in via LOXONE Config → Miniserver-instellingen → Locatie.

Polling

De plug-in voert geen automatische polling uit — hij haalt alleen gegevens op wanneer de ‘Poll Trigger’-ingang een stijgende flank ontvangt. Sluit hem aan op een willekeurig signaal dat de voertuiggegevens moet vernieuwen. Gebruik voor een snelle test een drukknop; in de praktijk kun je een geplande tijdtrigger (een paar keer per dag), het aansluiten van een wallbox of een wijziging in de laadstatus gebruiken. Houd rekening met de limiet van 50 verzoeken per dag per BMW-account, die voor alle voertuigen geldt (zie ‘Rate Limit en foutmeldingen’ hieronder).

Autorisatie

Elk voertuig moet eenmalig worden geautoriseerd via een BMW-account. De aanbevolen methode is via de LOXONE-app. Sla na het toevoegen van het voertuig de configuratie op in de Miniserver en activeer de Poll Trigger één keer. Er verschijnt een systeemmelding in de LOXONE-app en in LOXONE Config. Zolang de autorisatie nog in behandeling is, staat de uitgang ‘Authorization Required’ ingesteld op 1. Selecteer in deze melding ‘Open BMW login’ (niet de knop ‘OK’). Hierdoor wordt de BMW-login geopend met een ingebouwde autorisatiecode. De gebruiker logt in met zijn of haar BMW-account en bevestigt de toegang. Na succesvolle autorisatie haalt de plug-in de gegevens op en wordt de uitgang ‘Authorization Required’ teruggezet naar 0. Als per ongeluk op ‘OK’ is geklikt of de autorisatie mislukt, activeer dan de Poll Trigger opnieuw om het autorisatiebericht opnieuw weer te geven en het proces opnieuw te starten. Na succesvolle autorisatie wordt het toegangstoken automatisch vernieuwd. Herautorisatie is alleen nodig als de toegang in het MyBMW-portaal wordt ingetrokken.

Waar de autorisatiecode vandaan komt

Dit is geen code die u zelf aanmaakt — noch in het MyBMW-portaal, noch op de BMW API- of Swagger-pagina’s. Wanneer de Poll Trigger wordt geactiveerd, vraagt de plug-in automatisch een eenmalige code aan bij BMW en toont deze op twee plaatsen: in het systeembericht van de LOXONE-app (na 'voer de code in:') en in de autorisatie-URL als de parameter user_code van de link (https://customer.bmwgroup.com/oneid/link?user_code=...). Normaal gesproken hoeft u deze niet in te voeren: de knop ‘BMW-login openen’ en de autorisatie-URL bevatten de code al, dus BMW vraagt u alleen om in te loggen en te bevestigen. De code in platte tekst dient alleen als noodoplossing voor het geval een inlogpagina ooit om handmatige invoer vraagt. De code is enkele minuten geldig; als deze verloopt voordat u klaar bent, activeert u de Poll Trigger opnieuw om een nieuwe code te krijgen.

Aanvraaglimiet en foutmeldingen↑

De BMW CarData API staat maximaal 50 gegevensverzoeken per dag per BMW-account toe, verdeeld over alle voertuigen. De teller wordt om middernacht UTC gereset. Een normale gegevensvernieuwing kost 1 verzoek. De allereerste vernieuwing na de installatie kost eenmalig één of twee extra verzoeken om het voertuigmodel te detecteren en het gegevenskanaal voor te bereiden — houd rekening met ongeveer 3 verzoeken op de dag van de eerste installatie.

Voer in totaal niet meer dan ~45 polls per dag uit voor alle voertuigen op het account, zodat er ruimte overblijft voor verzoeken om een eerste poll en ad-hoc-updates.

Systeemberichten

De plugin genereert systeemberichten in LOXONE Config en de LOXONE App voor de volgende situaties: Autorisatie vereist — zie het gedeelte Autorisatie hierboven. Aanvraaglimiet bereikt — het quotum van 50 aanvragen/dag is overschreden; het bericht toont de tijd tot middernacht UTC wanneer de teller wordt teruggezet. Verbindingsfout — de Miniserver kan de BMW CarData API niet bereiken; controleer de internetverbinding. Client ID ontbreekt — er is geen Client ID geconfigureerd in de plugin-instellingen. Voertuig niet gevonden — de geconfigureerde VIN is niet aan het BMW-account toegewezen of bestaat niet; controleer de VIN en de voertuigmachtigingen in het MyBMW-portaal.

Bekende fout aan de kant van BMW (geen fout van de plug-in): tijdens de autorisatie kan BMW een interne synchronisatiefout retourneren — een HTTP 500 ‘Invalid Access Token’ (keymanagement.service.invalid_access_token), onmiddellijk gevolgd door access_denied (‘De gebruiker heeft de autorisatie geweigerd’), ook al ben je de hoofdgebruiker van het voertuig en heb je het delen van gegevens geaccepteerd. De klantenservice van BMW heeft bevestigd dat dit vooral van invloed is op nieuw aangemaakte CarData-clients. Oplossing, volledig via het MyBMW-webportaal (bmw.com/mybmw): verwijder de CarData-client, wacht ~30 seconden, maak een nieuwe client aan, wacht ~30 seconden, activeer de CarData-API, wacht ~30 seconden en activeer vervolgens CarData Streaming. Kopieer de nieuwe client-ID naar de instellingen van de plug-in en activeer de Poll Trigger opnieuw. Als de fout na het opnieuw aanmaken van de client blijft bestaan, ligt dit volledig aan de kant van BMW — neem dan rechtstreeks contact op met BMW (BMW biedt LOXONE geen partner- of ontwikkelaarstoegang om dit voor u op te lossen).

Sensoren en Actoren↑

In dit gedeelte wordt uitgelegd waarvoor elk signaal dient. De eenheden en waardebereiken staan vermeld in de tabellen ‘Sensoren’ en ‘Actoren’ hierboven.

Sensoren

VIN — het 17-cijferige voertuigidentificatienummer; wordt gebruikt om verschillende voertuigen van elkaar te onderscheiden of voor registratiedoeleinden.
Model — de door BMW opgegeven modelnaam; voor weergave en etikettering.
Accu-laadstatus (%) — laadstatus van de hoogspanningsaccu; laadregeling, meldingen bij lage accustand, visualisatie.
Elektrisch bereik (km) — resterend elektrisch bereik; bereikwaarschuwingen, reisplanning.
Kilometerstand (km) — stand van de kilometerteller; bijhouden van onderhoudsintervallen, registratie.
Opladen (0/1) — 1 terwijl het voertuig actief wordt opgeladen; logica voor overtollige PV-energie, meldingen, ventilatie van het interieur in de zomer.
Resterende oplaadtijd (min) — geschatte tijd tot het voertuig volledig is opgeladen (alleen relevant tijdens het opladen); weergave van ‘klaar om’, vertrekplanning.
Kabel aangesloten (0/1) — 1 zolang de oplaadkabel is aangesloten; herinner de gebruiker eraan om de kabel aan te sluiten, activeer oplaadautomatiseringen.
Oplaadvermogen (kW) — huidig oplaadvermogen; energiemonitoring, belastingbeheer.
Autorisatie vereist (0/1) — 1 zolang de stekker wacht op autorisatie; activeer een herinnering.
Autorisatie-URL (tekst) — de inloglink; geef deze weer in de LOXONE-app zodat de gebruiker autorisatie kan verlenen.
Afstand tot huis (km) — grootcirkelafstand tussen de locatie van de Miniserver en de GPS-positie van het voertuig. Gebruik deze waarde als een ruwe indicator om te bepalen of de auto thuis is, bijvoorbeeld in combinatie met ‘Opladen’ om te bevestigen dat de auto thuis wordt opgeladen. Deze waarde is niet geschikt voor realtime automatiseringen bij aankomst (zoals het openen van de garage), omdat daarvoor vrijwel constante polling nodig is, terwijl de API beperkt is tot 50 verzoeken per dag en de plug-in alleen gegevens ophaalt bij een ‘Poll Trigger’.

Actoren

Poll-trigger — bij een stijgende flank worden de actuele voertuiggegevens één keer opgehaald. De plug-in voert nooit zelfstandig een poll uit; activeer dit via een schema (bijvoorbeeld een paar keer per dag), een gebeurtenis ‘lader aangesloten’ of een knop.

Sensoren↑

Actoren↑

Diagnose-ingangen↑

Eigenschappen↑