Installer Gladys Assistant sur un Home Assistant Yellow (Zigbee interne)

Tutoriels
1

Tutoriel : installer Gladys Assistant sur un Home Assistant Yellow (Zigbee interne)

Nov 7, 2026 · @XDECO

Introduction

Ce tutoriel explique comment remplacer Home Assistant OS par Gladys Assistant (sous Docker) sur un Home Assistant Yellow, en conservant la radio Zigbee intégrée à la carte. La procédure a été réalisée une fois, sur un seul Yellow : elle n’est ni officielle côté Gladys, ni côté Nabu Casa.

À lire avant de commencer :

  • L’installation efface Home Assistant OS et tout le contenu du SSD. Sauvegardez ce que vous voulez garder.
  • La radio Zigbee doit recevoir un firmware adapté à Zigbee2MQTT (étape 1). Faites-le depuis Home Assistant OS, avant de l’effacer.
  • Dans notre test, le Wi-Fi ne fonctionne pas (firmware manquant) : branchez le Yellow en Ethernet.
  • Seuls le Zigbee, l’Ethernet et le SSD NVMe ont été vérifiés. Les autres fonctions de la carte (Wi-Fi, Bluetooth, horloge, LED, bouton) n’ont pas été testées.
  • Les commandes de préparation du SSD sont données pour macOS ; sous Linux ou Windows, la logique est la même.

Matériel et logiciels utilisés

Voici la configuration exacte sur laquelle la procédure a été testée.

Matériel

Élément Détail
Carte Home Assistant Yellow
Module de calcul Raspberry Pi CM4 Lite (sans eMMC), 8 Go de RAM, avec Wi-Fi
Stockage SSD NVMe Samsung 970 EVO Plus 500 Go, dans le port M.2 du Yellow
Réseau Ethernet (le Wi-Fi ne fonctionne pas dans ce montage)
Radio Zigbee Radio interne Silicon Labs du Yellow, reliée au port série /dev/ttyAMA1

Logiciels

Élément Détail
Système Raspberry Pi OS Lite 64 bits (Debian Trixie), noyau 6.18.50+rpt-rpi-v8
Conteneurs Docker et Docker Compose
Gladys Assistant image gladysassistant/gladys:v5
Mises à jour automatiques Watchtower (nickfedor/watchtower)
Courtier MQTT Mosquitto (eclipse-mosquitto:2)
Zigbee Zigbee2MQTT (koenkk/zigbee2mqtt), adaptateur ember
Firmware de la radio yellow_zigbee_ncp_7.4.4.0, installé avec le module Silicon Labs Flasher
Fichier de configuration matérielle bcm2711-rpi-cm4-ha-yellow.dtb, extrait de l’image Home Assistant OS 18.4 pour Yellow

Si votre Yellow est un CM4 avec eMMC, les étapes d’installation sur le SSD diffèrent : cette procédure ne le couvre pas.

Étape 1 : mettre le firmware Zigbee adapté sur la radio (depuis Home Assistant OS)

Zigbee2MQTT a besoin d’un firmware Zigbee “NCP” sur la radio du Yellow. Faites cette étape tant que Home Assistant OS fonctionne encore : elle repose sur un module complémentaire (add-on) qui n’existera plus après l’effacement.

  1. Dans Home Assistant, arrêtez tout ce qui utilise la radio (ZHA, Zigbee2MQTT, module multiprotocole), pour libérer le port série.
  2. Installez le module Silicon Labs Flasher depuis la boutique de modules complémentaires.
  3. Dans sa configuration, réglez : périphérique /dev/ttyAMA1, débit (baudrate) 115200, contrôle de flux matériel activé. Choisissez le firmware Zigbee du Yellow (yellow_zigbee_ncp_7.4.4.0). Les libellés peuvent varier selon la version du module.
  4. Démarrez le module et lisez ses journaux. Dans notre cas il a détecté la radio, puis le flash s’est terminé avec succès.

Le firmware n’est écrit qu’une fois : il reste en place après l’effacement du SSD.

Étape 2 : récupérer le fichier de configuration matérielle du Yellow

Raspberry Pi OS ne connaît pas la carte Yellow : il faut lui fournir le fichier bcm2711-rpi-cm4-ha-yellow.dtb (device tree), qui décrit les ports série reliés à la radio. On le prend dans l’image officielle de Home Assistant OS pour Yellow.

  1. Téléchargez l’image haos_yellow-<version>.img.xz sur la page des versions de Home Assistant Operating System (nous avons utilisé la 18.4), puis décompressez-la.
  2. Montez la première partition de l’image (la partition de démarrage, au format FAT) et copiez-en le fichier .dtb. Gardez aussi, pour référence, ses fichiers config.txt et cmdline.txt.

