Instalação do WLED no ESP32: controle LEDs endereçáveis sem programar

A instalação do WLED é a forma mais rápida de transformar um ESP32 em um controlador de LEDs por Wi-Fi sem escrever uma única linha de código. WLED é um firmware gratuito e de código aberto, criado para controlar fitas, anéis e matrizes de LEDs endereçáveis, como o WS2812B. Ele é gravado na placa pelo navegador com poucos cliques; depois, você escolhe entre mais de 100 efeitos, dezenas de paletas de cores, temporizadores e animações que reagem à música pelo celular ou computador. Iluminação atrás da TV, de prateleiras, de escadas ou decoração de Natal: tudo funciona com a mesma configuração.

Neste guia, você verá passo a passo como ligar corretamente o ESP32, a fita de LEDs e a fonte de alimentação, instalar o WLED com o instalador web, fazer a configuração inicial do Wi-Fi e definir a quantidade de LEDs, o pino de dados e a ordem das cores. Depois, aprenderá a usar efeitos, paletas, segmentos e predefinições, calcular a alimentação e injetá-la ao longo de fitas compridas, sincronizar a luz com a música usando um microfone I2S e integrar tudo ao Home Assistant. Por fim, há dois programas curtos que controlam o WLED pela API JSON a partir de outro ESP32 e de um Raspberry Pi Pico W, além de soluções para os problemas mais comuns.

O que é WLED e o que ele pode fazer?

Normalmente, para controlar LEDs endereçáveis, você escreve código no Arduino IDE com Adafruit NeoPixel ou FastLED e reprograma a placa a cada mudança. O WLED muda completamente essa lógica: a placa é programada uma vez, e todas as configurações, efeitos e programações de horário são feitas pela interface web da própria placa. O ESP32 se conecta ao Wi-Fi da sua casa, executa um servidor web e pode ser acessado por qualquer dispositivo na mesma rede pelo navegador ou pelo app do celular. As configurações ficam na memória flash da placa, por isso, depois de uma queda de energia, as luzes continuam de onde pararam.

• LEDs compatíveis: WS2812B, WS2811, WS2813, WS2815, SK6812 (incluindo RGBW), TM1814 e LEDs com clock, como APA102 e SK9822.
• Efeitos e paletas: Mais de 100 efeitos incorporados e mais de 70 paletas de cores; cada efeito pode ser ajustado com controles deslizantes de velocidade e intensidade.
• Segmentos: Divida uma única fita em seções e atribua a cada uma seu próprio efeito e cor.
• Predefinições e listas de reprodução: Salve os visuais de que você gosta e recupere-os com um toque, ou crie listas que mudam em sequência.
• Temporizadores: Luzes que ligam ou desligam em um horário definido, ao nascer ou ao pôr do sol, além de um temporizador para dormir.
• Integração: Comunica-se com outros sistemas na rede por Home Assistant, MQTT, Alexa, E1.31 e Art-Net.

O que você precisa

Nota de compatibilidade: o WLED também funciona em placas baseadas no ESP8266 (NodeMCU, Wemos D1 mini), mas, como a memória e a capacidade de processamento são mais limitadas, elas controlam menos LEDs, e o recurso que reage à música só existe no ESP32. Por isso, recomendamos um ESP32 para projetos novos, e todo este guia foi escrito para o ESP32. O Raspberry Pi Pico não executa o WLED; para controlar LEDs endereçáveis com um Pico, você pode usar o módulo neopixel do MicroPython ou, como no exemplo de API JSON abaixo, usar um Pico W para controlar remotamente um ESP32 que executa o WLED.

Ligação: ESP32, fita de LEDs e fonte de alimentação

Instalação do WLED com o instalador web

