Guide · 9 min di lettura

ESP32 gestore schede: errore di installazione in Arduino IDE

ESP32 gestore schede in errore? URL corretto, Error downloading, timeout, antivirus e proxy, vecchi pacchetti e installazione offline in Arduino IDE.

Un errore del gestore schede ESP32 è il problema più comune quando si aggiunge il supporto ESP32 ad Arduino IDE: esp32 non compare mai nel Gestore schede, l'installazione si ferma a metà con "Error downloading" oppure va in timeout dopo minuti di attesa. La causa è quasi sempre una di queste cinque: un URL del gestore schede sbagliato o vecchio, una connessione Internet lenta o limitata, un antivirus che blocca i file, vecchi download rimasti a metà e residui di pacchetti precedenti sul disco.

In questa guida farai prima un'installazione pulita passo passo, poi troverai la soluzione in base al messaggio di errore che vedi sullo schermo. Vedrai anche come installare offline nelle reti limitate di scuole e uffici, come ottenere un output dettagliato con Arduino CLI e come scegliere tra i core 2.x e 3.x. Alla fine un piccolo sketch di prova confermerà che l'installazione funziona davvero.

Scheda di sviluppo ESP32 DevKit
ESP32 DevKit: per programmarla con Arduino IDE devi prima installare il pacchetto schede di Espressif.

Cos'è il pacchetto schede ESP32 e perché è così grande?

Appena installato, Arduino IDE conosce solo le schede di Arduino. Per l'ESP32 devi installare il pacchetto arduino-esp32 (core) di Espressif. Non si tratta di pochi file: contiene le toolchain di compilazione Xtensa e RISC-V, le librerie ESP-IDF, lo strumento di caricamento esptool e gli strumenti per il file system. Le versioni 3.x attuali scaricano centinaia di megabyte e, una volta estratte, occupano diversi gigabyte sul disco. Più il download è grande, più è facile che si interrompa, ed è da qui che nasce la maggior parte degli errori.

Installazione corretta passo passo

  1. Usa la versione 2.x più recente di Arduino IDE; la vecchia base Java della 1.8.x a volte non riesce ad aprire connessioni sicure con alcuni server.
  2. Apri File > Preferenze (su macOS Arduino IDE > Settings).
  3. Nel campo URL aggiuntive per il Gestore schede incolla questo indirizzo: https://espressif.github.io/arduino-esp32/package_esp32_index.json. Se ci sono già altri URL, metti ciascuno su una riga.
  4. Fai clic su OK e attendi che l'IDE scarichi l'indice dei pacchetti nella parte bassa della finestra.
  5. Apri il Gestore schede dalla barra laterale, scrivi esp32 e fai clic su Installa per esp32 by Espressif Systems. Il pacchetto "Arduino ESP32 Boards" di Arduino serve solo per la Nano ESP32, non confonderli.
  6. Al termine scegli ESP32 Dev Module o il modello della tua scheda in Strumenti > Scheda.
L'indirizzo https://dl.espressif.com/dl/package_esp32_index.json citato nelle vecchie guide non viene più aggiornato e mostra solo versioni molto vecchie. Se è ancora nel tuo elenco, cancellalo: due URL ESP32 diversi contemporaneamente confondono l'elenco delle versioni e possono far fallire i download.

Tabella delle soluzioni in base al messaggio di errore

Quando l'installazione fallisce, il pannello Output in basso nell'IDE mostra un lungo messaggio in inglese. Non serve decifrarlo tutto: cerca nella tabella qui sotto l'espressione chiave e applica la soluzione accanto. Se ne vedi più di una, di solito l'ultima riga è la causa vera.

