WLED Home Assistant Solución de problemas Hogar inteligente

WLED y Home Assistant: problemas comunes y soluciones

Soluciones para la integración WLED de Home Assistant: no se detecta, 'Unknown error occurred', entidades no disponibles, cambio de IP, preajustes, segmentos y firmware.

Por

Home Assistant trae una integración WLED incluida, y casi siempre funciona sin problemas: encuentra la luz, crea una entidad de luz y un puñado de controles, y se mantiene sincronizada. Cuando no funciona, la causa suele ser una de unas pocas cosas, y varias se arreglaron en versiones recientes de Home Assistant. Por eso la primera pregunta siempre es: ¿qué versión de Home Assistant tienes? Esta página indica la versión que cambió cada comportamiento.

La configuración de la integración desde cero está bien explicada en la documentación oficial. Esta página trata de lo que sale mal.

Qué crea la integración

Saber qué esperar hace más fácil notar las entidades que “faltan”. Por cada luz WLED obtienes:

EntidadQué es
LightLa luz en sí, con color, brillo y una lista de efectos. Con más de un segmento, una luz por segmento
Main lightSolo con más de un segmento (o con Keep Main Light activado): encendido y brillo general de todo el dispositivo
Selects de preajuste y de lista de reproducciónCargan un preajuste o inician una lista de reproducción
Select de Color palettePor segmento, en configuración
Select de Live overrideOff, On o Until device restarts (lo mismo que el live data override de WLED)
Números de Speed e IntensityPor segmento, los controles del efecto
InterruptoresNightlight, Sync send, Sync receive y, por segmento, Reverse y Freeze
SensoresCorriente estimada, corriente máxima, número de LED, IP. Los de tiempo de actividad, memoria libre y Wi-Fi existen pero vienen desactivados
Botón de reinicio y actualización de firmwareEn configuración y diagnóstico

La integración necesita WLED 0.14.0 o más reciente. Con firmware más antiguo, la configuración falla. Desde Home Assistant 2025.12 lo dice claramente; antes mostraba un error genérico.

Home Assistant no detecta WLED

Home Assistant encuentra WLED con mDNS (zeroconf, el servicio _wled._tcp). No aparece nada en Discovered cuando:

  • La luz y Home Assistant están en VLAN o subredes distintas. mDNS no cruza subredes salvo que tu router o un reflector lo reenvíe. Es la razón más común en redes con una VLAN aparte para IoT.
  • El nombre mDNS de WLED está vacío. En Config›WiFi & Network (WiFi Setup antes de WLED 16), el campo mDNS address tiene que tener un nombre (el predeterminado se parece a wled-abcdef). Vacío significa que no hay mDNS en absoluto.
  • Tu punto de acceso aísla a los clientes Wi-Fi (se suele llamar aislamiento de clientes o de AP, y es común en redes de invitados).
  • La configuración de red de Home Assistant excluye la interfaz donde está la luz.

No necesitas la detección. Añade la integración a mano: Settings›Devices & services›Add integration›WLED y escribe la dirección IP de la luz. Las versiones recientes también aceptan una URL pegada y se quedan solo con el host.

Si no sabes la IP: la interfaz web de WLED la muestra en Info, tu router la tiene en su lista, y en WLED Max está en la sección Información del dispositivo de la configuración de una luz, como Dirección IP.

“Unknown error occurred” al añadir WLED

Hasta Home Assistant 2026.9, la configuración solo reconocía dos problemas: “no se puede conectar” y (desde 2025.12) “firmware demasiado antiguo”. Todo lo demás terminaba en Unknown error occurred (ocurrió un error desconocido). En la práctica, “todo lo demás” era:

  • Un archivo de preajustes dañado en la luz. La integración lee los preajustes de la luz durante la configuración, y un JSON inválido en presets.json la hacía fallar. Es la causa en la mayoría de los informes. Guarda una copia de lo que puedas y arregla los preajustes; consulta preajustes de WLED que no se guardan o error 12 y hacer copia de seguridad de WLED. Quienes hicieron un restablecimiento de fábrica lo arreglaron por la misma razón: el restablecimiento borra el archivo dañado.
  • Algo en esa dirección que no es WLED, o un WLED que responde con una página de error, por ejemplo mientras está ocupado reiniciándose.
  • Firmware anterior a 0.14 en versiones de Home Assistant anteriores a 2025.12.

Home Assistant 2026.10 reemplaza el mensaje vago por “The device didn’t respond like a WLED device” (el dispositivo no respondió como un dispositivo WLED), que te lleva a las mismas causas.

