WLED Firmware OTA ESP8266 ESP32 WLED Max Passo a passo

Atualização OTA do WLED no ESP8266 e ESP02: de qual .bin você precisa e por que ela falha

Escolha o .bin certo do WLED para ESP8266, ESP02 ou ESP01, entenda por que placas de 2 MB ficam sem espaço e use a atualização em duas etapas quando um OTA falha.

Por Publicado em Atualizado em

Resposta rápida: use o arquivo da versão cujo nome bate com a compilação que a sua luz informa (o campo “release” na página Info do WLED, como ESP8266, ESP02 ou ESP32). No ESP8266 a nova imagem precisa caber entre o firmware em execução e o sistema de arquivos, então placas de 2 MB (compilações ESP02) muitas vezes falham com “not enough space”. Use o .bin.gz compactado, ou atualize em duas etapas: primeiro a compilação pequena _min, depois a completa. Placas de 1 MB (compilações ESP01) não têm atualização sem fio nenhuma. Essas precisam de um cabo USB e do install.wled.me.

Qual compilação a sua luz está rodando?

Abra a luz no navegador e toque em Info (o botão “i”). A versão e o nome da compilação estão ali. Ou abra http://<light-ip>/json/info e procure "release", por exemplo "release":"ESP02" ou "release":"ESP32".

/json/info (uma parte)
"ver""0.15.1"
"release""ESP02"
"arch""esp8266"

O campo release é o nome da compilação que deve bater na hora de baixar.

Os arquivos das versões no GitHub (github.com/wled/WLED/releases) usam os mesmos nomes:

Nome da compilaçãoHardware típicoFlashAtualização sem fio
ESP8266D1 mini, NodeMCU4 MBsim, com bastante espaço
ESP02placas com flash de 2 MB, muitos controladores baratos2 MBsim, mas apertado
ESP01ESP-01, ESP-01S1 MBnão, compilado sem OTA
ESP32placas de desenvolvimento ESP32, QuinLED, a maioria dos controladores4 MBsim
ESP32-S2, S3, C3chips ESP32 mais novosvariasim

Fique no nome de compilação que você tem agora. Trocar de compilação via OTA pode deixar você com pinos padrão errados, ou com uma luz que não inicia.

Atualizando pela interface web

