Dati dell’auto BMW

Il plugin BMW CarData recupera i dati del veicolo dall'API BMW CarData e li mette a disposizione come ingressi in LOXONE Config. Ogni veicolo viene configurato come dispositivo figlio separato.

Requisiti: un account BMW attivo con il veicolo ad esso associato, un LOXONE Miniserver Gen.2 con accesso a Internet e un browser desktop per l'attivazione una tantum. L'interruttore dell'API CarData è disponibile solo nel portale web MyBMW all'indirizzo bmw.com/mybmw — NON è presente nell'app mobile MyBMW.

Veicoli compatibili: tipicamente modelli BMW dal 2017 in poi, con equipaggiamento ConnectedDrive. L'API BMW CarData consente un massimo di 50 richieste di dati al giorno per account BMW, condivise tra tutti i veicoli.

Contenuto

• Configurazione
• Limite di richieste e messaggi di errore
• Sensori e attuatori
• Ingressi, uscite, proprietà

Configurazione↑

Configurazione iniziale

Segui questi passaggi in ordine:
1. In un browser desktop (l'app mobile MyBMW non offre questa funzione), apri bmw.com/mybmw e accedi con il tuo account BMW.
2. Seleziona il tuo veicolo, quindi spostati su: BMW CarData → Technical Access to BMW CarData → CarData API. Attiva 'Request access to CarData API' e accetta i termini di condivisione dei dati CarData di BMW. Il portale mostra quindi un identificativo nel formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx — copialo negli appunti.
3. In LOXONE Config, aggiungi il plugin 'BMW CarData' alla periferia di rete. Apri le impostazioni del plugin tramite l'icona a forma di ingranaggio e incolla l'identificativo nel campo Client ID. (Un unico identificativo è condiviso tra tutti i veicoli configurati con questo plugin.)
4. Fai clic con il tasto destro sul plugin e aggiungi un figlio 'BMW Vehicle'. Inserisci il VIN, ovvero il numero di identificazione del veicolo di 17 caratteri. Il VIN si trova sul documento di immatricolazione del veicolo, sul bordo inferiore del parabrezza e in MyBMW → Vehicle overview quando selezioni il veicolo.
5. Collega l'ingresso Poll Trigger a un segnale che deve attivare un aggiornamento dei dati — per una prova rapida è sufficiente un pulsante; in produzione le sorgenti tipiche sono un evento di collegamento della wallbox, le variazioni dello stato di ricarica o qualsiasi altro evento di automazione. Senza un Poll Trigger collegato il plugin non recupera alcun dato.
6. Salva la configurazione nel Miniserver.
7. La prima volta che il Poll Trigger si attiva, in LOXONE Config e nella LOXONE App compare un messaggio di sistema con un link di autorizzazione. Apri il link in un browser, accedi con il tuo account BMW e conferma — il codice utente è già incorporato nel link, quindi BMW chiede solo la conferma.
8. Il plugin ora recupera i dati del veicolo a ogni impulso del Poll Trigger. Il token di accesso viene memorizzato sul Miniserver e aggiornato automaticamente; non devi accedere di nuovo a meno che non revochi l'accesso nel portale MyBMW.

Client ID

Il Client ID viene creato una sola volta per account BMW nel portale web MyBMW all'indirizzo bmw.com/mybmw (è necessario un browser desktop — l'app mobile MyBMW non dispone di questo menu) alla voce Vehicle overview → BMW CarData → Technical Access to BMW CarData → CarData API. L'accettazione dei termini di condivisione dei dati CarData di BMW è obbligatoria alla prima attivazione. Un unico Client ID è condiviso tra tutti i veicoli configurati con questo plugin e rimane valido finché l'accesso non viene revocato nello stesso portale.

Coordinate di casa

L'output Distanza da Casa viene calcolato come la distanza in linea d'aria tra le coordinate del Miniserver e la posizione GPS attuale del veicolo. Configura la posizione del Miniserver in LOXONE Config → Impostazioni Miniserver → Posizione.

Polling

