Corso ESP-IDF, puntata 2: installare l’ambiente

In questa puntata

Obiettivi

• Installare ESP-IDF v6.1 su Windows, Linux o macOS con il metodo che la documentazione raccomanda: l’ESP-IDF Installation Manager (EIM).
• Attivare l’ambiente nel terminale e sapere a cosa servono l’estensione per VS Code ed Espressif-IDE.
• Usare idf.py per l’intero ciclo: create-project, set-target, menuconfig, build, flash, monitor, size, fullclean.
• Capire che cosa produce la build e dove finisce ogni file nella flash.
• Riconoscere le porte seriali della ESP32-C6-DevKitC-1, compresa la USB Serial/JTAG integrata, e risolvere gli errori più comuni.

Prerequisiti: Puntata 1 “ESP-IDF in una mappa” (pubblicazione in arrivo); un PC con Windows, Linux o macOS; una ESP32-C6-DevKitC-1 e un cavo USB-C che porti anche i dati, non solo l’alimentazione.

Che cosa installiamo davvero

La documentazione v6.1 elenca tre ingredienti:

• la toolchain, cioè compilatore, linker e debugger per il chip (per il C6, che è RISC-V, gli strumenti riscv32-esp-elf);
• gli strumenti di build: CMake, che descrive il progetto, e Ninja, che esegue la compilazione;
• ESP-IDF vero e proprio: librerie, driver, sorgenti e gli script Python che tengono insieme il resto.

Python fa da collante: idf.py, esptool e il monitor sono scritti in Python. Dalla 6.0 servono almeno Python 3.10 e CMake 3.22.1.

Il metodo raccomandato: ESP-IDF Installation Manager

Per la v6.1 la guida “Get Started” indica un solo strumento per installare ESP-IDF, la toolchain e gli strumenti di build: l’ESP-IDF Installation Manager, in breve EIM. Esiste in due forme:

• GUI (interfaccia grafica): la scelta consigliata per la maggior parte delle persone;
• CLI (riga di comando): comoda per l’integrazione continua (CI/CD) e le installazioni automatiche.

Entrambe si scaricano dalla pagina di download dell’EIM in versione online (scarica ciò che serve durante l’installazione) oppure offline (pacchetto completo, per PC senza Internet).

Installare l’EIM

Installare ESP-IDF con l’EIM

Dalla GUI: New Installation → Start Installation, poi Easy Installation → Start Easy Installation; superati i controlli compare Ready to Install e l’EIM installa l’ultima versione stabile con le impostazioni predefinite. Per scegliere la versione o la cartella c’è invece Custom Installation.

Dalla CLI i comandi documentati sono tre:

eim install              # ultima versione stabile, impostazioni predefinite
eim wizard               # procedura guidata interattiva
eim install -i v6.1      # una versione precisa (la guida usa come esempio v5.4.2)

Attivare l’ambiente

Prima di usare idf.py bisogna attivare l’ambiente nel terminale: percorsi della toolchain, ambiente virtuale Python, variabile IDF_PATH. Le strade documentate sono queste:

• dalla GUI dell’EIM: Manage Installations → Open Dashboard, scegli la versione e premi Open IDF Terminal;
• su Windows, dopo l’installazione da CLI: l’EIM mette sul desktop un collegamento che apre PowerShell con l’ambiente già pronto (la guida cita come esempio IDF_v5.4.2_Powershell);
• su Linux e macOS: alla fine l’EIM stampa il comando da eseguire, del tipo source ".../tools/activate_idf_v5.4.2.sh" (anche qui l’esempio della guida è per la 5.4.2).

Il metodo precedente, con gli script install.bat, install.ps1 o install.sh e poi export nella cartella di ESP-IDF, è ancora documentato come legacy e funziona. Per un’installazione nuova, però, la strada è l’EIM.

Gli IDE: VS Code ed Espressif-IDE

Le versioni installate con l’EIM si possono usare in due ambienti grafici:

• Visual Studio Code con l’ESP-IDF Extension for VS Code, che permette di sviluppare, compilare, scrivere la flash e monitorare la scheda senza uscire dall’editor;
• Espressif-IDE, basato su Eclipse CDT, con i plugin IDF già inclusi.

Ciascuno ha la sua documentazione, linkata in fondo. Nel corso useremo la riga di comando: è uguale su tutti i sistemi e non cambia quando cambiano i menu.

idf.py: un comando per tutto il ciclo

idf.py guida CMake, Ninja, esptool e il monitor. Va lanciato dentro la cartella del progetto, cioè quella con il CMakeLists.txt principale, oppure indicandola con -C cartella.

Una sessione tipica, dal nulla alla scheda che parla:

idf.py create-project primo_progetto
cd primo_progetto
idf.py set-target esp32c6
idf.py menuconfig                 # facoltativo: per hello world vanno bene i default
idf.py -p COM5 flash monitor      # COM5 è un esempio: usa la tua porta

