Zum Inhalt springen

VolvoConnect

Aus FHEMWiki
VolvoConnect
Zweck / Funktion
Volvo-Fahrzeugdaten über die Volvo Cars APIs in FHEM lesen und unterstützte Fahrzeugaktionen auslösen.
Allgemein
Typ Inoffizielles Community-Modul; externe Updatequelle.
Details
Dokumentation Installations- und Betriebsanleitung
Modulname 50_VolvoConnect.pm
Ersteller / Betreuung stapetz
Projekt GitHub-Repository
Wichtig: Beachte die zum installierten Modul gehörende englische Beschreibung in der lokalen commandref.

VolvoConnect verbindet ein Volvo-Fahrzeug mit FHEM über die offiziellen Volvo Cars APIs. Du kannst unter anderem Ladezustand, Kilometerstand, Fahrzeugstatus, Diagnosewerte und optional den zuletzt bekannten Standort abrufen. Unterstützte Fahrzeugbefehle und ein eigenes Dashboard ergänzen die Readings.

Das Modul ist ein Community-Projekt und kein von Volvo Cars herausgegebenes oder unterstütztes Produkt. Verfügbarkeit, Aktualität und Umfang hängen von Fahrzeugmodell, Modelljahr, Region, Volvo-Anwendung und genehmigten Berechtigungen ab.

Dieser Artikel beschreibt den stabilen Modulstand 1.1.0. Für aktuelle Freigaben und Änderungen beachte die Änderungshistorie.

Voraussetzungen

  • Eine aktuelle FHEM-Installation mit FHEMWEB und HTTPS-Zugriff auf die Volvo-Endpunkte.
  • Die Perl-Module JSON, MIME::Base64 und Digest::SHA; HttpUtils gehört zu FHEM.
  • Eine Volvo ID mit zugeordnetem Fahrzeug.
  • Die 17-stellige Fahrzeugidentifikationsnummer (VIN).
  • Eine Anwendung im Volvo Cars Developer Portal.
  • VCC API Key, OAuth Client-ID und Client-Secret dieser Anwendung.
  • Eine von Volvo für die Anwendung akzeptierte Redirect-URI.


Die VIN ist nicht die Volvo ID. Ein in der Volvo-App sichtbares Fahrzeug bedeutet nicht automatisch, dass jede Developer-API oder jeder Befehl für deine Anwendung freigeschaltet ist. Maßgeblich sind die aktuellen Volvo-Bedingungen und Freigaben.


Sicherheit und Datenschutz

VolvoConnect verwendet Volvo-Cloud-Dienste. FHEM benötigt dafür Zugangsdaten und OAuth-Tokens.

  • Schütze FHEMWEB mit geeigneter Anmeldung, Rechten und bei Bedarf HTTPS bzw. einem abgesicherten Zugang. Gib die Oberfläche nicht ungeschützt im Internet frei.
  • Behandle client_secret und vcc_api_key wie Passwörter. Sie werden als FHEM-Attribute konfiguriert; FHEM-Konfigurationen und Sicherungen müssen entsprechend geschützt sein.
  • Veröffentliche keine Autorisierungscodes, Tokens, VIN, Standortkoordinaten oder unbereinigten Device-Ausgaben.
  • Aktiviere nur tatsächlich benötigte Daten- und Befehlsbereiche.
  • Fahrzeugbefehle können reale Auswirkungen haben. Prüfe Fahrzeugzustand und Berechtigungen vor der Bedienung.
  • Die Standortkarte und die optionale Adressauflösung können externe Dienste verwenden. Hinweise dazu stehen im Abschnitt Standort.