Il plugin non esegue sondaggi automaticamente: recupera i dati solo quando l'ingresso del Poll Trigger riceve un fronte alto. Collegarlo a qualsiasi segnale che dovrebbe aggiornare i dati del veicolo. Per un test rapido, utilizzare un pulsante; in produzione utilizzare un trigger programmato (alcune volte al giorno), un collegamento wallbox o un cambiamento dello stato di carica. Tenere presente il limite di 50 richieste al giorno per account BMW, condiviso tra tutti i veicoli (vedi Limite di frequenza ed Errori di seguito).

Autorizzazione

Ogni veicolo deve essere autorizzato una volta tramite un account BMW. Il metodo consigliato è tramite l'App LOXONE. Dopo aver aggiunto il veicolo, salvare la configurazione sul Miniserver e attivare il Poll Trigger una volta. Nella App LOXONE e in LOXONE Config viene visualizzato un messaggio di sistema. Mentre l'autorizzazione è in attesa, l'uscita Authorization Required viene impostata a 1. In questo messaggio, selezionare 'Open BMW login' (non il pulsante 'OK'). Questa azione apre il login BMW con un codice di autorizzazione incorporato. L'utente accede con il proprio account BMW e conferma l'accesso. Dopo un'autorizzazione avvenuta con successo, il plugin recupera i dati e l'uscita Authorization Required viene reimpostata a 0. Se OK è stato selezionato accidentalmente o l'autorizzazione fallisce, attivare nuovamente il Poll Trigger per visualizzare di nuovo il messaggio di autorizzazione e riavviare il processo. Dopo un'autorizzazione avvenuta con successo, il token di accesso viene aggiornato automaticamente. La nuova autorizzazione è necessaria solo se l'accesso viene revocato nel portale MyBMW.

Da dove proviene il codice di autorizzazione

