Installare WLED su ESP32: LED indirizzabili senza programmare

Installare WLED è il modo più rapido per trasformare un ESP32 in un controller LED via Wi-Fi senza scrivere una sola riga di codice. WLED è un firmware gratuito e open source scritto per pilotare strisce, anelli e matrici di LED indirizzabili come il WS2812B. Si carica sulla scheda dal browser con pochi clic; poi scegli dal telefono o dal computer tra oltre 100 effetti, decine di palette di colori, timer e animazioni che reagiscono alla musica. Luce d'atmosfera dietro la TV, illuminazione delle mensole, luci per le scale o decorazioni natalizie funzionano tutte con lo stesso montaggio.

In questa guida vedrai passo passo come collegare correttamente ESP32, striscia LED e alimentatore, installare WLED con l'installer web, fare la prima configurazione Wi-Fi e impostare numero di LED, pin dati e ordine dei colori. Poi imparerai a usare effetti, palette, segmenti e preset, a calcolare l'alimentazione e a iniettare corrente sulle strisce lunghe, a sincronizzare la luce con la musica tramite un microfono I2S e a integrare tutto in Home Assistant. Infine trovi due brevi programmi che controllano WLED con l'API JSON da un altro ESP32 e da un Raspberry Pi Pico W, e le soluzioni ai problemi più comuni.

Cos'è WLED e cosa può fare?

Di solito, per pilotare LED indirizzabili scrivi codice nell'Arduino IDE con Adafruit NeoPixel o FastLED e riprogrammi la scheda a ogni modifica. WLED ribalta completamente il discorso: la scheda si programma una volta sola e tutte le impostazioni, gli effetti e le programmazioni orarie si gestiscono dall'interfaccia web della scheda stessa. L'ESP32 si collega al Wi-Fi di casa, avvia un server web e qualsiasi dispositivo nella stessa rete lo raggiunge dal browser o dall'app del telefono. Le impostazioni sono salvate nella memoria flash della scheda, quindi dopo un blackout le luci ripartono da dove si erano fermate.

• LED supportati: WS2812B, WS2811, WS2813, WS2815, SK6812 (anche RGBW), TM1814 e LED con clock come APA102 e SK9822.
• Effetti e palette: oltre 100 effetti integrati e più di 70 palette di colori; ogni effetto si regola con i cursori di velocità e intensità.
• Segmenti: dividi una singola striscia in tratti e dai a ciascuno un effetto e un colore diversi.
• Preset e playlist: salva gli stili che ti piacciono e richiamali con un tocco, oppure crea liste che si alternano in sequenza.
• Timer: luci che si accendono o spengono a un orario, all'alba o al tramonto, più un timer di spegnimento.
• Integrazione: comunica con gli altri sistemi della rete tramite Home Assistant, MQTT, Alexa, E1.31 e Art-Net.

Materiale necessario

Nota di compatibilità: WLED funziona anche sulle schede con ESP8266 (NodeMCU, Wemos D1 mini), ma avendo memoria e potenza di calcolo più limitate gestiscono meno LED, e la funzione che reagisce alla musica esiste solo sull'ESP32. Per questo per un nuovo progetto consigliamo un ESP32, e tutta la guida è scritta per l'ESP32. Il Raspberry Pi Pico non può eseguire WLED; per pilotare LED indirizzabili con un Pico puoi usare il modulo neopixel di MicroPython oppure, come nell'esempio con l'API JSON qui sotto, comandare a distanza da un Pico W un ESP32 su cui gira WLED.

Collegamento: ESP32, striscia LED e alimentatore

Installare WLED con l'installer web

Per installare WLED non servono l'Arduino IDE né altri programmi. L'installer web ufficiale (install.wled.me) si collega direttamente all'ESP32 tramite la funzione Web Serial del browser, riconosce il chip della scheda e scrive il firmware adatto. Funziona nei browser desktop basati su Chromium come Chrome, Edge e Opera; Firefox e Safari al momento non supportano Web Serial. Perché la scheda compaia come porta seriale sul computer deve essere installato il driver CP210x o CH340.

