Tutorial: Integra Node-RED con Home Assistant para automatizaciones avanzadas

Introducción

Home Assistant es potente por sí solo, pero cuando las necesidades de automatización superan la capacidad de los YAML simples o las automatizaciones gráficas estándar, Node-RED se convierte en la herramienta indispensable para cualquier entusiasta del hogar inteligente. Al integrar este editor de flujos basado en nodos con nuestra plataforma central, ganamos una flexibilidad lógica superior, manejo avanzado de datos y visualización en tiempo real que complementa perfectamente la infraestructura base que hemos construido. En este tutorial, guiaremos paso a paso la instalación y configuración inicial para asegurar una comunicación fluida entre ambos sistemas.

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente preparado para evitar interrupciones durante el proceso:

• Home Assistant instalado y funcionando en tu Raspberry Pi o Mini PC (versión 2023.x o superior recomendada).
• Acceso al panel de control web de Home Assistant.
• Conocimientos básicos sobre la estructura de carpetas si decides una instalación avanzada (opcional).
• Navegador actualizado para el editor de flujos.

Paso 1: Instalación del Add-on en Home Assistant

La forma más segura y compatible de ejecutar Node-RED es utilizando el add-on oficial mantenido por la comunidad, ya que integra automáticamente las dependencias necesarias y gestiona los permisos del sistema operativo host.

1. Accede al panel lateral izquierdo de Home Assistant y selecciona Supervisor > Add-on Store.
2. En la esquina superior derecha, haz clic en el icono de configuración (engranaje) y activa el modo experto si no lo tienes ya activo (esto permite ver opciones avanzadas, aunque para este tutorial no es estrictamente necesario).
3. Busca “Node-RED” en la barra de búsqueda. Selecciona Node-RED.
4. Haz clic en Instalar y espera a que el sistema descargue las imágenes Docker necesarias. Este proceso puede tardar unos minutos dependiendo de tu conexión.

Paso 2: Configuración Inicial del Add-on

Una vez instalado, es crucial ajustar la configuración para permitir la comunicación bidireccional con Home Assistant. Aunque la integración automática hace mucho trabajo por nosotros, debemos habilitar explícitamente el acceso.

1. En la lista de add-ons, haz clic en Node-RED y luego en la pestaña Configuración.
2. Asegúrate de que la opción HTTP API esté marcada como True. Esto permite que Home Assistant envíe estados a Node-RED sin intervención manual constante.
3. En la sección de MQTT, si tienes un broker MQTT externo (como Mosquitto), asegúrate de que las credenciales coincidan exactamente con las de tu configuración principal de Home Assistant para evitar errores de autenticación en los nodos de suscripción.

Paso 3: Instalación de Integraciones Nativas

Node-RED viene con soporte básico, pero necesita la integración oficial de Home Assistant para interactuar nativamente con tu ecosistema. Sin esto, solo podrías enviar comandos MQTT genéricos sin entender el contexto de los dispositivos HA.

1. Haz clic en la pestaña Información del add-on Node-RED y asegúrate de que esté iniciado. Si no lo está, pulsa Iniciar.
2. Abre una nueva ventana del navegador y ve a http://<TU_IP>:1880. Deberías ver el editor de flujos de Node-RED.
3. En la esquina superior derecha del editor, haz clic en los tres puntos verticales y selecciona Manage palette.
4. Ve a la pestaña Install, busca home-assistant e instala el paquete node-red-contrib-home-assistant-websocket. Este paquete es el que nos permite usar nodos como ha-state, ha-call-service y otros nativos de HA.

Paso 4: Configuración del Nodo Home Assistant

Ahora que tenemos las herramientas instaladas, debemos configurar la conexión para que Node-RED hable fluentemente con tu instancia principal.

1. Ve a la pestaña Palettes > Nodes y busca el nodo llamado Home Assistant. Arrástralo al canvas de flujo.
2. Haz doble clic en el nodo configurado. En el menú desplegable del host, selecciona New Home Assistant Connection.
3. El sistema te pedirá permisos. Deberás autorizar la conexión desde la interfaz web de Home Assistant siguiendo las instrucciones que aparecen (se generará un token de larga duración).
4. Una vez autorizado, vuelve a Node-RED y refina la configuración del nodo:
   • Name: Dile algo descriptivo como “Mi Casa HA”.
   • Context Storage: Selecciona db si necesitas guardar variables entre mensajes (útil para contadores o estados temporales).
   • Verifica que el estado inicial se cargue correctamente. El nodo debería cambiar a un indicador verde si la conexión es exitosa.

Paso 5: Creando tu Primera Automatización

Para probar que todo funciona, crearemos un flujo simple: cuando cambie el estado de una luz o sensor en Home Assistant, envíe una notificación o registre el evento.

1. Busca en la paleta izquierda el nodo ha-state. Este nodo escucha cambios en las entidades de Home Assistant.
2. Configúralo para que escuche a light.salon (o cualquier entidad disponible).
3. Conecta este nodo a un nodo debug ubicado en la parte inferior derecha del panel izquierdo. Arrastra el nodo debug al canvas y conecta los puntos de salida e entrada.
4. Haz clic en Deploy (esquina superior derecha) para guardar los cambios.
5. Ve a la pestaña Debug (icono de terminal o lista junto a Deploy). Pulsa una tecla en tu interruptor real o virtual del salon.
6. Deberías ver en el panel de depuración un mensaje JSON detallado con el payload completo, incluyendo old_state y new_state.

Paso 6: Automatización Avanzada con Condicionales

A diferencia de las automatizaciones básicas de HA, aquí podemos usar lógica compleja de JavaScript dentro del flujo. Por ejemplo, activar una alarma solo si la temperatura es superior a 25°C y la ventana está cerrada.

1. Añade un nodo switch después del nodo de estado de la ventana.
2. Configura el switch para verificar la propiedad state del mensaje JSON (ej. msg.payload.state === "off").
3. Conecta la salida verdadera a un nodo template o directamente a un nodo ha-call-service.
4. En el nodo de servicio, selecciona media_player.play_media y configura los datos del payload para enviar una alerta por la aplicación móvil de Home Assistant.

Problemas comunes

Al integrar estos sistemas, es normal encontrar algunos obstáculos iniciales:

• Token expirado o no válido: Si la conexión se pierde, verifica que tu token de larga duración en la configuración de Node-RED coincida con el generado en tu perfil de usuario de Home Assistant. Renueva el token si ha pasado mucho tiempo.
• Errores de MQTT: Asegúrate de que el broker MQTT esté corriendo y que las reglas de firewall no bloqueen el puerto 1883 o 8884 entre el contenedor de Node-RED y el servicio MQTT.
• Flujos que no se ejecutan: Revisa la pestaña “Debug” en Node-RED. Si no hay salida, el mensaje puede estar siendo filtrado por un nodo anterior o el estado de la entidad no ha cambiado realmente (HA es estricto con los cambios de estado, no envía eventos si el valor es idéntico al previo).

Conclusión

Integrar Node-RED con Home Assistant desbloquea un nivel de personalización que va más allá de lo ofrecido por las interfaces gráficas estándar. Aunque la curva de aprendizaje inicial puede parecer pronunciada debido a la lógica de flujos y el manejo de objetos JSON, una vez dominada, te permite crear automatizaciones resilientes, complejas y altamente visuales que adaptan tu hogar inteligente a tus necesidades específicas sin depender exclusivamente del YAML manual. Con la conexión MQTT establecida y los nodos de HA instalados, tienes la base técnica sólida para expandir tu domótica hacia niveles avanzados de eficiencia y control.