Tesla fuer Home Assistant

HACS-Integration fuer Tesla-Fahrzeuge ueber die offizielle Tesla Fleet API. Owner API wurde entfernt, weil Tesla den Legacy-Zugriff fuer betroffene Accounts mit 403 blockiert.

---

Overview

tesla-ha ist eine Home Assistant Custom Integration fuer Tesla-Fahrzeuge. Die Integration nutzt Teslas offizielle Fleet API ueber Home Assistants Application-Credentials- und OAuth-Flow, richtet eine Fleet-Partnerdomain ein und stellt Fahrzeugdaten sowie Steuerfunktionen als Home Assistant Entitaeten bereit.

Der Fokus des Projekts liegt auf einer nachvollziehbaren und wartbaren Tesla-Anbindung fuer Home Assistant. Seit Teslas Umstellung auf Fleet API und signierte Commands benoetigt der Betrieb eine Tesla Developer App, passende Scopes, eine registrierte Public-Key-Domain und fuer viele Fahrzeuge einen gekoppelten Virtual Key.

---

Features

• Home Assistant Application Credentials fuer Tesla Client ID und Client Secret
• Offizieller Tesla Fleet OAuth Flow mit tesla-fleet-api
• Partner-Domainregistrierung mit lokal erzeugtem Public/Private-Key-Paar
• Virtual-Key-Hinweis fuer signierte Fahrzeugbefehle
• 23 Sensoren fuer Ladezustand, Temperaturen, Reifendruck, Medienstatus und Fahrzeugdaten
• 22 Binaersensoren fuer Tueren, Fenster, Laden, Klima, Sentry Mode und Reifendruckwarnungen
• Steuerung fuer Klima, Laden, Verriegelung, Sitzheizung, Sitzkuehlung, Medien und Komfortfunktionen
• Wake-up-Logik fuer schlafende Fahrzeuge vor expliziten Befehlen
• Deutsche und englische UI-Texte fuer den Einrichtungsdialog
• HACS-kompatible Repository-Struktur inklusive Brand-Assets und Validierungs-Workflows

---

Screenshots

Die Bilder zeigen Home Assistant Karten mit Entitaeten dieser Integration.

Hinweis: Die Vehicle Status-Karte im Screenshot oben stammt aus einer externen Integration und dient hier nur zur Darstellung im Dashboard. Vielen Dank an die Entwickler:innen dieser Karte.

TODO: Das Repository enthaelt aktuell kein eigenes breites Banner oder ein dediziertes README-Logo fuer dieses Projekt. Falls spaeter eigenes Branding hinzukommt, sollte es getrennt von den HACS-Brand-Assets unter assets/branding/ abgelegt werden.

---

Installation

Die detaillierte Schritt-fuer-Schritt-Anleitung fuer Tesla Developer Portal, Home Assistant, Cloudflare Access, Reverse Proxy und externe Public-Key-Hosts steht in docs/TESLA_FLEET_SETUP.md.

Voraussetzungen

• Home Assistant 2025.1.0 oder neuer
• HACS installiert
• Tesla-Account
• Tesla Developer App mit Client ID und Client Secret
• OAuth Grant Type in der Tesla Developer App: Authorization Code und Machine-to-Machine
• OAuth Redirect URI in der Tesla Developer App: https://my.home-assistant.io/redirect/oauth
• Oeffentliche HTTPS-Domain, die den Tesla Public Key unter /.well-known/appspecific/com.tesla.3p.public-key.pem ausliefert Die Integration liefert diesen Pfad ab 2.0.3 automatisch aus, wenn die Domain auf Home Assistant zeigt.

HACS Installation

1. Oeffne in Home Assistant HACS.
2. Oeffne das Drei-Punkte-Menue oben rechts.
3. Waehle Custom repositories.
4. Trage https://github.com/Feberdin/tesla-ha als Repository ein.
5. Waehle als Kategorie Integration.
6. Lade die Integration herunter und starte Home Assistant neu.

Einrichtung in Home Assistant

