Instalar Gladys Assistant en un Home Assistant Yellow (Zigbee interno)

Tutoriales
1

Tutorial: Instalar Gladys Assistant en un Home Assistant Yellow (Zigbee interno)

7 de noviembre de 2026 · @XDECO

Introducción

Este tutorial explica cómo reemplazar Home Assistant OS por Gladys Assistant (bajo Docker) en un Home Assistant Yellow, conservando la radio Zigbee integrada en la tarjeta. El procedimiento se realizó una vez, en un solo Yellow: no es oficial ni por parte de Gladys ni por parte de Nabu Casa.

Lea antes de comenzar:

  • La instalación borra Home Assistant OS y todo el contenido del SSD. Guarde lo que desee conservar.
  • La radio Zigbee debe recibir un firmware adaptado a Zigbee2MQTT (paso 1). Hágalo desde Home Assistant OS, antes de borrarlo.
  • En nuestra prueba, el Wi-Fi no funciona (firmware faltante): conecte el Yellow mediante Ethernet.
  • Solo se han verificado Zigbee, Ethernet y el SSD NVMe. Las otras funciones de la tarjeta (Wi-Fi, Bluetooth, reloj, LED, botón) no se han probado.
  • Los comandos de preparación del SSD se dan para macOS; en Linux o Windows, la lógica es la misma.

Material y software utilizados

Aquí está la configuración exacta en la que se probó el procedimiento.

Material

Elemento Detalle
Tarjeta Home Assistant Yellow
Módulo de cálculo Raspberry Pi CM4 Lite (sin eMMC), 8 GB de RAM, con Wi-Fi
Almacenamiento SSD NVMe Samsung 970 EVO Plus 500 GB, en el puerto M.2 del Yellow
Red Ethernet (el Wi-Fi no funciona en este montaje)
Radio Zigbee Radio interna Silicon Labs del Yellow, conectada al puerto serie /dev/ttyAMA1

Software

Elemento Detalle
Sistema Raspberry Pi OS Lite 64 bits (Debian Trixie), núcleo 6.18.50+rpt-rpi-v8
Contenedores Docker y Docker Compose
Gladys Assistant imagen gladysassistant/gladys:v5
Actualizaciones automáticas Watchtower (nickfedor/watchtower)
Broker MQTT Mosquitto (eclipse-mosquitto:2)
Zigbee Zigbee2MQTT (koenkk/zigbee2mqtt), adaptador ember
Firmware de la radio yellow_zigbee_ncp_7.4.4.0, instalado con el módulo Silicon Labs Flasher
Archivo de configuración de hardware bcm2711-rpi-cm4-ha-yellow.dtb, extraído de la imagen Home Assistant OS 18.4 para Yellow

Si su Yellow es un CM4 con eMMC, los pasos de instalación en el SSD son diferentes: este procedimiento no lo cubre.

Paso 1: Poner el firmware Zigbee adaptado en la radio (desde Home Assistant OS)

Zigbee2MQTT necesita un firmware Zigbee “NCP” en la radio del Yellow. Haga este paso mientras Home Assistant OS aún funcione: se basa en un complemento (add-on) que ya no existirá después del borrado.

  1. En Home Assistant, detenga todo lo que use la radio (ZHA, Zigbee2MQTT, módulo multiprotocolo), para liberar el puerto serie.
  2. Instale el módulo Silicon Labs Flasher desde la tienda de complementos.
  3. En su configuración, ajuste: dispositivo /dev/ttyAMA1, velocidad (baudrate) 115200, control de flujo de hardware activado. Elija el firmware Zigbee del Yellow (yellow_zigbee_ncp_7.4.4.0). Las etiquetas pueden variar según la versión del módulo.
  4. Inicie el módulo y lea sus registros. En nuestro caso, detectó la radio, luego el flash se completó con éxito.

El firmware se escribe una vez: permanece en su lugar después de borrar el SSD.

Paso 2: Recuperar el archivo de configuración de hardware del Yellow

Raspberry Pi OS no conoce la tarjeta Yellow: debe proporcionarle el archivo bcm2711-rpi-cm4-ha-yellow.dtb (device tree), que describe los puertos serie conectados a la radio. Se toma de la imagen oficial de Home Assistant OS para Yellow.

  1. Descargue la imagen haos_yellow-<version>.img.xz en la página de versiones de Home Assistant Operating System (usamos la 18.4), luego descomprímala.
  2. Monte la primera partición de la imagen (la partición de arranque, en formato FAT) y copie el archivo .dtb. Guarde también, para referencia, sus archivos config.txt y cmdline.txt.