Você não precisa do Arduino IDE nem de outro programa para instalar o WLED. O instalador web oficial (install.wled.me) se conecta diretamente ao ESP32 pelo recurso Web Serial do navegador, detecta o chip da placa e grava o firmware correspondente. Isso funciona em navegadores de computador baseados em Chromium, como Chrome, Edge e Opera; Firefox e Safari não oferecem suporte a Web Serial no momento. Para a placa aparecer como porta serial no computador, o driver CP210x ou CH340 precisa estar instalado.

1. Conecte o ESP32 ao computador com um cabo USB capaz de transmitir dados. Ainda não é necessário ligar a fita de LEDs.
2. Abra o instalador web do WLED no Chrome ou Edge. Na lista de versões, escolha a versão estável mais recente; versões beta são para testes.
3. Pressione o botão Install. Na janela que abrir, selecione a porta da sua placa (algo como COM3 no Windows, cu.usbserial... ou cu.wchusbserial... no macOS) e clique em Connect.
4. Depois que o instalador detectar o chip, confirme a opção Install WLED. Se a placa já foi usada com outro programa, apagar a memória com “Erase device” evita que configurações antigas se misturem às novas.
5. A gravação leva cerca de um minuto. Se o carregamento não começar, mantenha pressionado o botão BOOT do ESP32 e tente novamente.
6. Quando a instalação terminar, o instalador pedirá os dados do Wi-Fi. Digite o nome da rede e a senha, clique em Connect e abra a interface do WLED pelo link Visit Device que aparecer.

Configuração inicial do Wi-Fi

Se você pulou a etapa de Wi-Fi do instalador, ou a placa não consegue entrar na rede, o WLED cria seu próprio ponto de acesso. Conecte o celular à rede chamada WLED-AP; a senha padrão é wled1234. Na maioria dos celulares, a página de configurações abre sozinha; se isso não acontecer, digite 4.3.2.1 no navegador. Na página WiFi Setup, informe o nome e a senha da rede de sua casa, salve e espere a placa reiniciar. O ESP32 só oferece suporte a Wi-Fi de 2,4 GHz; se o roteador usa o mesmo nome para 2,4 e 5 GHz, geralmente funciona, mas ele não consegue entrar em uma rede que transmite apenas em 5 GHz. Depois da conexão, você pode encontrar o endereço IP da placa na lista de dispositivos conectados do roteador ou pela descoberta automática do app WLED. Também é uma boa ideia mudar a senha do ponto de acesso nessa mesma página por segurança.

Quantidade de LEDs, pino de dados e ordem das cores

1. Na interface do WLED, abra o menu Config (ícone de engrenagem) e vá para LED Preferences.
2. Em LED outputs, escolha o tipo de LED: “WS281x” para WS2812B e “SK6812/WS2814 RGBW” para fitas RGBW.
3. Defina Color Order como GRB para o WS2812B; se as cores saírem erradas, altere esse campo até encontrar a ordem correta.
4. Em Length, informe a quantidade de LEDs da fita (por exemplo, 60 para 1 m de fita de 60 LED/m).
5. Em GPIO, informe o pino ao qual o fio de dados está ligado (16 neste guia). Os GPIOs 6–11 são reservados para a memória flash e 34–39 funcionam apenas como entrada; não os use.
6. Em Maximum Current (o limitador automático de brilho), informe cerca de 80% da corrente que sua fonte consegue fornecer, em mA; 3200 para uma fonte de 5 V e 4 A.
7. Pressione Save no fim da página. Volte à tela principal e escolha uma cor; toda a fita deve acender nessa cor.

Efeitos, paletas, segmentos e predefinições

A tela principal do WLED tem três partes: o seletor de cores e o brilho no alto, a lista de efeitos no meio e a lista de paletas ao lado. Quando você escolhe um efeito (por exemplo, Rainbow, Fire 2012, Twinkle), os controles deslizantes Speed e Intensity abaixo dele alteram a velocidade e a densidade. A paleta determina qual família de cores o efeito usa: o mesmo efeito “Colorwaves” parece ondas azuis com a paleta “Ocean” e chamas vermelhas com “Lava”. Se quiser que um efeito use as cores que você escolheu, selecione paletas como “Default” ou “Color 1”.

