Home Assistant integration, entity usage, ... (#1012)

naltatis · web-flow · commit 7e737d4395b4 · 2026-03-11T16:01:02.000+01:00
diff --git a/docs/integrations/home-assistant.mdx b/docs/integrations/home-assistant.mdx
@@ -2,80 +2,90 @@
 sidebar_position: 3
 ---
 
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
 # Home Assistant
 
-Hier erfährst du, wie du evcc-Daten in Home Assistant visualisieren und Automatisierungen erstellen kannst.
+Home Assistant sammelt und visualisiert Daten aus deinem Smart Home und bietet umfangreiche Automatisierungsmöglichkeiten.
+evcc ist auf intelligentes Laden und Heizen spezialisiert.
+Beide Systeme ergänzen sich und lassen sich auf verschiedene Arten miteinander verbinden.
+
+:::note
+evcc kann auch als Home Assistant Addon installiert werden. Die Anleitung dafür findest du [hier](../installation/home-assistant).
+:::
 
-Diese Anleitung setzt voraus, dass du evcc und Home Assistant bereits installiert hast.
-Wenn du nach einer Installationsanleitung suchst, findest du diese unter [Installation → Home Assistant Addon](../installation/home-assistant).
+## Visualisieren & Automatisieren {#control-evcc}
 
-## Schnittstellen
+evcc bringt viele Steuerungen für intelligentes Laden und Heizen mit, kann aber nicht alle Anwendungsfälle abdecken.
+Durch die Integration mit Home Assistant bekommst du mehr Flexibilität.
+Hier ein paar Beispiele:
 
-Falls du Geräte, wie Chargers, Meters oder Fahrzeuge, in evcc integrieren möchtest die von Geräten stammen die evcc nicht
-unterstützt (z. B. Zigbee Smartplugs) kannst du dies über [MQTT](./mqtt-api) oder das
-[REST API](./rest-api) realisieren.
+- Messwerte in Dashboards visualisieren
+- Ladepläne basierend auf Kalendereinträgen erstellen
+- Lademodus abhängig von Anwesenheit wechseln
+- ...
 
-Dank der beiden evcc Schnittstellen können zusätzliche Ladepunkte für eine Vielzahl von verschiebbaren Lasten (Verbrauchern),
-wie Heizgeräte, Waschmaschinen, Geschirrspüler oder Elektro-Zweiräder realisiert werden.
+### Home Assistant evcc Integration (empfohlen) {#ha-evcc}
 
-## Option 1: ha-evcc Integration
+Die [ha-evcc](https://github.com/marq24/ha-evcc) Integration von [marq24](https://github.com/marq24) bringt evcc-Daten und -Funktionen direkt in Home Assistant.
+Das funktioniert unabhängig davon, ob du evcc als Home Assistant Addon betreibst oder nicht.
+Voraussetzung ist, dass Home Assistant und evcc im gleichen Netzwerk erreichbar sind.
 
-Mit der [ha-evcc](https://github.com/marq24/ha-evcc) Integration von [marq24](https://github.com/marq24) kannst du evcc Daten und Funktionen einfach in Home Assistant integrieren.
-Unabhängig davon, ob du evcc in Home Assistant betreibst oder nicht.
+Die Integration stellt alle relevanten evcc-Entitäten bereit: Messwerte, Einstellungen, Ladepunkte und Fahrzeuge.
+Nach der Installation bekommst du eine umfangreiche Liste an Entitäten, die du in Dashboards und Automationen verwenden kannst.
 
-Die Integration unterstützt alle notwendigen von evcc via API bereitgestellten Entitäten, auch diese zur Anpassung der
-evcc Einstellungen, Ladepunkte und der entsprechenden Fahrzeuge.
+**Installation über HACS:**
 
-Nach der Installation bekommst du eine lange Liste aller Entitäten die du in Home Assistant nutzen kannst.
+1. [HACS](https://hacs.xyz/) in Home Assistant öffnen und nach „evcc" suchen.
+2. Den Eintrag **evcc☀️🚘- Solar Charging** von marq24 installieren.
+3. Home Assistant neu starten.
+4. Unter **Einstellungen → Geräte & Dienste → Integration hinzufügen** nach „evcc" suchen und die URL deiner evcc-Instanz angeben.
 
-## Option 2: manuelle MQTT-Integration
+Weitere Installationsvarianten und Details findest du im [GitHub-Repository](https://github.com/marq24/ha-evcc).
 
-MQTT ist ein einfaches Kommunikationsprotokoll, das für das Internet der Dinge (IoT) entwickelt wurde.
-Der Weg über MQTT ist etwas einfacher als über die REST-API, aber falls du noch nie mit MQTT gearbeitet hast,
-gilt es ein paar Punkte zu beachten.
+### Manuelle Integration {#manual}
 
-### Vorbereitung
+Alternativ kannst du evcc-Daten manuell über die REST API oder MQTT in Home Assistant einbinden.
 
-Du benötigst einen MQTT-Broker.
-Dieser ist ein zentraler Knoten, der Nachrichten zwischen verschiedenen Clients vermittelt.
-Ein sehr beliebter und einfacher Broker ist [Mosquitto](https://mosquitto.org/).
-Dieser lässt sich bspw. auch als Home Assistant Addon installieren (siehe [Anleitung](https://alkly.de/mqtt-mit-home-assistant-fuer-anfaenger)).
+#### REST API {#rest}
 
-Hast du einen Broker installiert, kannst du mit einem Tool wie [MQTT Explorer](http://mqtt-explorer.com) die Nachrichten auf dem Broker ansehen und verfolgen.
+evcc bietet eine [REST API](/docs/integrations/rest-api) an.
+[Diese Anleitung](https://github.com/marq24/ha-evcc/blob/main/HA_AS_EVCC_SOURCE.md) von [marq24](https://github.com/marq24) beschreibt die Einbindung in Home Assistant im Detail.
 
-### evcc MQTT Konfiguration
+#### MQTT {#mqtt}
 
-Als nächste müssen wir evcc mitteilen, dass es seine Daten an diesen Broker schicken soll.
-Dazu müssen in der `evcc.yaml` Datei die entsprechenden Zugangsdaten hinzugefügt werden.
+Du benötigst einen MQTT-Broker (z. B. [Mosquitto](https://mosquitto.org/), auch als Home Assistant Addon verfügbar).
 
-```yaml title="evcc.yaml"
-mqtt:
-  broker: <broker-ip>:1883
-  topic: evcc # root topic for publishing, set empty to disable
-  user: mosquitto
-  password: yourpassword
-```
+Konfiguriere in evcc unter **Konfiguration → MQTT** die Verbindung zum Broker.
+In Home Assistant muss der gleiche Broker und das gleiche Topic konfiguriert sein, damit beide Systeme die Daten austauschen können.
 
-Nach einem Neustart von evcc solltest du im MQTT Explorer die bereitgestellten evcc Topics sehen können.
+Mit einem Tool wie [MQTT Explorer](http://mqtt-explorer.com) kannst du prüfen, ob die Daten korrekt ankommen.
+Eine Anleitung zur Einrichtung von MQTT-Sensoren in Home Assistant findest du im [Blog von Alkly](https://alkly.de/mqtt-mit-home-assistant-fuer-anfaenger).
 
-![Screenshot von MQTT Explorer mit evcc Topics](screenshots/mqtt-explorer.webp)
+Die verfügbaren Topics sind in der [MQTT API](/docs/integrations/mqtt-api) dokumentiert.
 
-Nun können wir diese Daten in Home Assistant integrieren.
+## Home Assistant Entitäten nutzen {#ha-entities-in-evcc}
 
-### Home Assistant MQTT Konfiguration
+evcc kann sich direkt mit Home Assistant verbinden und dessen Entitäten (Sensoren, Schalter, Zahlenwerte) als Datenquelle verwenden.
+So lassen sich z. B. Geräte in evcc einbinden, die nicht direkt unterstützt werden, wie Zigbee-Smartplugs, Sensoren aus anderen Integrationen oder selbstgebaute Lösungen.
+Solange die Daten als Home Assistant Entität vorliegen, kann evcc damit arbeiten.
 
-Eine gute Anleitung, wie du MQTT in Home Assistant einrichtest, findest du im [Blog Artikel von Alkly](https://alkly.de/mqtt-mit-home-assistant-fuer-anfaenger).
-Hier gibt es auch Beispiele, wie du aus bestimmten Messwerten (bspw. der Ladeleistung) eine Home Assistant Entität erstellen kannst.
+### Einrichtung {#setup}
 
-## Option 3: manuelle REST Integration
+1. In der evcc-Oberfläche ein neues Gerät anlegen (z. B. **Konfiguration → Zusätzlichen Zähler hinzufügen**)
+2. Als Hersteller „Home Assistant" auswählen
+3. evcc erkennt deine Home Assistant Instanz automatisch im Netzwerk
+4. Autorisierung von evcc in Home Assistant durchführen (neuer Tab)
+5. Den angezeigten Feldern (z. B. „Leistung") Home Assistant Entitäten zuweisen
+   - Du bekommst Vorschläge und Autovervollständigung (z. B. `sensor.inverter_power`)
+   - Entitäten müssen rein numerische Werte liefern (`1234`, nicht `1234 W`)
+   - Um das Vorzeichen zu invertieren, stelle dem Entitätsnamen ein `-` voran (`-sensor.inverter_power`)
 
-Du kannst evcc Daten auch über die REST API in Home Assistant integrieren.
-Die verfügbaren Endpunkte findest du unter [REST API](/docs/integrations/rest-api).
+### Unterstützte Gerätetypen {#device-types}
 
-[Diese Anleitung](https://github.com/marq24/ha-evcc/blob/main/HA_AS_EVCC_SOURCE.md) von [marq24](https://github.com/marq24) gibt dir detaillierte Informationen wie das geht.
+- **[Zähler](/docs/devices/meters#home-assistant)** (Netz, PV, Batterie, ...) mit Leistung, Energie, Strömen, Spannungen, SoC
+- **[Wallboxen](/docs/devices/chargers#home-assistant-charger)** mit Status, Ein-/Ausschalten und maximalem Ladestrom
+- **[Schaltbare Steckdosen](/docs/devices/smartswitches#home-assistant-switch)** mit einfacher Ein-/Aus-Steuerung (für Smartplugs, Relais)
+- **[Fahrzeuge](/docs/devices/vehicles#home-assistant)** mit SoC, Reichweite, Status, Kilometerstand; optional Skripte zum Starten/Stoppen
+- **[Benachrichtigungen](/docs/reference/configuration/messaging)** unter **Konfiguration → Benachrichtigungen** kannst du evcc-Meldungen über Home Assistant versenden
 
 ## Weitere Ressourcen (Videos)
 
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/integrations/home-assistant.mdx b/i18n/en/docusaurus-plugin-content-docs/current/integrations/home-assistant.mdx
@@ -1,80 +1,91 @@
 ---
-fsidebar_position: 3
+sidebar_position: 3
 ---
 
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
 # Home Assistant
 
-Learn how to visualize evcc data in Home Assistant and create automations.
+Home Assistant collects and visualises data from your smart home and offers extensive automation capabilities.
+evcc specialises in smart charging and heating.
+Both systems complement each other and can be connected in different ways.
+
+:::note
+evcc can also be installed as a Home Assistant Addon. You can find the instructions [here](../installation/home-assistant).
+:::
 
-This guide assumes that you have already installed evcc and Home Assistant.
-If you are looking for installation instructions, you can find them under [Installation → Home Assistant Addon](../installation/home-assistant).
+## Visualise & Automate {#control-evcc}
 
-## APIs
+evcc comes with many controls for smart charging and heating but can't cover every use case.
+Integrating with Home Assistant gives you more flexibility.
+Here are some examples:
 
-If you want to integrate devices such as chargers, meters, or vehicles into evcc that come from devices that evcc doesn't
-support (e.g., Zigbee smart plugs), you can do this via [MQTT](./mqtt-api) or the [REST API](./rest-api).
+- Visualise measurements in dashboards
+- Create charging plans based on calendar events
+- Switch charging modes based on presence
+- ...
 
-Thanks to these two evcc APIs, additional charging points can be implemented for a variety of deferrable loads (consumers),
-such as heating devices, washing machines, dishwashers, or electric scooters.
+### Home Assistant evcc Integration (Recommended) {#ha-evcc}
 
-## Option 1: ha-evcc Integration
+The [ha-evcc](https://github.com/marq24/ha-evcc) integration by [marq24](https://github.com/marq24) brings evcc data and functions directly into Home Assistant.
+This works regardless of whether you run evcc as a Home Assistant addon or not.
+The only requirement is that Home Assistant and evcc are reachable on the same network.
 
-With the [ha-evcc](https://github.com/marq24/ha-evcc) integration by [marq24](https://github.com/marq24), you can easily integrate evcc data and functions into Home Assistant.
-This works regardless of whether you run evcc in Home Assistant or not.
+The integration provides all relevant evcc entities: measurements, settings, charging points, and vehicles.
+After installation, you get a comprehensive list of entities that you can use in dashboards and automations.
 
-The integration supports all necessary entities provided by evcc via API, including those for customizing
-evcc settings, charging points, and the corresponding vehicles.
+**Installation via HACS:**
 
-After installation, you'll get a long list of all entities that you can use in Home Assistant.
+1. Open [HACS](https://hacs.xyz/) in Home Assistant and search for "evcc".
+2. Install the entry **evcc☀️🚘- Solar Charging** by marq24.
+3. Restart Home Assistant.
+4. Go to **Settings → Devices & Services → Add Integration**, search for "evcc", and enter the URL of your evcc instance.
 
-## Option 2: Manual MQTT Integration
+For additional installation options and details, see the [GitHub repository](https://github.com/marq24/ha-evcc).
 
-MQTT is a simple communication protocol developed for the Internet of Things (IoT).
-The MQTT approach is somewhat easier than using the REST API, but if you've never worked with MQTT before,
-there are a few points to consider.
+### Manual Integration {#manual}
 
-### Preparation
+Alternatively, you can manually integrate evcc data into Home Assistant via the REST API or MQTT.
 
-You need an MQTT broker.
-This is a central node that mediates messages between different clients.
-A very popular and simple broker is [Mosquitto](https://mosquitto.org/).
-This can also be installed as a Home Assistant addon (see [guide (German)](https://alkly.de/mqtt-mit-home-assistant-fuer-anfaenger)).
+#### REST API {#rest}
 
-Once you have installed a broker, you can use a tool like [MQTT Explorer](http://mqtt-explorer.com) to view and track messages on the broker.
+evcc offers a [REST API](/docs/integrations/rest-api).
+[This guide](https://github.com/marq24/ha-evcc/blob/main/HA_AS_EVCC_SOURCE.md) by [marq24](https://github.com/marq24) describes the integration with Home Assistant in detail.
 
-### evcc MQTT Configuration
+#### MQTT {#mqtt}
 
-Next, we need to tell evcc to send its data to this broker.
-To do this, the corresponding credentials must be added to the `evcc.yaml` file.
+You need an MQTT broker (e.g. [Mosquitto](https://mosquitto.org/), also available as a Home Assistant addon).
 
-```yaml title="evcc.yaml"
-mqtt:
-  broker: <broker-ip>:1883
-  topic: evcc # root topic for publishing, set empty to disable
-  user: mosquitto
-  password: yourpassword
-```
+Configure the broker connection in evcc under **Configuration → MQTT**.
+The same broker and topic must be configured in Home Assistant so that both systems can exchange data.
 
-After restarting evcc, you should be able to see the provided evcc topics in MQTT Explorer.
+You can use a tool like [MQTT Explorer](http://mqtt-explorer.com) to verify that topics are arriving correctly.
+A guide on setting up MQTT sensors in Home Assistant is available in the [blog by Alkly (German)](https://alkly.de/mqtt-mit-home-assistant-fuer-anfaenger).
 
-![Screenshot of MQTT Explorer with evcc topics](screenshots/mqtt-explorer.webp)
+The available topics are documented in the [MQTT API](/docs/integrations/mqtt-api).
 
-Now we can integrate this data into Home Assistant.
+## Using Home Assistant Entities {#ha-entities-in-evcc}
 
-### Home Assistant MQTT Configuration
+evcc can connect directly to Home Assistant and use its entities (sensors, switches, numbers) as data sources.
+This allows you to integrate devices into evcc that are not natively supported, e.g. Zigbee smart plugs, sensors from other integrations, or DIY solutions.
+As long as the data is available as a Home Assistant entity, evcc can work with it.
 
-You can find a good guide on how to set up MQTT in Home Assistant in the [Blog Article by Alkly (German)](https://alkly.de/mqtt-mit-home-assistant-fuer-anfaenger).
-It also includes examples of how to create a Home Assistant entity from certain measurements (e.g., charging power).
+### Setup {#setup}
 
-## Option 3: Manual REST Integration
+1. Add a new device in the evcc UI (e.g. **Configuration → Add additional meter**)
+2. Select "Home Assistant" as the manufacturer
+3. evcc will automatically discover your Home Assistant instance on the network
+4. Authorise evcc in Home Assistant (new tab)
+5. Assign Home Assistant entities to the presented fields (e.g. "Power")
+   - You'll get suggestions and autocomplete (e.g. `sensor.inverter_power`)
+   - Entities must return pure numeric values (`1234`, not `1234 W`)
+   - To invert the sign, prepend `-` to the entity name (`-sensor.inverter_power`)
 
-You can also integrate evcc data into Home Assistant via the REST API.
-You can find the available endpoints under [REST API](/docs/integrations/rest-api).
+### Supported Device Types {#device-types}
 
-[This guide](https://github.com/marq24/ha-evcc/blob/main/HA_AS_EVCC_SOURCE.md) by [marq24](https://github.com/marq24) gives you detailed information on how to do this.
+- **[Meters](/docs/devices/meters#home-assistant)** (grid, solar, battery, ...) with power, energy, currents, voltages, SoC
+- **[Chargers](/docs/devices/chargers#home-assistant-charger)** with status, enable/disable, and maximum charging current
+- **[Smart switches](/docs/devices/smartswitches#home-assistant-switch)** with simple on/off control (for smart plugs, relays)
+- **[Vehicles](/docs/devices/vehicles#home-assistant)** with SoC, range, status, odometer; optionally scripts for start/stop
+- **[Notifications](/docs/reference/configuration/messaging)** under **Configuration → Notifications** you can send evcc messages via Home Assistant
 
 ## Further Resources (Videos)
 