En macOS:

xz -d haos_yellow-18.4.img.xz
hdiutil attach -nomount haos_yellow-18.4.img
diskutil list                      # identifica el disco de la imagen, por ejemplo 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

Copia el archivo antes de desmontar la imagen. Ajusta el número de disco (disk4) a tu máquina y verifica con ls /Volumes que el volumen correcto está montado: el comodín * puede referirse a varios.

En Linux: sudo losetup -fP --show haos_yellow-18.4.img, luego monta la partición p1 del dispositivo obtenido y copia los mismos archivos.

Paso 3: Escribir Raspberry Pi OS Lite en el SSD NVMe

Saca el SSD del Yellow y conéctalo a tu computadora con una carcasa o un adaptador USB para NVMe. Si tu Yellow ya arrancaba desde este SSD bajo Home Assistant OS, el orden de arranque del CM4 ya está configurado para el NVMe.

  1. Ejecuta Raspberry Pi Imager.
  2. Modelo de tarjeta: Raspberry Pi 4 (el CM4 es similar).
  3. Sistema: en Raspberry Pi OS (other), elige Raspberry Pi OS Lite (64-bit). No aparece en la lista principal.
  4. Almacenamiento: elige el SSD, asegurándote de que es el correcto y no otro disco, ya que será borrado.
  5. Personalización: nombre de host gladys, usuario pi con una contraseña que recuerdes, SSH activado, zona horaria y teclado a tu conveniencia. Desactiva Raspberry Pi Connect si el asistente lo sugiere.
  6. Escribe la imagen y espera a que finalice la verificación.

No vuelvas a colocar el SSD en el Yellow todavía: el siguiente paso modifica su partición de arranque.

Paso 4: Adaptar la partición de arranque al Yellow

Después de escribir, la partición bootfs del SSD (en formato FAT) es visible en tu computadora. Tres modificaciones son suficientes. Primero, haz una copia de los archivos originales.

cd /Volumes/bootfs                 # ajusta la ruta en Linux o 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: agrega estas líneas al final del archivo.

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

2. cmdline.txt: este archivo contiene una sola línea. Reemplaza la consola serie predeterminada (console=serial0,115200) por console=ttyAMA2,115200n8 y no toques nada más, especialmente root=PARTUUID=.... El archivo debe permanecer en una sola línea, sin saltos de línea en medio.

3. El archivo .dtb es el copiado anteriormente: debe estar en la raíz de bootfs, junto a config.txt.

Expulsa correctamente el SSD, colócalo de nuevo en el Yellow y conecta el cable Ethernet. Si el Yellow no arranca, los archivos .orig permiten volver al estado original para comparar.

Paso 5: Primer arranque, puertos serie y Docker

El primer arranque tarda uno o dos minutos. Conéctate luego por SSH, desde tu computadora:

ssh pi@gladys.local

Si el nombre gladys.local no se resuelve, usa la dirección IP del Yellow indicada por tu router.

Verificar que el archivo de configuración de hardware se está aplicando correctamente

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

Los puertos ttyAMA0, ttyAMA1 y ttyAMA2 deben aparecer. ttyAMA1 es el de la radio Zigbee. Si no aparecen, el .dtb no se está cargando: relee el paso 4.

Instalar Docker

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

Vuelve a conectarte por SSH para que la pertenencia al grupo docker se aplique, luego prueba:

docker run --rm hello-world
docker compose version

Paso 6: Instalar Gladys Assistant y Watchtower

Es la instalación habitual de Docker de Gladys, escrita en forma de archivo Docker Compose. Cree la carpeta y el archivo:

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

Contenido del archivo 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

Ajuste la zona horaria (TZ). Watchtower actualiza Gladys automáticamente; hemos utilizado la imagen nickfedor/watchtower, pero también puede usarse otra imagen de Watchtower.

Ejecute todo:

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

Luego, abra http://gladys.local en un navegador. Si comienza desde cero, cree su cuenta. Si está migrando una instancia existente (paso 9), no cree una cuenta aquí: la importación trae las cuentas de la antigua instancia.