Il messaggio contieneSignificatoSoluzione
Error downloading ... package_esp32_index.jsonL'indice dei pacchetti non è raggiungibileControlla l'URL lettera per lettera e aprilo nel browser; se non si apre, il problema è la rete o il proxy
context deadline exceeded, Client.Timeout exceeded, DEADLINE_EXCEEDEDIl download ha superato il tempo limiteAumenta il timeout, prova un cavo di rete o l'hotspot del telefono
TLS handshake timeout, x509: certificate signed by unknown authorityImpossibile creare una connessione sicuraCorreggi data e ora del computer; in una rete aziendale imposta il proxy
checksum mismatch, archive hash differs, CRC doesn't matchIl file scaricato è danneggiato o incompletoCancella i file ESP32 nella cartella staging e reinstalla
Access is denied, moving extracted archive, renameUn antivirus o un altro programma ha bloccato un fileAggiungi la cartella Arduino15 alle esclusioni dell'antivirus e riavvia l'IDE
no space left on deviceDisco pienoLibera almeno 5 GB e rimuovi le vecchie versioni del core
403 Forbidden, 404 Not Found (github.com)GitHub è bloccato o l'indirizzo è vecchioProva un'altra rete, aggiorna l'IDE e l'URL
esp32 non compare nel Gestore schedeURL mancante o indice non aggiornatoAggiungi l'URL e riavvia l'IDE

Timeout e connessione lenta

Il caso più frequente è che la connessione cada mentre si scarica uno dei grossi file della toolchain. Arduino IDE 2.x usa Arduino CLI dietro le quinte, e il suo timeout di rete predefinito può essere troppo breve per le connessioni lente. Prova prima le soluzioni semplici: cavo di rete o hotspot del telefono al posto del Wi-Fi, spegnere o accendere una VPN, oppure riprovare in un orario in cui la rete è libera. Se un'installazione si è interrotta, al riavvio l'IDE non scarica di nuovo i file già completati; con qualche tentativo spesso ci si arriva.

Se il problema continua, aumenta il timeout. Con l'IDE chiuso, apri con un editor di testo il file .arduinoIDE/arduino-cli.yaml nella tua cartella utente, aggiungi una sezione network: e, sotto e rientrata, la riga connection_timeout: 600s. Così l'attesa sale a 10 minuti; l'impostazione vale nelle versioni recenti dell'IDE che includono Arduino CLI 1.x, quindi se il tuo IDE è vecchio aggiornalo prima. Nelle reti aziendali inserisci l'indirizzo del proxy in Preferenze > Rete dell'IDE.

Antivirus, firewall e proxy

Su Windows, un'installazione che si ferma quasi alla fine con "Access is denied" o "moving extracted archive" dipende di solito dall'antivirus. Estraendo il pacchetto si creano migliaia di piccoli file; Windows Defender o un altro software di sicurezza li blocca per analizzarli e l'IDE non riesce a spostarli al loro posto. La soluzione è aggiungere la cartella Arduino15 alle esclusioni dell'antivirus durante l'installazione; escludere solo questa cartella è più sicuro che disattivare del tutto la protezione. Nelle reti di scuole e aziende, inoltre, un firewall può bloccare i server di download di GitHub. Se l'indice dei pacchetti si apre nel browser ma l'installazione fallisce comunque, chiedi l'indirizzo del proxy all'amministratore di rete, oppure installa il pacchetto a casa e trasferiscilo con il metodo offline descritto più sotto.

Sistema operativoCartella Arduino15Download parziali (staging)
Windows%LOCALAPPDATA%\Arduino15%LOCALAPPDATA%\Arduino15\staging\packages
macOS~/Library/Arduino15~/Library/Arduino15/staging/packages
Linux~/.arduino15~/.arduino15/staging/packages

Pulire i residui dei vecchi pacchetti