Più comandi nella stessa riga vengono eseguiti nell’ordine giusto: flash monitor compila, scrive e apre il monitor. Se la porta è sempre la stessa, puoi metterla nella variabile d’ambiente ESPPORT e omettere -p; se non indichi nessuna porta, idf.py prova da solo quelle USB disponibili.

Il target, prima di tutto

Il target conta più di quanto sembri. Se non lo fissi in nessun modo (né con set-target, né con la variabile IDF_TARGET, né con CONFIG_IDF_TARGET in sdkconfig.defaults), il sistema di build compila per il chip ESP32 originale. Il programma compila senza errori, poi al momento di scriverlo sul C6 esptool si ferma con un messaggio del tipo “This chip is ESP32-C6, not ESP32. Wrong chip argument?”. Per questo, in ogni progetto nuovo, il primo comando è idf.py set-target esp32c6. Nel corso il target non è scritto nei progetti degli esercizi: lo fissi tu, una volta, con quel comando.

sdkconfig e sdkconfig.defaults

Tutte le opzioni di configurazione (Kconfig) finiscono nel file sdkconfig, che menuconfig modifica. Il file sdkconfig.defaults, se c’è, contiene solo le opzioni che vuoi diverse dai valori di ESP-IDF. Attenzione al dettaglio: sdkconfig.defaults viene usato quando sdkconfig si crea da zero, oppure per le opzioni che sdkconfig non contiene ancora. Se cambi un valore in sdkconfig.defaults dopo la prima build, devi cancellare sdkconfig (o rifare set-target) perché abbia effetto. Lo vedrai nell’esercizio 02.2. Anatomia completa del progetto nella Puntata 3 (pubblicazione in arrivo).

Flash veloce

Dalla 6.1 idf.py flash salva nella cartella build una copia di ciò che ha scritto (file *_flashed.bin); la volta dopo riscrive solo i settori cambiati e verifica la flash, e se la verifica fallisce rifà tutto. Per forzare una scrittura completa c’è idf.py flash -a (o --all): la guida la consiglia per schede nuove o appena cancellate con idf.py -p PORTA erase-flash.

Che cosa produce la build

Una build riuscita termina con “Project build complete” e lascia nella cartella build diversi file. Quelli da conoscere subito:

• bootloader/bootloader.bin: il bootloader di secondo stadio, compilato come un piccolo progetto a parte. Sul C6 va all’indirizzo 0x0 della flash.
• partition_table/partition-table.bin: la tabella delle partizioni, all’indirizzo predefinito 0x8000. Con la tabella predefinita “Single factory app, no OTA” contiene una partizione nvs, una phy_init e l’app factory a 0x10000.
• nome_progetto.bin: l’applicazione, a 0x10000. Il nome viene dalla riga project() del CMakeLists.txt.
• nome_progetto.elf e nome_progetto.map: il programma con tutti i simboli e la mappa del linker. Non si scrivono sulla scheda, ma servono al monitor per tradurre gli indirizzi in file e riga, e a idf.py size per i conti.
• flash_project_args, flash_app_args, flasher_args.json: dove va ciascun file. Con questi si può scrivere la scheda anche senza idf.py, per esempio con esptool ... write-flash @build/flash_project_args.

Il monitor seriale

idf.py monitor avvia IDF Monitor, un terminale seriale con qualche abilità in più. Si collega a 115 200 baud, la velocità predefinita della console del C6, e colora le righe di log secondo il livello (errore, avviso, informazione…), riconoscendolo dalla lettera iniziale. Quando il chip va in panic e stampa indirizzi di codice, il monitor li cerca nel file .elf e scrive accanto file e numero di riga. Dettagli nella Puntata 5 (pubblicazione in arrivo).

Tutti i tasti premuti vanno alla scheda, tranne due: Ctrl+] e Ctrl+T. Il primo esce; il secondo apre un piccolo menu, cioè va seguito da un altro tasto:

E Ctrl+C? Nel monitor non esce: interrompe l’applicazione e avvia GDB, il debugger, e per farlo richiede un’opzione (CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME) che per impostazione predefinita è disattivata. Quando premi Invio, il monitor manda alla scheda un CR (ritorno carrello): è il valore predefinito per i chip reali, e ci servirà nell’esercizio 02.3.

Porte seriali e USB Serial/JTAG del C6

La ESP32-C6-DevKitC-1 ha due connettori USB-C, e tutti e due servono ad alimentare la scheda e a scrivere la flash:

• “USB-to-UART”: passa da un ponte USB-seriale montato sulla scheda, collegato alla UART0 del chip;
• “ESP32-C6 USB”: va direttamente ai piedini USB del chip, GPIO13 (D+) e GPIO12 (D−), dove c’è il controller USB Serial/JTAG.