1. Oeffne Einstellungen -> Geraete & Dienste -> Drei-Punkte-Menue -> Application Credentials.
2. Lege fuer Tesla / tesla_ha die Client ID und das Client Secret aus dem Tesla Developer Portal an. Der Dialog zeigt dir die OAuth Redirect URI, die in der Tesla Developer App exakt registriert sein muss.
3. Oeffne Einstellungen -> Geraete & Dienste.
4. Waehle + Integration hinzufuegen und suche nach Tesla.
5. Folge dem Tesla OAuth Login.
6. Gib im Domain-Schritt nur den Hostnamen ein, der den Tesla Public Key hostet, zum Beispiel ha.feberdin.de.
7. Pruefe, dass https://deine-domain/.well-known/appspecific/com.tesla.3p.public-key.pem von außen erreichbar ist.
8. Schließe die Partnerregistrierung ab.
9. Oeffne den angezeigten Virtual-Key-Link und fuege den Schluessel in der Tesla-App hinzu.

Nach erfolgreicher Einrichtung erscheint das Fahrzeug unter Einstellungen -> Geraete & Dienste -> Tesla.

---

Entitaeten

Typ	Anzahl	Hinweise
Sensor	23	Batterie, Laden, Klima, Reifendruck, Medien, Software
Binary Sensor	22	Tueren, Fenster, Laden, Klima, Sentry, TPMS-Warnungen
Climate	1	Standheizung / Klimaanlage
Lock	1	Tuerschloss
Switch	4	Laden, Sentry Mode, Lenkradheizung, Maximal-Heizung
Button	11	Hupe, Frunk, Kofferraum, Ladeport, Medien
Number	2	Ladelimit, Ladestrom
Select	4-6	Sitzheizung immer, Sitzkuehlung nur falls unterstuetzt

Was die Integration steuern kann

• Klima: Standheizung oder Klimaanlage ein- und ausschalten sowie Zieltemperatur setzen
• Fahrzeugzugriff: verriegeln und entriegeln
• Laden: Start, Stop, Ladelimit und Ladestrom zwischen 5 A und 10 A
• Komfort: Lenkradheizung und Maximal-Heizung
• Sicherheit: Sentry Mode
• Sitze: Sitzheizung vorne und hinten, Sitzkuehlung vorne falls vom Fahrzeug gemeldet
• Fahrzeugaktionen: Lichter blinken, Hupe, Frunk oeffnen, Kofferraum oeffnen
• Ladeport: Ladeanschluss oeffnen und schliessen
• Medien: Wiedergabe, naechster oder vorheriger Titel, Lautstaerke hoch oder runter

Sensoren (23)

Sensor	Beschreibung	Einheit
Ladestand	Aktueller Akkustand	%
Reichweite	Geschaetzte Reichweite	km
Ladelimit	Eingestelltes Ladelimit	%
Ladezustand	Charging, Complete, Disconnected	-
Ladeleistung	Aktuelle Ladeleistung	kW
Ladespannung	Spannung am Ladepunkt	V
Ladestrom	Strom am Ladepunkt	A
Energie geladen	Geladene Energie seit Anschluss	kWh
Minuten bis voll	Restzeit bis zum Ladelimit	min
Laderate	Reichweite pro Stunde Nachladung	km/h
Kilometerstand	Gesamtkilometer	km
Fahrstufe	P, D, R, N	-
Leistung	Verbrauch oder Rekuperation	kW
Software Version	Installierte Fahrzeugversion	-
Software Update	Verfuegbare Update-Version	-
Dashcam	Dashcam-Status	-
Innentemperatur	Temperatur im Innenraum	degC
Aussentemperatur	Temperatur ausserhalb des Fahrzeugs	degC
Reifendruck VL	Vorne links	bar
Reifendruck VR	Vorne rechts	bar
Reifendruck HL	Hinten links	bar
Reifendruck HR	Hinten rechts	bar
Wiedergabe	Aktuell gespielter Kuenstler und Titel	-

Binaersensoren (22)

