DokumentationHome Assistant auf einem Wiren Board Controller installieren
Beschreibung
Home Assistant ist eine quelloffene Automatisierungsplattform, die von der Community home-assistant.io entwickelt und gepflegt wird. Die mobile App ermöglicht die Steuerung über das lokale Netzwerk oder den Cloud-Dienst der Plattform.
Die Plattform kann auf einem Wiren Board Controller installiert werden, um angeschlossene Geräte anstelle der Standard-Weboberfläche.
Kompatibilität
Empfohlen werden Wiren Board 8/8M und neuere Controller. Die Unterstützung von Home Assistant für Wiren Board 6 und 7 (armhf) endete Ende 2025; diese Modelle erhalten keine Updates mehr. Siehe die Ankündigung der Entwickler.
Installation
Der Flash-Speicher des Controllers ist partitioniert. Eine separate Benutzerpartition wird unter /mnt/dataeingebunden. Wurde die Root-Partition auf nahezu den gesamten eMMC-Speicher erweitert, ist /mnt/data ein normales Verzeichnis auf der Root-Partition. Berücksichtigen Sie dies beim Installieren von Software und beim Aktualisieren der Firmware.
Fügen Sie Befehle mit Shift+Insert in die Controller-Konsole ein und führen Sie sie mit Enter aus. Vergewissern Sie sich zuvor, dass Sie den Zweck des Befehls und seine Änderungen verstehen. Lesen Sie Fehlermeldungen sorgfältig, um Hinweise zur Behebung zu erhalten.
Verwenden Sie nano zum Bearbeiten der Konfigurationsdateien. Benötigt Drittanbietersoftware mehr Platz, kann die Root-Partition auf nahezu die gesamte eMMC-Kapazität erweitert werden.
Diese Anleitung verwendet die von den Entwicklern empfohlene Installationsmethode Home Assistant Container. Sie enthält keinen Supervisor; Add-ons können daher nicht über die Home Assistant Weboberfläche installiert werden. Add-ons enthalten meist Drittanbietersoftware wie zigbee2mqtt, ESPHome oder Node-RED, die Sie separat in Containern installieren können.
- Installieren Sie Docker gemäß der Docker-Installationsanleitung.
- Erstellen Sie das Installationsverzeichnis und wechseln Sie hinein:
mkdir -p /mnt/data/.docker-compose/home-assistant cd /mnt/data/.docker-compose/home-assistant
- Erstellen Sie die Verzeichnisse für Konfiguration und Medien:
mkdir -p config/home-assistant mkdir -p store/media
- Öffnen Sie docker-compose.yaml im Editor:
nano docker-compose.yaml
- Fügen Sie für Wiren Board 8 die folgende Konfiguration ein:
services: # HomeAssistant homeassistant: container_name: home-assistant image: homeassistant/home-assistant:latest volumes: # Local path where your home assistant config will be stored - ./config/home-assistant:/config - ./store/media:/media - /etc/localtime:/etc/localtime:ro - /run/dbus:/run/dbus:ro # <-- Bluetooth adapter restart: unless-stopped network_mode: host environment: TZ: "${MYTZ}" privileged: true labels: - "com.centurylinklabs.watchtower.monitor-only=true"Verwenden Sie für Wiren Board 6 und 7 stattdessen diese Konfiguration:
services: # HomeAssistant homeassistant: container_name: home-assistant image: ghcr.io/home-assistant/armhf-homeassistant:latest volumes: # Local path where your home assistant config will be stored - ./config/home-assistant:/config - ./store/media:/media - /etc/localtime:/etc/localtime:ro - /run/dbus:/run/dbus:ro # <-- Bluetooth adapter restart: unless-stopped network_mode: host environment: TZ: "${MYTZ}" privileged: true labels: - "com.centurylinklabs.watchtower.monitor-only=true" - Speichern Sie mit Ctrl+S und schließen Sie mit Ctrl+X.
- Legen Sie Ihre Zeitzone in der Datei .env fest. Wählen Sie eines der folgenden Beispiele oder eine andere gültige Linux-Zeitzone:
UTC (koordinierte Weltzeit):
echo "MYTZ=UTC" >> .env
Mitteleuropa (CEST/CET):
echo "MYTZ=Europe/Berlin" >> .env
Moskau (MSK):
echo "MYTZ=Europe/Moscow" >> .env
Alle verfügbaren Linux-Zeitzonen anzeigen:
timedatectl list-timezones
- Starten Sie den Container im Hintergrund:
docker compose up -d
Öffnen Sie nach dem Start des Containers die IP-Adresse des Controllers mit Port 8123 im Browser, zum Beispiel http://192.168.42.1:8123. Die Konsole können Sie nun schließen.
Aktualisierung
Verbinden Sie den Controller mit dem Internet, laden Sie das aktualisierte Image herunter und erstellen Sie den Container neu:
cd /mnt/data/.docker-compose/home-assistant docker compose pull homeassistant # Update the image docker compose up -d homeassistant # Recreate the container
Alle Einstellungen bleiben beim Neuerstellen des Containers erhalten, da die Konfiguration im Verzeichnis config gespeichert ist.
Wiren Board Geräte verwenden
Wiren Board Integration installieren
Die benutzerdefinierte Wiren Board Integration erstellt Home Assistant Entitäten automatisch aus den MQTT-Topics der Geräte. Die aktuelle Integration erfordert Home Assistant 2025.6 oder neuer.
- Kopieren Sie den Ordner wirenboard aus dem Repository nach
/mnt/data/.docker-compose/home-assistant/config/home-assistant/custom_components/. - Öffnen Sie die Home Assistant Weboberfläche.
- Starten Sie Home Assistant über Developer Tools → Restart neu.
- Öffnen Sie Settings → Devices & Services → Add Integration und wählen Sie wirenboard.
- Die Felder Host und Port enthalten die Standard-Verbindungseinstellungen des Controllers. Ändern Sie sie nur bei Bedarf.
MQTT-Integration installieren
Home Assistant kann Modbus-Geräte über MQTT steuern. Installieren Sie die MQTT-Integration und konfigurieren Sie den Datenempfang und -versand. Die folgenden Schritte und Screenshots verwenden das ältere Menü Configuration; neuere Versionen verwenden Settings.
- Öffnen Sie die Home Assistant Weboberfläche.
- Wählen Sie Configuration in der linken Seitenleiste und öffnen Sie Devices & Services.
- Klicken Sie unten auf Add Integration, suchen Sie nach MQTT und wählen Sie die Integration aus.
- Warten Sie auf den Konfigurationsdialog. Setzen Sie Broker auf localhost und Port auf 1883. Lassen Sie bei einem Controller mit Standardkonfiguration Benutzername und Passwort leer. Klicken Sie auf Submit.
Geräte manuell konfigurieren
Beschreiben Sie nach dem Einrichten der Integration jedes Gerät in configuration.yaml. Öffnen Sie die Datei im Editor:
nano /mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml
Das Konfigurationsverzeichnis ist /mnt/data/.docker-compose/home-assistant/config/home-assistant/. Fügen Sie Abschnitte mit den Geräteparametern hinzu; Relais werden beispielsweise im Abschnitt switch beschrieben.
Speichern Sie die Datei und starten Sie Home Assistant neu. Öffnen Sie in der älteren Oberfläche Configuration → Settings und klicken Sie auf Restart. Vor dem Neustart wird die Konfiguration geprüft; Fehler werden mit Details angezeigt. Häufig sind falsche Einrückungen die Ursache, da diese in YAML eine Bedeutung haben.
Der Speicherplatz auf dem Controller ist begrenzt. Fügen Sie die folgende recorder-Einstellung hinzu, um den Verlauf 14 Tage aufzubewahren. Überwachen Sie den freien Speicherplatz; die Aufbewahrungsdauer legt keine feste Obergrenze für die Datenbankgröße fest.
recorder: purge_keep_days: 14
- Die vollständige Syntax und unterstützten Gerätetypen finden Sie unter MQTT Discovery .
- Die Adressen der MQTT-Topics finden Sie in der Standard-Weboberfläche des Controllers unter Settings → MQTT Channels.
- Tragen Sie bei state_topic die Adresse des MQTT-Topics ein. Verwenden Sie für command_topic dieselbe Adresse mit angehängtem /on.
- Definieren Sie Sensoren unter mqtt:, wie im folgenden Temperaturbeispiel. Das Format wird in der Dokumentation zu Home Assistant MQTT-Sensoren erläutert. Fügen Sie switch und light unter demselben Schlüssel mqtt: ein; erstellen Sie keine doppelten mqtt:-Schlüssel auf oberster Ebene.
Messwert des CPU-Temperatursensors anzeigen:
mqtt:
sensor:
- unique_id: wb_cpu_temperature
name: "CPU Temperature"
state_topic: "/devices/hwmon/controls/CPU Temperature"
unit_of_measurement: "°C"
Ausgänge A1 und A2 steuern. Dieses Beispiel kann auch zur Steuerung von Relaismodulen verwendet werden:
#mqtt:
switch:
- unique_id: wb_a1_switch
name: "WB A1 Switch"
state_topic: "/devices/wb-gpio/controls/A1_OUT"
command_topic: "/devices/wb-gpio/controls/A1_OUT/on"
payload_on: "1"
payload_off: "0"
retain: true
- unique_id: wb_a2_switch
name: "WB A2 Switch"
state_topic: "/devices/wb-gpio/controls/A2_OUT"
command_topic: "/devices/wb-gpio/controls/A2_OUT/on"
payload_on: "1"
payload_off: "0"
retain: true
Summer des Controllers steuern. Dieses Beispiel kann für einen LED-Lampendimmer angepasst werden:
#mqtt:
light:
- unique_id: wb_buzzer
name: "Buzzer"
state_topic: "/devices/buzzer/controls/enabled"
command_topic: "/devices/buzzer/controls/enabled/on"
brightness_state_topic: '/devices/buzzer/controls/volume'
brightness_command_topic: '/devices/buzzer/controls/volume/on'
brightness_scale: 100
payload_on: "1"
payload_off: "0"
retain: true
Cloud-Zugriff
Fügen Sie Home Assistant für den Zugriff außerhalb des lokalen Netzwerks als Dienst in Wiren Board Cloud hinzu. Klicken Sie auf der Controller-Seite auf Services und wählen Sie Home Assistant im Katalog. Port 8123 wird automatisch eingetragen.
Zunächst meldet Home Assistant 400: Bad Request , da Anfragen über den Cloud-Proxy nicht als vertrauenswürdig gelten. Öffnen Sie Home Assistant lokal über die Controller-Adresse und Port 8123 und gehen Sie zu Settings → System → Network. Die weiteren Schritte hängen von Ihrer Home Assistant Version ab.
Enthält die Seite Network den Abschnitt HTTP server, verwenden Sie Home Assistant 2026.8 oder neuer. Konfigurieren Sie die HTTP-Einstellungen in diesen Versionen über die Weboberfläche:
- Klappen Sie unter HTTP server den Bereich Reverse proxy auf.
- Aktivieren Sie Trust X-Forwarded-For.
- Fügen Sie unter Trusted proxies einzeln 127.0.0.1, ::1 und 172.16.0.0/12 hinzu.
- Klicken Sie auf Save und anschließend auf Save and restart.
- Klicken Sie nach dem Neustart im Dialog zur Bestätigung der neuen HTTP-Serverkonfiguration auf Confirm. Bestätigen Sie innerhalb von 5 Minuten; andernfalls stellt Home Assistant die vorherigen Einstellungen wieder her.
Fehlt der Abschnitt HTTP server, verwenden Sie eine Version vor 2026.8. Dies gilt auch für Wiren Board 6 und 7, die keine neuen Versionen mehr erhalten:
- Fügen Sie Folgendes in
/mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml:http: use_x_forwarded_for: true trusted_proxies: - 127.0.0.1 - ::1 - 172.16.0.0/12 - Starten Sie den Container neu:
docker restart home-assistant
Wenn Sie später auf Home Assistant 2026.8 oder neuer aktualisieren, werden die HTTP-Einstellungen beim ersten Start in den Abschnitt HTTP server übernommen. Klicken Sie bei Aufforderung innerhalb von 5 Minuten auf Confirm; andernfalls werden die Einstellungen zurückgesetzt und müssen wie oben beschrieben erneut eingegeben werden. Prüfen Sie die Adressen unter Trusted proxies und entfernen Sie anschließend den Block http: aus configuration.yaml.