Il controller USB Serial/JTAG è un dispositivo USB a funzione fissa, realizzato interamente in hardware. Offre tre cose: una console seriale bidirezionale (la parte CDC-ACM, cioè la classe USB delle porte seriali), la scrittura della flash con esptool e idf.py flash, e il debug JTAG, anche in contemporanea con la seriale (Puntata 6, pubblicazione in arrivo). Non si riprogramma per fare altro: per dispositivi USB personalizzati servono i chip con USB OTG.

Come appare sul PC

Il sistema operativo vede la parte seriale come una porta qualsiasi:

• Windows: una porta COM in Gestione dispositivi; scollega e ricollega la scheda e guarda quale porta sparisce e ricompare.
• Linux: /dev/ttyACM* (il ponte UART appare invece come /dev/ttyUSB*). Lancia ls /dev/tty* prima e dopo aver collegato la scheda.
• macOS: /dev/cu*; anche qui ls /dev/cu.* prima e dopo.

Per la seriale di solito non serve installare nulla. Per la parte JTAG, su Windows possono servire i driver USB: la documentazione indica il pulsante Install Drivers nella dashboard dell’EIM, oppure il comando eim install-drivers. Su Linux, per il JTAG, vanno aggiunte le regole udev di OpenOCD.

Quale porta per la console

Nella v6.1 il canale della console si sceglie in Component config → ESP-STDIO → Channel for console output. Sul C6 il predefinito è la UART0, con una console secondaria sulla USB Serial/JTAG (opzione CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG). Quindi i log escono da entrambi i connettori, ma la secondaria è solo in uscita: per leggere tasti dalla USB bisogna fare della USB Serial/JTAG la console principale, con CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y. È quello che farai nell’esercizio 02.3.

Di norma il controller USB Serial/JTAG mette da solo il chip in modalità download. Se non ci riesce (alla primissima scrittura, se l’app ha riconfigurato i piedini USB o se il chip è in deep sleep, perché in quel caso il dispositivo USB sparisce dal PC) si fa a mano: tieni premuto BOOT, premi e rilascia RESET, poi rilascia BOOT. Il pulsante BOOT è collegato a GPIO9, il piedino che sceglie la modalità di avvio.

Errori comuni

I (296) main_task: Calling app_main()
Ciao da Cheap! Primo progetto ESP-IDF su esp32c6.
Contatore: 0
Contatore: 1
Contatore: 2
...

I (310) livelli: Livello di log predefinito: 4
I (310) livelli: Giro 1
D (310) livelli: Dettaglio: prossimo avviso fra 4 giri
I (1310) livelli: Giro 2
D (1310) livelli: Dettaglio: prossimo avviso fra 3 giri
...
I (4310) livelli: Giro 5
W (4310) livelli: Avviso: sono passati altri 5 giri
D (4310) livelli: Dettaglio: prossimo avviso fra 5 giri

I (305) eco: Pronto: scrivi qualcosa e premi Invio.
CIAO CHEAP
Riga (10 caratteri): CIAO CHEAP

Riepilogo

• Dalla 6.0 si installa con l’EIM, in GUI o CLI, online o offline; servono Python 3.10 o più recente e percorsi senza spazi.
• L’ambiente va attivato in ogni terminale: dalla dashboard dell’EIM, dal collegamento sul desktop o con lo script activate_idf_....
• idf.py copre l’intero ciclo; il primo comando di ogni progetto è set-target esp32c6.
• La build produce bootloader (0x0 sul C6), tabella partizioni (0x8000) e app (0x10000), più .elf e .map per monitor e analisi.
• Nella 6.1 idf.py flash riscrive solo ciò che è cambiato; -a forza la scrittura completa.
• Il monitor si chiude con Ctrl+]; Ctrl+T apre il menu delle scorciatoie.
• Il C6 ha la USB Serial/JTAG integrata: seriale, flash e JTAG con un solo cavo. Per leggere tasti da lì serve CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y.

Nella prossima puntata

Apriamo il progetto e guardiamo dentro: i due CMakeLists.txt, i componenti e il componente main, il rapporto tra sdkconfig, sdkconfig.defaults e menuconfig, e come aggiungere opzioni Kconfig nostre al menu di configurazione.

Per approfondire

• Get Started: installazione con l’EIM e primo progetto (v6.1, ESP32-C6)
• Establish Serial Connection with ESP32-C6
• IDF Frontend: idf.py
• IDF Monitor e le sue scorciatoie
• USB Serial/JTAG Controller Console
• Migration guide 6.1: strumenti (flash veloce)
• Documentazione dell’ESP-IDF Installation Manager (EIM)
• ESP-IDF Extension for VS Code
• Guida utente della ESP32-C6-DevKitC-1

Corso ESP-IDF di Web App Portal. Testi CC BY-NC-SA 4.0, codice MIT. ESP-IDF è un marchio di Espressif Systems; gli altri marchi appartengono ai rispettivi proprietari.