Se in passato hai installato l'ESP32 in un altro modo (per esempio a mano da GitHub) o hai caricato una versione vecchia anni fa, la nuova installazione può scontrarsi con i vecchi file. Segnali tipici: l'installazione finisce senza errori ma l'ESP32 compare due volte nell'elenco delle schede, in compilazione escono avvisi "multiple libraries were found" oppure l'IDE continua a usare una versione vecchia. Con questi passaggi riparti da zero.

  1. Chiudi completamente Arduino IDE.
  2. Cancella la cartella packages/esp32 e il file package_esp32_index.json dentro Arduino15.
  3. Cancella i file ESP32 parziali in staging/packages (quelli che iniziano con esp32-, xtensa-, riscv32- ed esptool).
  4. Se nella cartella degli sketch (di solito Documenti/Arduino) c'è una cartella hardware/espressif, rimuovi anche quella; deriva da una vecchia installazione manuale e va in conflitto con quella del Gestore schede.
  5. Apri l'IDE, controlla che nelle Preferenze resti solo l'URL ESP32 attuale e reinstalla il pacchetto.
Nella maggior parte dei casi basta fare clic una volta su Rimuovi sul pacchetto esp32 nel Gestore schede e reinstallarlo; cancella le cartelle a mano solo se questo non funziona. Se vuoi prima un backup, basta copiare la cartella packages dentro Arduino15.

Installazione offline e manuale

In un laboratorio scolastico con Internet limitato o con una connessione molto lenta, la strada più affidabile è installare il pacchetto su un computer ben connesso e poi trasferirlo. Funziona senza problemi tra due computer con lo stesso sistema operativo, perché i compilatori sono specifici per ogni sistema: un pacchetto installato su Windows non funziona su macOS.

  1. Sul computer ben connesso installa Arduino IDE e il pacchetto ESP32 nel modo normale.
  2. Copia su una chiavetta USB la cartella packages/esp32 e il file package_esp32_index.json dalla cartella Arduino15 di quel computer.
  3. Sul computer di destinazione apri e chiudi una volta Arduino IDE, così viene creata la cartella Arduino15.
  4. Incolla ciò che hai copiato negli stessi punti della cartella Arduino15 di destinazione e aggiungi lo stesso URL ESP32 nelle Preferenze.
  5. Apri l'IDE: il Gestore schede mostrerà esp32 come installato e in Strumenti > Scheda compariranno le schede ESP32.

Una seconda strada è scaricare con il browser i file che l'IDE fatica a scaricare e metterli nella cartella staging/packages. Prima di installare, l'IDE controlla questa cartella; se nome e checksum del file coincidono esattamente con l'indice dei pacchetti (package_esp32_index.json), salta il download ed estrae direttamente il file. La riga "Downloading" del pannello Output ti dice quale file serve. Per gli sviluppatori c'è una terza via: clonare il repository GitHub in hardware/espressif nella cartella degli sketch, ma questo metodo non va usato insieme a un'installazione dal Gestore schede.

Installazione dettagliata con Arduino CLI

L'IDE mostra solo un breve messaggio di errore. Se vuoi vedere esattamente su quale file e in quale passaggio si blocca, puoi fare lo stesso dalla riga di comando con Arduino CLI. Poiché l'IDE 2.x usa già questo strumento dietro le quinte, un pacchetto installato con la CLI compare anche nell'IDE, purché entrambi usino la stessa cartella dati.

ComandoCosa fa
arduino-cli config initCrea il file di configurazione
arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.jsonAggiunge l'URL del pacchetto ESP32
arduino-cli core update-indexScarica gli indici dei pacchetti
arduino-cli core install esp32:esp32 -vInstalla il pacchetto ESP32 con output dettagliato
arduino-cli core install esp32:[email protected]Installa una versione specifica
arduino-cli core listElenca i core installati e le loro versioni

Scegliere la versione giusta del core

Il Gestore schede propone sempre la versione più recente, ma non è detto che sia quella giusta per ogni progetto. Con la versione 3.0 arduino-esp32 è passato alla base ESP-IDF 5 e alcune funzioni sono cambiate: per il PWM ora si usa ledcAttach al posto di ledcSetup e ledcAttachPin, per i timer timerBegin(frequenza) al posto di timerBegin(0, 80, true). Per questo una vecchia libreria o un tutorial scritto per la 2.x può non compilare con la 3.x. Nel Gestore schede puoi scegliere qualsiasi versione dall'elenco sotto il pacchetto; è installata una sola versione alla volta.