Sensor	Beschreibung
Laedt	Fahrzeug laedt gerade
Kabel angesteckt	Ladekabel ist verbunden
Ladeanschluss offen	Ladeklappe ist geoeffnet
Batterieheizung	Batterieheizung ist aktiv
Verriegelt	Fahrzeug ist verriegelt
Nutzer anwesend	Jemand sitzt im Fahrzeug
Fahrertuer	Fahrertuer offen
Beifahrertuer	Beifahrertuer offen
Fondtuer Links	Hintere Fahrertuer offen
Fondtuer Rechts	Hintere Beifahrertuer offen
Frunk offen	Vordere Haube offen
Kofferraum offen	Hintere Klappe offen
Fenster Fahrer	Fahrerfenster offen
Fenster Beifahrer	Beifahrerfenster offen
Fenster Fond Links	Hinteres Fahrerfenster offen
Fenster Fond Rechts	Hinteres Beifahrerfenster offen
Klimaanlage	Klimaanlage aktiv
Sentry Mode	Sentry Mode aktiv
Reifendruckwarnung VL	Problem vorne links
Reifendruckwarnung VR	Problem vorne rechts
Reifendruckwarnung HL	Problem hinten links
Reifendruckwarnung HR	Problem hinten rechts

Steuerbare Entitaeten

Entitaet	Typ	Beschreibung
Standheizung	Climate	Ein oder Aus und Zieltemperatur 15-28 degC
Tuerschloss	Lock	Verriegeln und entriegeln
Sentry Mode	Switch	Sentry Mode ein oder ausschalten
Laden	Switch	Laden starten oder stoppen
Lenkradheizung	Switch	Lenkradheizung ein oder ausschalten
Maximal-Heizung	Switch	Alle Heizungen auf Maximum
Ladelimit	Number	Ladelimit 50-100 %
Ladestrom	Number	Ladestrom 5-10 A
Sitzheizung Fahrer	Select	Aus, Stufe 1, Stufe 2, Stufe 3
Sitzheizung Beifahrer	Select	Aus, Stufe 1, Stufe 2, Stufe 3
Sitzheizung Fond Links	Select	Aus, Stufe 1, Stufe 2, Stufe 3
Sitzheizung Fond Rechts	Select	Aus, Stufe 1, Stufe 2, Stufe 3
Sitzkuehlung Fahrer	Select	Aus, Stufe 1, Stufe 2, Stufe 3 falls verfuegbar
Sitzkuehlung Beifahrer	Select	Aus, Stufe 1, Stufe 2, Stufe 3 falls verfuegbar
Lichter blinken	Button	Fahrzeuglichter kurz aufblinken lassen
Hupe	Button	Hupe betaetigen
Frunk oeffnen	Button	Vordere Haube oeffnen
Kofferraum oeffnen	Button	Hintere Klappe oeffnen
Ladeanschluss oeffnen	Button	Ladeklappe oeffnen
Ladeanschluss schliessen	Button	Ladeklappe schliessen
Wiedergabe Pause/Play	Button	Musik pausieren oder fortsetzen
Naechster Titel	Button	Naechsten Titel ueberspringen
Vorheriger Titel	Button	Vorherigen Titel wiederholen
Lautstaerke lauter	Button	Lautstaerke erhoehen
Lautstaerke leiser	Button	Lautstaerke verringern

---

Konfiguration

Update-Intervall

Das Datenupdate laeuft standardmaessig alle 10 Minuten. Der Wert ist in const.py als UPDATE_INTERVAL hinterlegt.

UPDATE_INTERVAL = 10  # minutes

Hinweis: Tesla Fleet vehicle_data Abrufe koennen kosten- und rate-limit-relevant sein. Die Integration weckt schlafende Fahrzeuge deshalb nicht mehr fuer normale Polling-Updates, sondern nur bei expliziten Befehlen.

Authentifizierung

Die Integration verwendet Home Assistants Application-Credentials- und OAuth2-Flow in config_flow.py. Das Token wird nach erfolgreichem Abschluss durch Home Assistant gespeichert und erneuert.

Seit Version 2.0.0 nutzt die Integration keine Legacy Owner API mehr. Der Tesla Developer Flow benoetigt:

• Client ID und Client Secret aus dem Tesla Developer Portal
• OAuth Grant Type Authorization Code fuer den Benutzer-Login und Machine-to-Machine fuer die Partner-Domainregistrierung
• Redirect URI aus Home Assistant. Standard mit aktivem my-Modul: https://my.home-assistant.io/redirect/oauth
• Scopes openid, offline_access, user_data, vehicle_device_data, vehicle_location, vehicle_cmds, vehicle_charging_cmds
• eine Allowed Origin passend zur Public-Key-Domain
• Allowed Returned URL(s) leer lassen
• einen Public Key unter https://deine-domain/.well-known/appspecific/com.tesla.3p.public-key.pem
• fuer signierte Befehle einen gekoppelten Virtual Key im Fahrzeug