1. Collega l'ESP32 al computer con un cavo USB che trasmetta dati. Per ora non serve collegare la striscia LED.
2. Apri l'installer web di WLED in Chrome o Edge. Dall'elenco scegli l'ultima versione stabile (stable); le beta servono per i test.
3. Premi il pulsante Install. Nella finestra che si apre seleziona la porta della scheda (per esempio COM3 su Windows, cu.usbserial... o cu.wchusbserial... su macOS) e premi Connect.
4. Quando l'installer ha riconosciuto il chip, conferma l'opzione Install WLED. Se la scheda è stata usata prima con un altro programma, cancellare la memoria con "Erase device" evita che si mescolino vecchie impostazioni.
5. La scrittura dura circa un minuto. Se il caricamento non parte, tieni premuto il pulsante BOOT dell'ESP32 e riprova.
6. Alla fine l'installer chiede i dati del Wi-Fi. Inserisci nome della rete e password, premi Connect e poi apri l'interfaccia di WLED con il link Visit Device che compare.

Prima configurazione Wi-Fi

Se hai saltato il passaggio Wi-Fi dell'installer o la scheda non riesce a collegarsi, WLED apre un proprio access point. Collega il telefono alla rete WLED-AP; la password predefinita è wled1234. Sulla maggior parte dei telefoni la pagina delle impostazioni si apre da sola; altrimenti scrivi 4.3.2.1 nel browser. Nella pagina WiFi Setup inserisci nome e password della rete di casa, salva e aspetta che la scheda si riavvii. L'ESP32 supporta solo il Wi-Fi a 2,4 GHz; se il router usa lo stesso nome per 2,4 e 5 GHz di solito va bene, ma non può collegarsi a una rete che trasmette solo a 5 GHz. Dopo la connessione trovi l'indirizzo IP della scheda nell'elenco dei dispositivi del router o con la ricerca automatica dell'app WLED. Per sicurezza conviene anche cambiare nella stessa pagina la password dell'access point.

Numero di LED, pin dati e ordine dei colori

1. Nell'interfaccia di WLED apri il menu Config (icona dell'ingranaggio) ed entra in LED Preferences.
2. In LED outputs scegli il tipo di LED: "WS281x" per il WS2812B, "SK6812/WS2814 RGBW" per le strisce RGBW.
3. Imposta Color Order su GRB per il WS2812B; se i colori risultano sbagliati, cambia questo campo finché trovi quello giusto.
4. In Length scrivi il numero di LED della striscia (per esempio 60 per 1 m di striscia da 60 LED/m).
5. In GPIO scrivi il pin a cui è collegato il filo dati (16 in questa guida). I GPIO 6–11 sono riservati alla memoria flash e i 34–39 sono solo ingressi; non usarli.
6. In Maximum Current (il limitatore automatico di luminosità) scrivi in mA circa l'80% della corrente che il tuo alimentatore può dare; 3200 per uno da 5 V 4 A.
7. Premi Save in fondo alla pagina. Torna alla schermata principale e scegli un colore: tutta la striscia dovrebbe accendersi di quel colore.

Effetti, palette, segmenti e preset

La schermata principale di WLED ha tre parti: in alto il selettore di colore e la luminosità, al centro l'elenco degli effetti e accanto quello delle palette. Quando scegli un effetto (per esempio Rainbow, Fire 2012 o Twinkle), i cursori Speed e Intensity sotto di esso ne cambiano velocità e intensità. La palette decide quale famiglia di colori usa l'effetto: lo stesso effetto "Colorwaves" sembra onde blu con la palette "Ocean" e fiamme rosse con "Lava". Se vuoi che un effetto usi i colori che hai scelto, seleziona palette come "Default" o "Color 1".

