Gladys Assistant auf einem Home Assistant Yellow (internes Zigbee) installieren

Anleitungen
1

Tutorial: Gladys Assistant auf einem Home Assistant Yellow (internes Zigbee) installieren

  1. Nov. 2026 · @XDECO

Einführung

Dieses Tutorial erklärt, wie man Home Assistant OS durch Gladys Assistant (unter Docker) auf einem Home Assistant Yellow ersetzt, wobei das integrierte Zigbee-Radio auf der Karte beibehalten wird. Das Verfahren wurde einmal an einem einzigen Yellow durchgeführt: Es ist weder offiziell von Gladys noch von Nabu Casa.

Lesen Sie dies, bevor Sie beginnen:

  • Die Installation löscht Home Assistant OS und alle Inhalte der SSD. Sichern Sie alles, was Sie behalten möchten.
  • Das Zigbee-Radio muss ein für Zigbee2MQTT geeignetes Firmware erhalten (Schritt 1). Führen Sie dies von Home Assistant OS aus, bevor Sie es löschen.
  • In unserem Test funktioniert das Wi-Fi nicht (fehlendes Firmware): Verbinden Sie den Yellow per Ethernet.
  • Nur Zigbee, Ethernet und der NVMe-SSD wurden überprüft. Die anderen Funktionen der Karte (Wi-Fi, Bluetooth, Uhr, LED, Taste) wurden nicht getestet.
  • Die Befehle zur Vorbereitung der SSD werden für macOS angegeben; unter Linux oder Windows ist die Logik dieselbe.

Verwendete Hardware und Software

Hier ist die genaue Konfiguration, auf der das Verfahren getestet wurde.

Hardware

Element Details
Karte Home Assistant Yellow
Rechenmodul Raspberry Pi CM4 Lite (ohne eMMC), 8 GB RAM, mit Wi-Fi
Speicher Samsung 970 EVO Plus 500 GB NVMe-SSD, im M.2-Anschluss des Yellow
Netzwerk Ethernet (Wi-Fi funktioniert in dieser Anordnung nicht)
Zigbee-Radio Internes Silicon Labs-Radio des Yellow, an den seriellen Port /dev/ttyAMA1 angeschlossen

Software

Element Details
System Raspberry Pi OS Lite 64-Bit (Debian Trixie), Kernel 6.18.50+rpt-rpi-v8
Container Docker und Docker Compose
Gladys Assistant Image gladysassistant/gladys:v5
Automatische Updates Watchtower (nickfedor/watchtower)
MQTT-Broker Mosquitto (eclipse-mosquitto:2)
Zigbee Zigbee2MQTT (koenkk/zigbee2mqtt), Adapter ember
Radio-Firmware yellow_zigbee_ncp_7.4.4.0, installiert mit dem Silicon Labs Flasher-Modul
Hardware-Konfigurationsdatei bcm2711-rpi-cm4-ha-yellow.dtb, extrahiert aus dem Home Assistant OS 18.4-Image für Yellow

Wenn Ihr Yellow ein CM4 mit eMMC ist, unterscheiden sich die Installationsschritte auf der SSD: Dieses Verfahren deckt dies nicht ab.

Schritt 1: Installieren des geeigneten Zigbee-Firmware auf dem Radio (von Home Assistant OS aus)

Zigbee2MQTT benötigt ein „NCP“-Zigbee-Firmware auf dem Radio des Yellow. Führen Sie diesen Schritt aus, solange Home Assistant OS noch funktioniert: Er basiert auf einem Zusatzmodul (Add-on), das nach dem Löschen nicht mehr existiert.

  1. In Home Assistant alles stoppen, das das Radio verwendet (ZHA, Zigbee2MQTT, Multiprotocol-Modul), um den seriellen Port freizugeben.
  2. Installieren Sie das Modul Silicon Labs Flasher aus dem Zusatzmodul-Shop.
  3. In dessen Konfiguration einstellen: Gerät /dev/ttyAMA1, Baudrate 115200, Hardware-Flow-Control aktiviert. Wählen Sie das Zigbee-Firmware des Yellow (yellow_zigbee_ncp_7.4.4.0). Die Bezeichnungen können je nach Modulversion variieren.
  4. Starten Sie das Modul und lesen Sie seine Protokolle. In unserem Fall hat es das Radio erkannt, dann wurde das Flashen erfolgreich abgeschlossen.