Anwendung bei Volvo einrichten

  1. Melde dich im Volvo Cars Developer Portal an.
  2. Lege eine Anwendung an und prüfe deren Test-/Produktions- und Regionsbeschränkungen.
  3. Übernimm den VCC API Key sowie OAuth Client-ID und Client-Secret in deine sichere lokale Konfiguration.
  4. Registriere die gewünschte Redirect-URI.
  5. Aktiviere bzw. beantrage die benötigten APIs und Berechtigungen.
  6. Prüfe, ob Anwendung, Volvo ID und Fahrzeug für diesen Zugriff zugelassen sind.

Die Portalbezeichnungen können sich ändern. Die folgenden Schritte beschreiben den Ablauf, nicht eine unveränderliche Bildschirmfolge im Volvo-Portal.

Redirect-URI

Die URI muss in FHEM und im Developer Portal zeichengetreu übereinstimmen: Schema, Host, Port, Pfad und gegebenenfalls abschließender Schrägstrich.

Für lokale Tests wird häufig http://localhost verwendet, sofern Volvo diese URI für deine Anwendung akzeptiert. Das Modul verwendet die manuelle Übergabe des Autorisierungscodes; eine öffentlich erreichbare Callback-Seite ist dafür nicht erforderlich.

Eine nach dem Login nicht erreichbare lokale Zielseite ist für sich genommen noch kein fehlgeschlagener Login: Entscheidend ist, ob die Weiterleitungsadresse einen gültigen code-Parameter enthält. Kopiere niemals den Wert von state anstelle des Codes.

Installation

Erstelle vor Änderungen eine Sicherung deiner FHEM-Installation.

Gib diese Befehle in die FHEM-Befehlszeile ein, nicht in ein Betriebssystemterminal: 

update add https://raw.githubusercontent.com/stapetz/fhem-modules/main/controls_volvo.txt
update all https://raw.githubusercontent.com/stapetz/fhem-modules/main/controls_volvo.txt
shutdown restart


Die Adresse zeigt bewusst auf eine Controls-Datei, nicht direkt auf die Perl-Datei. update add registriert die Quelle; update all lädt die zugehörigen Dateien. Der Neustart unterbricht FHEM kurz.


Für den produktiven Einsatz verwendest du main. Entwicklungsstände aus dev sind nur für bewusst durchgeführte Tests vorgesehen.

Device anlegen und konfigurieren

Beispiel für ein Device namens Volvo1: 

define Volvo1 VolvoConnect
attr Volvo1 vin <17-stellige-VIN>
attr Volvo1 client_id <Client-ID>
attr Volvo1 client_secret <Client-Secret>
attr Volvo1 vcc_api_key <VCC-API-Key>
attr Volvo1 redirect_uri http://localhost

Ersetze die Platzhalter einschließlich der spitzen Klammern durch deine Werte. Passe die Redirect-URI an die tatsächlich registrierte URI an. Speichere die FHEM-Konfiguration und halte sie vertraulich.

Benötigte Datenbereiche auswählen

Öffne die grafische Auswahl: 

get Volvo1 _showEntityConfig

Alternativ setzt du die Attribute direkt, beispielsweise: 

attr Volvo1 scope_battery_charge 1-aktiviert
attr Volvo1 scope_odometer 1-aktiviert
attr Volvo1 scope_engine_status 1-aktiviert

Nicht gesetzte scope_*-Attribute sind deaktiviert. Konfiguriere die benötigten Bereiche möglichst vor der Anmeldung.


Scope-Änderungen erfordern eine neue Anmeldung. Eine Änderung der Scope-Auswahl löscht die bestehende Autorisierung; anschließend musst du dich erneut bei Volvo anmelden. Das Aktivieren in FHEM erteilt keine fehlende Berechtigung im Developer Portal.


