Moin liebe FHEM Gemeinde.
Volvo ändert immer wieder gerne was an der API und das mir zuletzt bekannte Modul auf Basis von fhempy (https://forum.fhem.de/index.php?topic=132504) wollte auch nicht mehr so richtig.
Zwischenzeitlich hatte ich mir extra ein HomeAssistant aufgebaut, nur um von dort die Volvo Daten per MQTT nach fhem zu holen. War funktional ok, aber auch nicht so toll.
Daher habe ich mich mit meinem KI Freund in Visual Studio zusammengesetzt und ein neues Volvo Modul geschrieben. Das findet ihr hier nebst Doku im Anhang.
Ich suche mögliche Mitstreiter, um das voranzubringen.
Vorteil der Lösung:
- kein fhempy notwendig
- in meinen Augen simpel zu bedienen
- Access Token kann direkt aus der Oberfläche beim Device erzeugt werden
- Refresh des Tokens erfolgt alle 50 Minuten automatisch (das Intervall kann aber in einem Attribut selber angepasst werden, default 300 Sekunden)
Nicht so schön:
- die ReturnURL vom OUTH2 von Volvo kann so nicht einfach ausgewertet werden
--> heisst beim Klick auf den Button in der DeviceOberfläche für den Erhalt
eines Tokens erhält man einen NotFound Fehler im Browser, kann aber dann
aus der BrowserZeile den CODE einfach rauskopieren und in das entsprechende
Attribut beim Device eintragen
Würde das gerne noch weiter entwickeln und ggf. auch auf GIT übertragen. Stelle das jetzt aber erstmal hier so zur Verfügung.
Das Ganze läuft meinem meinem XC40 Recharge einwandfrei. Über Rückmeldungen zu anderen Modellen würde ich mich freuen.
Bei Fragen / Wünschen / Anregungen gerne auf mich zukommen.
Dokumentation:
# FHEM VolvoConnect Modul - Dokumentation
## Inhaltsverzeichnis
1. [Überblick](#überblick)
2. [Voraussetzungen bei Volvo](#voraussetzungen-bei-volvo)
3. [Installation](#installation)
4. [Device-Erstellung](#device-erstellung)
5. [Konfiguration](#konfiguration)
6. [Befehle](#befehle)
7. [Readings](#readings)
8. [Troubleshooting](#troubleshooting)
---
## Überblick
Das **VolvoConnect**-Modul ermöglicht die Verbindung deines FHEM-Systems mit einem Volvo-Fahrzeug über die offizielle Volvo Cars API. Du kannst damit:
- 🔋 **Batteriestand** und **Reichweite** abfragen
- ⚡ **Ladevorgänge** starten/stoppen und Limits setzen
- 🔒 **Türen verriegeln/entriegeln**
- 🎯 **Klimaanlage** steuern
- 📊 **Detaillierte Fahrzeuginformationen** auslesen
---
## Voraussetzungen bei Volvo
### 1. Volvo ID erstellen
1. Gehe zu **[my.volvocars.com](https://my.volvocars.com)** oder öffne die **Volvo Cars App**
2. Registriere dich oder melde dich an
3. Bestätige deine Emailadresse und Telefonnummer
4. Speichere deine **Volvo ID** (Email/Benutzername)
### 2. Connected Services aktivieren
1. In der **Volvo App** oder auf **[volvoid.eu.volvocars.com](https://volvoid.eu.volvocars.com)**
2. Gehe zu **Einstellungen → Datenschutz & Datensicherheit**
3. Aktiviere: **"Connected Services"** oder **"API Access"**
4. Akzeptiere die Nutzungsbedingungen
### 3. Developer Portal registrieren
1. Öffne **[developer.volvocars.com](https://developer.volvocars.com)**
2. Registriere dich mit deiner **Volvo ID**
3. Gehe zu **"Apps"** → **"Create New App"**
4. Gehe zu **Your API applications" und veröffentliche die APP
4. Fülle folgende Angaben aus:
- **Name**: z.B. "FHEM Integration"
- **Description**: z.B. "Home Automation with FHEM"
- **Redirect URI**: `https://fhem.fritz.box/redirect` (oder deine FHEM-URL) --> muss https sein
### 4. Credentials generieren
Nach der App-Erstellung erhältst du folgende Werte. **Speichere diese sicher ab!** ✅
| Parameter | Beschreibung | Beispiel |
|-----------|------------|---------|
| **Client ID** | OAuth2 Client Identifier | `ClientID` |
| **Client Secret** | OAuth2 Secret für Token-Austausch | `ClientSecret` |
| **VCC API Key** | Volvo Cars Connected Services API Key | `VCCApiKey` |
⚠️ **Sicherheit:** Diese Werte sind sensibel! Geben Sie sie nicht weiter.
### 5. VIN des Fahrzeugs ermitteln
Die **VIN** (Fahrzeugidentnummer) findest du:
- Im **Fahrzeugschein** (Punkt 3)
- In der **Volvo App** unter Fahrzeugdetails
- Auf dem **Typenschild** im Motorraum
Beispiel: `HereIsYourVehiceNumber_VIN` (17-stellig)
---
## Installation
### Modul kopieren
Kopiere die Datei `50_VolvoConnect.pm` in das FHEM-Verzeichnis:
```bash
cp 50_VolvoConnect.pm /opt/fhem/FHEM/
```
Oder über die FHEM-Weboberfläche:
1. **Bearbeiten** → **Datei-Editor**
2. Neue Datei erstellen: `/opt/fhem/FHEM/50_VolvoConnect.pm`
3. Code einfügen und speichern
### FHEM neu starten
```bash
service fhem restart
# oder in FHEM-Shell:
restart
```
---
## Device-Erstellung
### Über die FHEM-Shell oder Web-UI
```fhem
define MeinElch VolvoConnect
```
Nach der Erstellung werden **automatisch Platzhalter-Attribute** gesetzt. Du siehst folgende Error-Message:
```
Please replace dummy values for: vin, client_id, client_secret, vcc_api_key, redirect_uri
```
Das ist **normal** und erwartet! 👍
---
## Konfiguration
### Erforderliche Attribute
Bearbeite die Attribute in der FHEM-UI oder via Befehl:
#### 1. **VIN** (Fahrzeugidentnummer)
Deine 17-stellige Fahrzeugidentnummer aus der Volvo App:
```fhem
attr MeinElch vin MyVIN_GetFromVolvoOrFromYourCar
```
#### 2. **Client ID**
Aus dem Developer Portal (unter "App Details"):
```fhem
attr MeinElch client_id <ClientID>
```
#### 3. **Client Secret**
Aus dem Developer Portal (unter "App Details"):
```fhem
attr MeinElch client_secret <ClientSecret>
```
#### 4. **VCC API Key**
Aus dem Developer Portal (unter "API Keys"):
```fhem
attr MeinElch vcc_api_key <VCCApiKey>
```
#### 5. **Redirect URI**
Die muss **exakt** mit der im Developer Portal eingetragenen URI übereinstimmen:
```fhem
attr MeinElch redirect_uri https://fhem.fritz.box/redirect
```
> ⚠️ **Wichtig**: Falls FHEM nicht auf `fhem.fritz.box` erreichbar ist, trage die richtige URL ein (z.B. `https://192.168.1.100:8083/redirect`)
#### 6. **Abfrageintervall** (optional)
Standard: 300 Sekunden (5 Minuten). Volvo limitiert auf ca. 1 Anfrage pro Minute.
```fhem
attr MeinElch interval 300
```
### Konfigurationsbeispiel (Komplett)
```fhem
define MeinElch VolvoConnect
attr MeinElch vin <VIN>
attr MeinElch client_id <ClientID>
attr MeinElch client_secret <ClientSecret>
attr MeinElch vcc_api_key <VCCApiKey>
attr MeinElch redirect_uri https://fhem.fritz.box/redirect
attr MeinElch interval 300
attr MeinElch room Auto
attr MeinElch verbose 3
```
---
## Authentifizierung
### Erste OAuth2-Anmeldung
Nach der Konfiguration zeigt das Device folgenden State:
```
Initialization required. Bitte Code generieren und mit set MeinElch authCode <code> eintragen.
🔐 Bei Volvo anmelden / Token generieren
```
**Schritte:**
1. **Klicke auf den Link** "🔐 Bei Volvo anmelden / Token generieren"
2. Du wirst zu Volvo ID weitergeleitet
3. **Melde dich an** mit deinen Volvo-Credentials
4. **Bestätige die Berechtigung** für die angeforderten Scopes
5. Nach erfolgreicher Autorisierung wirst du weitergeleitet
6. **Kopiere den Authorization Code** aus der URL (Parameter `code=XXXXX`)
### Code eingeben
Paste den Code in diesen Befehl:
```fhem
set MeinElch authCode <authCodeAusRedirectURL_inBrowserZeile>
```
Das System tauscht den Code automatisch gegen einen **Access Token** ein und speichert ihn.
> ✅ Nach erfolgreicher Authentifizierung werden Daten alle 5 Minuten automatisch abgerufen.
---
## Befehle
### Fahrzeugkontrolle
#### 🔒 Türen verriegeln
```fhem
set MeinElch lock
```
#### 🔓 Türen entriegeln
```fhem
set MeinElch unlock
```
#### 📢 Hupe betätigen
```fhem
set MeinElch horn
```
### Laden steuern
#### ⚡ Ladeprozess starten
```fhem
set MeinElch charge_start
```
#### ⏹ Ladeprozess stoppen
```fhem
set MeinElch charge_stop
```
#### 🎯 Ladengrenze setzen (10-100%)
```fhem
set MeinElch charge_limit 80
```
**Beispiele:**
- `set MeinElch charge_limit 100` - Vollladung
- `set MeinElch charge_limit 80` - 80% Limit (Standard)
- `set MeinElch charge_limit 50` - 50% für Kurztrips
### Klimaanlage
#### ❄️ Klimaanlage starten (16-30°C)
```fhem
set MeinElch climate 21
```
**Beispiele:**
- `set MeinElch climate 16` - Kalt
- `set MeinElch climate 21` - Angenehm (Standard)
- `set MeinElch climate 25` - Warm
- `set MeinElch climate 30` - Sehr warm
#### ❌ Klimaanlage ausschalten
```fhem
set MeinElch climate_stop
```
### Wartung
#### 🔥 Vorkonditionierung starten (Wärmepumpe)
Wärmt das Auto vor, während es lädt. Nutzt Strom vom Netz, nicht von der Batterie.
```fhem
set MeinElch precondition
```
#### 🔄 Manuelles Update erzwingen
Lädt sofort die Daten, ohne auf das Intervall zu warten:
```fhem
set MeinElch update
```
---
## Readings
### Hauptinformationen
| Reading | Beschreibung | Beispiel |
|---------|-------------|---------|
| `state` | Gerätestatus | `vehicle_state_fetched`, `all_data_fetched` |
| `state_batteryChargeLevel` | Batteriestand in % | `100` |
| `state_electricRange` | Reichweite in km | `400` |
| `state_targetBatteryChargeLevel` | Zielladung in % | `80` |
### Ladestatus
| Reading | Beschreibung | Mögliche Werte |
|---------|-------------|---------|
| `state_chargingStatus` | Ladestatus | `DONE`, `ONGOING`, `STOPPED` |
| `state_chargingType` | Ladetyp | `AC` (Wechselstrom), `DC` (Gleichstrom) |
| `state_chargerConnectionStatus` | Steckerverbindung | `CONNECTED`, `DISCONNECTED` |
| `state_chargerPowerStatus` | Stromliefer-Status | `PROVIDING_POWER`, `CHARGING_STOPPED` |
| `state_estimatedChargingTimeToTargetBatteryChargeLevel` | Zeit bis Zielladung | `0` (sofort), `120` (2 Stunden) |
| `state_chargingSystemStatus` | Ladesystem OK? | `OK`, `ERROR` |
| `state_chargingPower` | Aktuelle Ladeleistung | `5500` (Watt) |
### Fahrzeugfunktionen (Capabilities)
Diese Readings zeigen, welche Funktionen dein Auto unterstützt:
| Reading | Beschreibung | Wert |
|---------|-------------|------|
| `capabilities_getEnergyState_batteryChargeLevel_isSupported` | Batterie abfragbar | `1` = ja, `0` = nein |
| `capabilities_getEnergyState_chargerConnectionStatus_isSupported` | Stecker-Status abfragbar | `1` = ja, `0` = nein |
| `capabilities_getEnergyState_chargingSystemStatus_isSupported` | Ladesystem Status abfragbar | `1` = ja, `0` = nein |
| `capabilities_getEnergyState_chargingPower_isSupported` | Ladeleistung abfragbar | `1` = ja, `0` = nein |
| `capabilities_getEnergyState_targetBatteryChargeLevel_isSupported` | Zielladung setzbar | `1` = ja, `0` = nein |
| `capabilities_getEnergyState_electricRange_isSupported` | Reichweite abfragbar | `1` = ja, `0` = nein |
### Authentifizierung
| Reading | Beschreibung |
|---------|-------------|
| `login_url` | OAuth2-Login URL (klickbar) |
| `accessToken` | Aktueller Access Token (versteckt in Logs) |
| `refreshToken` | Refresh Token (versteckt in Logs) |
| `tokenValidUntil` | Gültigkeit des Tokens (Unix Timestamp) |
---
## Weitere Ressourcen
- **Volvo Developer Docs**: https://developer.volvocars.com/docs
- **Volvo Cars Connected Services API**: https://developer.volvocars.com/apis
- **FHEM Forum**: https://forum.fhem.de/
- **FHEM Dokumentation**: https://fhem.de/
- **Volvo Connected Services**: https://www.volvocars.com/en-gb/connected-car
---
**Viel Spaß mit deinem Volvo und FHEM!** 🚗⚡
Letzte Aktualisierung: August 2026
# FHEM VolvoConnect Modul - Dokumentatio.md