DocumentaciónInstalar Home Assistant en un controlador Wiren Board
Descripción
Home Assistant es una plataforma de automatización de código abierto desarrollada y mantenida por la comunidad home-assistant.io . Su aplicación móvil permite controlar el sistema a través de la red local o del servicio en la nube de la plataforma.
Puede instalarla en un controlador Wiren Board para controlar los dispositivos conectados en lugar de utilizar la interfaz web estándar.
Compatibilidad
Se recomiendan los controladores Wiren Board 8/8M y posteriores. El soporte de Home Assistant para Wiren Board 6 y 7 (armhf) terminó a finales de 2025; estos modelos ya no reciben actualizaciones. Consulte el anuncio de los desarrolladores.
Instalación
La memoria flash del controlador está dividida en particiones. Una partición de usuario independiente se monta en /mnt/data. Si se ha ampliado la partición raíz hasta ocupar casi toda la eMMC, /mnt/data es un directorio normal de esa partición. Téngalo en cuenta al instalar software o actualizar el firmware.
Copie los comandos en la consola del controlador con Shift+Insert y ejecútelos con Enter. Antes de ejecutar un comando, asegúrese de comprender su finalidad y los cambios que realizará. Lea atentamente los mensajes de error para obtener instrucciones y sugerencias.
Utilice nano para editar los archivos de configuración. Si el software de terceros necesita más espacio, puede ampliar la partición raíz hasta ocupar casi toda la capacidad de la eMMC.
Esta guía utiliza el método Home Assistant Container recomendado por los desarrolladores. No incluye Supervisor, por lo que no se pueden instalar complementos desde la interfaz web de Home Assistant. Los complementos suelen contener software de terceros, como zigbee2mqtt, ESPHome o Node-RED, que puede instalar por separado en contenedores.
- Instale Docker siguiendo la guía de instalación de Docker.
- Cree el directorio de instalación y acceda a él:
mkdir -p /mnt/data/.docker-compose/home-assistant cd /mnt/data/.docker-compose/home-assistant
- Cree los directorios de configuración y archivos multimedia:
mkdir -p config/home-assistant mkdir -p store/media
- Abra docker-compose.yaml en el editor:
nano docker-compose.yaml
- Pegue la siguiente configuración para Wiren Board 8:
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"Para Wiren Board 6 y 7, utilice esta configuración:
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" - Guarde con Ctrl+S y cierre con Ctrl+X.
- Configure su zona horaria en el archivo .env. Elija uno de los ejemplos siguientes u otra zona horaria válida de Linux:
UTC (tiempo universal coordinado):
echo "MYTZ=UTC" >> .env
Europa central (CEST/CET):
echo "MYTZ=Europe/Berlin" >> .env
Moscú (MSK):
echo "MYTZ=Europe/Moscow" >> .env
Muestre todas las zonas horarias disponibles en Linux:
timedatectl list-timezones
- Inicie el contenedor en segundo plano:
docker compose up -d
Cuando se inicie el contenedor, abra la dirección IP del controlador con el puerto 8123 en un navegador, por ejemplo http://192.168.42.1:8123. Ya puede cerrar la consola.
Actualización
Conecte el controlador a Internet, descargue la imagen actualizada y vuelva a crear el contenedor:
cd /mnt/data/.docker-compose/home-assistant docker compose pull homeassistant # Update the image docker compose up -d homeassistant # Recreate the container
Todos los ajustes se conservan al volver a crear el contenedor, ya que la configuración se almacena en el directorio config.
Trabajar con dispositivos Wiren Board
Instalar la integración Wiren Board
La integración personalizada Wiren Board crea automáticamente entidades de Home Assistant a partir de los temas MQTT de los dispositivos. La integración actual requiere Home Assistant 2025.6 o posterior.
- Copie la carpeta wirenboard del repositorio en
/mnt/data/.docker-compose/home-assistant/config/home-assistant/custom_components/. - Abra la interfaz web de Home Assistant.
- Reinicie Home Assistant mediante Developer Tools → Restart.
- Abra Settings → Devices & Services → Add Integration y seleccione wirenboard.
- Los campos Host y Port contienen los ajustes predeterminados de conexión al controlador. Cámbielos solo si es necesario.
Instalar la integración MQTT
Home Assistant puede controlar dispositivos Modbus mediante MQTT. Instale la integración MQTT y configure la recepción y el envío de datos. Los pasos y capturas siguientes utilizan el antiguo menú Configuration; las versiones más recientes utilizan Settings.
- Abra la interfaz web de Home Assistant.
- Seleccione Configuration en la barra lateral izquierda y abra Devices & Services.
- Haga clic en Add Integration en la parte inferior, busque MQTT y seleccione la integración.
- Espere al cuadro de configuración. Introduzca localhost en Broker y 1883 en Port. Deje vacíos el nombre de usuario y la contraseña si el controlador utiliza la configuración estándar. Haga clic en Submit.
Configurar los dispositivos manualmente
Después de configurar la integración, describa cada dispositivo en configuration.yaml. Abra el archivo en el editor:
nano /mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml
El directorio de configuración es /mnt/data/.docker-compose/home-assistant/config/home-assistant/. Añada secciones con los parámetros de cada dispositivo; por ejemplo, describa los relés en la sección switch.
Guarde el archivo y reinicie Home Assistant. En la interfaz antigua, abra Configuration → Settings y haga clic en Restart. La configuración se comprueba antes del reinicio y los errores se muestran con detalles. Una causa frecuente es una sangría incorrecta, ya que la sangría es significativa en YAML.
El almacenamiento del controlador es limitado. Añada el siguiente ajuste recorder para conservar 14 días de historial. Supervise el espacio libre en disco; este período de retención no establece un límite fijo para el tamaño de la base de datos.
recorder: purge_keep_days: 14
- Consulte MQTT Discovery para conocer la sintaxis completa y los tipos de dispositivos compatibles.
- Las direcciones de los temas MQTT se encuentran en la interfaz web estándar del controlador, en Settings → MQTT Channels.
- Configure state_topic con la dirección del tema MQTT. Para command_topic, utilice la misma dirección añadiendo /on.
- Defina los sensores bajo mqtt:, como en el ejemplo de temperatura siguiente. Consulte la documentación de sensores MQTT de Home Assistant para conocer el formato. Coloque switch y light bajo la misma clave mqtt:; no duplique la clave mqtt: de nivel superior.
Muestre la lectura del sensor de temperatura de la CPU:
mqtt:
sensor:
- unique_id: wb_cpu_temperature
name: "CPU Temperature"
state_topic: "/devices/hwmon/controls/CPU Temperature"
unit_of_measurement: "°C"
Controle las salidas A1 y A2. Este ejemplo también puede utilizarse para controlar módulos de relés:
#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
Controle el zumbador del controlador. Este ejemplo puede adaptarse a un regulador de lámparas LED:
#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
Acceso mediante la nube
Para acceder desde fuera de la red local, añada Home Assistant como servicio en Wiren Board Cloud. En la página del controlador, haga clic en Services y seleccione Home Assistant en el catálogo. El puerto 8123 se completa automáticamente.
Al principio, Home Assistant devuelve 400: Bad Request porque no confía en las solicitudes que llegan a través del proxy de la nube. Abra Home Assistant en la red local con la dirección del controlador y el puerto 8123, y vaya a Settings → System → Network. Los pasos siguientes dependen de su versión de Home Assistant.
Si la página Network contiene una sección HTTP server, está utilizando Home Assistant 2026.8 o posterior. En estas versiones, configure los ajustes HTTP en la interfaz web:
- En HTTP server, despliegue Reverse proxy.
- Active Trust X-Forwarded-For.
- Añada por separado 127.0.0.1, ::1 y 172.16.0.0/12 en Trusted proxies.
- Haga clic en Save y después en Save and restart.
- Después del reinicio, haga clic en Confirm en el cuadro que solicita confirmar la nueva configuración del servidor HTTP. Debe confirmar en un plazo de 5 minutos; de lo contrario, Home Assistant restablece los ajustes anteriores.
Si no aparece la sección HTTP server, utiliza una versión anterior a 2026.8. Esto también se aplica a Wiren Board 6 y 7, que ya no reciben versiones nuevas:
- Añada lo siguiente a
/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 - Reinicie el contenedor:
docker restart home-assistant
Al actualizar posteriormente a Home Assistant 2026.8 o una versión más reciente, los ajustes HTTP se migran a la sección HTTP server durante el primer inicio. Si se solicita, haga clic en Confirm en un plazo de 5 minutos; de lo contrario, los ajustes se revierten y deberá introducirlos de nuevo siguiendo los pasos anteriores. Compruebe las direcciones de Trusted proxies y elimine el bloque http: de configuration.yaml.