Sous macOS :

xz -d haos_yellow-18.4.img.xz
hdiutil attach -nomount haos_yellow-18.4.img
diskutil list                      # repérez le disque de l'image, par exemple 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

Copiez le fichier avant de détacher l’image. Adaptez le numéro de disque (disk4) à votre machine, et vérifiez avec ls /Volumes que le bon volume est monté : le caractère générique * peut en désigner plusieurs.

Sous Linux : sudo losetup -fP --show haos_yellow-18.4.img, puis montez la partition p1 du périphérique obtenu et copiez les mêmes fichiers.

Étape 3 : écrire Raspberry Pi OS Lite sur le SSD NVMe

Sortez le SSD du Yellow et branchez-le à votre ordinateur avec un boîtier ou un adaptateur USB pour NVMe. Si votre Yellow démarrait déjà sur ce SSD sous Home Assistant OS, l’ordre de démarrage du CM4 est déjà réglé pour le NVMe.

  1. Lancez Raspberry Pi Imager.
  2. Modèle de carte : Raspberry Pi 4 (le CM4 en est proche).
  3. Système : dans Raspberry Pi OS (other), choisissez Raspberry Pi OS Lite (64-bit). Il n’apparaît pas dans la liste principale.
  4. Stockage : choisissez le SSD, en vérifiant bien que c’est lui et pas un autre disque, car il sera effacé.
  5. Personnalisation : nom d’hôte gladys, utilisateur pi avec un mot de passe que vous retiendrez, SSH activé, fuseau horaire et clavier à votre convenance. Désactivez Raspberry Pi Connect si l’assistant le propose.
  6. Écrivez l’image et attendez la fin de la vérification.

Ne remettez pas encore le SSD dans le Yellow : l’étape suivante modifie sa partition de démarrage.

Étape 4 : adapter la partition de démarrage au Yellow

Après l’écriture, la partition bootfs du SSD (au format FAT) est visible sur votre ordinateur. Trois modifications suffisent. Faites d’abord une copie des fichiers d’origine.

cd /Volumes/bootfs                 # adaptez le chemin sous Linux ou Windows
cp config.txt config.txt.orig
cp cmdline.txt cmdline.txt.orig
cp ~/yellow-gladys/bcm2711-rpi-cm4-ha-yellow.dtb .

1. config.txt : ajoutez ces lignes à la fin du fichier.

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

2. cmdline.txt : ce fichier ne contient qu’une seule ligne. Remplacez la console série par défaut (console=serial0,115200) par console=ttyAMA2,115200n8 et ne touchez à rien d’autre, en particulier à root=PARTUUID=.... Le fichier doit rester sur une seule ligne, sans retour à la ligne au milieu.

3. Le fichier .dtb est celui copié ci-dessus : il doit se trouver à la racine de bootfs, à côté de config.txt.

Éjectez proprement le SSD, remettez-le dans le Yellow et branchez le câble Ethernet. Si le Yellow ne démarre pas, les fichiers .orig permettent de revenir à l’état d’origine pour comparer.

Étape 5 : premier démarrage, ports série et Docker

Le premier démarrage prend une à deux minutes. Connectez-vous ensuite en SSH, depuis votre ordinateur :

ssh pi@gladys.local

Si le nom gladys.local ne se résout pas, utilisez l’adresse IP du Yellow indiquée par votre box internet.

Vérifier que le fichier de configuration matérielle est bien pris en compte

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

Les ports ttyAMA0, ttyAMA1 et ttyAMA2 doivent apparaître. ttyAMA1 est celui de la radio Zigbee. S’ils sont absents, le .dtb n’est pas chargé : relisez l’étape 4.

Installer Docker

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

Reconnectez-vous en SSH pour que l’appartenance au groupe docker soit prise en compte, puis testez :

docker run --rm hello-world
docker compose version

Étape 6 : installer Gladys Assistant et Watchtower

C’est l’installation Docker habituelle de Gladys, écrite sous forme de fichier Docker Compose. Créez le dossier et le fichier :

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

Contenu du fichier 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

Adaptez le fuseau horaire (TZ). Watchtower met à jour Gladys automatiquement ; nous avons utilisé l’image nickfedor/watchtower, mais une autre image Watchtower convient aussi.

Lancez le tout :

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