Das Firmware wird nur einmal geschrieben: Es bleibt nach dem Löschen der SSD erhalten.

Schritt 2: Abrufen der Hardware-Konfigurationsdatei des Yellow

Raspberry Pi OS kennt die Yellow-Karte nicht: Es muss die Datei bcm2711-rpi-cm4-ha-yellow.dtb (Device Tree) bereitgestellt werden, die die mit dem Radio verbundenen seriellen Ports beschreibt. Diese wird aus dem offiziellen Home Assistant OS-Image für Yellow entnommen.

  1. Laden Sie das Image haos_yellow-<version>.img.xz auf der Seite der Home Assistant Operating System-Versionen herunter (wir haben die 18.4 verwendet), und entpacken Sie es.
  2. Mounten Sie die erste Partition des Images (die Startpartition im FAT-Format) und kopieren Sie die .dtb-Datei. Bewahren Sie auch die Dateien config.txt und cmdline.txt als Referenz auf.

Unter macOS:

xz -d haos_yellow-18.4.img.xz
hdiutil attach -nomount haos_yellow-18.4.img
diskutil list                      # Identifizieren Sie die Festplatte des Bildes, z. B. disk4
diskutil mount readOnly /dev/disk4s1
mkdir -p ~/yellow-gladys
cp /Volumes/*/bcm2711-rpi-cm4-ha-yellow.dtb ~/yellow-gladys/
cp /Volumes/*/config.txt /Volumes/*/cmdline.txt ~/yellow-gladys/
hdiutil detach /dev/disk4

Kopieren Sie die Datei vor dem Trennen des Bildes. Passen Sie die Festplattennummer (disk4) an Ihren Computer an und überprüfen Sie mit ls /Volumes, ob das richtige Volume gemountet ist: Der Platzhalter * kann mehrere bezeichnen.

Unter Linux: sudo losetup -fP --show haos_yellow-18.4.img, dann mounten Sie die Partition p1 des erhaltenen Geräts und kopieren Sie dieselben Dateien.

Schritt 3: Raspberry Pi OS Lite auf den NVMe-SSD schreiben

Nehmen Sie den SSD aus dem Yellow und schließen Sie ihn mit einem Gehäuse oder einem USB-Adapter für NVMe an Ihren Computer an. Wenn Ihr Yellow bereits von diesem SSD unter Home Assistant OS gestartet wurde, ist die Bootreihenfolge des CM4 bereits für NVMe eingestellt.

  1. Starten Sie Raspberry Pi Imager.
  2. Kartenmodell: Raspberry Pi 4 (das CM4 ist ähnlich).
  3. Betriebssystem: Unter Raspberry Pi OS (other) wählen Sie Raspberry Pi OS Lite (64-bit). Es erscheint nicht in der Hauptliste.
  4. Speicher: Wählen Sie den SSD aus und stellen Sie sicher, dass es der richtige und kein anderes Laufwerk ist, da es gelöscht wird.
  5. Anpassung: Hostname gladys, Benutzer pi mit einem Passwort, das Sie sich merken, SSH aktiviert, Zeitzone und Tastaturlayout nach Ihren Wünschen. Deaktivieren Sie Raspberry Pi Connect, wenn der Assistent dies vorschlägt.
  6. Schreiben Sie das Bild und warten Sie, bis die Überprüfung abgeschlossen ist.

Setzen Sie den SSD noch nicht in den Yellow ein: Der nächste Schritt ändert seine Boot-Partition.

Schritt 4: Anpassen der Boot-Partition für den Yellow

Nach dem Schreiben ist die Partition bootfs des SSDs (im FAT-Format) auf Ihrem Computer sichtbar. Drei Änderungen reichen aus. Machen Sie zunächst eine Kopie der Originaldateien.

cd /Volumes/bootfs                 # Pfad unter Linux oder Windows anpassen
cp config.txt config.txt.orig
cp cmdline.txt cmdline.txt.orig
cp ~/yellow-gladys/bcm2711-rpi-cm4-ha-yellow.dtb .

1. config.txt: Fügen Sie diese Zeilen am Ende der Datei hinzu.

[cm4]
device_tree=bcm2711-rpi-cm4-ha-yellow.dtb
enable_uart=1
arm_64bit=1
gpu_mem=32

2. cmdline.txt: Diese Datei enthält nur eine einzige Zeile. Ersetzen Sie die Standard-Serienkonsole (console=serial0,115200) durch console=ttyAMA2,115200n8 und ändern Sie nichts anderes, insbesondere nicht root=PARTUUID=.... Die Datei muss in einer einzigen Zeile bleiben, ohne Zeilenumbrüche in der Mitte.

3. Die .dtb-Datei ist die oben kopierte: Sie muss sich im Stammverzeichnis von bootfs, neben config.txt, befinden.

Trennen Sie den SSD ordnungsgemäß, setzen Sie ihn in den Yellow ein und schließen Sie das Ethernet-Kabel an. Wenn der Yellow nicht startet, ermöglichen die .orig-Dateien eine Rückkehr zum ursprünglichen Zustand zum Vergleich.

Schritt 5: Erster Start, serielle Ports und Docker

Der erste Start dauert eine bis zwei Minuten. Melden Sie sich anschließend per SSH von Ihrem Computer aus an:

ssh pi@gladys.local

Wenn der Name gladys.local nicht aufgelöst wird, verwenden Sie die IP-Adresse des Yellow, die von Ihrer Internet-Box angezeigt wird.

Überprüfen Sie, ob die Hardware-Konfigurationsdatei korrekt geladen wird

ls /dev | grep -E 'tty(AMA|S|USB|ACM)'

Die Ports ttyAMA0, ttyAMA1 und ttyAMA2 müssen angezeigt werden. ttyAMA1 ist der der Zigbee-Funkgerät. Wenn sie nicht vorhanden sind, wird das .dtb nicht geladen: Lesen Sie Schritt 4 noch einmal.

Docker installieren

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker pi
exit

Melden Sie sich erneut per SSH an, damit die Zugehörigkeit zur Gruppe docker berücksichtigt wird, und testen Sie dann:

docker run --rm hello-world
docker compose version

Schritt 6: Gladys Assistant und Watchtower installieren

Dies ist die übliche Docker-Installation von Gladys, geschrieben als Docker Compose-Datei. Erstellen Sie den Ordner und die Datei:

mkdir -p ~/gladys && cd ~/gladys
nano gladys-compose.yml

Inhalt der Datei gladys-compose.yml:

services:
  gladys:
    image: gladysassistant/gladys:v5
    container_name: gladys
    restart: always
    privileged: true
    network_mode: host
    cgroup: host
    environment:
      NODE_ENV: production
      SQLITE_FILE_PATH: /var/lib/gladysassistant/gladys-production.db
      SERVER_PORT: 80
      TZ: Europe/Paris
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/gladysassistant:/var/lib/gladysassistant
      - /dev:/dev
      - /run/udev:/run/udev:ro
      - /run/dbus:/run/dbus:ro

  watchtower:
    image: nickfedor/watchtower
    container_name: watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --cleanup --include-restarting

Passen Sie die Zeitzone (TZ) an. Watchtower aktualisiert Gladys automatisch; wir haben das Bild nickfedor/watchtower verwendet, aber jedes andere Watchtower-Bild funktioniert ebenfalls.

Starten Sie alles:

docker compose -f gladys-compose.yml up -d
docker logs --tail 20 gladys

Öffnen Sie anschließend http://gladys.local in einem Browser. Wenn Sie von vorne beginnen, erstellen Sie Ihr Konto. Wenn Sie eine bestehende Instanz migrieren (Schritt 9), erstellen Sie hier kein Konto: Der Import bringt die Konten der alten Instanz mit.

Schritt 7: Mosquitto und Zigbee2MQTT auf dem internen Radio

Der Modus “Installation von Gladys” der Zigbee2MQTT-Integration ist für einen USB-Dongle vorgesehen, den Gladys auf den USB-Ports sucht. Das Radio des Yellow ist ein interner Serial-Port (/dev/ttyAMA1): Wir starten also Mosquitto und Zigbee2MQTT selbst und verbinden Gladys dann mit dieser bestehenden Installation (Schritt 8).

mkdir -p ~/zigbee/mosquitto/config ~/zigbee/mosquitto/data ~/zigbee/z2m-data
cd ~/zigbee

~/zigbee/mosquitto/config/mosquitto.conf

listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/

Diese Konfiguration akzeptiert Verbindungen ohne Identifikation: Dies sollte nur in einem vertrauenswürdigen lokalen Netzwerk verwendet werden.

~/zigbee/docker-compose.yml

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: always
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    restart: always
    depends_on:
      - mosquitto
    ports:
      - "8080:8080"
    volumes:
      - ./z2m-data:/app/data
    devices:
      - /dev/ttyAMA1:/dev/ttyAMA1
    environment:
      - TZ=Europe/Paris

~/zigbee/z2m-data/configuration.yaml

version: 5
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
serial:
  port: /dev/ttyAMA1
  adapter: ember
  baudrate: 115200
  rtscts: true
frontend:
  enabled: true
  port: 8080
advanced:
  channel: 20
  pan_id: GENERATE
  ext_pan_id: GENERATE
  network_key: GENERATE

Wichtige Punkte: Der Adapter ist ember, die Baudrate 115200 und die Hardware-Flusssteuerung (rtscts: true) muss aktiviert sein, wie beim Firmware-Flash. Die Werte GENERATE lassen Zigbee2MQTT beim ersten Start eine zufällige Netzwerk-ID und einen zufälligen Netzwerkschlüssel erstellen.

Starten und überprüfen Sie:

docker compose up -d
docker logs --tail 30 zigbee2mqtt

Die Nachricht RESET_WATCHDOG beim Start des Radios ist harmlos. Die Weboberfläche von Zigbee2MQTT ist anschließend unter http://gladys.local:8080 erreichbar.

Netzwerkschlüssel: Die Datei configuration.yaml enthält den generierten Zigbee-Netzwerkschlüssel. Veröffentlichen Sie ihn niemals (Forum, Screenshot, Kopie der Datei): Jeder, der ihn kennt, kann Ihr Zigbee-Netzwerk abhören. Falls er geleakt wurde, generieren Sie ihn neu, bevor Sie ein Gerät hinzufügen.

Schritt 8: Gladys mit Zigbee2MQTT verbinden und Geräte hinzufügen

Verbindung

  1. In Gladys, öffnen Sie Integrationen, dann Zigbee2MQTT, Registerkarte Konfiguration.
  2. Zwei Karten werden angeboten. Klicken Sie auf Auswählen in der rechten, “Verbindung zu einer bestehenden Installation”. Wählen Sie nicht “Installation von Gladys”: Gladys würde seine eigenen Container starten, die sich mit Ihren um das Radio und den Port 8080 streiten würden.
  3. Geben Sie die Adresse des MQTT-Brokers an: mqtt://localhost:1883 (Gladys ist im Host-Netzwerk, localhost erreicht Mosquitto). Andernfalls verwenden Sie mqtt://<IP-Adresse des Yellow>:1883. Lassen Sie Benutzername und Passwort mit der obigen Mosquitto-Konfiguration leer.
  4. Wenn die URL der Zigbee2MQTT-Oberfläche gefragt wird: http://<IP-Adresse des Yellow>:8080.
  5. Speichern Sie und überprüfen Sie, dass die Integration eine Verbindung anzeigt.

Gerät hinzufügen

  • Ein bereits mit einem anderen Koordinator verbundenes Gerät muss zuerst zurückgesetzt werden (Werkseinstellung), sonst sucht es nicht nach einem neuen Netzwerk. Entfernen Sie es auch vom alten Netzwerk, falls möglich.
  • Aktivieren Sie die Verbindung: Registerkarte Zigbee-Erkennung in Gladys oder Permit join-Button in der Zigbee2MQTT-Oberfläche. Das Fenster dauert etwa vier Minuten.
  • Setzen Sie das Gerät in den Verbindungsmodus, ein oder zwei Meter vom Yellow entfernt, ein Gerät nach dem anderen.
  • Verbinden Sie zuerst die netzgebundenen Geräte (Steckdosen, Lampen), die das Netzwerk verstärken, dann die batteriebetriebenen.
  • Geben Sie jedem Gerät einen klaren Namen. Gladys identifiziert ein Zigbee2MQTT-Gerät an seinem Namen: Beim Migrieren übernehmen Sie die alten Namen, um bereits vorhandene Geräte wiederzufinden.

Um die Verfügbarkeit und den letzten Empfang anzuzeigen, in der Zigbee2MQTT-Oberfläche: Einstellungen, Registerkarte Availability, aktivieren Sie Enabled; Registerkarte Advanced, setzen Sie last_seen auf ISO_8601.

Linky-Zähler (ZLinky_TIC), falls vorhanden: In den spezifischen Geräteeinstellungen muss der Linky-Modus dem des Zählers entsprechen (historisch oder standardmäßig, oder auto). In unserem Fall ist der Zähler im historischen Modus mit einem Tempo-Tarif, und linky_mode ist auf historique eingestellt. Der Tarif ist auf „Historique - BBR“ eingestellt. Der historische Modus ist mit Tempo kompatibel.

Schritt 9 (optional): Eine bestehende Gladys-Instanz mit ihrem Verlauf migrieren

Dieser Schritt übernimmt die Daten eines anderswo installierten Gladys (hier auf einem Synology-NAS). Der Datenordner enthält die SQLite-Datenbank, die DuckDB-Verlaufsdatenbank und die Integrationsdateien.

Behalten Sie die alte Instanz während und nach der Migration gestoppt, damit nicht zwei Gladys dieselben Geräte steuern.

Auf dem alten Server

docker inspect gladys --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'
docker stop gladys

Der erste Befehl zeigt den Host-Datenordner an (der auf /var/lib/gladysassistant gemountet ist). Machen Sie ein Backup dieses Ordners, dann archivieren Sie ihn:

tar czf /tmp/gladys-data.tgz -C <übergeordneter Ordner> gladysassistant

Auf einem Synology erfordert docker sudo.

Auf dem Yellow

Rufen Sie das Archiv ab (die Option -O von scp ist erforderlich, wenn SFTP auf dem NAS deaktiviert ist):

scp -O <Benutzer>@<NAS-Adresse>:/tmp/gladys-data.tgz /tmp/

Dann ersetzen Sie die leeren Daten der neuen Installation:

cd ~/gladys
docker compose -f gladys-compose.yml stop gladys
sudo mv /var/lib/gladysassistant /var/lib/gladysassistant.leer
sudo mkdir /var/lib/gladysassistant
sudo tar xzf /tmp/gladys-data.tgz -C /var/lib/gladysassistant --strip-components=1
sudo chmod -R u+rwX /var/lib/gladysassistant
docker compose -f gladys-compose.yml start gladys

Melden Sie sich anschließend mit dem Konto der alten Instanz an.

Was nach dem Import noch zu tun ist

  • Die Erweiterungen (externe Integrationen) laufen in Containern gladys-ext-*, die nicht von selbst neu erstellt werden: In unserem Fall mussten wir das Update aller installierten Erweiterungen erzwingen, eine nach der anderen: Integrationen, die betroffene Erweiterung, Registerkarte Überwachung, Button Update erzwingen. Gladys erstellt dann ihren Container neu und sie funktioniert wieder. Überprüfen Sie dies mit docker ps.
  • Die Zigbee-Geräte müssen mit dem neuen Koordinator neu verbunden werden (Schritt 8), mit ihren alten Namen. Gladys hat die Umbenennungen auf bestehende Geräte angewendet; überprüfen Sie an einem Gerät, ob seine Historie erhalten bleibt, bevor Sie alle neu verbinden.
  • Die Konfiguration der importierten Zigbee2MQTT-Integration zeigt auf die alte Installation: Führen Sie Schritt 8 nach dem Import erneut aus.
  • Stoppen Sie die Erweiterung-Container des alten Servers und bewahren Sie sein Backup mehrere Tage auf.

Bekannte Grenzen, Fehlerbehebung und Backup

Festgestellte Grenzen

  • Wi-Fi: Es funktioniert nicht in unserer Konfiguration, da der Firmware der Wi-Fi-Chip für diesen Device Tree nicht bereitgestellt wird. Verwenden Sie Ethernet.
  • Weitere Funktionen der Karte (Bluetooth, Echtzeituhr, LED, Taste): nicht getestet.
  • Prozedur wurde nur einmal getestet, auf einem CM4 Lite 8 GB mit NVMe-SSD.

Fehlerbehebung

Symptom Spur
Der Yellow reagiert nicht nach dem Start Überprüfen Sie das Ethernet-Kabel und die IP-Adresse in Ihrer Box. Überprüfen Sie den Inhalt von config.txt und cmdline.txt (nur eine Zeile).
Kein ttyAMA1 Die .dtb wird nicht geladen: Block [cm4] von config.txt und Vorhandensein der Datei im Root-Verzeichnis von bootfs.
Zigbee2MQTT startet nicht Lesen Sie docker logs zigbee2mqtt. Überprüfen Sie adapter: ember, baudrate: 115200, rtscts: true und ob der NCP-Firmware tatsächlich geflasht wurde.
Ein Gerät verbindet sich nicht Setzen Sie es zurück, halten Sie “Permit join” aktiv, bringen Sie es näher an den Yellow, folgen Sie docker logs -f zigbee2mqtt.
Eine Gladys-Erweiterung ist nicht verbunden docker ps, um zu sehen, ob ihr Container läuft, dann docker logs <Container-Name>. Testen Sie den Zugriff auf das Gerät vom Container aus (docker exec <Container> ping <Adresse>).
Ein Gerät reagiert auf ping, aber nicht in der Anwendung Starten Sie es vollständig neu (30 Sekunden lang vom Strom getrennt): Das hat unser AirSend-Gehäuse wiederhergestellt.

Kontrollen nach der Installation

docker inspect -f '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' gladys zigbee2mqtt mosquitto watchtower
sudo reboot

Die vier Container müssen always anzeigen, und alle Container müssen nach dem Neustart (docker ps) “Up” sein.

Backup: Kopieren Sie regelmäßig /var/lib/gladysassistant und ~/zigbee/z2m-data auf ein anderes Gerät. Letzteres enthält den Zigbee-Netzwerkschlüssel und die Geräteliste: Ohne ihn müssten alle Geräte neu verbunden werden.

sudo tar czf ~/gladys-sauvegarde-$(date +%F).tgz /var/lib/gladysassistant zigbee/z2m-data
sudo chown $USER:$USER ~/gladys-sauvegarde-*.tgz && chmod 600 ~/gladys-sauvegarde-*.tgz

Führen Sie diesen Befehl aus Ihrem persönlichen Ordner aus und bewahren Sie das Archiv an einem sicheren Ort auf, da es den Netzwerkschlüssel enthält.

Yellow für Gladys OS? Quellen

Dieses Verfahren zeigt, dass ein Yellow Gladys auf Raspberry Pi OS mit internem Zigbee ausführen kann. Ein fertiges Flash-Image wäre möglich, indem die Datei bcm2711-rpi-cm4-ha-yellow.dtb, die drei Änderungen von config.txt und cmdline.txt, Docker, Gladys, Mosquitto und Zigbee2MQTT integriert werden. Für ein sauberes Image müssen noch überprüft werden: WLAN, Bluetooth, die Echtzeituhr und die Firmwareverwaltung des Radios. Die Rückmeldungen anderer Yellow-Nutzer, insbesondere mit einem CM4 und eMMC, wären wertvoll.

Quellen:

2 „Gefällt mir“