WLED Home Assistant Solução de problemas Casa inteligente

WLED e Home Assistant: problemas comuns e soluções

Soluções para a integração do WLED no Home Assistant: não encontrado, 'Unknown error occurred', entidades indisponíveis, IP que mudou, predefinições e sequências que não aparecem, segmentos como entidades e atualizações de firmware.

Por

O Home Assistant tem uma integração do WLED embutida e, na maioria das vezes, ela funciona sem drama: encontra a luz, cria uma entidade de luz e alguns controles, e fica sincronizada. Quando não funciona, a causa costuma ser uma entre poucas, e várias delas foram corrigidas em versões recentes do Home Assistant. Então a primeira pergunta é sempre: qual versão do Home Assistant você está usando? Esta página indica a versão que mudou cada comportamento.

A configuração da integração do zero está bem explicada na documentação oficial. Esta página é sobre o que dá errado.

O que a integração cria

Saber o que esperar facilita perceber entidades “faltando”. Para cada luz WLED você ganha:

EntidadeO que é
LightA própria luz, com cor, brilho e uma lista de efeitos. Com mais de um segmento, uma luz por segmento
Main lightSó com mais de um segmento (ou com Keep Main Light ativado): energia e brilho geral do dispositivo inteiro
Seletores Preset e Playlist (nomes da integração)Carregam uma predefinição ou iniciam uma sequência
Seletor Color palettePor segmento, em configuração
Seletor Live overrideOff, On ou Until device restarts (o mesmo que o live data override do WLED)
Números de Speed e IntensityPor segmento, os controles do efeito
SwitchesNightlight, Sync send, Sync receive e, por segmento, Reverse e Freeze
SensoresEstimated current, Max current, LED count, IP. Uptime, memória livre e os sensores de Wi-Fi existem, mas vêm desativados por padrão
Botão de reinício e atualização de firmwareEm configuração e diagnóstico

A integração precisa do WLED 0.14.0 ou mais recente. Com firmware mais antigo, a configuração falha. Desde o Home Assistant 2025.12 ele diz isso com todas as letras; antes mostrava um erro genérico.

O Home Assistant não encontra o WLED

O Home Assistant encontra o WLED por mDNS (zeroconf, o serviço _wled._tcp). Nada aparece em Discovered quando:

  • A luz e o Home Assistant estão em VLANs ou sub-redes diferentes. O mDNS não atravessa sub-redes, a não ser que o roteador ou um refletor repasse. É o motivo mais comum em redes com uma VLAN separada para IoT.
  • O nome mDNS do WLED está vazio. Em Config›WiFi & Network (WiFi Setup antes do WLED 16), o campo mDNS address precisa ter um nome (o padrão é algo como wled-abcdef). Vazio quer dizer nenhum mDNS.
  • O seu ponto de acesso isola os clientes Wi-Fi (muitas vezes chamado de isolamento de clientes ou de AP, comum em redes de convidados).
  • As próprias configurações de rede do Home Assistant excluem a interface em que a luz está.

Você não precisa da busca automática. Adicione a integração à mão: Settings›Devices & services›Add integration›WLED e digite o endereço IP da luz. As versões recentes também aceitam uma URL colada e ficam só com o host.

Se você não sabe o IP: a interface web do WLED mostra em Info, o seu roteador lista, e no WLED Max ele fica na seção Informações do dispositivo das configurações da luz, como Endereço IP.

“Unknown error occurred” ao adicionar o WLED

Até o Home Assistant 2026.9, a configuração só reconhecia dois problemas: “can’t connect” e (a partir do 2025.12) “firmware too old”. Todo o resto terminava em Unknown error occurred. Na prática, “todo o resto” era:

  • Um arquivo de predefinições danificado na luz. A integração lê as predefinições da luz durante a configuração, e JSON inválido no presets.json fazia a configuração falhar. É a causa na maioria dos relatos. Faça backup do que der e conserte as predefinições; veja predefinições do WLED que não salvam ou erro 12 e backup do WLED. Quem fez um reset de fábrica resolveu pelo mesmo motivo: o reset apaga o arquivo ruim.
  • Algo nesse endereço que não é WLED, ou um WLED que responde com uma página de erro, por exemplo enquanto está reiniciando.
  • Firmware anterior ao 0.14 em versões do Home Assistant anteriores ao 2025.12.

O Home Assistant 2026.10 troca a mensagem vaga por “The device didn’t respond like a WLED device”, que aponta para as mesmas causas.

