ESP Web Tools: flashare un ESP32 dal browser

Flashare un ESP32 dal browser con ESP Web Tools o esptool-js: come funzionano Web Serial, manifest e offset, con un manifest reale di OpenGizmo.

Pubblicato
Tempo di lettura
10 min
Categoria
Guide
Un uomo con la barba e una felpa blu siede accanto a un portatile il cui browser mostra un pulsante Install arancione e una barra al 68%, con un cavo USB fino a una scheda ESP32.

In breve

ESP Web Tools flasha un ESP32 via Web Serial, con Chrome o Edge su una pagina HTTPS, da un manifest.json che elenca ogni parte del firmware e il suo offset. OpenGizmo fa lo stesso con esptool-js.

Sì, un ESP32 si può flashare da un browser. ESP Web Tools, o qualunque pagina costruita su esptool-js di Espressif, parla con la scheda tramite la Web Serial API: apri una pagina HTTPS in Chrome o Edge su desktop, colleghi un cavo USB dati, scegli la porta seriale e premi un pulsante.

In questa guida ti spiego come funziona ESP Web Tools (Web Serial, il manifest.json, gli offset) e poi come i tre dispositivi OpenGizmo usano la stessa idea, con un manifest reale ospitato su una CDN. Un dettaglio subito: il sito di OpenGizmo non incorpora il pulsante di ESP Web Tools. Usa direttamente esptool-js, e ti mostro perché.

I quattro passi del flash da browser: scegli la porta USB con Web Serial, identifica il chip, scegli la sua build nel manifest, scrivi le parti ai loro offset

Come funziona ESP Web Tools?

ESP Web Tools è un web component open source del progetto ESPHome (Open Home Foundation) che aggiunge a qualsiasi pagina web un pulsante per installare il firmware su ESP8266 e ESP32. Il suo sito dice che funziona combinando Web Serial, Improv Wi-Fi (opzionale) e un manifest che descrive il firmware.

Un momento, che cos'è Web Serial? È un'API del browser che permette a una pagina di leggere e scrivere su dispositivi seriali, compresi quelli USB che espongono una porta seriale virtuale, come fa una scheda di sviluppo ESP32. Il browser mostra un selettore di porta e la scegli tu, quindi una pagina non può aprire un dispositivo di nascosto.

Ecco cosa succede quando qualcuno preme il pulsante:

  1. Il browser chiede all'utente di scegliere una porta seriale.
  2. Lo strumento si collega al bootloader ROM del chip e lo riconosce. Secondo la documentazione, sceglie poi in automatico dal manifest la variante di firmware giusta.
  3. Scarica le parti di quella build e scrive ciascuna al suo offset.
  4. Se serve, aspetta Improv Serial per conoscere lo stato del dispositivo e proporre la configurazione del Wi-Fi.

Il flash vero e proprio non è stato reinventato. A novembre 2026, il pacchetto ESP Web Tools (versione 10.5.x) dipende da esptool-js, il port JavaScript di esptool di Espressif, oltre all'SDK seriale di Improv. Ecco perché i due strumenti si comportano in modo simile.

Aggiungere il pulsante alla tua pagina richiede due snippet, entrambi dalle istruzioni ufficiali: carichi lo script, poi inserisci l'elemento e lo punti al tuo manifest.

index.html
index.html
<script type="module" src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js?module"></script>

<esp-web-install-button manifest="https://example.com/firmware/manifest.json"></esp-web-install-button>
Riga 3, col. 1UTF-8HTML

Quali browser lo supportano, e perché HTTPS?

Web Serial esiste solo in contesti sicuri, quindi la pagina con il pulsante deve essere servita in HTTPS. ESP Web Tools lo indica come requisito di Web Serial. Poi il browser deve implementare l'API, ed è questo il vero limite.

BrowserWeb SerialNota
Chrome (desktop)Sì, dalla versione 89esptool-js indica Chrome ed Edge 89 o successivi
Edge (desktop)Sì, dalla versione 89Uguale a Chrome nei dati di compatibilità di MDN
Chrome su AndroidSì, dalla versione 148Le versioni da 138 a 147 vedevano solo porte seriali Bluetooth
Firefox (desktop)Sì, dalla versione 151Dati MDN. Non l'ho provato
Firefox su AndroidNoDati MDN
Safari, qualsiasi browser su iOSNoDati MDN. Anche ESP Web Tools dice: non iOS