• Segmenti: dividi la striscia in parti nella sezione Segments; per esempio i LED 0–29 possono "respirare" in blu mentre i 30–59 mostrano un arcobaleno. Ogni segmento ha effetto, palette, luminosità e direzione propri.
• Preset: dai un nome e salva nella sezione Presets lo stile che ti piace. Un preset memorizza insieme effetto, colore, segmenti e luminosità e li richiama con un tocco.
• Playlist: crea un elenco che passa in sequenza da un preset all'altro per la durata che scegli; ideale per vetrine o luci da festa.
• Timer: imposta il fuso orario in Config > Time & Macros e avvia un preset a un orario, all'alba o al tramonto.
• Luce notturna: il pulsante con la luna abbassa lentamente la luce e la spegne nel tempo scelto; comodo per la cameretta.
• Sincronizzazione: più dispositivi WLED nella stessa rete possono collegarsi via UDP e riprodurre lo stesso effetto nello stesso momento.

L'app per il telefono

L'interfaccia funziona in qualsiasi browser, ma per l'uso quotidiano è più comoda l'app gratuita WLED per iOS e Android. L'app trova da sola i dispositivi WLED nella stessa rete, li mostra in un elenco e con un tocco apre l'interfaccia della scheda. Se hai più dispositivi (per esempio soggiorno, cucina e scale), li gestisci tutti da un'unica schermata. Se un dispositivo non compare, verifica che telefono ed ESP32 siano nella stessa rete o aggiungi l'indirizzo IP a mano. Dato che l'app è solo un'interfaccia, il telefono non deve restare acceso perché le luci funzionino; timer e preset continuano a girare dentro l'ESP32.

Calcolo della potenza e iniezione di corrente

Un LED WS2812B contiene tre minuscoli LED, rosso, verde e blu, e ciascuno assorbe circa 20 mA alla massima luminosità. Un singolo pixel richiede quindi circa 60 mA col bianco pieno. È il caso peggiore; con effetti colorati e luminosità media il consumo reale è spesso circa un terzo. L'impostazione Maximum Current di WLED (il limitatore automatico di luminosità) calcola la corrente di ogni fotogramma e abbassa da sola la luminosità se il limite verrebbe superato. Grazie a questo puoi far funzionare in sicurezza una striscia da 300 LED con un alimentatore da 5 V 10 A; solo il bianco pieno risulta un po' attenuato. Il limite predefinito è basso per tenere la scheda al sicuro quando è alimentata da USB, quindi aggiornalo sempre quando passi a un alimentatore esterno.

• Caduta di tensione: le piste di rame delle strisce a 5 V sono sottili; quando la corrente aumenta la tensione cala verso la fine della striscia e il bianco appare giallastro o rosato. Di solito inizia dopo 1–2 metri (60–120 LED).
• Iniezione di corrente: porta dall'alimentatore fili 5 V e GND separati a ogni tratto di 1–2 metri e saldali sulle piazzole di rame della striscia. Nelle strisce lunghe funziona bene anche alimentare entrambe le estremità. La linea dati entra solo all'inizio; i fili di iniezione portano solo 5 V e GND.
• Sezione dei cavi: usa almeno 0,75–1 mm² (circa 18 AWG) per pochi ampere e 1,5 mm² da 10 A in su; i sottili cavetti della striscia vanno bene solo per tratti corti.
• Fusibile: metti un fusibile tra alimentatore e striscia su ogni linea di alimentazione, adeguato alla corrente che il cavo regge; evita che il cavo bruci in caso di cortocircuito.
• Opzione 12 V: nelle installazioni molto lunghe le strisce a 12 V come la WS2815 assorbono un terzo della corrente a parità di potenza e soffrono molto meno la caduta di tensione.
• Calcolatore: se costruisci qualcosa di portatile a batteria o con un powerbank, calcola l'autonomia con il calcolatore di durata della batteria.

Luce sincronizzata con la musica tramite microfono