• Segmentos: Divida a fita em partes na seção Segments; por exemplo, os LEDs 0–29 podem pulsar suavemente em azul enquanto 30–59 exibem um arco-íris. Cada segmento tem seu próprio efeito, paleta, brilho e direção.
• Predefinições: Dê um nome e salve o visual de que você gosta na seção Presets. Uma predefinição armazena efeito, cor, segmentos e brilho de uma só vez e recupera tudo com um toque.
• Listas de reprodução: Crie uma lista que percorra várias predefinições em ordem, pelos tempos que você escolher; ideal para vitrines ou iluminação de festas.
• Temporizadores: Defina seu fuso horário na página Config > Time & Macros e execute uma predefinição em um horário definido, ao nascer ou ao pôr do sol.
• Luz noturna: O botão de lua reduz o brilho gradualmente e desliga a luz ao longo do tempo escolhido; útil para o quarto de uma criança.
• Sincronização: Vários dispositivos WLED na mesma rede podem se conectar por UDP e reproduzir o mesmo efeito ao mesmo tempo.

O app para celular

A interface funciona em qualquer navegador, mas, para o uso diário, o app gratuito WLED para iOS e Android é mais prático. O app encontra automaticamente os dispositivos WLED na mesma rede, lista todos e abre a interface da própria placa quando você toca em um deles. Se tiver vários dispositivos (por exemplo, sala, cozinha e escadas), você controla todos em uma única tela. Se um dispositivo não aparecer na lista, confira se o celular e o ESP32 estão na mesma rede ou adicione o endereço IP manualmente. Como o app é apenas uma interface, o celular não precisa ficar ligado para as luzes funcionarem; temporizadores e predefinições continuam sendo executados dentro do ESP32.

Dimensionamento e injeção de alimentação

Um LED WS2812B contém três pequenos LEDs, vermelho, verde e azul, cada um consumindo cerca de 20 mA no brilho máximo. Assim, um único pixel precisa de cerca de 60 mA com branco no brilho máximo. Esse é o pior caso; com efeitos coloridos e brilho médio, o consumo real costuma ser cerca de um terço disso. A configuração Maximum Current do WLED (o limitador automático de brilho) calcula a corrente que cada quadro consumirá e reduz o brilho automaticamente se o limite for ultrapassado. Graças a isso, você pode usar com segurança uma fita de 300 LEDs com uma fonte de 5 V e 10 A; apenas o branco no brilho máximo fica um pouco menos intenso. O limite padrão é mantido baixo para proteger a placa quando alimentada pela USB, por isso não deixe de atualizá-lo ao passar para uma fonte externa.

• Queda de tensão: As trilhas de cobre das fitas de 5 V são finas; à medida que a corrente aumenta, a tensão cai em direção ao fim da fita e o branco fica amarelado ou rosado. Isso costuma começar depois de 1–2 metros (60–120 LEDs).
• Injeção de alimentação: Leve fios separados de 5 V e GND da fonte de alimentação a cada 1–2 metros da fita e solde-os nas ilhas de cobre da fita. Alimentar as duas extremidades de uma fita longa também funciona bem. A linha de dados entra apenas no início; os fios de injeção levam somente 5 V e GND.
• Bitola dos fios: Use pelo menos 0,75–1 mm² (cerca de 18 AWG) para alguns amperes e 1,5 mm² para 10 A ou mais; os próprios fios finos de conexão da fita servem apenas para fitas curtas.
• Fusível: Instale um fusível entre a fonte e a fita em cada ponto de alimentação, dimensionado para a corrente que o fio suporta; ele evita que o fio queime em um curto-circuito.
• Opção de 12 V: Para instalações muito longas, fitas de 12 V, como a WS2815, consomem um terço da corrente para a mesma potência e sofrem muito menos com a queda de tensão.
• Calculadora: Se você estiver montando um sistema portátil com baterias ou power bank, calcule a autonomia com a calculadora de autonomia da bateria.