Le versioni vengono dai dati di compatibilità dei browser di MDN a novembre 2026, e MDN stessa segna la funzione come non Baseline. Ho verificato il comportamento del flasher di OpenGizmo solo nel codice, non browser per browser. La sua card mostra "Flash non disponibile da questo browser" quando navigator.serial manca o la pagina non è un contesto sicuro.

Se usi Safari o uno smartphone, flasha una volta con uno strumento installato su un computer: vedi Arduino IDE vs PlatformIO per ESP32 oppure, per la ESP32-CAM, la guida al programmatore ESP32-CAM-MB.

Come si scrive il manifest e si scelgono gli offset?

Un manifest è un piccolo file JSON che dice al flasher quale firmware installare su quale chip. Ogni build elenca i file (le parti) da scrivere e l'offset in flash di ciascuno. Questo è il più piccolo manifest utile, nel formato della documentazione di ESP Web Tools:

manifest.json
manifest.json
{
  "name": "My Firmware",
  "version": "1.0.0",
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "parts": [
        {
          "path": "merged-firmware.bin",
          "offset": 0
        }
      ]
    }
  ]
}
Riga 15, col. 1UTF-8JSON

I percorsi delle parti sono risolti rispetto al manifest e possono anche essere URL completi su altri host. I campi che incontrerai più spesso:

ChiaveDoveCosa fa
name, versionlivello principaleCompaiono nell'interfaccia. Il nome viene confrontato con il firmware che il dispositivo comunica tramite Improv
builds[].chipFamilybuildESP8266, ESP32, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-P4, ESP32-S2 o ESP32-S3
builds[].parts[]buildIl percorso di un file e l'offset di flash intero a cui scriverlo
builds[].serialTypebuildcdc o uart: una build separata per l'USB nativa o per un bridge USB-UART
new_install_prompt_eraselivello principaletrue permette all'utente di scegliere se cancellare tutto a una nuova installazione
new_install_improv_wait_timelivello principaleSecondi di attesa per una risposta Improv dopo l'installazione (10 di default, 0 disattiva Improv)
home_assistant_domain, funding_urllivello principaleLink opzionali mostrati dopo l'installazione

Gli offset dipendono dal chip e da come hai compilato il firmware. Per un firmware diviso in quattro file, la documentazione di ESP-IDF mette il bootloader di secondo stadio a 0x1000 sull'ESP32 e a 0x0 sull'ESP32-S3. La pagina dell'S3 mette anche la tabella delle partizioni a 0x8000 di default. Nelle build PlatformIO che distribuisco, l'immagine boot_app0 sta a 0xE000 e l'app a 0x10000. Non andare a intuito: leggili dalla tua build, come fa la prossima sezione.

Serve un file firmware unico (merged)?

Per un ESP32 compilato con ESP-IDF 4 o successivo, la documentazione di ESP Web Tools dice di sì. Il motivo che danno: quando i quattro file si installano con il comando esptool, esptool corregge frequenza, dimensione e modalità della flash in base al dispositivo di destinazione, e ESP Web Tools non può farlo al volo. Quindi crei un'unica immagine con merge_bin e la elenchi a offset 0.

Unisci le quattro parti (comando dalla documentazione di ESP Web Tools)
esptool --chip esp32 merge_bin -o merged-firmware.bin --flash_mode dio --flash_freq 40m --flash_size 4MB 0x1000 bootloader.bin 0x8000 partitions.bin 0xe000 boot.bin 0x10000 your_app.bin