Attribute Daten / Funktion
scope_capabilities Fahrzeugfähigkeiten und unterstützte Energiefunktionen.
scope_vehicle_relation Modell, Modelljahr, Fahrzeugdetails und Bild-URLs.
scope_battery_charge, scope_fuel Batterie- und Kraftstoffdaten; der Batteriebereich aktiviert ebenfalls den Fuel-Abruf.
scope_odometer, scope_statistics Kilometerstand, Fahrt- und Verbrauchsstatistik.
scope_warnings, scope_brakes Warnungen und Bremsstatus.
scope_doors, scope_windows Tür-, Verriegelungs- und Fensterstatus.
scope_engine_status Motorstatus.
scope_tyres Reifendaten.
scope_engine_diagnostics, scope_workshop_diagnostics Motor-, Werkstatt- und Wartungsinformationen.
scope_location Standortdaten und Karte.
scope_commands, scope_command_accessibility Befehlsliste und aktuelle Befehlsverfügbarkeit.
scope_lock, scope_unlock Ver- und Entriegeln.
scope_honk_flash Hupe-/Lichtsignalbereich.
scope_climatization, scope_engine_commands Klimatisierung, Motorbefehle und Vorkonditionierung, soweit unterstützt.

Anmeldung mit OAuth2 und PKCE

  1. Starte die Anmeldung mit set Volvo1 reauth.
  2. Öffne den angebotenen Volvo-Login-Link am Gerätestatus.
  3. Melde dich mit der passenden Volvo ID an und bestätige die angeforderten Berechtigungen.
  4. Lies nach der Weiterleitung die Adresse aus.
  5. Kopiere nur den Wert des URL-Parameters code, nicht die komplette Adresse und nicht den state-Wert.
  6. Übergib den Code zeitnah an FHEM.
set Volvo1 authCode <Autorisierungscode>

Der Code ist kurzlebig und nur einmal verwendbar. Bei einem Fehler wiederholst du den vollständigen Login mit einem neuen Code.

Prüfe anschließend: 

get Volvo1 summary
get Volvo1 tokenInfo
get Volvo1 scopes
set Volvo1 update

tokenInfo zeigt Vorhandensein und Gültigkeit der Tokens, nicht deren Werte. Access- und Refresh-Tokens werden im FHEM-Key-Value-Store gespeichert. Das Modul erneuert Access-Tokens bei Bedarf automatisch mit dem gespeicherten Refresh-Token.

Wird die Erneuerung von Volvo abgelehnt, ist eine neue interaktive Anmeldung erforderlich. Prüfe lastError und führe reauth aus. Nach Änderungen an Client-ID, Client-Secret, API-Key oder Scopes autorisierst du ebenfalls neu.

Datenabruf und Intervalle

Einstellung Standard Typische Daten
interval 300 Sekunden Energie-/Ladestatus, Kilometerstand, Statistik, Warnungen und weitere dynamische Zustände.
interval_slow 1800 Sekunden Reifen-, Motor- und Werkstattdiagnose.
interval_location 900 Sekunden Standort.
Statische Endpunkte Einmal je VIN Fähigkeiten, Befehlsliste und Fahrzeugdetails.

Beispiel: 

attr Volvo1 interval 300
attr Volvo1 interval_slow 1800
attr Volvo1 interval_location 900

Erfolgreiche Endpoint-Abrufe werden zwischengespeichert; ihre Zeitpunkte bleiben über einen FHEM-Neustart erhalten. Ein manueller Abruf übergeht die Intervallplanung und fordert alle aktivierten Endpunkte an: 

set Volvo1 update

Damit kannst du auch statische Fahrzeugdetails und befristete Bild-URLs neu laden. Reduziere die Intervalle nicht unnötig: Volvo kann Abfragen begrenzen, und häufigeres Polling macht veraltete Backendwerte nicht automatisch aktueller.

Readings verstehen

Readings entstehen abhängig von Scopes und API-Antworten dynamisch. Verschachtelte JSON-Felder werden mit Unterstrichen abgeflacht; Einheiten können in zusätzlichen _unit-Readings erscheinen.