Teste rápido

Abra http://<light-ip>/json e http://<light-ip>/presets.json no navegador. Se algum dos dois não carregar ou não parecer um JSON limpo, o Home Assistant também vai ter dificuldade.

Entidades do WLED indisponíveis

“Unavailable” quer dizer coisas diferentes dependendo da entidade:

  • Tudo indisponível. O Home Assistant não consegue alcançar a luz. Confira se ela está conectada (abra a interface web dela) e se o IP não mudou (próxima seção).
  • Só a Main light. A luz agora tem um único segmento. A Main light só existe enquanto houver dois ou mais segmentos, e ela fica na lista de entidades como indisponível quando você volta para um. Ative Keep Main Light se você adiciona e remove segmentos com frequência (veja abaixo).
  • Luzes de segmento, speed, paleta, reverse ou freeze de segmento. Aquele segmento não existe mais. O Home Assistant nunca apaga entidades de segmento sozinho; remova as que sobraram à mão.
  • Seletor Preset ou Playlist. A luz não tem predefinições, ou não tem sequências. Salve uma e ele aparece.

Em luzes ESP8266 com muitos efeitos e paletas, o dispositivo inteiro ficava indisponível de vez em quando porque a resposta grande do /json da luz era cortada. O Home Assistant 2026.10 lê efeitos e paletas separadamente e corrigiu isso, junto com o caso em que um arquivo de predefinições danificado deixava o dispositivo inteiro indisponível.

O WLED mudou de endereço IP

O DHCP pode dar um endereço novo para a luz depois de reiniciar o roteador ou de uma queda de energia longa. O que acontece depois depende da sua versão:

  • Se a busca automática funciona, o Home Assistant percebe o endereço novo e atualiza sozinho. Desde o 2026.10 ele confere primeiro se o dispositivo no endereço novo tem o mesmo endereço MAC, o que também acabou com um bug em que um endereço corrigido à mão era revertido meia hora depois.
  • Se a busca automática não enxerga a luz (VLAN diferente), use Reconfigure na entrada da integração WLED e digite o IP novo. Ele recusa se o MAC não bater (“MAC address does not match”), o que é uma verificação de segurança, não um defeito.

A solução definitiva é uma reserva de DHCP no roteador para cada luz WLED. IPs fixos nas configurações de WiFi do WLED também funcionam, mas uma reserva é mais fácil de acompanhar.

Só no 2025.12

Do Home Assistant 2025.12.0 ao 2025.12.4, ele podia acusar um MAC diferente quando o MAC era o mesmo, só escrito com maiúsculas e minúsculas diferentes. O 2025.12.5 corrigiu isso. Se você está preso nesse erro, atualize primeiro.

Predefinições ou sequências que não aparecem

  • Predefinições novas não aparecem no seletor. Antes do Home Assistant 2025.11, a lista de predefinições era lida uma vez só, então era preciso recarregar a integração para ver predefinições novas. As versões mais novas atualizam quando a luz informa que as predefinições mudaram.
  • O seletor Playlist está indisponível. Não há sequências na luz. Crie uma no WLED (veja sequências do WLED).
  • O seletor mostra “unknown” depois que você muda a luz. Isso é do WLED, não do Home Assistant. Assim que você muda a cor, o efeito ou o brilho, a luz não está mais “na predefinição 3”, então o WLED informa que nenhuma predefinição está ativa e o Home Assistant mostra unknown. É o esperado.

Para usar uma predefinição numa automação, chame select.select_option no seletor Preset com o nome da predefinição.

Segmentos como entidades

Cada segmento do WLED além do primeiro vira uma luz própria no Home Assistant, com os nomes “Segment 1”, “Segment 2” e assim por diante. A integração não usa os nomes de segmento que você deu no WLED.

  • Entidades demais? Desative as luzes de segmento que você não usa.
  • Entidades ligadas ao segmento errado depois de apagar um do meio. Corrigido no Home Assistant 2026.10. Nas versões mais antigas, recarregue a integração depois de mudar os segmentos.
  • Keep Main Light. Nas opções da integração, “Add ‘Main’ control even with single LED segment” mantém a Main light o tempo todo. Com isso ativado, as luzes de segmento controlam só o próprio segmento, e a energia e o brilho geral ficam na Main light. Ative se as suas automações adicionam e removem segmentos.

Segmentos do WLED explicados mostra o que são os segmentos do lado do WLED.