Anche le parti separate possono funzionare: il manifest d'esempio nel README di ESP Web Tools elenca quattro file, con un bootloader chiamato bootloader_dout_40m.bin le cui impostazioni di flash erano già state scelte in fase di build. L'unione è la strada documentata quando parti da una build normale. La documentazione aggiunge due avvertenze: usa dout quando il tipo di memoria è opi_opi o opi_qspi, e sostituisci qio o qout con dio. Il file unito ha un prezzo che vale la pena conoscere. La documentazione di esptool dice che nel formato raw gli spazi tra i file vengono riempiti con byte 0xFF, il valore della flash cancellata. Un'immagine unita copre quindi tutto l'intervallo dal bootloader all'app, compresa l'area delle impostazioni tra la tabella delle partizioni e boot_app0. Tienilo a mente per la sezione sugli aggiornamenti.

Come fa OpenGizmo a flashare dal browser senza il web component?

Ogni pagina di progetto di OpenGizmo ha una card del firmware che non è l'elemento di ESP Web Tools. È il componente app/components/projects/FlashFirmware.vue nel codice sorgente del sito, che importa ESPLoader e Transport da esptool-js (versione 0.7.1 nel package.json del sito) e legge un manifest nel formato di ESP Web Tools. Il formato è quindi lo stesso, cambia solo il front end.

Progetto open-source ESP32 + MAX7219
Gizmo Ticker

Un display per criptovalute connesso al WiFi, realizzato con ESP32, matrice LED MAX7219 e web app Nuxt 4 configurabile dal browser.

  • Ticker di criptovalute in tempo reale
  • Matrice LED MAX7219
  • Configurazione via web
Dagli un'occhiata

Ecco il manifest reale che legge la card del Gizmo Ticker, su https://cdn.opengizmo.dev/gizmo-ticker/manifest.json (scaricato il 14 novembre 2026):

manifest.json
manifest.json
{
  "name": "Gizmo Ticker",
  "version": "v1.2.0",
  "new_install_prompt_erase": false,
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "parts": [
        {
          "path": "v1.2.0/release-bootloader.bin",
          "offset": 0
        },
        {
          "path": "v1.2.0/release-partitions.bin",
          "offset": 32768
        },
        {
          "path": "v1.2.0/release-boot_app0.bin",
          "offset": 57344
        },
        {
          "path": "v1.2.0/release-firmware.bin",
          "offset": 65536
        }
      ]
    }
  ]
}
Riga 28, col. 1UTF-8JSON

Gli offset sono decimali, come richiede JSON: 32768 è 0x8000, 57344 è 0xE000, 65536 è 0x10000. Il manifest del Gizmo Reolink Switch ha le stesse quattro parti sullo stesso chip. Il manifest del Gizmo Camera ha "chipFamily": "ESP32" e il bootloader a 4096 (0x1000), come nella pagina di ESP-IDF vista sopra. Gli altri offset sono uguali.

Una chiave di questi manifest serve solo al componente ufficiale: new_install_prompt_erase: false. La card di OpenGizmo non la legge mai. ESP Web Tools tratterebbe false come il suo default, cioè cancellare tutti i dati a una nuova installazione.

Quando premi Flash firmware, la card fa questo, in quest'ordine:

  1. Chiama navigator.serial.requestPort() e si collega con esptool-js a 115200 baud, il che identifica il chip.
  2. Scarica il manifest con cache: 'no-store', così una nuova release compare subito.
  3. Cerca la build il cui chipFamily coincide con il nome del chip rilevato. Se non c'è, si ferma con "Questo firmware non è compilato per il chip collegato", così un'immagine per ESP32 non finisce mai su un ESP32-S3.
  4. Scarica le quattro parti una alla volta, risolvendo ogni percorso rispetto all'URL del manifest.
  5. Chiama writeFlash con flashMode, flashFreq e flashSize impostati su 'keep', eraseAll: false e compress: true.
  6. Resetta la scheda.

