Installation

Diese Seite richtet sich an Leser:innen, die noch nie Home Assistant installiert, MQTT eingerichtet oder ein Zigbee-Gerät gekoppelt haben. Falls du bereits eine laufende Home-Assistant-Instanz mit funktionierendem Zigbee2MQTT hast, kannst du direkt zu GrowAssistant installieren springen.

Der Einsteiger-Teil verweist durchgehend auf die offizielle Dokumentation von Home Assistant, Zigbee2MQTT und HACS für jeden Schritt — diese Seite verbindet diese offiziellen Anleitungen zu einem verständlichen Gesamtweg und erklärt, welche Optionen dieses konkrete Projekt (ein nativer Home-Assistant-Grow-Controller) tatsächlich benötigt. Quellenlinks sind durchgehend angegeben, damit du für weitere Details jederzeit zur Originalanleitung wechseln kannst.

1. Welche Home-Assistant-Installation wählen, und warum

Home Assistant bietet aktuell zwei unterstützte Installationsmethoden an: Home Assistant Operating System (HA OS) und Home Assistant Container (Docker). Zwei ältere Methoden, Home Assistant Core und Home Assistant Supervised, werden schrittweise abgeschafft — der Support endet mit dem Release 2025.12, und Home Assistant empfiehlt, von beiden wegzumigrieren (siehe die Deprecation-Ankündigung).

Dieses Projekt ist für Home Assistant OS gebaut und dokumentiert. Der Grund ist der Supervisor: HA OS ist die einzige aktuelle Option, die dir den Add-on-Store des Supervisors gibt, und das Setup dieses Projekts basiert auf mehreren Add-ons:

• Mosquitto Broker (MQTT, für Zigbee2MQTT benötigt, siehe Schritt 5),
• Zigbee2MQTT (siehe Schritt 5),
• File Editor oder Studio Code Server (zum Bearbeiten der YAML-Dateien dieses Projekts, siehe Schritt 3),
• HACS (für die individuellen Dashboard-Karten, die in den Dashboards dieses Projekts verwendet werden, siehe Schritt 6),
• optional MotionEye (nur falls du USB-Zeltkameras hinzufügst, siehe Modul M13 – Kameras).

Home Assistant Container kann all das auch, aber ohne den Supervisor müsstest du MQTT/Zigbee2MQTT/HACS als separate, selbst verwaltete Docker-Container betreiben — mehr bewegliche Teile für eine Ersteinrichtung. Siehe den offiziellen Vergleich der Installationstypen und die HA-OS-vs.-Container-FAQ, falls du vor der Entscheidung das ganze Bild sehen willst.

2. Hardware und Voraussetzungen

Bevor du irgendetwas installierst, stelle sicher, dass du Folgendes hast:

• Einen dedizierten Host. Ein Raspberry Pi 4 oder 5 (mindestens 2 GB RAM), ein kleiner x86-64-Mini-PC, oder eine übrige Maschine, auf der alles in einer VM läuft. Home Assistants offizielles, vorgefertigtes Gerät, Home Assistant Green, ist die unkomplizierteste Option, falls du nichts selbst zusammenbauen/flashen möchtest. Siehe die offizielle Installationsübersicht für alle unterstützten Optionen und deren Hardware-Anforderungen.
• Speicher. Für einen Raspberry Pi: eine microSD-Karte mit mindestens 32 GB, idealerweise “Application Class 2” (A2-Rating) für bessere Performance, laut der offiziellen Raspberry-Pi-Installationsanleitung. Ein SD-Kartenleser (in den meisten Laptops eingebaut, oder ein günstiger USB-Leser).
• Eine kabelgebundene Ethernet-Verbindung für die Ersteinrichtung. Der erste Boot von HA OS benötigt Ethernet, selbst wenn du später auf WLAN wechseln möchtest (siehe die oben verlinkte Raspberry-Pi-Anleitung).
• Ein passendes Netzteil — die offizielle Anleitung warnt ausdrücklich vor Handy-Ladegeräten oder dem USB-Port eines Computers, die oft keine stabile Stromversorgung für einen Raspberry Pi unter Last liefern können.
• Einen USB-Zigbee-Koordinator (Dongle). Damit kann Home Assistant mit deinen Zigbee-Sensoren/Steckdosen kommunizieren; siehe Schritt 5 für Adapterempfehlungen — entscheide dich jetzt schon dafür, da es beeinflusst, was du später anschließt.
• Die von diesem Projekt benötigten Home-Assistant-Sensoren/Aktoren. GrowAssistant selbst benötigt nur einen Temperatursensor, einen Feuchtigkeitssensor und mindestens einen Ent- oder Befeuchter — alles andere (Beleuchtung, CO2, Bewässerung, Substratsensoren, Energiemessung, Kameras) ist optional und kann später ergänzt werden. Siehe Core / Entity Mapping – Pflicht vs. optional für die vollständige Liste. Du musst diese Hardware nicht schon besitzen, bevor du startest — Home Assistant, MQTT und Zigbee2MQTT lassen sich vollständig installieren und verifizieren, bevor reale Geräte nach und nach zugeordnet werden.