Ab Version 2.0.3 registriert die Integration in Home Assistant eine oeffentliche Route fuer den Tesla Public Key:

/.well-known/appspecific/com.tesla.3p.public-key.pem

Wenn deine Public-Key-Domain direkt auf Home Assistant zeigt, reicht es, diesen Pfad in Cloudflare Access ohne Login, Captcha oder Challenge freizugeben. Die Datei muss danach von außen mit HTTP 200 erreichbar sein und mit -----BEGIN PUBLIC KEY----- beginnen.

Wenn Tesla direkt nach dem Oeffnen der Login-Seite meldet, dass redirect_uri nicht fuer die client_id registriert ist, ist die Tesla Developer App noch nicht passend konfiguriert. Trage exakt die von Home Assistant angezeigte Redirect URI ein, speichere die App und starte den OAuth-Flow danach erneut. Ab Version 2.0.2 prueft die Integration diese Authorize-URL vor dem Browser-Redirect und zeigt Client ID plus Redirect URI direkt im Home Assistant Dialog an, wenn Tesla die Kombination ablehnt.

Die komplette Einrichtung inklusive Cloudflare Access, externer Public-Key- Hosts und Troubleshooting ist in docs/TESLA_FLEET_SETUP.md beschrieben.

Lokale Entwicklung

Fuer lokale Entwicklung werden keine echten Tesla-Tokens benoetigt. Application Credentials, OAuth Tokens und private Keys gehoeren ausschliesslich in Home Assistants lokalen Storage und duerfen nicht committed oder veroeffentlicht werden.

Lokale Pruefung ohne echte Tesla-Zugangsdaten:

python3 -m venv .venv
.venv/bin/python -m pip install pytest tesla-fleet-api==1.4.7
.venv/bin/python -m compileall -q custom_components tests
.venv/bin/python -m pytest tests/test_tesla_fleet.py -q

---

Automationsbeispiele

Standheizung automatisch einschalten

automation:
  alias: "Tesla vorheizen"
  trigger:
    - platform: time
      at: "07:30:00"
  action:
    - service: climate.set_hvac_mode
      target:
        entity_id: climate.tesla_model_3_standheizung
      data:
        hvac_mode: heat_cool
    - service: climate.set_temperature
      target:
        entity_id: climate.tesla_model_3_standheizung
      data:
        temperature: 22

Benachrichtigung bei niedrigem Reifendruck

automation:
  alias: "Tesla Reifendruck Warnung"
  trigger:
    - platform: state
      entity_id:
        - binary_sensor.tesla_model_3_reifendruckwarnung_vl
        - binary_sensor.tesla_model_3_reifendruckwarnung_vr
        - binary_sensor.tesla_model_3_reifendruckwarnung_hl
        - binary_sensor.tesla_model_3_reifendruckwarnung_hr
      to: "on"
  action:
    - service: notify.mobile_app
      data:
        title: "Tesla Reifendruck"
        message: "Reifendruck pruefen: {{ trigger.to_state.name }}"

Laden stoppen wenn Ladestand erreicht

automation:
  alias: "Tesla Laden bei 80% stoppen"
  trigger:
    - platform: numeric_state
      entity_id: sensor.tesla_model_3_ladestand
      above: 80
  condition:
    - condition: state
      entity_id: binary_sensor.tesla_model_3_ladt
      state: "on"
  action:
    - service: switch.turn_off
      target:
        entity_id: switch.tesla_model_3_laden

---

Architektur

Die Integration ist bewusst kompakt aufgebaut:

• application_credentials.py verbindet Home Assistant Application Credentials mit Tesla OAuth
• oauth.py definiert Tesla Fleet OAuth-Server, Scopes und Token-Exchange-Parameter
• config_flow.py implementiert OAuth, Partner-Domainregistrierung und Virtual-Key-Hinweise
• tesla_fleet.py kapselt Fleet-Datenmapping und Command-Mapping
• coordinator.py kapselt Fleet-Abrufe, Wake-up-Logik und Tesla-Befehle
• Die Plattformdateien unter custom_components/tesla_ha/ definieren die Home Assistant Entitaeten fuer Sensoren und Steuerung