Perché non usare il web component? Posso indicare tre cose nel codice, e non ho provato il pulsante ufficiale con questi manifest, quindi non so dirti come si comporterebbe:

  • Le quattro parti restano separate. Con 'keep', esptool-js lascia l'header del bootloader come l'ha prodotto la build, quindi non serve nessun passaggio di unione. E le parti saltano l'area delle impostazioni, che un file unito sovrascriverebbe.
  • Una correzione del reset. Un commento in app/utils/hardReset.js del sito dice che esptool-js rilascia solo RTS, il che non fa nulla quando la linea è già rilasciata, come succede con l'USB nativa del chip sull'ESP32-S3. La scheda restava nel bootloader finché non la scollegavi. Il sito passa un reset suo: DTR rilasciato, RTS tenuto per 100 ms, poi rilasciato.
  • Una card su misura. Mostra la versione prima del flash, quattro fasi (connessione, download, flash, riavvio), un log, le note di rilascio della versione che installa e messaggi tradotti.

Il firmware non supporta Improv: non ho trovato codice Improv nei tre repository. La prima configurazione del Wi-Fi passa invece da un captive portal. Il confronto sul provisioning Wi-Fi mette Improv a confronto con le alternative, e la guida per sistemare il captive portal tratta il portale.

Le quattro parti flashate del Gizmo Ticker e i loro offset, con l'area delle impostazioni a 0x9000 lasciata intatta

Qual è la via più breve per avere la tua pagina di installazione?

Ecco tutto il lavoro in ordine, per il tuo firmware:

  1. Compila il firmware e raccogli le sue parti con i loro offset (oppure un unico file unito a offset 0 per ESP Web Tools).
  2. Carica le parti e un manifest.json che le elenca su un host HTTPS, con gli header CORS se non è il sito stesso della pagina.
  3. Aggiungi lo snippet <script> e <esp-web-install-button> visto sopra a una pagina HTTPS, con l'URL del manifest.
  4. Apri la pagina in Chrome o Edge su desktop, collega la scheda con un cavo dati, premi il pulsante e scegli la porta.
  5. Controlla che la scheda avvii il tuo firmware e che la pagina proponga la build giusta per ogni chip che elenchi.

Dove ospitare il firmware, e che dire del CORS?

Puoi ospitare il manifest e le parti sullo stesso sito della pagina di installazione, e allora non serve nessuna configurazione CORS. OpenGizmo li tiene su una CDN (cdn.opengizmo.dev, appoggiata a un bucket Cloudflare R2 nel workflow di rilascio), quindi il browser fa richieste cross-origin. In quel caso ESP Web Tools ti dice di inviare Access-Control-Allow-Origin: https://domain-of-your-website.com.

L'ho verificato il 14 novembre 2026 richiedendo il manifest del Ticker con Origin: https://opengizmo.dev: la risposta conteneva access-control-allow-origin: https://opengizmo.dev e vary: Origin, e una richiesta preflight ha restituito 204 con access-control-allow-methods: GET. La CDN accetta solo l'origine del sito, non *. Prova il tuo con curl -I -H "Origin: https://your.site" <manifest-url>.

Come rilasci una nuova versione senza perdere le impostazioni Wi-Fi?

Tieni i file di ogni versione nella loro cartella, non modificarli mai, e sposta il manifest per ultimo. Il workflow di rilascio di OpenGizmo fa così, con un'esecuzione manuale da main:

Un browser mostra la memoria flash scritta in quattro parti arancioni, mentre una parte grigia resta bloccata e intatta, con una XIAO collegata in USB-C

  1. Legge VERSION e si ferma se il tag esiste già o se la versione della web app è diversa.
  2. Esegue i test della web app e i test nativi del firmware, poi compila il firmware.
  3. Esegue package_firmware.py, che chiede a PlatformIO le immagini di flash e i loro offset (pio project metadata) e scrive manifest.json.
  4. Crea una release su GitHub con le parti, le cui note riportano un comando esptool per flashare via USB.
  5. Carica le parti con Cache-Control: public, max-age=31536000, immutable, poi il manifest con max-age=60.

Caricare il manifest per ultimo significa che il sito propone solo una versione caricata per intero, e una cache di un minuto fa comparire una release entro un minuto. Gli header che ho visto il 14 novembre 2026 corrispondono.