Paso 7: Mosquitto y Zigbee2MQTT en la radio interna

El modo “Instalación desde Gladys” de la integración Zigbee2MQTT está previsto para un dongle USB, que Gladys busca en los puertos USB. La radio del Yellow es un puerto serie interno (/dev/ttyAMA1): por lo tanto, se ejecuta Mosquitto y Zigbee2MQTT por sí mismo, luego se conecta Gladys a esta instalación existente (paso 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/

Esta configuración acepta conexiones sin identificación: reservada para una red local de confianza.

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

Los puntos importantes: el adaptador es ember, la velocidad 115200 y el control de flujo de hardware (rtscts: true) debe estar activado, como en el flash del firmware. Los valores GENERATE hacen que Zigbee2MQTT cree un identificador y una clave de red aleatorios en el primer arranque.

Ejecute y verifique:

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

El mensaje RESET_WATCHDOG al inicio de la radio no es grave. La interfaz web de Zigbee2MQTT está luego en http://gladys.local:8080.

Clave de red: el archivo configuration.yaml contiene la clave de red Zigbee generada. Nunca la publiquen (foro, captura, copia del archivo): cualquiera que la conozca puede escuchar su red Zigbee. Si ha sido filtrada, regénérenla antes de asociar cualquier dispositivo.

Paso 8: conectar Gladys a Zigbee2MQTT y asociar dispositivos

Conexión

  1. En Gladys, abra Integraciones, luego Zigbee2MQTT, pestaña Configuración.
  2. Se ofrecen dos tarjetas. Haga clic en Elegir en la de la derecha, “Conexión a una instalación existente”. No elija “Instalación desde Gladys”: Gladys lanzaría sus propios contenedores, que competirían por la radio y el puerto 8080 con los suyos.
  3. Indique la dirección del broker MQTT: mqtt://localhost:1883 (Gladys está en red de host, localhost alcanza Mosquitto). De lo contrario, use mqtt://<dirección IP del Yellow>:1883. Deje el nombre de usuario y la contraseña vacíos con la configuración Mosquitto anterior.
  4. Si se solicita la URL de la interfaz Zigbee2MQTT: http://<dirección IP del Yellow>:8080.
  5. Guarde y verifique que la integración indique una conexión.

Asociar un dispositivo

  • Un dispositivo ya asociado a otro coordinador debe ser reiniciado (reinicio de fábrica) primero, de lo contrario no busca una nueva red. También retírelo de la antigua red si es posible.
  • Active la asociación: pestaña Descubrimiento Zigbee de Gladys, o botón Permitir unirse de la interfaz Zigbee2MQTT. La ventana dura aproximadamente cuatro minutos.
  • Ponga el dispositivo en modo asociación, a uno o dos metros del Yellow, un dispositivo a la vez.
  • Asocie primero los dispositivos alimentados por corriente (enchufes, bombillas), que refuerzan la red, luego los de batería.
  • Asigne a cada dispositivo un nombre claro. Gladys identifica un dispositivo Zigbee2MQTT por su nombre: al migrar, use los nombres antiguos para encontrar los dispositivos ya presentes.

Para mostrar la disponibilidad y la última recepción, en la interfaz Zigbee2MQTT: Configuración, pestaña Disponibilidad, active Habilitado; pestaña Avanzado, configure last_seen en ISO_8601.

Contador Linky (ZLinky_TIC), si es el caso: en los parámetros específicos del dispositivo, el modo del Linky debe corresponder al del contador (histórico o estándar, o auto). En nuestro caso, el contador está en modo histórico con un contrato Tempo, y linky_mode está configurado en histórico. La tarifa está configurada en “Histórico - BBR”. El modo histórico es compatible con Tempo.

Paso 9 (opcional): migrar una instancia Gladys existente con su historial

Este paso recupera los datos de un Gladys instalado en otro lugar (aquí en un NAS Synology). La carpeta de datos contiene la base de datos SQLite, la base de datos de historial DuckDB y los archivos de las integraciones.

Mantenga la antigua instancia detenida durante y después de la migración, para que dos Gladys no controlen los mismos dispositivos.

En el antiguo servidor

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

El primer comando indica la carpeta de datos del host (aquella montada en /var/lib/gladysassistant). Haga una copia de seguridad de esta carpeta, luego archívela:

tar czf /tmp/gladys-data.tgz -C <carpeta padre> gladysassistant

En un Synology, docker requiere sudo.

En el Yellow

Recupere el archivo (la opción -O de scp es necesaria si el SFTP está desactivado en el NAS):

scp -O <usuario>@<dirección del NAS>:/tmp/gladys-data.tgz /tmp/

Luego reemplace los datos vacíos de la nueva instalación:

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

Conéctese luego con la cuenta de la antigua instancia.

Qué queda por hacer después de la importación

  • Las extensiones (integraciones externas) se ejecutan en contenedores gladys-ext-* que no se recrean solos: en nuestro caso, fue necesario forzar la actualización de todas las extensiones instaladas, una por una: Integraciones, la extensión correspondiente, pestaña Supervisión, botón Forzar la actualización. Gladys recrea entonces su contenedor y vuelve a funcionar. Verifique con docker ps.
  • Los dispositivos Zigbee deben volver a asociarse con el nuevo coordinador (paso 8), con sus antiguos nombres. Gladys ha aplicado correctamente los renombrados a los dispositivos existentes; verifique en un dispositivo que su historial se conserva antes de volver a hacerlos todos.
  • La configuración de la integración Zigbee2MQTT importada apunta a la antigua instalación: vuelva a hacer el paso 8 después de la importación.
  • Detenga los contenedores de extensión del antiguo servidor y guarde su copia de seguridad durante varios días.

Límites conocidos, solución de problemas y copia de seguridad

Límites observados

  • Wi-Fi: no funciona en nuestro montaje, ya que el firmware del chip Wi-Fi no se proporciona para este device tree. Utilice Ethernet.
  • Otras funciones de la tarjeta (Bluetooth, reloj de tiempo real, LED, botón): no probadas.
  • Procedimiento probado una sola vez, en un CM4 Lite de 8 GB con SSD NVMe.

Solución de problemas

Síntoma Pista
El Yellow no responde después del arranque Verifique el cable Ethernet y la dirección IP en su box. Verifique el contenido de config.txt y cmdline.txt (una sola línea).
No hay ttyAMA1 El .dtb no se carga: bloque [cm4] de config.txt y presencia del archivo en la raíz de bootfs.
Zigbee2MQTT no arranca Lea docker logs zigbee2mqtt. Verifique adapter: ember, baudrate: 115200, rtscts: true y que el firmware NCP esté correctamente flashado.
Un dispositivo no se asocia Restablezcalo, mantenga “Permit join” activo, acérquelo al Yellow, siga docker logs -f zigbee2mqtt.
Una extensión Gladys no está conectada docker ps para ver si su contenedor se ejecuta, luego docker logs <nombre del contenedor>. Pruebe el acceso al dispositivo desde el contenedor (docker exec <contenedor> ping <dirección>).
Un dispositivo responde al ping pero no en la aplicación Reinícelo por completo (alimentación desconectada durante 30 segundos): es lo que restauró nuestro dispositivo AirSend.

Controles después de la instalación

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

Los cuatro contenedores deben mostrar always, y todos los contenedores deben estar “Up” después del reinicio (docker ps).

Copia de seguridad: copie regularmente /var/lib/gladysassistant y ~/zigbee/z2m-data a otro dispositivo. El segundo contiene la clave de red Zigbee y la lista de dispositivos: sin él, sería necesario volver a asociarlos todos.

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

Ejecuta este comando desde tu directorio personal y guarda el archivo en un lugar seguro, ya que contiene la clave de red.

¿Un Gladys OS para el Yellow? Fuentes

Este procedimiento demuestra que un Yellow puede ejecutar Gladys en Raspberry Pi OS, con Zigbee interno. Sería posible una imagen lista para flash integrando el archivo bcm2711-rpi-cm4-ha-yellow.dtb, las tres modificaciones de config.txt y cmdline.txt, Docker, Gladys, Mosquitto y Zigbee2MQTT. Queda por verificar, para una imagen limpia: el Wi-Fi, el Bluetooth, el reloj de tiempo real y la gestión del firmware de la radio. Los comentarios de otros usuarios de Yellow, con un CM4 en eMMC, por ejemplo, serían valiosos.

Fuentes :

2 Me gusta