Prueba rápida

Abre http://<light-ip>/json y http://<light-ip>/presets.json en un navegador. Si alguno no carga o no parece un JSON limpio, Home Assistant también va a tener problemas.

Entidades de WLED no disponibles

“Unavailable” (no disponible) significa cosas distintas según la entidad:

  • Todo no disponible. Home Assistant no puede comunicarse con la luz. Revisa que esté en línea (abre su interfaz web) y que su IP no haya cambiado (siguiente sección).
  • Solo la Main light. Ahora la luz tiene un solo segmento. La Main light solo existe mientras hay dos o más segmentos, y se queda en la lista de entidades como no disponible cuando vuelves a uno. Activa Keep Main Light si añades y quitas segmentos a menudo (más abajo).
  • Luces de segmento, velocidad, paleta, reverse o freeze de un segmento. Ese segmento ya no existe. Home Assistant nunca borra por su cuenta las entidades de segmento; quita a mano las que sobren.
  • Select de preajuste o de lista de reproducción. La luz no tiene preajustes, o no tiene listas de reproducción. Guarda uno y aparece.

En luces ESP8266 con muchos efectos y paletas, todo el dispositivo pasaba a no disponible de vez en cuando porque la respuesta grande de /json de la luz llegaba cortada. Home Assistant 2026.10 lee los efectos y las paletas por separado y lo arregló, junto con “a broken presets file no longer makes the whole device unavailable” (un archivo de preajustes dañado ya no deja todo el dispositivo no disponible).

WLED cambió de dirección IP

DHCP puede darle a la luz una dirección nueva después de reiniciar el router o de un corte de luz largo. Lo que pasa después depende de tu versión:

  • Si la detección funciona, Home Assistant se da cuenta de la nueva dirección y la actualiza solo. Desde 2026.10 primero revisa que el dispositivo en la nueva dirección tenga la misma dirección MAC, y eso también acabó con un error por el que una dirección corregida a mano se revertía media hora después.
  • Si la detección no puede ver la luz (VLAN distinta), usa Reconfigure en la entrada de la integración WLED y escribe la nueva IP. Se niega si la MAC no coincide (“MAC address does not match”), y eso es una verificación de seguridad, no una falla.

La solución duradera es una reserva DHCP para cada luz WLED en tu router. Las IP estáticas en la configuración de Wi-Fi de WLED también funcionan, pero una reserva es más fácil de controlar.

Solo 2025.12

Home Assistant 2025.12.0 a 2025.12.4 podía reportar que la MAC no coincidía cuando era la misma pero escrita con mayúsculas o minúsculas distintas. 2025.12.5 lo arregló. Si te topas con ese error, actualiza primero.

Preajustes o listas de reproducción que no aparecen

  • Los preajustes nuevos no aparecen en el select. Antes de Home Assistant 2025.11 la lista de preajustes se leía una sola vez, así que los preajustes nuevos necesitaban recargar la integración. Las versiones más nuevas la actualizan cuando la luz avisa que sus preajustes cambiaron.
  • El select de listas de reproducción no está disponible. No hay listas de reproducción en la luz. Crea una en WLED (consulta listas de reproducción de WLED).
  • El select muestra “unknown” después de cambiar la luz. Eso es de WLED, no de Home Assistant. En cuanto cambias el color, el efecto o el brillo, la luz ya no está “en el preajuste 3”, así que WLED no informa ningún preajuste activo y Home Assistant muestra unknown. Es lo esperado.

Para usar un preajuste en una automatización, llama a select.select_option en el select de preajustes con el nombre del preajuste.

Segmentos como entidades

Cada segmento de WLED después del primero se vuelve una luz propia en Home Assistant, con el nombre “Segment 1”, “Segment 2” y así. La integración no usa los nombres de segmento que pusiste en WLED.

  • ¿Demasiadas entidades? Desactiva las luces de segmento que no uses.
  • Entidades conectadas al segmento equivocado después de borrar uno de en medio. Se arregló en Home Assistant 2026.10. En versiones anteriores, recarga la integración después de cambiar los segmentos.
  • Keep Main Light. En las opciones de la integración, “Add ‘Main’ control even with single LED segment” mantiene la Main light todo el tiempo. Con esto activado, las luces de segmento solo controlan su propio segmento, y el encendido y el brillo general quedan en la Main light. Actívalo si tus automatizaciones añaden y quitan segmentos.