3. Home Assistant OS installieren und die Ersteinrichtung durchführen

1. Image flashen. Lade den Raspberry Pi Imager herunter und öffne ihn, wähle Other specific-purpose OS -> Home automation -> Home Assistant, wähle das zu deinem Pi-Modell passende Image, wähle deine SD-Karte aus und schreibe sie. Vollständige Anleitung inkl. x86-64/VM-Instruktionen: Home-Assistant-OS-Installation.

2. Erster Start. Karte einlegen, Ethernet und Strom anschließen und ein paar Minuten warten, bis die Ersteinrichtung abgeschlossen ist. Öffne http://homeassistant.local:8123 in einem Browser im gleichen Netzwerk (nutze die Geräteliste deines Routers, um die IP-Adresse zu finden, falls dieser Hostname in deinem Netzwerk nicht aufgelöst wird).

3. Onboarding-Assistent. Home Assistant führt dich durch das Anlegen deines Besitzerkontos (Benutzername/Passwort — für dieses Konto gibt es keine Wiederherstellung, also sicher aufbewahren), das Festlegen des Standorts deines Zuhauses (wird für Zeitzone, Einheitensystem und sonnenauf-/-untergangsbasierte Automationen genutzt) sowie ein optionales Analytics-Opt-in. Details: Onboarding.