O WLED 16 faz quase todo o trabalho por você. Vá em Config›Security & Updates e toque em Update WLED (ou abra http://<light-ip>/update). A página mostra a versão instalada, o nome da sua compilação e a versão mais recente. O Auto update baixa o arquivo certo do GitHub e envia. Em ESP32 e em placas ESP8266 de 4 MB, é só isso. Em placas de 2 MB, leia a próxima seção antes, porque o Auto update escolhe o .bin comum.

Interface web do WLED
Seção Software Update de Security and Updates no WLED: botão Update WLED e a opção marcada Only allow update from same network/WiFi com o aviso sobre VLAN
Security & Updates, seção Software Update.
Interface web do WLED
Página Software Update do WLED: versão instalada WLED 16.0.1, release ESP32, versão mais recente v16.0.1, botão Auto update, Manual upload com Choose File, Ignore firmware validation e Upload, e Revert update
A página de atualização no WLED 16.0.1 (uma luz ESP32).

No WLED 0.15 e anteriores, ou quando você quer escolher o arquivo:

  1. Baixe o arquivo da sua compilação na página Releases do GitHub.
  2. Vá em Config > Security & Updates e toque em Manual OTA Update (no WLED 16, Update WLED), ou abra http://<light-ip>/update.
  3. Escolha o arquivo e toque em Update! (no WLED 16, Upload).
  4. Espere. Ele envia, grava e reinicia, normalmente em menos de um minuto. Não mexa na alimentação enquanto isso.

Antes de tudo isso, faça um backup. Security & Updates tem os botões Backup presets e Backup configuration. Uma atualização normal mantém as suas configurações, mas o backup leva dez segundos. Backup e restauração da configuração do WLED explica o que tem em cada arquivo.

Interface web do WLED
Seção Backup and Restore do WLED: texto de aviso, botão Backup presets, Restore presets com Choose File e Upload, botão Backup configuration, Restore configuration com Choose File e Upload
Os botões de backup ficam mais abaixo na mesma página Security & Updates.

Solução de problemas: por que as atualizações do ESP8266 falham

Update failed: “Not enough space” em placas de 2 MB

O ESP8266 não tem uma partição de atualização fixa como o ESP32. A nova imagem fica estacionada no espaço entre o fim do firmware em execução e o começo do sistema de arquivos. Numa placa de 2 MB o sistema de arquivos começa em 1.572.864 bytes (0x180000). Com uns 800 KB de firmware atual, sobram mais ou menos 750 KB para a nova imagem, e uma compilação completa do WLED é maior que isso. O WLED até o 0.15.1 também reserva um setor extra de 4 KB, então fica ainda mais apertado.

01,5 MB2 MB

Por que as placas de 2 MB ficam sem espaço: a nova imagem precisa caber no vão.

Há duas saídas:

  • O arquivo .bin.gz. O ESP8266 aceita uma imagem compactada com gzip do jeito que está e descompacta na inicialização. Ela é mais ou menos um quarto menor, o que muitas vezes é a diferença entre caber e falhar.
  • Duas etapas. Instale primeiro a compilação pequena ESP02_min (menos recursos, cabe com folga), reinicie, depois instale a compilação completa ESP02. Com a compilação pequena rodando sobra mais espaço, então a completa cabe. Os arquivos ESP02_min existem a partir do WLED 16. As versões 0.15 não têm.

O WLED 16 confere se o nome da compilação enviada bate com a compilação em execução, então passar de ESP02 para ESP02_min exige marcar Ignore firmware validation na página de atualização. É um problema conhecido no projeto (wled/WLED#5576). O caminho manual é ESP02, depois ESP02_min.bin.gz, depois ESP02.bin.gz.

Falha na hora no ESP01

As compilações ESP01 são feitas sem OTA. Não há para onde enviar. Conecte a placa por USB e use o install.wled.me (como).

Arquivo errado

Um .bin de ESP32 num ESP8266, ou o contrário, é recusado se você tiver sorte. Se não tiver, a luz não inicia até você gravar de novo por USB. Confira o nome da compilação toda vez.

Update failed com 401 “Access Denied”

Um 401 quer dizer que a luz recusou o envio antes de ler o arquivo. A segunda linha da mensagem diz o motivo:

MensagemCausaSolução
Please unlock OTA in security settings!Lock wireless (OTA) software update está marcadoDesmarque em Security & Updates (precisa da senha de OTA)
Please unlock settings using PIN code!Há um PIN nas configurações e ele ainda não foi digitado neste navegadorDigite o PIN e envie de novo
Client is not on local subnet.Só no WLED 16: o envio veio de outra sub-rede com Only allow update from same network/WiFi marcado, ou de um endereço fora das faixas privadasAtualize de um dispositivo na rede da luz, desmarque a opção ou defina um PIN nas configurações

Apps e o Home Assistant recebem a mesma resposta quando atualizam a luz. O Home Assistant 2026.10 e mais novos mostram o motivo; versões mais antigas falhavam em silêncio (veja correções para WLED e Home Assistant).

Bloqueada, ou em outra sub-rede

Com Lock wireless (OTA) software update marcado em Security & Updates, a luz recusa envios até você desmarcar, o que exige a senha de OTA. Com Only allow update from same network/WiFi marcado, ela recusa atualizações de outras sub-redes. Se o seu celular está em outra VLAN, desmarque essa opção (ou defina um PIN, como a página sugere), ou atualize de um dispositivo na rede da luz.

No WLED Max, as mesmas duas opções são Bloquear atualizações OTA e Limitar OTA à mesma sub-rede, em Configurações do dispositivo, Segurança e atualizações.

iOS
Tela Segurança e atualizações do WLED Max: Bloquear atualizações OTA desligado, Bloquear configurações de Wi-Fi desligado, Ativar ArduinoOTA ligado, Limitar OTA à mesma sub-rede ligado, senha de OTA definida (7 caracteres)
As duas opções no WLED Max.

Outros sintomas

Travada em 0%, ou o tempo esgota. Wi-Fi fraco na luz. Aproxime o celular do roteador (do roteador, não da luz), ou atualize de um computador com conexão a cabo.

Reiniciou na versão antiga. O envio terminou, mas a imagem não foi validada. Tente o .bin.gz ou o método em duas etapas.

Voltou para o modo WLED-AP depois. É raro, mas acontece quando a configuração se perde. Entre na rede WLED-AP (senha wled1234), configure o Wi-Fi de novo e restaure o seu backup.

Os efeitos ficam diferentes no WLED 16. Alguns IDs de efeito mudaram (o efeito 77, por exemplo). O WLED Max marca as predefinições que usam o efeito 77 para você saber quais salvar de novo.

Atualizando pelo celular

No WLED Max, abra Atualização de firmware tocando e segurando a luz na lista de dispositivos e escolhendo Firmware, ou pela faixa Atualização de firmware disponível. No Android também fica em Configurações do dispositivo.

  1. O app lista as versões recentes do repositório oficial do WLED no GitHub, incluindo as de pré-lançamento. Não há seletor de estável ou beta, então confira a versão antes de tocar.
  2. Ele escolhe exatamente a compilação que a sua luz informa (ESP32, ESP8266, ESP02, ESP01, S2, S3 ou C3). Se esse arquivo exato não existir, ele usa o tipo de chip, e Ver todas as compilações deixa você escolher.
  3. Toque em Baixar ao lado da versão em Versões disponíveis, depois em Instalar ao lado dele em Firmware em cache. Os downloads ficam guardados, então um firmware que você baixou antes pode ser instalado depois sem internet.
iOS
Aba Dispositivos do WLED Max com Garage Strip marcada com Atualizar e uma faixa Atualização de firmware disponível: Garage Strip pode atualizar para v16.0.1, com os botões Não lembrar e Atualizar
A faixa na lista de dispositivos.

A versão 1.1.4 resolve os casos de ESP8266 acima por você, no iOS e no Android:

  • As versões que precisam de duas etapas na sua placa avisam na lista (“Precisa de uma atualização em duas etapas. Ao tocar em Baixar, os dois arquivos são baixados.”).
  • Quando a compilação completa não cabe, o app oferece Iniciar atualização em duas etapas. Ele instala primeiro a versão pequena (“Passo 1 de 2: versão reduzida”), depois a completa (“Passo 2 de 2: versão completa”), sem downloads manuais. Se a etapa 1 não terminar, a luz continua no firmware antigo e nada mudou. Se a etapa 2 não terminar, a luz continua funcionando na versão pequena e Tentar o passo 2 de novo termina o serviço.
  • Se uma versão é grande demais para aquela placa mesmo em duas etapas, a linha diz “Grande demais para instalar pelo Wi-Fi nesta luz”, nada é enviado, e o app sugere instalar por USB com o install.wled.me.
  • Numa compilação sem atualização sem fio (ESP01), o app avisa e indica o install.wled.me em vez de falhar no meio.
iOS
Lista Atualização de firmware de uma luz ESP02: em Versões disponíveis um nightly marcado Grande demais para instalar pelo Wi-Fi nesta luz, depois v16.0.1 e v16.0.0, cada uma marcada Precisa de uma atualização em duas etapas, depois v16.0.0-beta e v0.15.4, cada uma com um botão Baixar
Uma luz ESP02 na lista Atualização de firmware. O Android mostra as mesmas notas.

Quando uma atualização é recusada, a tela sugere soluções como remover a senha de OTA ou permitir atualizações de outra sub-rede. Se uma luz roda uma compilação personalizada, a faixa de atualização avisa que instalar uma versão oficial substitui o firmware personalizado e os usermods extras pelo firmware padrão. O app não envia o seu próprio .bin. Para compilações personalizadas, use a interface web.

Para receber avisos sobre novas versões estáveis para as suas luzes, ative Atualizações de firmware em Ajustes›Preferências do app›Notificações (no Android, Configurações no lugar de Ajustes). Vem desativado por padrão.

Relacionados: configurações do WLED explicadas e por que uma luz WLED vive ficando sem conexão.