VersioneBase ESP-IDFChip supportatiQuando sceglierla?
1.0.63.3Solo ESP32Solo per ricompilare così com'è un progetto molto vecchio
2.0.174.4ESP32, S2, S3, C3Librerie non ancora aggiornate alla 3.x e vecchi tutorial
3.x (attuale)5.xESP32, S2, S3, C3, C6, H2 e più recentiLa scelta predefinita per nuovi progetti e nuovi chip

Se vuoi che il tuo codice compili con entrambe le versioni, usa la macro di versione. L'esempio qui sotto accende gradualmente il LED integrato; se ESP_ARDUINO_VERSION_MAJOR vale 3 o più compila le nuove funzioni PWM, altrimenti quelle vecchie. Puoi usare lo stesso trucco nel codice dei timer e dei pin touch.

C++ (Arduino IDE)
1// Hem 2.x hem 3.x çekirdekte derlenen PWM örneği / PWM example that builds on both 2.x and 3.x cores
2const int LED_PIN  = 2;
3const int PWM_FREQ = 5000;     // 5 kHz
4const int PWM_RES  = 8;        // 8 bit: 0-255
5
6void setup() {
7#if ESP_ARDUINO_VERSION_MAJOR >= 3
8  ledcAttach(LED_PIN, PWM_FREQ, PWM_RES);   // 3.x: pin tabanlı API / pin-based API
9#else
10  ledcSetup(0, PWM_FREQ, PWM_RES);          // 2.x: önce kanal kurulur / set up the channel first
11  ledcAttachPin(LED_PIN, 0);
12#endif
13}
14
15void loop() {
16  for (int duty = 0; duty <= 255; duty++) {
17#if ESP_ARDUINO_VERSION_MAJOR >= 3
18    ledcWrite(LED_PIN, duty);               // 3.x: pin numarası / pin number
19#else
20    ledcWrite(0, duty);                     // 2.x: kanal numarası / channel number
21#endif
22    delay(5);
23  }
24}

Verificare l'installazione

Non dare per scontato che tutto funzioni solo perché l'installazione è terminata. Carica lo sketch qui sotto e apri il Monitor seriale a 115200 baud: vedrai la versione del core installato, quella di ESP-IDF, il modello del chip e la dimensione della flash, e il LED integrato lampeggerà. Se ottieni errori in compilazione, il problema è ancora l'installazione; se il caricamento finisce con "Failed to connect", il problema ormai è la scheda, il cavo o il driver.

C++ (Arduino IDE)
1// ESP32 kart paketi kurulum testi / ESP32 board package install test
2// Seri Monitör: 115200 baud / Serial Monitor: 115200 baud
3
4const int LED_PIN = 2;      // çoğu DevKit'te dahili LED / onboard LED on most DevKits
5
6void setup() {
7  Serial.begin(115200);
8  delay(1000);
9  Serial.printf("Arduino-ESP32 core: %d.%d.%d\n",
10                ESP_ARDUINO_VERSION_MAJOR, ESP_ARDUINO_VERSION_MINOR, ESP_ARDUINO_VERSION_PATCH);
11  Serial.printf("ESP-IDF: %s\n", ESP.getSdkVersion());
12  Serial.printf("Yonga / Chip: %s rev %d, %d cekirdek / cores\n",
13                ESP.getChipModel(), ESP.getChipRevision(), ESP.getChipCores());
14  Serial.printf("Flash: %u MB, CPU: %u MHz\n",
15                (unsigned)(ESP.getFlashChipSize() / (1024 * 1024)), (unsigned)ESP.getCpuFreqMHz());
16  pinMode(LED_PIN, OUTPUT);
17}
18
19void loop() {
20  digitalWrite(LED_PIN, !digitalRead(LED_PIN));   // LED yanıp söner / LED blinks
21  delay(500);
22}
Se l'ESP32 non compare proprio nell'elenco delle porte, a mancare non è il pacchetto schede ma il driver USB; leggi la guida all'installazione del driver CH340. Se il codice compila ma il caricamento finisce con "Failed to connect", il metodo del pulsante BOOT della guida ESP32 Failed to connect risolve il problema.

