Blog
esptool: comandi, flag e soluzioni
esptool, lo strumento che ogni possessore di ESP32 finisce a usare a mano quando il flashing fallisce — l’Arduino IDE lo nasconde, PlatformIO lo nasconde, e poi un giorno stai scrivendo Python in un terminale. Comandi, flag e gli errori che sembrano senza senso finché non li vedi una volta.
Cos’è esptool?
esptool è lo strumento da riga di comando ufficiale di Espressif per parlare con i chip ESP32 via seriale — flashare, cancellare, leggere la memoria, estrarre l’identità. Ogni percorso di flashing passa da lì: l’Arduino IDE lo impacchetta, PlatformIO lo impacchetta, gli installer web lo eseguono. Conoscerlo è l’ora di debug che non ripeti mai.
Come verifico che esptool sia installato?
Esegui esptool.py version. Un numero di versione (5.x, 4.7, quello che è attuale) significa che sei a posto. “Command not found” significa pip install esptool — Python 3.7+ è l’unico requisito.
Quali sono i comandi esptool più utili?
I comandi esptool di base sono cinque: chip_id identifica il chip, flash_id legge la flash, read_mac stampa il MAC di fabbrica, erase_flash cancella tutto e write_flash scrive un binario a un indirizzo — il 90% dell’uso quotidiano. merge_bin combina più binari in un’unica immagine da passare a qualcun altro.
Come flasho il firmware con esptool?
Una riga basta: esptool.py write_flash 0x0 firmware.bin, con --port COM3 aggiunto sulla maggior parte delle macchine. L’offset conta più di quanto la gente pensi: 0x0 è dove parte un’immagine di fabbrica, mentre le app ESP-IDF vanno a 0x10000. Flasha all’offset sbagliato e la scheda avvia nel nulla, ed è così che molte schede “brickate” si rivelano solo flashate male. La FAQ sul flashing copre gli offset e i layout delle partizioni.
Come cancello la flash dell’ESP32?
esptool.py erase_flash spazza via l’intero chip in secondi. L’avvertimento che tutti saltano: rimuove anche il bootloader, quindi una scheda che girava col firmware di serie non si avvierà finché non flashi qualcosa. La cancellazione risolve una partition table corrotta e i boot loop — trattala come un reset, non una riparazione.
Posso fare il backup della flash prima di toccarla?
esptool.py read_flash 0x0 0x400000 backup.bin scarica i primi 4MB su file — la mossa standard prima di un upgrade; il ripristino è write_flash allo stesso offset. Una avvertenza: un backup semplice non si ripristina su una scheda con la crittografia della flash attiva — l’ho imparato a mie spese la primavera scorsa.
Cosa fanno –port, –baud e gli altri flag?
--port sceglie la porta seriale (COM3 su Windows, /dev/ttyUSB0 su Linux, /dev/cu.usbserial-XXXX su macOS); --baud imposta la velocità — 460800 è una scelta veloce e sicura, e alcuni chip USB balbettano oltre 921600, quindi dipende dal chip ponte della tua scheda; --chip forza il target se l’auto-rilevamento fallisce. Il resto puoi ignorarlo finché un errore non ne nomina uno.
Perché ottengo “Failed to Connect to ESP32: Timed Out Waiting for Packet Header”?
Il chip non è in modalità boot. esptool ha bisogno del bootloader della ROM in ascolto, e le cause classiche sono: un circuito di auto-reset non cablato (moduli nudi), la porta sbagliata, o qualcos’altro che tiene la linea seriale — una volta ho inseguito questo errore per un’ora perché il Monitor Seriale era ancora aperto. Tieni premuto BOOT, tocca EN, rilascia BOOT, riprova. Sui moduli nudi, collega GPIO0 a massa all’accensione. La FAQ sul debug ha di più.
Perché il flashing si blocca al 100%?
I dati sono scritti e la scheda si resetta nel nuovo firmware, restando in silenzio — normale quando il firmware non ha output seriale. Un boot loop invece significa che l’immagine punta alla dimensione flash o al chip sbagliati. Conferma con esptool.py chip_id, controlla flash_id, ri-flasha.
esptool funziona uguale su Windows, Linux e Mac?
Sì — stessi comandi, flag e offset, perché è uno script Python su ogni piattaforma. Cambiano solo i nomi delle porte e i driver; la nostra KB ha le note sui driver per ogni OS.
I progetti di questo argomento girano direttamente nel simulatore gratuito di sensbench: circuito pre-cablato, firmware incluso, senza account né installazione.