Hassio: updated documentation (#740)

dm82m · web-flow · commit 15766e3bf6af · 2025-02-19T00:57:50.000+01:00
diff --git a/docs/installation/home-assistant.mdx b/docs/installation/home-assistant.mdx
@@ -2,13 +2,29 @@
 sidebar_position: 7
 ---
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 # Home Assistant Addon
 
-:::important Wichtig
+:::info Wichtig
 Das evcc Home Assistant Addon ist eine Community Integration und wird "noch" nicht offiziell von den evcc Maintainern unterstützt.
 Der Grund dafür ist, dass im Fehlerfall wichtige Daten nicht einfach bereitgestellt werden können (fehlende `evcc cli`).
 :::
 
+:::caution Datenmigration
+Bitte beachte, dass wir seit dem 16.02.2025 mit der Version 0.200.1 die Pfade im Addon geändert haben, um mit der [Vorgabe](https://developers.home-assistant.io/blog/2023/11/06/public-addon-config/) von Home Assistant konsistent zu sein.
+
+Ab sofort werden also folgende Pfade im Addon verbunden:
+
+- `/homeassistant/` -> zeigt in Home Assistant auf `/homeassistant/` bzw. `/config/`.
+- `/config/`-> zeigt in Home Assistant auf `/addon_configs/49686a9f_evcc/`.
+
+Falls du von einer alten Version updatest, wird Deine Konfigurationsdatei automatisch in das neue Verzeichnis kopiert.
+Die Datenbank kopieren wir nur, wenn sie ebenfalls in `/config/` lag. Falls du sie in `/data/` hattest, bleibt sie dort.
+Den alten Dateien fügen wir `.migrated` an. Diese können dann von dir händisch gelöscht werden.
+:::
+
 Diese Anleitung beschreibt die Installation von evcc als Home Assistant Addon.
 Im Gegensatz zur [Linux-Installation](./linux) oder [Docker-Installation](./docker) benötigst du hier kein Kommandozeilenwissen.
 
@@ -20,15 +36,44 @@ Siehe [Home Assistant Dokumentation](https://www.home-assistant.io/installation/
 
 ## Installation
 
-1. Klicke auf **Einstellungen** → **Addons** → **Addon Store**
-2. Klicke auf die **drei Punkte** → **Repositories**
-3. Füge die Repository-URL ein und klicke auf **Hinzufügen**
-    ```
-    https://github.com/evcc-io/hassio-addon
-    ```
-4. Webseite neu laden
-5. Finde das Addon **evcc** und klicke es an.
-6. Klicke auf die Schaltfläche **Installieren**
+<Tabs groupId="release-type">
+  <TabItem value="Release" label="Release" default>
+  Die aktuelle stabile Version.
+
+  1. Repository automatisch hinzufügen: Klicke auf den nachfolgenden Button und dann auf **Open link**, dann auf **Hinzufügen**.
+  [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fevcc%2Fhassio-addon)
+  2. Repository manuell hinzufügen:
+     1. Klicke auf **Einstellungen** → **Addons** → **Addon Store**
+     2. Klicke auf die **drei Punkte** → **Repositories**
+     3. Füge die Repository-URL ein und klicke auf **Hinzufügen**
+        ```
+        https://github.com/evcc-io/hassio-addon
+        ```
+  3. Webseite neu laden
+  4. Finde das Addon **evcc** und klicke es an
+  5. Klicke auf die Schaltfläche **Installieren**
+
+  </TabItem>
+  <TabItem value="Nightly" label="Nightly">
+  Die aktuelle Entwicklerversion. Täglich aktualisiert. Kann instabil sein.
+  Kann zwar parallel zur Release Version installiert werden, aber es kann immer nur eine Version gleichzeitig laufen.
+  Falls du das Nightly nutzt, ändern sich auch die in dieser Anleitung genannten Pfade bzw. Docker Container Namen, d.h. statt `evcc` muss `evcc-nightly` verwendet werden. 
+
+  1. Repository automatisch hinzufügen: Klicke auf den nachfolgenden Button und dann auf **Open link**, dann auf **Hinzufügen**.
+  [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fevcc%2Fhassio-addon)
+  2. Repository manuell hinzufügen:
+     1. Klicke auf **Einstellungen** → **Addons** → **Addon Store**
+     2. Klicke auf die **drei Punkte** → **Repositories**
+     3. Füge die Repository-URL ein und klicke auf **Hinzufügen**
+        ```
+        https://github.com/evcc-io/hassio-addon
+        ```
+  3. Webseite neu laden
+  4. Finde das Addon **evcc (nightly)** und klicke es an
+  5. Klicke auf die Schaltfläche **Installieren**
+
+  </TabItem>
+</Tabs>
 
 ## Konfigurationsdatei
 
@@ -45,13 +90,62 @@ Gehe zum Menü **Konfiguration** und wähle dein Arbeitsverzeichnis aus (Beispie
 
 Lasse den Abschnitt Netzwerk unverändert.
 
-Lege eine Konfigurationsdatei `evcc.yaml` in deinem Home Assistant-Stammkonfigurationsordner (`/homeassistant`) an.
-Unter [Konfiguration](./configuration) findest du eine Anleitung, wie du diese erstellen kannst.
+Lege eine leere Konfigurationsdatei `evcc.yaml` in deinem Home Addon-Stammkonfigurationsordner (`/addon_configs/49686a9f_evcc`) an.
+Falls dieser Ordner noch nicht exisiert, erstelle ihn manuell.
+
+Um die Konfigurationsdatei anzulegen bzw. zu editieren, hast du verschiedene Möglichkeiten, hier ein paar zur Auswahl:
+- [Visual Studio Code](https://github.com/hassio-addons/addon-vscode), in Visual Studio Code wähle das Hamburger-Menü oben links aus und wähle "File", "Open Folder...", select `/addon_configs/49686a9f_evcc`
+- [File Editor](https://github.com/home-assistant/addons/tree/master/configurator), stelle sicher, dass Du die Option "Enforce Basepath" in der Addon Konfiguration deaktiviert hast, starte das Addon neu und navigiere nach `/addon_configs/49686a9f_evcc`
+- [Advanced SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh), navigiere nach `/addon_configs/49686a9f_evcc` und verwende z.B. nano
+
+Unter [Konfiguration](./configuration) findest du eine Anleitung, wie du den Inhalt für die `evcc.yaml` erstellen kannst.
+
+Wenn du erstmal mit einer Demo starten möchtest, kopiere den Inhalt dieser [Demo](https://github.com/evcc-io/evcc/blob/master/cmd/demo.yaml) in deine `evcc.yaml` Datei.
+
+Jetzt bist du bereit und kannst das Addon starten.
 
 ## Aktualisierungen
 
 Die Aktualisierung auf die neueste Version von evcc ist in den Home Assistant Update-Prozess integriert.
 
+## Erweiterte Tips
+
+Um die folgenden Funktionen auszuführen, benötigst du SSH Zugriff auf Home Assistant. Diesen kannst du z.B. mit dem oben erwähnten SSH Addon bekommen.
+
+- Installiere [Advanced SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh)
+- deaktiviere den "secure mode" in der Addon Konfiguration
+- Starte das Addon neu
+- Öffne die Benutzeroberfläche des Addons
+
+### Wie komme ich an die evcc Datenbank?
+
+Zeige die Dateien in `/data` an:
+```sh
+docker exec addon_49686a9f_evcc ls -la /data
+```
+
+Kopiere die `evcc.db` nach `/addon_configs/49686a9f_evcc`:
+```sh
+docker cp addon_49686a9f_evcc:/data/evcc.db /addon_configs/49686a9f_evcc/
+```
+
+### Wie kann ich das evcc CLI nutzen?
+
+Öffne eine Shell zum evcc Docker Container:
+```sh
+docker exec -it addon_49686a9f_evcc /bin/sh
+```
+
+Starte evcc CLI Befehle (hier als Beispiel `checkconfig`):
+```sh
+evcc -c /config/evcc.yaml checkconfig
+```
+
+Schließe die Shell im evcc Docker Container wenn du fertig bist:
+```sh
+exit
+```
+
 ## Nächster Schritt: Integration
 
 Wenn dein System läuft, kannst du dich um die Integration zwischen evcc und Home Assistant kümmern.
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/home-assistant.mdx b/i18n/en/docusaurus-plugin-content-docs/current/installation/home-assistant.mdx
@@ -2,13 +2,29 @@
 sidebar_position: 7
 ---
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 # Home Assistant Addon
 
-:::important
+:::info
 The evcc Home Assistant addon is a community integration and is not officially supported by the evcc maintainers.
 The reason for this is that important data cannot simply be made available in the event of an error (missing `evcc cli`).
 :::
 
+:::warning Datamigration
+Please note that since February 16, 2025, with version 0.200.1, we have changed the paths in the addon to be consistent with the [guidelines](https://developers.home-assistant.io/blog/2023/11/06/public-addon-config/) of Home Assistant.
+
+From now on, the following paths are mapped in the addon:
+
+- `/homeassistant/` -> points to `/homeassistant/` or `/config/` in Home Assistant.
+- `/config/` -> points to `/addon_configs/49686a9f_evcc/` in Home Assistant.
+
+If you are updating from an older version, your configuration file will be automatically copied to the new directory.
+We will only copy the database if it was also located in `/config/`. If you had it in `/data/`, it will remain there.
+We will append `.migrated` to the old files. These can then be manually deleted by you.
+:::
+
 This guide describes the installation of evcc as a Home Assistant addon.
 Unlike the [Linux installation](./linux) or [Docker installation](./docker), you don't need command line knowledge here.
 
@@ -20,19 +36,48 @@ See [Home Assistant Documentation](https://www.home-assistant.io/installation/#a
 
 ## Installation
 
-1. Click on **Settings** → **Addons** → **Add-on Store**
-2. Click on the **three dots** → **Repositories**
-3. Add the repository URL and click **Add**
-    ```
-    https://github.com/evcc-io/hassio-addon
-    ```
-4. Reload the webpage
-5. Find the **evcc** addon and click on it
-6. Click on the **INSTALL** button
+<Tabs groupId="release-type">
+  <TabItem value="Release" label="Release" default>
+  The current stable version.
+
+  1. Automatically add repository: Click on the following button and then on **Open link**, then on **Add**.
+  [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fevcc%2Fhassio-addon)
+  2. Manually add repository:
+     1. Click on **Settings** → **Addons** → **Add-on Store**
+     2. Click on the **three dots** → **Repositories**
+     3. Add the repository URL and click **Add**
+         ```
+         https://github.com/evcc-io/hassio-addon
+         ```
+  3. Reload the webpage
+  4. Find the **evcc** addon and click on it
+  5. Click on the **INSTALL** button
+
+  </TabItem>
+  <TabItem value="Nightly" label="Nightly">
+  The current developer version. Updated daily. May be unstable.
+  Although it can be installed alongside the release version, only one version can run at a time.
+  If you use the nightly version, the paths and Docker container names mentioned in this guide will change, i.e., instead of `evcc`, you must use `evcc-nightly`.
+
+  1. Automatically add repository: Click on the following button and then on **Open link**, then on **Add**.
+  [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fevcc%2Fhassio-addon)
+  2. Manually add repository:
+     1. Click on **Settings** → **Addons** → **Add-on Store**
+     2. Click on the **three dots** → **Repositories**
+     3. Add the repository URL and click **Add**
+         ```
+         https://github.com/evcc-io/hassio-addon
+         ```
+  3. Reload the webpage
+  4. Find the **evcc (nightly)** addon and click on it
+  5. Click on the **INSTALL** button
+
+  </TabItem>
+</Tabs>
 
 ## Configuration File
 
-Go to Information menu in the "evcc" Addon and activate "show in side bar" (evcc UI http://your-ha-instance-ip-address:7070)
+Go to Information menu in the "evcc" Addon and activate "show in sidebar" (evcc UI http://your-ha-instance-ip-address:7070)
 
 Go to Configuration menu and select your working directory (example):
 
@@ -45,13 +90,62 @@ Go to Configuration menu and select your working directory (example):
 
 Leave the Network section unchanged.
 
-Create an evcc configuration file `evcc.yaml` in your Home Assistant root configuration folder (`/homeassistant`).
-Under [Configuration](./configuration) you'll find instructions on how to create this.
+Create an empty evcc configuration file `evcc.yaml` in your Addon root configuration folder (`/addon_configs/49686a9f_evcc`).
+If this folder does not exist, create it manually.
+
+To create or edit the configuration file, you have many options, here are a few:
+- [Visual Studio Code](https://github.com/hassio-addons/addon-vscode), in Visual Studio Code select the hamburger menu in the top left and choose "File", "Open Folder...", select `/addon_configs/49686a9f_evcc`
+- [File Editor](https://github.com/home-assistant/addons/tree/master/configurator), make sure you have disabled the "Enforce Basepath" option in the Addon configuration, restart the Addon and navigate to `/addon_configs/49686a9f_evcc`
+- [Advanced SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh), navigate to `/addon_configs/49686a9f_evcc` and use e.g. nano
+
+Under [Configuration](./configuration) you'll find instructions on how to create the content for the `evcc.yaml`.
+
+If you want to start with a demo, copy the content of this [demo](https://github.com/evcc-io/evcc/blob/master/cmd/demo.yaml) into your `evcc.yaml` file.
+
+Now you are ready and can start the addon.
 
 ## Updates
 
 The update to the latest version of evcc is integrated into the Home Assistant update process.
 
+## Advanced Tips
+
+To perform the following functions, you need SSH access to Home Assistant. You can get this, for example, with the above-mentioned SSH Addon.
+
+- Install [Advanced SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh)
+- Disable the "secure mode" in the Addon configuration
+- Restart the Addon
+- Open the Addon user interface
+
+### How do I access the evcc database?
+
+Show the files in `/data`:
+```sh
+docker exec addon_49686a9f_evcc ls -la /data
+```
+
+Copy the `evcc.db` to `/addon_configs/49686a9f_evcc`:
+```sh
+docker cp addon_49686a9f_evcc:/data/evcc.db /addon_configs/49686a9f_evcc/
+```
+
+### How can I use the evcc CLI?
+
+Open a shell to the evcc Docker container:
+```sh
+docker exec -it addon_49686a9f_evcc /bin/sh
+```
+
+Run evcc CLI commands (here as an example `checkconfig`):
+```sh
+evcc -c /config/evcc.yaml checkconfig
+```
+
+Close the shell in the evcc Docker container if you are done:
+```sh
+exit
+```
+
 ## Next Step: Integration
 
 Once your system is running, you can set up the integration between evcc and Home Assistant.