4. Eine Möglichkeit installieren, YAML-Dateien zu bearbeiten. Dieses Projekt wird als YAML-Dateien (packages/*.yaml, dashboards/*.yaml) ausgeliefert, die in deinen Home-Assistant-config-Ordner kopiert werden müssen. Unter Einstellungen -> Add-ons -> Add-on Store installierst du eines von:

   • File editor — ein einfacher browserbasierter Editor mit YAML-Syntaxprüfung, standardmäßig auf den config-Ordner beschränkt; oder
   • Studio Code Server — ein vollständiges webbasiertes VS Code inkl. Terminal (mächtiger, etwas schwergewichtiger); oder
   • Samba share — bindet deinen config-Ordner als Netzlaufwerk ein (\\<deine-ha-ip> unter Windows, smb://<deine-ha-ip> unter Mac/Linux), sodass du Dateien mit Werkzeugen auf deinem eigenen Computer bearbeiten kannst.

   Alle drei sind offizielle Home-Assistant-Add-ons; siehe Common tasks – Home Assistant OS für die Installationsschritte und einen Vergleich.

5. packages:-Unterstützung aktivieren. Dieses Projekt liegt als Home-Assistant-Packages vor (eine YAML-Datei pro Modul). Öffne configuration.yaml mit dem installierten Editor und stelle sicher, dass es genau einen homeassistant:-Block mit einer packages:-Zeile gibt:

   homeassistant:
     name: Home
     packages: !include_dir_named packages

   Lege danach den Ordner packages neben configuration.yaml an, falls er noch nicht existiert. Falls später der Fehler Integration 'packages' not found auftritt, siehe Troubleshooting — meist liegt es an einem doppelten oder falsch eingerückten homeassistant:-Block.

4. MQTT (Mosquitto) installieren und verbinden

Zigbee2MQTT benötigt einen MQTT-Broker, um mit Home Assistant zu kommunizieren. Die offizielle Option ohne manuelle Konfiguration ist das Mosquitto-Broker-Add-on:

1. Unter Einstellungen -> Add-ons -> Add-on Store nach Mosquitto broker suchen (ein offizielles Home-Assistant-Add-on — es muss vorher keine Repository-URL hinzugefügt werden) und installieren.
2. Starten und “Beim Start starten” aktivieren.
3. Unter Einstellungen -> Geräte & Dienste -> Integration hinzufügen nach MQTT suchen und hinzufügen. Läuft das offizielle Mosquitto-Add-on bereits, erkennt Home Assistant es automatisch und generiert die Zugangsdaten selbstständig — im Normalfall ist keine manuelle Eingabe von Broker-Adresse/Benutzername/Passwort nötig.

Offizielle Referenzen: die MQTT-Integration und das Mosquitto-Broker-Add-on.

5. Zigbee2MQTT installieren, konfigurieren und verbinden

Dieses Projekt nutzt Zigbee2MQTT statt der eingebauten ZHA-Integration von Home Assistant als Zigbee-Backend — praktisch ist es GrowAssistant egal, welches Backend du nutzt, da jede Entity über die in Core / Entity Mapping beschriebenen Mapping-Helper referenziert wird, aber diese Seite folgt aus Konsistenzgründen mit dem Rest der Dokumentation dieser Wahl.

1. Koordinator-Adapter wählen. Die eigene Empfehlung von Zigbee2MQTT ist ein USB-Koordinator auf Basis von zStack (Texas Instruments), EmberZNet (Silicon Labs) oder deCONZ (Dresden Elektronik), angeschlossen über ein kabelgebundenes USB-Verlängerungskabel statt direkt am Host (USB-3.0-Ports und die Elektronik des Pi selbst sind eine bekannte Quelle für Zigbee-Störungen). Siehe den offiziellen Adapter-Guide vor dem Kauf, und prüfe dort zuerst die FAQ, falls du bereits einen Adapter besitzt und unsicher bist, ob er unterstützt wird.
2. Add-on-Repository hinzufügen. Unter Einstellungen -> Add-ons -> Add-on Store -> ⋮ (oben rechts) -> Repositories https://github.com/zigbee2mqtt/hassio-zigbee2mqtt hinzufügen (das offizielle Zigbee2MQTT-Home-Assistant-Add-on-Repository).
3. Zigbee2MQTT installieren und starten. “Zigbee2MQTT” im Store finden, installieren, dann die Web-UI öffnen. Der Onboarding-Flow erkennt deinen USB-Adapter und lässt dich ihn auswählen; wird er nicht automatisch erkannt, Adaptertyp und seriellen Port manuell in der Add-on-Konfiguration setzen (ein einzelnes USB-Gerät ist meist /dev/ttyACM0 oder /dev/ttyUSB0). Vollständige Schritte: das offizielle Add-on-Repository-README.
4. Zigbee-Geräte koppeln (pairen). Web-UI von Zigbee2MQTT öffnen, den Join-/“Permit join”-Button klicken (oben rechts — öffnet das Netzwerk für 254 Sekunden) und dein Sensor/deine Steckdose gemäß eigener Anleitung in den Pairing-Modus versetzen (meist ein Werksreset oder ein langer Tastendruck). Im Zigbee2MQTT-Log auf eine “successfully paired”-Meldung achten. Für jeden Sensor und Aktor wiederholen. Offizielle Anleitung: Pairing devices.
5. Prüfen, ob die Entities in Home Assistant erscheinen. Mit der in Schritt 4 installierten MQTT-Integration erscheint jedes gekoppelte Zigbee2MQTT-Gerät automatisch als eine oder mehrere Home-Assistant-Entities (über MQTT Discovery) — ohne weitere Konfiguration. Diese Entity-IDs ordnest du später in Dashboard 1 – Configuration GrowAssistant zu.

6. Was GrowAssistant selbst zusätzlich zu einem laufenden Home Assistant benötigt

Sobald Home Assistant, MQTT und Zigbee2MQTT laufen, benötigt dieses Projekt zusätzlich:

• HACS (Home Assistant Community Store), für die individuellen Dashboard-Karten, die in den Dashboards dieses Projekts verwendet werden — apexcharts-card (Charts), mushroom (kompakte Status-Karten), card-mod (dynamisches Styling) und expander-card (einklappbare Erklärhinweise). HACS selbst gemäß der offiziellen HACS-Download-Anleitung installieren, dann jede Karte über HACS -> Frontend -> Explore & Add Repositories namentlich installieren. Weder Dashboard 1s Mapping-Felder noch die Setup-Status-Karte benötigen HACS — nur die visuelleren Teile von Dashboard 2/3 tun das, dieser Schritt kann also warten, bis das funktionale Setup bestätigt läuft.
• Die Home-Assistant-Companion-App (optional, nur für Push-Benachrichtigungs-Alarme benötigt), installiert aus dem App Store oder bei Google Play, dann bei deiner Instanz angemeldet. Nach der Anmeldung erhält dein Gerät automatisch einen notify.mobile_app_<device>-Dienst, an den Home Assistant Meldungen senden kann. Siehe die offizielle Companion-App-Dokumentation für Details.
• Eine SMTP-Integration (optional, nur für E-Mail-Alarme benötigt) über Einstellungen -> Geräte & Dienste -> Integration hinzufügen -> E-Mail, mit dem SMTP-Server, Port und den Zugangsdaten deines Mail-Anbieters (Gmail und ähnliche Anbieter verlangen meist ein App-Passwort statt deines normalen Kontopassworts). Siehe die offizielle SMTP-Integrationsdokumentation.
• Nichts Besonderes für Verlauf/Diagramme. Der eingebaute Recorder von Home Assistant nutzt standardmäßig eine lokale SQLite-Datenbank, was zum Start ausreicht — für dieses Projekt ist kein separater Datenbankserver nötig.

7. Vor der GrowAssistant-Installation alles überprüfen

Arbeite diese Checkliste durch, bevor du weitermachst — sie grenzt Probleme auf die richtige Ebene ein (Home Assistant vs. MQTT vs. Zigbee2MQTT vs. ein einzelnes Gerät), statt GrowAssistants eigene Templates gegen ein wackliges Fundament zu debuggen.

1. Home Assistant selbst ist gesund. Einstellungen -> System -> Protokolle zeigt keine sich wiederholenden Fehler, und Entwicklerwerkzeuge -> YAML -> Konfiguration prüfen meldet “Konfiguration gültig!”.
2. MQTT ist verbunden. Einstellungen -> Geräte & Dienste listet einen MQTT-Integrationseintrag ohne “nicht geladen”/“Verbindung fehlgeschlagen”-Warnhinweis.
3. Die Zigbee2MQTT-Bridge ist online. Web-UI von Zigbee2MQTT öffnen — das Dashboard zeigt die Bridge als verbunden, und jedes gekoppelte Gerät ist mit einer aktuellen “zuletzt gesehen”-Zeit und einer Link-Qualität größer null gelistet.
4. Gekoppelte Geräte melden echte Werte in Home Assistant. Unter Entwicklerwerkzeuge -> Zustände nach deinem Gerät filtern (z. B. nach seinem Zigbee2MQTT-Anzeigenamen) und prüfen, dass seine sensor.*/switch.*-Entities einen live wechselnden Wert zeigen — nicht unavailable oder unknown. Bei einer Steckdose/einem Schalter über den Tab Zustände (oder physisch) umschalten und prüfen, dass sich der Zustand innerhalb weniger Sekunden aktualisiert.

8. Häufige Probleme für Erstnutzer:innen

• homeassistant.local wird nicht aufgelöst. Nicht jeder Router/jedes Netzwerk unterstützt .local-Hostnamen (mDNS). Stattdessen die IP-Adresse des Geräts verwenden (in der Geräteliste deines Routers nachsehen), oder eine mDNS-fähige Browser-Erweiterung — siehe die Raspberry-Pi-Installationsanleitung.
• Neue input_*-Helper aus einem Package erscheinen nicht. Ein erstmaliges Package-Deployment benötigt einen vollständigen Neustart von Home Assistant, kein reines YAML-Reload — siehe Troubleshooting.
• Zigbee2MQTT erkennt den USB-Adapter nicht, oder Geräte fallen zufällig aus. Meist ein Problem mit dem seriellen Port/Störungen: ein kabelgebundenes USB-Verlängerungskabel nutzen, um den Adapter vom Host und von USB-3.0-Ports fernzuhalten, und den Portpfad (/dev/ttyACM0//dev/ttyUSB0) in der Add-on-Konfiguration prüfen. Siehe den offiziellen Adapter-Guide und die dort verlinkte FAQ für adapterspezifische Eigenheiten.
• Ein Gerät koppelt nicht. “Permit join” erneut aktivieren (bleibt nur 254 Sekunden offen), dann das Gerät gemäß Anleitung erneut auf Werkseinstellungen zurücksetzen — die meisten fehlgeschlagenen Kopplungen liegen daran, dass das Join-Fenster bereits geschlossen war, nicht an einem echten Defekt. Siehe Pairing devices für geräteabhängige Pairing-Hinweise und den dortigen Troubleshooting-Abschnitt.
• MQTT-Integration installiert, aber Zigbee2MQTT-Geräte erscheinen nie in Home Assistant. Die eigene MQTT-Verbindung von Zigbee2MQTT prüfen (dessen Web-UI zeigt einen verbundenen Bridge-Status) — kann Zigbee2MQTT den Broker nicht erreichen, werden nie Entities veröffentlicht, die Home Assistant entdecken könnte.
• Immer noch festgefahren? Das offizielle Home Assistant Community Forum und die Zigbee2MQTT-GitHub-Discussions sind die richtigen Anlaufstellen — beide sind deutlich aktiver und aktueller als jede einzelne Doku-Seite, auch diese hier.

GrowAssistant installieren

Sobald die Checkliste in Abschnitt 7 erfüllt ist — oder sofort, falls du bereits ein funktionierendes Home-Assistant-/MQTT-/Zigbee2MQTT-Setup hattest — installierst du das Projekt selbst:

1. Sicherstellen, dass packages: wie in Schritt 3.5 oben aktiviert ist (innerhalb deines bestehenden homeassistant:-Blocks, nicht als eigener Top-Level-Key).
2. Den Inhalt des Repo-Ordners packages/ in deinen HA-Ordner config/packages/ kopieren (anlegen, falls noch nicht vorhanden).
3. Entwicklerwerkzeuge -> YAML -> Konfiguration prüfen (oder ha core check) ausführen, bei Erfolg neu laden — mindestens Template Entities und Automationen. Beim allerersten Hinzufügen des packages:-Blocks oder einer neuen Package-Datei ist ein vollständiger Neustart statt eines Reloads nötig (neue input_*-Helper-Definitionen werden nur beim Start eingelesen; spätere Wertänderungen benötigen nie einen Neustart).
4. dashboards/dashboard_1_configuration.yaml als neues Dashboard importieren: Einstellungen -> Dashboards -> Dashboard hinzufügen -> “Steuerung per YAML übernehmen”, dann den Dateiinhalt im Raw-Edit-Modus einfügen. Gleiches Vorgehen für dashboards/dashboard_2_control_panel.yaml und dashboards/dashboard_3_log.yaml.
5. Auf dem neuen “Configuration”-Dashboard mindestens die Pflicht-Zuordnungen ausfüllen (Temperatursensor, Feuchtigkeitssensor und mindestens einen Ent-/Befeuchter). Entity-IDs müssen nicht per Hand getippt/eingefügt werden — stattdessen den such-basierten Helfer nutzen: Entwicklerwerkzeuge -> Aktionen -> “Grow Assistant: Set Mapping”, Funktion wählen und nach deinem Gerät suchen. Details siehe Mapping-Tool. Die “Setup Status”-Karte oben bestätigt, sobald alle Pflicht-Zuordnungen vollständig sind.
6. Falls noch nicht geschehen, HACS und die vier oben in Schritt 6 genannten Dashboard-Karten installieren, für das volle visuelle Erlebnis von Dashboard 2/3.

Weiter

• Core / Entity Mapping — wie das Mapping funktioniert und welche Felder Pflicht bzw. optional sind.
• Dashboard 1 – Configuration — das Dashboard, das dein Mapping steuert.
• Troubleshooting bei Fehlern während der Installation.
• Modul-Referenz siehe Sidebar unter „Module”.