Ancora non si installa? Ultima lista di controllo

  • Data e ora sono corrette? Un orologio sbagliato invalida i certificati delle connessioni sicure e tutti i download falliscono.
  • Il tuo nome utente contiene accenti o spazi? Alcuni strumenti falliscono con percorsi che contengono lettere come à, è o ù; con l'impostazione directories.data di arduino-cli.yaml puoi spostare la cartella dei pacchetti in un percorso breve come C:\Arduino15.
  • Limite dei percorsi lunghi su Windows: i percorsi oltre 260 caratteri possono impedire l'estrazione del pacchetto; attivare il supporto ai percorsi lunghi in Windows o usare percorsi brevi aiuta.
  • Spazio su disco: durante l'installazione archivi scaricati e file estratti convivono per un po', quindi lascia almeno 5 GB liberi.
  • Prova un altro strumento: se l'IDE non ci riesce, prova Arduino CLI e poi PlatformIO, che scarica i pacchetti dai propri server.
  • Nel frattempo prova il codice: finché l'installazione non è risolta puoi far girare circuito e codice nel browser con il simulatore Wokwi.

Una volta installato correttamente il pacchetto schede ESP32, passare ai progetti con Wi-Fi, Bluetooth e sensori richiede pochi minuti. Se l'ESP32 è una novità per te, comincia da Cos'è l'ESP32?; poi, nell'app BlueGrays, puoi provare passo passo i progetti accendere un LED con ESP32, LED integrato e connessione Wi-Fi, con schema di collegamento e codice pronto.

Domande frequenti

Perché il pacchetto ESP32 non si installa?

Le cause più comuni sono un URL del gestore schede sbagliato o vecchio, una connessione lenta che va in timeout, un antivirus che blocca i file e vecchi download incompleti. Controlla prima che l'URL sia https://espressif.github.io/arduino-esp32/package_esp32_index.json, poi applica la soluzione corrispondente al messaggio nel pannello Output.

Qual è l'URL corretto del gestore schede per ESP32?

Per la versione stabile attuale si usa https://espressif.github.io/arduino-esp32/package_esp32_index.json. Il vecchio indirizzo di dl.espressif.com mostra solo versioni molto vecchie; se è ancora nel tuo elenco toglilo, perché due URL ESP32 insieme possono creare problemi.

Come risolvo "Error downloading" in Arduino IDE?

Prova prima ad aprire l'URL del pacchetto nel browser; se non si apre, il problema è nella rete, nel proxy o nel firewall. Se si apre, cancella i file parziali nella cartella staging, controlla l'orologio del computer e riavvia l'installazione con un cavo di rete o con l'hotspot del telefono.

Meglio installare il core ESP32 2.x o 3.x?

Per i nuovi progetti e i chip recenti come l'ESP32-C6 scegli la 3.x. Se una libreria o un tutorial che ti serve è stato scritto per la 2.x e non compila con la 3.x, installa la 2.0.17, l'ultima versione 2.x. Puoi cambiare versione quando vuoi dall'elenco del Gestore schede.

Si può installare il pacchetto ESP32 senza Internet?

Sì. Installa il pacchetto su un computer connesso con lo stesso sistema operativo e copia la cartella packages/esp32 e il file package_esp32_index.json dalla sua cartella Arduino15 nello stesso punto del computer di destinazione. All'apertura dell'IDE il pacchetto risulta installato.

Quanto spazio occupa il pacchetto ESP32?

Dipende dalla versione; le 3.x attuali occupano diversi gigabyte con toolchain e librerie. Durante l'installazione archivi e file estratti convivono, quindi lasciare almeno 5 GB liberi è un margine sicuro.