Der Coordinator arbeitet mit DataUpdateCoordinator und nutzt die asynchrone tesla-fleet-api Library, die auch Home Assistants offizielle Tesla-Fleet-Integration verwendet.

---

Einschraenkungen und Fehlerbehebung

Bekannte Einschraenkungen

• Aktuell wird nur das erste gefundene Fahrzeug verwendet (vehicles[0])
• Normale Polling-Updates wecken das Fahrzeug nicht automatisch
• Signierte Befehle funktionieren nur mit registrierter Domain, gehostetem Public Key und gekoppeltem Virtual Key
• Tesla Fleet API kann je nach Developer-App, Region und Nutzung kosten- oder rate-limit-relevant sein
• Das Aufwecken eines schlafenden Fahrzeugs fuer Befehle kann fehlschlagen, wenn Mobile Access deaktiviert ist

Haeufige Probleme

• Integration erscheint nicht in HACS: Stelle sicher, dass https://github.com/Feberdin/tesla-ha als Custom Repository eingetragen ist.
• Application Credentials fehlen: Lege Client ID und Client Secret in Home Assistant unter Application Credentials fuer diese Integration an.
• Domainregistrierung schlaegt fehl: Pruefe Allowed Origin im Tesla Developer Portal und ob der Public Key exakt unter der angezeigten Well-Known-URL erreichbar ist.
• Befehle funktionieren nicht, Sensoren aber schon: Pruefe, ob der Virtual Key ueber https://www.tesla.com/_ak/deine-domain gekoppelt wurde und ob die OAuth-Scopes vehicle_cmds sowie vehicle_charging_cmds erlaubt sind.
• Token-Refresh schlaegt fehl: Entferne die Integration und richte sie mit einem frischen Tesla Fleet Login neu ein.
• Fahrzeug wacht nicht auf: Pruefe Mobile Access, Mobilfunk- oder WLAN-Empfang des Fahrzeugs und gib dem Wake-up etwas Zeit.

---

Projektstruktur

tesla-ha/
├── .github/workflows/              # HACS- und Hassfest-Validierung
├── assets/screenshots/             # README-Screenshots
├── docs/                           # Setup- und Migrationsdokumentation
├── custom_components/tesla_ha/     # Home Assistant Integration
│   ├── brand/                      # HACS/Home Assistant Brand-Assets
│   ├── translations/               # de/en Config-Flow Uebersetzungen
│   ├── config_flow.py
│   ├── coordinator.py
│   ├── sensor.py
│   ├── binary_sensor.py
│   ├── climate.py
│   ├── lock.py
│   ├── switch.py
│   ├── button.py
│   ├── number.py
│   └── select.py
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── hacs.json

Vorgeschlagene Doku- und Asset-Struktur

Die docs/-Struktur ist jetzt als Ausgangspunkt vorhanden und kann bei Bedarf weiter ausgebaut werden:

docs/
├── SETUP.md
├── MIGRATION.md
├── installation.md
├── configuration.md
├── automations.md
└── troubleshooting.md

assets/branding/                   # TODO
└── readme-banner.png

TODO: Falls die Projektdoku weiter waechst, sollten Installationsanleitung, Automationsbeispiele und Troubleshooting schrittweise in eigene Dateien unter docs/ ausgelagert werden.

---

Contributing

Beitraege sind willkommen. Die projektspezifischen Hinweise stehen in CONTRIBUTING.md.

Wichtig fuer dieses Repository:

• Keine Secrets, Tokens oder lokale cache.json Dateien committen
• Dokumentationsaenderungen immer gegen die echte Implementierung pruefen
• Externe Dashboard-Karten oder Drittanbieter-Assets in Screenshots klar kennzeichnen

---

Security

Bitte keine sensiblen Sicherheitsdetails in oeffentlichen Issues posten. Siehe SECURITY.md fuer den bevorzugten Meldeweg.

---

License

Dieses Projekt steht unter der MIT License. Details stehen in LICENSE.

---

Support

• Issues: github.com/Feberdin/tesla-ha/issues
• Releases: github.com/Feberdin/tesla-ha/releases
• Maintainer: Feberdin

Wenn du einen Bug meldest, sind Home Assistant Version, Integrationsversion, relevante Logs und reproduzierbare Schritte am hilfreichsten.