Ouvrez ensuite http://gladys.local dans un navigateur. Si vous partez de zéro, créez votre compte. Si vous migrez une instance existante (étape 9), ne créez pas de compte ici : l’import apporte les comptes de l’ancienne instance.

Étape 7 : Mosquitto et Zigbee2MQTT sur la radio interne

Le mode “Installation depuis Gladys” de l’intégration Zigbee2MQTT est prévu pour un dongle USB, que Gladys cherche sur les ports USB. La radio du Yellow est un port série interne (/dev/ttyAMA1) : on lance donc Mosquitto et Zigbee2MQTT soi-même, puis on connecte Gladys à cette installation existante (étape 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/

Cette configuration accepte les connexions sans identifiant : à réserver à un réseau local de confiance.

~/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

Les points importants : l’adaptateur est ember, le débit 115200 et le contrôle de flux matériel (rtscts: true) doit être activé, comme au flash du firmware. Les valeurs GENERATE font créer à Zigbee2MQTT un identifiant et une clé réseau aléatoires au premier démarrage.

Lancez et vérifiez :

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

Le message RESET_WATCHDOG au démarrage de la radio est sans gravité. L’interface web de Zigbee2MQTT est ensuite sur http://gladys.local:8080.

Clé réseau : le fichier configuration.yaml contient la clé réseau Zigbee générée. Ne la publiez jamais (forum, capture, copie du fichier) : quiconque la connaît peut écouter votre réseau Zigbee. Si elle a fuité, régénérez-la avant d’associer le moindre appareil.

Étape 8 : connecter Gladys à Zigbee2MQTT et associer les appareils

Connexion

  1. Dans Gladys, ouvrez Intégrations, puis Zigbee2MQTT, onglet Configuration.
  2. Deux cartes sont proposées. Cliquez sur Choisir dans celle de droite, “Connexion à une installation existante”. Ne choisissez pas “Installation depuis Gladys” : Gladys lancerait ses propres conteneurs, qui se disputeraient la radio et le port 8080 avec les vôtres.
  3. Indiquez l’adresse du courtier MQTT : mqtt://localhost:1883 (Gladys étant en réseau hôte, localhost atteint Mosquitto). Sinon utilisez mqtt://<adresse IP du Yellow>:1883. Laissez l’identifiant et le mot de passe vides avec la configuration Mosquitto ci-dessus.
  4. Si l’URL de l’interface Zigbee2MQTT est demandée : http://<adresse IP du Yellow>:8080.
  5. Enregistrez et vérifiez que l’intégration indique une connexion.

Associer un appareil

  • Un appareil déjà associé à un autre coordinateur doit d’abord être réinitialisé (reset d’usine), sinon il ne cherche pas de nouveau réseau. Retirez-le aussi de l’ancien réseau si possible.
  • Activez l’association : onglet Découverte Zigbee de Gladys, ou bouton Permit join de l’interface Zigbee2MQTT. La fenêtre dure environ quatre minutes.
  • Mettez l’appareil en mode association, à un ou deux mètres du Yellow, un appareil à la fois.
  • Associez d’abord les appareils alimentés sur secteur (prises, ampoules), qui renforcent le réseau, puis ceux sur pile.
  • Donnez à chaque appareil un nom clair. Gladys identifie un appareil Zigbee2MQTT par son nom : en migrant, reprenez les anciens noms pour retrouver les appareils déjà présents.

Pour afficher la disponibilité et la dernière réception, dans l’interface Zigbee2MQTT : Paramètres, onglet Availability, activez Enabled ; onglet Advanced, réglez last_seen sur ISO_8601.

Compteur Linky (ZLinky_TIC), le cas échéant : dans les paramètres spécifiques de l’appareil, le mode du Linky doit correspondre à celui du compteur (historique ou standard, ou auto). Dans notre cas, le compteur est en mode historique avec un contrat Tempo, et linky_mode est réglé sur historique. Le tarif est réglé sur « Historique - BBR ». Le mode historique est compatible avec Tempo.

Étape 9 (optionnelle) : migrer une instance Gladys existante avec son historique

Cette étape reprend les données d’un Gladys installé ailleurs (ici sur un NAS Synology). Le dossier de données contient la base SQLite, la base d’historique DuckDB et les fichiers des intégrations.

Gardez l’ancienne instance arrêtée pendant et après la migration, pour que deux Gladys ne pilotent pas les mêmes appareils.

Sur l’ancien serveur

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

La première commande indique le dossier de données de l’hôte (celui monté sur /var/lib/gladysassistant). Faites une copie de sauvegarde de ce dossier, puis archivez-le :

tar czf /tmp/gladys-data.tgz -C <dossier parent> gladysassistant

Sur un Synology, docker demande sudo.

Sur le Yellow

Récupérez l’archive (l’option -O de scp est nécessaire si le SFTP est désactivé sur le NAS) :

scp -O <utilisateur>@<adresse du NAS>:/tmp/gladys-data.tgz /tmp/

Puis remplacez les données vides de la nouvelle installation :

cd ~/gladys
docker compose -f gladys-compose.yml stop gladys
sudo mv /var/lib/gladysassistant /var/lib/gladysassistant.vide
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

Connectez-vous ensuite avec le compte de l’ancienne instance.

Ce qu’il reste à faire après l’import

  • Les extensions (intégrations externes) tournent dans des conteneurs gladys-ext-* qui ne sont pas recréés tous seuls : dans notre cas, il a fallu forcer la mise à jour de toutes les extensions installées, une par une : Intégrations, l’extension concernée, onglet Supervision, bouton Forcer la mise à jour. Gladys recrée alors son conteneur et elle refonctionne. Contrôlez avec docker ps.
  • Les appareils Zigbee sont à réassocier au nouveau coordinateur (étape 8), avec leurs anciens noms. Gladys a bien appliqué les renommages à des appareils existants ; vérifiez sur un appareil que son historique est conservé avant de tous les refaire.
  • La configuration de l’intégration Zigbee2MQTT importée pointe vers l’ancienne installation : refaites l’étape 8 après l’import.
  • Arrêtez les conteneurs d’extension de l’ancien serveur et gardez sa sauvegarde plusieurs jours.

Limites connues, dépannage et sauvegarde

Limites constatées

  • Wi-Fi : il ne fonctionne pas dans notre montage, le firmware de la puce Wi-Fi n’étant pas fourni pour ce device tree. Utilisez l’Ethernet.
  • Autres fonctions de la carte (Bluetooth, horloge temps réel, LED, bouton) : non testées.
  • Procédure testée une seule fois, sur un CM4 Lite 8 Go avec SSD NVMe.

Dépannage

Symptôme Piste
Le Yellow ne répond pas après le démarrage Vérifiez le câble Ethernet et l’adresse IP dans votre box. Contrôlez le contenu de config.txt et de cmdline.txt (une seule ligne).
Pas de ttyAMA1 Le .dtb n’est pas chargé : bloc [cm4] de config.txt et présence du fichier à la racine de bootfs.
Zigbee2MQTT ne démarre pas Lisez docker logs zigbee2mqtt. Vérifiez adapter: ember, baudrate: 115200, rtscts: true et que le firmware NCP est bien flashé.
Un appareil ne s’associe pas Réinitialisez-le, gardez “Permit join” actif, rapprochez-le du Yellow, suivez docker logs -f zigbee2mqtt.
Une extension Gladys n’est pas connectée docker ps pour voir si son conteneur tourne, puis docker logs <nom du conteneur>. Testez l’accès à l’appareil depuis le conteneur (docker exec <conteneur> ping <adresse>).
Un appareil répond au ping mais pas dans l’application Redémarrez-le complètement (alimentation débranchée 30 secondes) : c’est ce qui a rétabli notre boîtier AirSend.

Contrôles après installation

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

Les quatre conteneurs doivent afficher always, et tous les conteneurs doivent être “Up” après le redémarrage (docker ps).

Sauvegarde : copiez régulièrement /var/lib/gladysassistant et ~/zigbee/z2m-data sur un autre appareil. Le second contient la clé réseau Zigbee et la liste des appareils : sans lui, il faudrait tout réassocier.

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

Lancez cette commande depuis votre dossier personnel et gardez l’archive en lieu sûr, car elle contient la clé réseau.

Vers un Gladys OS pour le Yellow ? Sources

Cette procédure démontre qu’un Yellow peut faire tourner Gladys sur Raspberry Pi OS, avec le Zigbee interne. Une image prête à flasher serait possible en intégrant le fichier bcm2711-rpi-cm4-ha-yellow.dtb, les trois modifications de config.txt et cmdline.txt, Docker, Gladys, Mosquitto et Zigbee2MQTT. Reste à vérifier, pour une image propre : le Wi-Fi, le Bluetooth, l’horloge temps réel et la gestion du firmware de la radio. Les retours d’autres utilisateurs de Yellow, avec un CM4 à eMMC notamment, seraient précieux.

Sources :

2 « J'aime »