Vedi tutti i progetti
Lampeggio del LED interno dell'ESP32
ES-4Principiante

Lampeggio del LED interno dell'ESP32

Far lampeggiare il LED blu integrato nell'ESP32 DevKit V1. Non sono necessari componenti esterni! Il primo progetto da provare quando si acquista un ESP32. Il GPIO 2 è collegato al LED interno.

4.8(29)
54
LED Lampeggiante con ESP32
ES-1Principiante

LED Lampeggiante con ESP32

Insegna l'uso di base delle uscite GPIO con l'ESP32. Otteniamo un effetto lampeggiante accendendo e spegnendo un LED dal pin digitale. Versione ESP32 del classico progetto blink su Arduino UNO; i comandi di base di blink nell'ambiente Arduino sono gli stessi, ma la disposizione dei pin e i livelli GPIO a 3,3 V dell'ESP32 sono diversi da quelli di Arduino UNO.

4.7(37)
108
Controllo LED ESP32 con pulsante (Push)
ES-2Principiante

Controllo LED ESP32 con pulsante (Push)

Il LED si accende quando il pulsante viene premuto e si spegne quando viene rilasciato. Mostra come vengono utilizzati il pin di ingresso digitale dell'ESP32 e la resistenza di pull-up interna. Grazie alla modalità INPUT_PULLUP, non è necessaria alcuna resistenza esterna.

4.6(36)
57
Semaforo ESP32
ES-5Principiante

Semaforo ESP32

Simulazione di un vero semaforo con 3 LED rosso-giallo-verde. I tempi si avvicinano alla logica del traffico reale: rosso lungo, giallo corto, verde lungo. Classico esempio di controllo GPIO sequenziale.

4.4(22)
45
Lettura dell'intensità luminosa con il modulo LDR ESP32
ES-11Principiante

Lettura dell'intensità luminosa con il modulo LDR ESP32

Monitoraggio in tempo reale sul Serial Monitor del valore grezzo dell'ADC del modulo LDR e della percentuale relativa di luce calcolata dai valori di riferimento al buio e alla luce. Questa percentuale non è una misurazione in lux. Spiega il principio di calibrazione del modulo. È consigliabile eseguirlo prima del Progetto 10, poiché serve a determinare il valore di soglia.

4.6(36)
55
Dissolvenza LED ESP32 con PWM
ES-8Principiante

Dissolvenza LED ESP32 con PWM

Modificare la luminosità del LED in modo fluido da 0 a max, da max a 0. Controlliamo il PWM con analogWrite() come in Arduino - la stessa sintassi con ESP32 Arduino Core 3.0+ funziona senza problemi. La definizione del pin + pinMode + analogWrite è sufficiente.

4.8(36)
55
Connessione Wi-Fi STA con ESP32 (con display LCD)
ES-25Avanzato

Connessione Wi-Fi STA con ESP32 (con display LCD)

In questo progetto colleghiamo l'ESP32 alla rete Wi-Fi domestica in modalità Station (STA) in modo sicuro e tollerante agli errori. Separiamo SSID e password in un file secrets.h per impedire fughe su Git, impostiamo un meccanismo di riconnessione automatica e visualizziamo il livello del segnale RSSI e l'indirizzo IP su un display LCD I2C. Il LED interno funge da indicatore di stato.

4.4(21)
38
Server web asincrono ESP32 (con indicazione dell'IP sul display LCD)
ES-27Avanzato

Server web asincrono ESP32 (con indicazione dell'IP sul display LCD)

In questo progetto trasformiamo l'ESP32 in un server web asincrono che potrete controllare dal vostro telefono o computer collegato alla stessa rete Wi-Fi. Grazie alla libreria ESPAsyncWebServer, il server è in grado di elaborare più richieste contemporaneamente (a differenza del classico WebServer.h, che si blocca su una singola richiesta).

4.8(16)
26