Cores ou branco errados pelo Home Assistant

A integração define só a cor principal do segmento. Antes do 2026.10 ela não conseguia definir cor e temperatura de cor de forma independente em fitas com branco quente e branco frio (RGB mais CCT). A própria documentação do WLED também avisa que o Home Assistant não funciona com uma configuração de CCT ou com correção de balanço de branco, e sugere ativar Calculate CCT from RGB nas configurações de LED. O Home Assistant 2026.10 corrigiu os pulos da roda de cores e os modos de cor errados em fitas RGB mais CCT, então atualize antes de mudar configurações.

Atualizações de firmware pelo Home Assistant

A entidade de atualização oferece as versões estáveis do WLED (e betas se você já usa um beta) e procura novas a cada poucas horas. O que pode dar errado:

  • A atualização falha no WLED 16. O WLED 16 tem uma opção de segurança “Only allow update from same network/WiFi” (Config > Security & Updates). Se o Home Assistant estiver em outra sub-rede, a luz recusa. Desde o 2026.10 o Home Assistant mostra um erro em vez de falhar em silêncio. Desligue a opção ou atualize a partir da mesma rede.
  • Nenhuma entidade de atualização. Desde o 2026.10, uma luz cuja origem do firmware o Home Assistant não consegue identificar (uma compilação feita por você, por exemplo) não ganha entidade de atualização, e uma atualização só é oferecida quando a versão tem um arquivo para a sua placa.
  • O arquivo errado foi instalado (por exemplo uma placa com Ethernet que perde a conexão Ethernet). Corrigido no 2026.5, que escolhe a compilação que corresponde à sua placa.

Para atualizar à mão, veja atualizações OTA do WLED.

Home Assistant e outros apps ao mesmo tempo

A integração mantém uma conexão WebSocket aberta com a luz e recebe as mudanças por ela. Desde o Home Assistant 2026.6 ela para de consultar a luz periodicamente enquanto essa conexão está ativa; antes disso ela também consultava a cada 10 segundos, o que podia fazer os efeitos engasgarem em placas pequenas.

O WLED limita os clientes WebSocket (a documentação do WLED para a versão 16 fala em 3 no ESP8266 e 8 no ESP32; quando mais um conecta, o mais antigo cai). O Home Assistant, cada aba aberta da interface web e alguns apps de celular ocupam um cada. Se as atualizações ao vivo pararem em algum deles, feche as abas da interface web de que você não precisa. Um ESP32 tem mais espaço.

Se você usa o Home Assistant para transmitir efeitos para o WLED (LedFx ou apps parecidos), a luz entra no modo em tempo real e ignora todo o resto. Veja WLED preso no modo em tempo real.

E o MQTT?

O WLED também fala MQTT, mas a documentação do WLED recomenda a integração nativa, e a descoberta automática por MQTT para o Home Assistant não é suportada (o WLED removeu isso há anos). Use MQTT só se tiver um motivo, e aí configure a luz à mão em YAML.

Perguntas frequentes

Por que o Home Assistant diz “Unknown error occurred” para o WLED? Na maioria das vezes é um arquivo de predefinições danificado na luz, às vezes um firmware anterior ao 0.14 ou um dispositivo que não responde como WLED. O Home Assistant 2026.10 mostra uma mensagem mais clara.

Como mudo o endereço IP do WLED no Home Assistant? Abra a entrada da integração WLED, escolha Reconfigure e digite o endereço novo. Depois crie uma reserva de DHCP para isso não acontecer de novo.

Por que a main light do meu WLED está indisponível? A luz tem só um segmento. Ative Keep Main Light nas opções da integração se quiser que ela fique sempre lá.

O Home Assistant mostra os nomes dos segmentos do WLED? Não, os segmentos aparecem como Segment 1, Segment 2 e assim por diante. Renomeie as entidades no Home Assistant.

Funciona com o WLED 16? Funciona. O Home Assistant 2026.10 corrigiu os problemas com o WLED 16 relatados até agora, como as falhas silenciosas de atualização com a trava de mesma rede. Ele também corrigiu as entidades de segmento que se misturavam depois de apagar um segmento do meio.

Quem escreveu

Jamie Conde, que desenvolve o app WLED Max na MeowScript. O WLED é um projeto independente de código aberto, e nós não fazemos parte dele. WLED Max, nosso app de WLED para iOS e Android, é grátis para uma luz, sem nada bloqueado. Uma compra única libera mais luzes.