Reading / Präfix Bedeutung
authStatus Authentifizierungsstatus.
lastUpdate Letzter erfolgreicher Datenabruf.
lastError, lastErrorCode Letzter bekannter Fehler.
state_* Energie- und Ladezustandsdaten, etwa state_batteryChargeLevel.
doors_*, windows_*, warnings_* Karosseriestatus und Warnungen.
fuel_*, batteryCharge_*, odometer_*, statistics_* Energie-, Fahrt- und Fahrzeugwerte.
engine_*, engineDiagnostics_*, workshopDiagnostics_*, tyres_* Motor-, Diagnose- und Reifendaten.
vehicle_*, capabilities_* Fahrzeugdetails und Fähigkeiten.
location_* Standort und gegebenenfalls Adressdaten.
commands_*, commandAccessibility_* Befehle und deren Verfügbarkeit.
command_state, last_command Status des zuletzt gesendeten Fahrzeugbefehls.

Ein fehlendes Reading bedeutet nicht automatisch einen Modulfehler. Prüfe Scope, Fahrzeugunterstützung und Volvo-Freigabe. Ein erfolgreicher API-Abruf ist außerdem nicht zwingend eine aktuelle Messung direkt am Fahrzeug.

Fahrzeugbefehle

Achtung: Die folgenden Befehle lösen reale Fahrzeugaktionen aus. Verwende sie nur bewusst und unter geeigneten Bedingungen. API- oder Fahrzeugbeschränkungen lassen sich nicht durch wiederholtes Senden umgehen.


FHEM-Befehl Wirkung
set Volvo1 lock / set Volvo1 unlock Verriegeln / Entriegeln.
set Volvo1 horn Hupe betätigen.
set Volvo1 climate / set Volvo1 climate_stop Klimatisierung starten / stoppen.
set Volvo1 charge_start / set Volvo1 charge_stop Laden starten / stoppen.
set Volvo1 charge_limit 80 Zielladestand setzen; Modulwertebereich 10 bis 100 Prozent, Fahrzeugunterstützung vorausgesetzt.
set Volvo1 precondition Vorkonditionierung anfordern.

Die passenden Scopes müssen aktiviert und autorisiert sein. Eine unmittelbare FHEM-Rückmeldung über die Übergabe bedeutet noch nicht, dass die Aktion am Fahrzeug erfolgreich abgeschlossen ist. Prüfe danach command_state, last_command und den tatsächlichen Fahrzeugzustand.

Dashboard

get Volvo1 _showDashboard
get Volvo1 _dashboardURL

Das Dashboard gruppiert Messwerte und Zustände in Kacheln und bietet unterstützte Fahrzeugaktionen. Bei aktiviertem Standortbereich erscheint eine Standortkachel mit Karte.

  • Bearbeiten ist beim Aufruf über _showDashboard verfügbar.
  • Dort kannst du Kacheln und einzelne Readings ein-/ausblenden sowie Labels und Reihenfolgen speichern.
  • Die isolierte Dashboard-URL ist nicht editierbar und zeigt keinen Bearbeitungsstift.
  • Die Vier-Wege-Pfeile aktivieren den kompakten Verschiebemodus.
  • Das responsive Mehrspaltenlayout zeigt die gespeicherte Reihenfolge spaltenweise, nicht als starres zeilenweises Raster.
  • Die Konfiguration wird je Device im FHEM-Key-Value-Store gespeichert.

Die Adresse liegt unter deinem FHEMWEB-Pfad, beispielsweise /fhem/VolvoConnect/Volvo1. Verwende bevorzugt den vom Modul gelieferten Link.

Einbettung in andere Oberflächen

Die relative Fragmentadresse erhältst du mit: 

get Volvo1 _dashboardEmbedURL

Der Parameter embed=1 liefert ein HTML-Fragment für geeignete Oberflächen. Eine einfache Iframe-Einbindung der vollständigen Seite ist beispielsweise: 

<iframe src="/fhem/VolvoConnect/Volvo1" style="width:100%;height:900px;border:0"></iframe>