Le impostazioni sopravvivono grazie a ciò che non viene scritto. I progetti usano la tabella delle partizioni huge_app.csv, in cui il core Arduino definisce nvs a 0x9000 (0x5000 byte) e otadata a 0xE000. Le quattro parti non coprono la regione nvs (da 0x9000 a 0xDFFF) e eraseAll è false, quindi i dati di Preferences restano. Lo deduco dagli offset e dal codice: non ho misurato una flash prima e dopo. La guida alla tabella delle partizioni spiega il layout, e il confronto sugli aggiornamenti OTA spiega perché questi dispositivi si aggiornano via USB, dato che non hanno un secondo slot per l'app.

Con il componente ufficiale, leggi bene la regola di cancellazione: ESP Web Tools cancella tutti i dati a una nuova installazione, a meno che new_install_prompt_erase sia true e l'utente rifiuti. Propone una nuova installazione quando non riesce a rilevare il firmware attuale del dispositivo, o quando il firmware rilevato non corrisponde al name del manifest.

Cosa si rompe più spesso?

La maggior parte dei guasti dipende da cavo, porta o browser, non dal firmware. Scorri questa tabella dall'alto, cambiando una cosa alla volta.

Cosa vediCausa probabileCosa provare
Pulsante disabilitato, o 'Flash non disponibile da questo browser'Browser senza Web Serial, o la pagina non è in HTTPSUsa Chrome o Edge su desktop, in HTTPS o su localhost
Il selettore di porta non mostra nessun dispositivoCavo USB solo ricarica, o scheda non rilevataUsa un cavo dati e un'altra porta USB, poi ricarica la pagina
La connessione fallisce, nessun dato seriale ricevutoIl chip non è in modalità download, o il collegamento USB è instabileVedi la guida a 'Failed to connect'
'Questo firmware non è compilato per il chip collegato'Il manifest non ha una build per quella famiglia di chipAggiungi una build per quel chip, o usa la scheda giusta
'Download del firmware fallito con stato 404'Il percorso di una parte nel manifest è sbagliatoApri l'URL di ogni parte in una scheda del browser
Il manifest non si legge, con un errore CORS nella consoleLa CDN non consente l'origine della tua paginaInvia Access-Control-Allow-Origin per il tuo dominio
Il flash finisce ma la scheda resta nel bootloaderNessun vero impulso di reset dopo il flashScollega e ricollega; un hard reset personalizzato come quello visto sopra risolve

Per la terza riga, Failed to Connect to ESP32: No Serial Data Received passa in rassegna boot mode, cavi e driver. I testi d'errore nella tabella sono quelli del file delle traduzioni della card di OpenGizmo, e la tua pagina dirà altro.

Dove si ferma il flash dal browser?

Il flash dal browser ti dà una pagina in cui chiunque abbia Chrome o Edge, un cavo e una scheda può installare il tuo firmware in un minuto, con le impostazioni conservate e un numero di versione a schermo. Abbiamo visto i pezzi: Web Serial su HTTPS, un manifest di parti e offset (unito per ESP Web Tools, oppure quattro parti con esptool-js), il CORS se i file stanno altrove, e una release che carica il manifest per ultimo.

Restano tre limiti. Copre solo il flash via cavo; per gli aggiornamenti via Wi-Fi vedi il confronto tra i metodi OTA. Il supporto dei browser fuori da Chrome ed Edge è scarso a novembre 2026, e non ne ho provato nessuno. E il componente ufficiale l'ho descritto solo dalla sua documentazione e dal suo codice, non per averlo usato io. Se vuoi vedere il tutto in funzione, la guida alla costruzione del Gizmo Ticker flasha una scheda dall'inizio alla fine, e le tre pagine dei progetti hanno ciascuna la card.

Domande frequenti

Trova risposte rapide alle domande più comuni su questo argomento.

Sì. Una pagina che usa ESP Web Tools o esptool-js parla con la scheda tramite la Web Serial API, quindi bastano un cavo USB dati e Chrome o Edge su desktop. La pagina deve essere servita in HTTPS. Scegli la porta seriale e il firmware viene scritto direttamente dal browser.

Pubblicato

Pronto a costruire il tuo gizmo?

Scegli un progetto ESP32 open source e segui la sua guida passo passo, dalla lista dei componenti e dai collegamenti fino al firmware e al primo avvio.

Leggi anche

Esplora le categorie