Los segmentos de WLED explicados explica qué son los segmentos del lado de WLED.

Colores o blancos que se ven mal desde Home Assistant

La integración solo ajusta el color principal del segmento. Antes de 2026.10 no podía ajustar el color y la temperatura de color por separado en tiras con blanco cálido y frío (RGB más CCT). La propia documentación de WLED también advierte que Home Assistant no funciona con una configuración CCT ni con la corrección de balance de blancos, y sugiere activar Calculate CCT from RGB en la configuración de LED. Home Assistant 2026.10 arregló los saltos de la rueda de color y los modos de color equivocados en tiras RGB más CCT, así que actualiza antes de cambiar ajustes.

Actualizaciones de firmware desde Home Assistant

La entidad de actualización ofrece las versiones estables de WLED (y las beta si ya usas una beta), y busca versiones nuevas cada pocas horas. Lo que puede salir mal:

  • La actualización falla en WLED 16. WLED 16 tiene una opción de seguridad “Only allow update from same network/WiFi” (Config > Security & Updates). Si Home Assistant está en otra subred, la luz se niega. Desde 2026.10 Home Assistant muestra un error en lugar de fallar en silencio. Desactiva la opción o actualiza desde la misma red.
  • No hay entidad de actualización. Desde 2026.10, una luz cuyo origen de firmware Home Assistant no puede identificar (una compilación hecha por ti, por ejemplo) no recibe entidad de actualización, y solo se ofrece una actualización cuando la versión tiene un archivo para tu placa.
  • Se instaló el archivo equivocado (por ejemplo, una placa con Ethernet que pierde el Ethernet). Se arregló en 2026.5, que elige la compilación que corresponde a tu placa.

Para actualizar a mano, consulta actualizaciones OTA de WLED.

Home Assistant y otras apps al mismo tiempo

La integración mantiene abierta una conexión WebSocket con la luz y recibe los cambios al momento. Desde Home Assistant 2026.6 deja de consultar a la luz mientras esa conexión está activa; antes también consultaba cada 10 segundos, lo que podía hacer que los efectos se trabaran en placas pequeñas.

WLED limita los clientes WebSocket (la documentación de WLED para la versión 16 da 3 en ESP8266 y 8 en ESP32; cuando se conecta uno más, se desconecta el más antiguo). Home Assistant, cada pestaña abierta de la interfaz web y algunas apps de móvil ocupan uno cada uno. Si las actualizaciones en directo se detienen en uno de ellos, cierra las pestañas de la interfaz web que no necesites. Un ESP32 tiene más espacio.

Si usas Home Assistant para transmitir efectos a WLED (LedFx o apps parecidas), la luz entra en modo en tiempo real e ignora todo lo demás. Consulta WLED atascado en modo en tiempo real.

¿Y MQTT?

WLED también habla MQTT, pero la documentación de WLED recomienda la integración nativa, y la detección automática por MQTT para Home Assistant no es compatible (WLED la quitó hace años). Usa MQTT solo si tienes una razón, y en ese caso configura la luz a mano en YAML.

Preguntas frecuentes

¿Por qué Home Assistant dice “Unknown error occurred” con WLED? Casi siempre es un archivo de preajustes dañado en la luz, a veces firmware anterior a 0.14 o un dispositivo que no responde como WLED. Home Assistant 2026.10 muestra un mensaje más claro.

¿Cómo cambio la dirección IP de WLED en Home Assistant? Abre la entrada de la integración WLED, elige Reconfigure y escribe la nueva dirección. Después configura una reserva DHCP para que no vuelva a pasar.

¿Por qué mi main light de WLED no está disponible? La luz tiene un solo segmento. Activa Keep Main Light en las opciones de la integración si la quieres siempre.

¿Home Assistant puede mostrar los nombres de los segmentos de WLED? No, los segmentos aparecen como Segment 1, Segment 2 y así. Cambia el nombre de las entidades en Home Assistant.

¿Funciona con WLED 16? Sí. Home Assistant 2026.10 arregló los problemas con WLED 16 reportados hasta ahora, como las actualizaciones que fallaban en silencio por el bloqueo de misma red. También arregló que las entidades de segmento se mezclaran después de borrar un segmento de en medio.

Quién escribió esto

Jamie Conde, que desarrolla la app WLED Max en MeowScript. WLED es un proyecto independiente de código abierto y no formamos parte de él. WLED Max, nuestra app de WLED para iOS y Android, es gratis para una luz, sin limitaciones. Un pago único cubre más luces.