Luz sincronizada com a música usando um microfone

As versões do WLED para ESP32 já vêm com o complemento AudioReactive incorporado; conecte um microfone, altere algumas configurações e os efeitos acompanharão o ritmo e as frequências da música. Os melhores resultados vêm do INMP441, um microfone I2S digital: como ele envia o sinal digitalmente, você evita os problemas de ruído e ganho dos microfones analógicos. Módulos de microfone analógico, como MAX9814 ou MAX4466, também podem ser usados em um pino ADC1 (por exemplo, GPIO 36), mas exigem mais ajustes. Sensores de som como o KY-038 apenas informam se há som, por isso não são adequados para essa função.

Depois de fazer as ligações, ative a seção AudioReactive na página Config > Usermods, escolha “Generic I2S” como tipo de microfone e informe os pinos SD, WS e SCK conforme a tabela. Depois de salvar e reiniciar a placa, os efeitos que reagem ao som se destacam na lista de efeitos; GEQ, Gravimeter e Waterfall são bons pontos de partida. Se as luzes oscilarem quando não houver som, aumente o valor de Squelch (limiar de ruído); se elas reagirem pouco à música, aumente Gain. Colocar o microfone em um lugar onde capte o som do ambiente, em vez de diretamente em frente ao alto-falante, produz o resultado mais equilibrado.

Integração com Home Assistant

O Home Assistant tem uma integração nativa com WLED e geralmente encontra sozinho os dispositivos WLED na mesma rede. Se aparecer uma notificação de “Novo dispositivo descoberto”, basta confirmar; caso contrário, vá para Configurações > Dispositivos e serviços > Adicionar integração, escolha WLED e informe o endereço IP do dispositivo. A integração adiciona a fita e cada segmento como luzes separadas, predefinições, listas de reprodução e paletas como caixas de seleção, e velocidade e intensidade como controles deslizantes. Isso permite criar automações como “mudar a fita da sala para branco quente ao pôr do sol” ou “iluminar o corredor quando a porta abrir” com poucos cliques. Se preferir usar MQTT, o WLED também pode se conectar a um broker MQTT pela página Sync Interfaces; abordamos o uso de MQTT com Home Assistant no artigo ESP32, MQTT e Home Assistant.

Controle do WLED por código: a API JSON

O WLED funciona sem código, mas, quando você quer que outro dispositivo o controle, basta uma requisição HTTP simples. Uma mensagem JSON enviada ao endereço /json/state do dispositivo altera o estado da luz: {"on":"t"} alterna entre ligada e desligada, {"bri":128} define metade do brilho e {"ps":2} executa a predefinição número 2. Se você adicionar "v":true à mensagem, o WLED responderá com o estado atual. O primeiro programa abaixo usa um botão em outro ESP32 para percorrer as três primeiras predefinições no WLED; o segundo faz o mesmo com um Raspberry Pi Pico W e MicroPython. Nos dois programas, informe os dados da sua rede e o endereço IP do dispositivo WLED.