Le versioni di WLED per ESP32 includono già il componente aggiuntivo AudioReactive: colleghi un microfono, cambi qualche impostazione e gli effetti si muovono a ritmo e secondo le frequenze della musica. I risultati migliori li dà l'INMP441, un microfono I2S digitale: inviando il segnale in digitale evita i problemi di rumore e guadagno dei microfoni analogici. Anche i moduli analogici come MAX9814 o MAX4466 si possono usare su un pin ADC1 (per esempio GPIO 36), ma richiedono più regolazioni. I sensori di suono come il KY-038 dicono solo se c'è rumore, quindi non sono adatti a questo scopo.

Dopo il collegamento attiva la sezione AudioReactive nella pagina Config > Usermods, scegli "Generic I2S" come tipo di microfono e inserisci i pin SD, WS e SCK come in tabella. Dopo aver salvato e riavviato la scheda, gli effetti che reagiscono al suono risaltano nell'elenco; GEQ, Gravimeter e Waterfall sono un buon punto di partenza. Se le luci si muovono senza suono, alza il valore di Squelch (soglia del rumore); se reagiscono poco alla musica, aumenta Gain. Mettere il microfono dove sente la stanza, e non proprio davanti alla cassa, dà il risultato più equilibrato.

Integrazione con Home Assistant

Home Assistant ha un'integrazione WLED già inclusa e di solito trova da solo i dispositivi WLED nella stessa rete. Se compare la notifica "Nuovo dispositivo rilevato" basta confermare; altrimenti vai in Impostazioni > Dispositivi e servizi > Aggiungi integrazione, scegli WLED e inserisci l'indirizzo IP del dispositivo. L'integrazione aggiunge la striscia e ogni segmento come luci separate, preset, playlist e palette come menu di selezione, velocità e intensità come cursori. Così crei in pochi clic automazioni come "al tramonto porta la striscia del soggiorno su bianco caldo" o "accendi il corridoio quando si apre la porta". Se preferisci MQTT, WLED si collega anche a un broker MQTT dalla pagina Sync Interfaces; come usare MQTT con Home Assistant lo spieghiamo nell'articolo ESP32, MQTT e Home Assistant.

Controllare WLED dal codice: l'API JSON

WLED funziona senza codice, ma se vuoi che un altro dispositivo lo controlli basta una semplice richiesta HTTP. Un messaggio JSON inviato all'indirizzo /json/state del dispositivo cambia lo stato della luce: {"on":"t"} la accende o spegne, {"bri":128} imposta metà luminosità, {"ps":2} avvia il preset numero 2. Se aggiungi "v":true al messaggio, WLED risponde con lo stato attuale. Il primo programma qui sotto usa un pulsante su un altro ESP32 per passare tra i primi tre preset di WLED; il secondo fa lo stesso con un Raspberry Pi Pico W e MicroPython. In entrambi devi inserire i dati della tua rete e l'indirizzo IP del 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)

In entrambi i programmi lo stato attuale viene confrontato con il precedente perché ogni pressione invii una sola richiesta, e l'attesa di 50 ms filtra il rimbalzo meccanico del pulsante. In un progetto reale conviene assegnare al dispositivo WLED un IP fisso nel router o usare il suo nome mDNS indicato nell'interfaccia di WLED, perché l'IP può cambiare quando manca la corrente e il router si riavvia. Con lo stesso metodo puoi accendere le luci delle scale quando scatta un sensore di movimento, passare a un preset notturno quando un LDR segnala che fa buio o cambiare il colore della striscia in base a una temperatura.

Problemi comuni e soluzioni

WLED è uno dei modi più divertenti per lavorare con i LED indirizzabili: l'installazione richiede pochi minuti, ottieni effetti dall'aspetto professionale senza scrivere codice e, quando serve, puoi collegarlo ai tuoi progetti con l'API JSON. Se vuoi imparare a pilotare i LED con il codice, nell'app BlueGrays puoi costruire passo passo, con schema e codice pronto, il progetto "Controllo striscia NeoPixel WS2812B con ESP32" e quelli di luce che scorre, supercar e lampeggiante della polizia con WS2812B.