Questo codice non viene generato dall'utente, né nel portale MyBMW né nelle pagine dell'API BMW o di Swagger. Quando si attiva il Poll Trigger, il plugin richiede automaticamente un codice monouso a BMW e te lo mostra in due punti: nel messaggio di sistema dell’app LOXONE (dopo «inserisci il codice:») e nell’URL di autorizzazione come parametro user_code del link (https://customer.bmwgroup.com/oneid/link?user_code=...). Normalmente non è necessario digitarlo: il pulsante «Accedi a BMW» e il link dell’URL di autorizzazione contengono già il codice, quindi BMW richiede solo di effettuare l’accesso e confermare. Il codice in testo semplice è solo una soluzione di riserva nel caso in cui una pagina di accesso richieda l’inserimento manuale. Il codice è valido per alcuni minuti; se scade prima che tu abbia terminato, attiva nuovamente il Poll Trigger per ottenere un nuovo codice.

Limite di richieste e messaggi di errore↑

L'API BMW CarData consente un massimo di 50 richieste di dati al giorno per ogni account BMW, condivise tra tutti i veicoli. Il contatore si azzera a mezzanotte UTC. Un normale aggiornamento dei dati consuma 1 richiesta. Il primissimo aggiornamento dopo l'installazione consuma una o due richieste aggiuntive una volta per rilevare il modello del veicolo e preparare il canale dati: prevedi ~3 richieste nel giorno dell'installazione iniziale.

Non attivare più di ~45 sondaggi al giorno in totale su tutti i veicoli dell'account per lasciare spazio per le richieste di primo sondaggio e gli aggiornamenti ad hoc.

Messaggi di sistema

Il plugin genera messaggi di sistema in LOXONE Config e nella LOXONE App nelle seguenti situazioni: Autorizzazione richiesta — vedi la sezione Autorizzazione qui sopra. Limite di richieste raggiunto — la quota di 50 richieste/giorno è stata superata; il messaggio mostra il tempo che manca alla mezzanotte UTC, quando il contatore si reimposta. Errore di connessione — il Miniserver non riesce a raggiungere l'API BMW CarData; verifica la connessione Internet. Client ID mancante — nelle impostazioni del plugin non è stato configurato alcun Client ID. Veicolo non trovato — il VIN configurato non è associato all'account BMW o non esiste; verifica il VIN e i permessi del veicolo nel portale MyBMW.

Errore noto da parte di BMW (non è un problema del plugin): durante l’autorizzazione, BMW potrebbe restituire un errore di sincronizzazione interno — un codice HTTP 500 “Token di accesso non valido” (keymanagement.service.invalid_access_token) immediatamente seguito da access_denied (“L’utente ha rifiutato l’autorizzazione”), anche se sei l’utente principale del veicolo e hai accettato la condivisione dei dati. Il servizio clienti BMW ha confermato che questo problema riguarda principalmente i client CarData appena creati. Soluzione alternativa, interamente nel portale web MyBMW (bmw.com/mybmw): elimina il client CarData, attendi circa 30 secondi, crea un nuovo client, attendi circa 30 secondi, attiva l’API CarData, attendi circa 30 secondi, quindi attiva CarData Streaming. Copiare il nuovo ID cliente nelle impostazioni del plugin e riavviare il Poll Trigger. Se l’errore persiste dopo aver ricreato il client, la responsabilità è interamente da attribuire a BMW: si prega di contattare BMW direttamente (BMW non offre a LOXONE alcun accesso come partner o sviluppatore per risolvere il problema per conto dell’utente).

Sensori e attuatori↑

Questa sezione spiega a cosa serve ciascun segnale. Unità e intervalli di valori sono elencati nelle tabelle dei Sensori e Attuatori sopra.

Sensori

VIN — il numero di identificazione del veicolo composto da 17 caratteri; da utilizzare per distinguere diversi veicoli o per la registrazione dei dati.
Modello — il nome del modello indicato da BMW; per la visualizzazione e l’etichettatura.
SOC batteria (%) — stato di carica della batteria ad alta tensione; controllo della carica, notifiche di batteria scarica, visualizzazione.
Autonomia elettrica (km) — autonomia elettrica residua; avvisi sull’autonomia, pianificazione del viaggio.
Chilometraggio (km) — lettura del contachilometri; monitoraggio degli intervalli di manutenzione, registrazione dei dati.
Ricarica (0/1) — 1 mentre il veicolo è in fase di ricarica; logica di gestione dell’eccedenza fotovoltaica, notifiche, ventilazione dell’abitacolo in estate.
Tempo di ricarica rimanente (min) — tempo stimato fino alla ricarica completa (significativo solo durante la ricarica); visualizzazione “pronto entro”, pianificazione della partenza.
Cavo collegato (0/1) — 1 mentre il cavo di ricarica è collegato; promemoria per l’utente di collegare il cavo, automazioni di ricarica al cancello.
Potenza di ricarica (kW) — potenza di ricarica attuale; monitoraggio dell’energia, gestione del carico.
Autorizzazione richiesta (0/1) — 1 mentre il dispositivo di ricarica è in attesa di autorizzazione; attiva un promemoria.
URL di autorizzazione (Testo) — il link di accesso; visualizzalo nell’app LOXONE in modo che l’utente possa autorizzare.
Distanza da casa (km) — distanza in linea d'aria tra la posizione del Miniserver e la posizione GPS del veicolo. Utilizzarla come indicatore approssimativo per capire se «l’auto è a casa?», ad esempio insieme a «Ricarica» per confermare che l’auto si sta ricaricando a casa. Non è adatta per automazioni in tempo reale all’arrivo (come l’apertura del garage), poiché ciò richiederebbe un polling quasi costante, mentre l’API è limitata a 50 richieste al giorno e il plugin effettua il recupero solo tramite un trigger di polling.

Attuatori

Attivazione tramite polling — un fronte di salita recupera una volta i dati attuali del veicolo. Il plugin non esegue mai il polling autonomamente; è possibile attivarlo tramite una pianificazione (ad esempio, alcune volte al giorno), un evento “caricatore collegato” o un pulsante.

Sensori↑

Attuatori↑

Ingressi di diagnosi↑

Proprietà↑