1// İkinci bir ESP32'den WLED preset değiştirme (JSON API) / Switch WLED presets from a second ESP32 (JSON API)
2// Buton: GPIO 4 -> GND (dahili pull-up) / button: GPIO 4 -> GND (internal pull-up)
3#include <WiFi.h>
4#include <HTTPClient.h>
5
6const char* WIFI_SSID = "AgAdi";                           // ağ adı / network name
7const char* WIFI_PASS = "Sifre";                           // ağ şifresi / network password
8const char* WLED_URL = "http://192.168.1.50/json/state";   // WLED cihazının IP'si / IP of the WLED device
9const int BUTTON_PIN = 4;
10
11int preset = 1;
12bool lastState = HIGH;
13
14int sendJson(const String& body) {
15  HTTPClient http;
16  http.begin(WLED_URL);
17  http.addHeader("Content-Type", "application/json");
18  int code = http.POST(body);                              // 200 = başarılı / success
19  http.end();
20  return code;
21}
22
23void setup() {
24  Serial.begin(115200);
25  pinMode(BUTTON_PIN, INPUT_PULLUP);
26  WiFi.begin(WIFI_SSID, WIFI_PASS);
27  while (WiFi.status() != WL_CONNECTED) {
28    delay(300);
29    Serial.print('.');
30  }
31  Serial.print("\nIP: ");
32  Serial.println(WiFi.localIP());
33}
34
35void loop() {
36  bool state = digitalRead(BUTTON_PIN);
37  if (lastState == HIGH && state == LOW) {                 // butona basıldı / button pressed
38    String body = "{\"on\":true,\"ps\":" + String(preset) + "}";
39    int code = sendJson(body);
40    Serial.printf("Preset %d -> HTTP %d\n", preset, code);
41    preset = preset % 3 + 1;                               // 1 -> 2 -> 3 -> 1
42    delay(50);                                             // basit debounce / simple debounce
43  }
44  lastState = state;
45}

1# Raspberry Pi Pico W: butonla WLED aç/kapat (JSON API) / toggle WLED with a button (JSON API)
2# Buton: GP14 -> GND (dahili pull-up) / button: GP14 -> GND (internal pull-up)
3import network
4import time
5import urequests
6from machine import Pin
7
8SSID = "AgAdi"                                  # ağ adı / network name
9PASSWORD = "Sifre"                              # ağ şifresi / network password
10WLED_URL = "http://192.168.1.50/json/state"     # WLED cihazının IP'si / IP of the WLED device
11
12button = Pin(14, Pin.IN, Pin.PULL_UP)
13
14wlan = network.WLAN(network.STA_IF)
15wlan.active(True)
16wlan.connect(SSID, PASSWORD)
17while not wlan.isconnected():
18    time.sleep(0.3)
19print("IP:", wlan.ifconfig()[0])
20
21last = 1
22while True:
23    now = button.value()
24    if last == 1 and now == 0:                  # butona basıldı / button pressed
25        r = urequests.post(WLED_URL, json={"on": "t", "v": True})
26        state = r.json()                        # güncel durum / current state
27        r.close()
28        print("Acik / On:", state["on"], " Parlaklik / Brightness:", state["bri"])
29        time.sleep_ms(50)                       # basit debounce / simple debounce
30    last = now
31    time.sleep_ms(10)

Nos dois programas, o estado atual é comparado ao anterior para que um único pressionamento envie apenas uma requisição, e a espera de 50 ms filtra o repique mecânico do botão. Em um projeto real, é uma boa ideia atribuir um endereço IP fixo ao dispositivo WLED no roteador ou usar seu nome mDNS da interface do WLED, porque o IP pode mudar quando a energia cai e o roteador reinicia. Com o mesmo método, você pode acender luzes de escada quando um sensor de movimento for acionado, mudar para uma predefinição noturna quando um LDR indicar que está escurecendo ou alterar a cor da fita conforme uma leitura de temperatura.

Problemas comuns e soluções

O WLED é uma das formas mais agradáveis de trabalhar com LEDs endereçáveis: a instalação leva poucos minutos, você obtém efeitos com aparência profissional sem escrever código e, quando precisar, pode integrá-lo aos seus próprios projetos pela API JSON. Se quiser aprender como os LEDs são controlados por código, você pode montar o projeto “Controle de fita WS2812B NeoPixel com ESP32” e os projetos de LEDs sequenciais WS2812B, efeito Super Máquina e luz de polícia no app BlueGrays, passo a passo com diagrama de fiação e código pronto.