Passe FHEMWEB-Pfad und Device-Namen an. Anmeldung, Browserregeln und die Möglichkeiten der Zieloberfläche gelten weiterhin. Die weiterführenden FTUI-Beispiele in der Repositorydokumentation sind nicht als getestete FTUI-Installation zugesichert.

Standort und Adressauflösung

Die Location API liefert den zuletzt bekannten Standort, keine Live-Ortung.


Bei aktivem scope_location ist die zusätzliche Adressauflösung standardmäßig eingeschaltet: Neue Koordinaten werden an OpenStreetMap Nominatim übermittelt. Wenn du das nicht möchtest, deaktiviere die externe Adressabfrage: 

attr Volvo1 location_reverse_geocode 0

Das deaktiviert die zusätzliche Adressauflösung, nicht den Volvo-Standortabruf. Soll das Modul auch keine Standortdaten von Volvo abrufen, deaktiviere den Standort-Scope und autorisiere die geänderte Auswahl neu.

Updates und Sicherungen

Für spätere stabile Updates: 

update all https://raw.githubusercontent.com/stapetz/fhem-modules/main/controls_volvo.txt
shutdown restart

Prüfe das Updateprotokoll und danach das Internal VERSION. Lade Dashboardseiten vollständig neu.

Sichere zusammengehörig:

  • FHEM-Device-Definition und Attribute.
  • Die FHEM-Konfiguration.
  • Den FHEM-Key-Value-Store für Tokens, Abrufzustände und Dashboardkonfiguration.
  • Einen nachvollziehbaren Modulstand.

Sicherungen können Zugangsdaten enthalten und müssen geschützt werden. Bei einem Umzug prüfst du Redirect-URI, Netzwerkerreichbarkeit und Volvo-Portal-Konfiguration.

set Volvo1 reauth entfernt die Tokens und startet die Anmeldung neu; Device-Attribute und Dashboardkonfiguration werden dadurch nicht zurückgesetzt.

Häufige Probleme

Problem Prüfung / Abhilfe
Gerät bleibt bei auth_required VIN, Clientdaten, API-Key, Redirect-URI und Fahrzeugfreigabe prüfen; mit reauth neu anmelden.
OAuth-Code abgelehnt Frischen Code verwenden; nur den code-Wert kopieren. Redirect-URI und Scopes prüfen.
Nach Scope-Änderung keine Daten Erneute Volvo-Autorisierung erforderlich.
Wenige oder fehlende Readings get Volvo1 scopes, Fahrzeugunterstützung und Volvo-Freigabe prüfen; anschließend set Volvo1 update.
Daten oder Standort wirken veraltet Aktualität des Volvo-Backends und langsamere Intervalle beachten; kein Live-Ortungssystem.
Fahrzeugbefehl wirkt nicht Scope, Autorisierung, Verfügbarkeit, Fahrzeugzustand und command_state prüfen.
Fahrzeugbild nicht mehr sichtbar Befristete Bild-URL mit set Volvo1 update neu abrufen.
Dashboard lässt sich nicht bearbeiten Über get Volvo1 _showDashboard öffnen, nicht über die isolierte Dashboard-URL.
Token-Erneuerung schlägt fehl lastError prüfen und gegebenenfalls vollständig neu anmelden.

Für eine lesende Diagnose: 

get Volvo1 summary
get Volvo1 tokenInfo
get Volvo1 scopes

Veröffentliche Ausgaben nur bereinigt. Insbesondere vollständige Device-Listen und Konfigurationsdateien können geheime Attribute oder private Fahrzeugdaten enthalten.

Dokumentation und Support

Beschreibe bei Fehlerberichten Modulversion, erwartetes und tatsächliches Verhalten sowie reproduzierbare Schritte und bereinigte Fehlermeldungen. Nenne keine Zugangsdaten, Autorisierungscodes, Tokens, VIN oder Standortdaten.

Abgerufen von „http://wiki.fhem.de/w/index.php?title=VolvoConnect&oldid=41370“