← Guida hardware | Indice | Avanti: Struttura dell'applicazione →

2. Requisiti di compilazione

💡 Non vuoi compilare? I binari del firmware precompilati sono disponibili nella pagina GitHub Releases . Basta scaricare, estrarre e flashare con gli script inclusi — nessuna compilazione richiesta!

2.1 Piattaforma e strumenti

Piattaforma principale

Versione ESP-IDF: 5.5.1 (obbligatoria)
Microcontroller: ESP32 (classico, non ESP32-S2/S3/C3)
Architettura: Xtensa dual-core LX6
Frequenza CPU: 240 MHz
Flash minimo: 4 MB
RAM minima: 520 KB (ESP32-WROOM-32 o ESP32-WROVER)

Framework e componenti

Arduino Core per ESP32: versione 3.x (tramite ESP-IDF Component Manager)
CMake: versione minima 3.16
Python: 3.8+ (per gli script idf.py)

2.2 Librerie richieste

Dipendenze principali (tramite IDF Component Manager)

Definite nel file main/idf_component.yml:

yaml

dependencies:
  # Arduino Core 3.x for ESP32
  espressif/arduino-esp32:
    version: "^3.0.0"

  # ArduinoJson v7 - JSON serialization
  bblanchon/arduinojson:
    version: "^7.0.0"

  # IDF built-in components
  idf:
    version: ">=5.0.0"

Componenti ESP-IDF integrati (usati automaticamente)

nvs_flash – Memoria non volatile per la configurazione
esp_wifi – Driver e protocolli WiFi
esp_http_server – Server web asincrono
esp_adc – Driver ADC con supporto DMA
driver – Driver GPIO, LEDC, Timer
freertos – Sistema operativo in tempo reale

Componenti personalizzati (locali)

Situati in components/:

Componente	Percorso	Funzione
comm	`components/comm`	WiFi, WebServer, REST API, interfaccia Material UI
hal	`components/hal`	Livello di astrazione hardware (DimmerHAL, PowerMeterADC)
utils	`components/utils`	ConfigManager, HardwareConfigManager, SerialCommand
control	`components/control`	RouterController, algoritmi di controllo
rbdimmer	`components/rbdimmer`	Libreria RBDimmer (dimmer TRIAC)

2.3 Configurazione del build (sdkconfig)

Parametri principali

ini

# Microcontroller
CONFIG_IDF_TARGET="esp32"
CONFIG_SOC_CPU_CORES_NUM=2
CONFIG_ESP32_DEFAULT_CPU_FREQ_240=y

# Flash configuration
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
CONFIG_ESPTOOLPY_FLASHMODE_DIO=y
CONFIG_ESPTOOLPY_FLASHFREQ_40M=y

# FreeRTOS
CONFIG_FREERTOS_HZ=1000                    # 1ms tick
CONFIG_FREERTOS_UNICORE=n                  # Dual-core mode

# Serial Monitor
CONFIG_ESPTOOLPY_MONITOR_BAUD=115200

Configurazioni chiave del progetto

Configurazione ADC

ini

CONFIG_SOC_ADC_SUPPORTED=y
CONFIG_SOC_ADC_DIG_CTRL_SUPPORTED=y        # Digital controller
CONFIG_SOC_ADC_DMA_SUPPORTED=y             # DMA for continuous reading
CONFIG_SOC_ADC_DIGI_MAX_BITWIDTH=12        # 12-bit resolution

Configurazione WiFi

ini

CONFIG_SOC_WIFI_SUPPORTED=y
CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM=10
CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=32
CONFIG_ESP_WIFI_AMPDU_RX_ENABLED=y

Flash e partizioni

ini

CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
CONFIG_PARTITION_TABLE_FILENAME="partitions.csv"

2.4 Tabella delle partizioni

File: partitions.csv

csv

# ESP32 Partition Table for AC Power Router Controller with OTA
# Flash Size: 4MB
#
# Name,     Type,    SubType,  Offset,   Size,     Flags
nvs,        data,    nvs,      0x9000,   0x6000,
otadata,    data,    ota,      0xf000,   0x2000,
app0,       app,     ota_0,    0x20000,  0x190000,
app1,       app,     ota_1,    0x1B0000, 0x190000,
spiffs,     data,    spiffs,   0x340000, 0xC0000,

Descrizione delle partizioni

Partizione	Tipo	Dimensione	Offset	Funzione
nvs	data (nvs)	24 KB (0x6000)	0x9000	Configurazione del dispositivo (WiFi, RouterController, HardwareConfig)
otadata	data (ota)	8 KB (0x2000)	0xf000	Metadati OTA (quale app0/app1 è attivo)
app0	app (ota_0)	1,6 MB (0x190000)	0x20000	Primo slot firmware (OTA slot 0)
app1	app (ota_1)	1,6 MB (0x190000)	0x1B0000	Secondo slot firmware (OTA slot 1)
spiffs	data (spiffs)	768 KB (0xC0000)	0x340000	File system per l'interfaccia Web (HTML/CSS/JS)

Mappa della memoria Flash (4 MB)

python

0x000000 ┌─────────────────────────┐
         │  Bootloader             │ (Automatic)
0x008000 ├─────────────────────────┤
         │  Partition Table        │ (Automatic)
0x009000 ├─────────────────────────┤
         │  NVS (24 KB)            │ ← Configuration
0x00F000 ├─────────────────────────┤
         │  OTA Data (8 KB)        │ ← OTA Metadata
0x020000 ├─────────────────────────┤
         │                         │
         │  APP 0 (1.6 MB)         │ ← Firmware slot 0
         │                         │
0x1B0000 ├─────────────────────────┤
         │                         │
         │  APP 1 (1.6 MB)         │ ← Firmware slot 1
         │                         │
0x340000 ├─────────────────────────┤
         │                         │
         │  SPIFFS (768 KB)        │ ← Web UI files
         │                         │
0x400000 └─────────────────────────┘ (4 MB)

2.5 Comandi di compilazione e flash

Configurazione dell'ambiente (Windows)

powershell

# Install ESP-IDF 5.5.1
# Download from https://dl.espressif.com/dl/esp-idf/

# Activate environment
cd %USERPROFILE%\esp\esp-idf
.\export.ps1

# Navigate to project directory
cd C:\Users\\Documents\ESP-PROJECTS\ACRouter\ACRouter-project

Configurazione dell'ambiente (Linux/macOS)

bash

# Install ESP-IDF 5.5.1
mkdir -p ~/esp
cd ~/esp
git clone -b v5.5.1 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32

# Activate environment
. $HOME/esp/esp-idf/export.sh

# Navigate to project directory
cd ~/ACRouter-project

Comandi principali di build

1. Installare le dipendenze (prima volta)

bash

idf.py set-target esp32
idf.py reconfigure

Questo installerà automaticamente:

Arduino Core 3.x (espressif/arduino-esp32)
ArduinoJson v7 (bblanchon/arduinojson)

2. Configurazione del progetto (opzionale)

bash

idf.py menuconfig

Impostazioni disponibili tramite menuconfig:

Serial flasher config → Dimensione flash (4 MB)
Serial flasher config → Frequenza flash (40 MHz)
Partition Table → Tabella partizioni personalizzata CSV
Component config → FreeRTOS → Frequenza tick (1000 Hz)

3. Compilare il progetto

bash

# Full build
idf.py build

# Quick rebuild (only changed files)
idf.py app

# Clean and full rebuild
idf.py fullclean
idf.py build

4. Flash e monitoraggio

bash

# Flash + Serial monitor
idf.py flash monitor

# Flash only
idf.py flash

# Serial monitor only
idf.py monitor

# Flash via specific port (Windows)
idf.py -p COM3 flash monitor

# Flash via specific port (Linux)
idf.py -p /dev/ttyUSB0 flash monitor

2.6 Comando di flash e indirizzi di memoria

Comando esptool.py (flash diretto)

Se è necessario flashare manualmente tramite esptool.py (ad esempio, da un altro computer):

bash

esptool.py --chip esp32 \
  --port COM3 \
  --baud 921600 \
  --before default_reset \
  --after hard_reset \
  write_flash -z \
  --flash_mode dio \
  --flash_freq 40m \
  --flash_size 4MB \
  0x1000 build/bootloader/bootloader.bin \
  0x8000 build/partition_table/partition-table.bin \
  0x20000 build/ACRouter-project.bin

Indirizzi dei file nel dump di memoria

File	Indirizzo	Dimensione	Descrizione
bootloader.bin	0x1000	~28 KB	Bootloader ESP32 (secondo stadio)
partition-table.bin	0x8000	~3 KB	Tabella delle partizioni
ACRouter-project.bin	0x20000	~1,6 MB	Firmware principale (app0)
ota_data_initial.bin	0xf000	8 KB	Dati OTA iniziali (opzionale)

Backup del flash

bash

# Read entire Flash (4 MB)
esptool.py --chip esp32 --port COM3 \
  read_flash 0x0 0x400000 backup_flash_4MB.bin

# Read firmware only (app0)
esptool.py --chip esp32 --port COM3 \
  read_flash 0x20000 0x190000 backup_app0.bin

# Read NVS only (configuration)
esptool.py --chip esp32 --port COM3 \
  read_flash 0x9000 0x6000 backup_nvs.bin

Ripristino da backup

bash

# Restore full Flash
esptool.py --chip esp32 --port COM3 --baud 921600 \
  write_flash 0x0 backup_flash_4MB.bin

# Restore NVS only (preserve configuration)
esptool.py --chip esp32 --port COM3 \
  write_flash 0x9000 backup_nvs.bin

2.7 Dimensione del firmware e utilizzo della memoria

Dimensioni tipiche dopo il build

python

Build Output:
=====================================
Bootloader:              28,512 bytes (0x6F80)
Partition Table:          3,072 bytes (0xC00)
ACRouter-project.bin:   ~1,200,000 bytes (~1.15 MB)
=====================================

Mappa di utilizzo del flash (dopo il flash)

python

Flash Usage (4 MB total):
├─ Bootloader + Partition     ~32 KB      (0.8%)
├─ NVS (configuration)         24 KB      (0.6%)
├─ OTA Data                     8 KB      (0.2%)
├─ APP 0 (firmware)          ~1.2 MB     (30%)
├─ APP 1 (OTA reserve)       ~1.2 MB     (30%)  ← Will be used during OTA update
├─ SPIFFS (Web UI)            768 KB     (19%)  ← Reserved for future
└─ Free                       ~748 KB    (18%)

Utilizzo della RAM (in esecuzione)

python

DRAM (Data RAM):
├─ Static .data + .bss       ~120 KB
├─ Heap (available)          ~180 KB
└─ FreeRTOS stacks           ~80 KB
=====================================
Total DRAM:                  ~380 KB / 520 KB

IRAM (Instruction RAM):
├─ Code (.text)              ~100 KB
├─ Cache                     ~32 KB
=====================================
Total IRAM:                  ~132 KB / 192 KB

2.8 Verifica della compilazione riuscita

Dopo aver eseguito idf.py build dovresti vedere:

python

Project build complete. To flash, run:
 idf.py flash
or
 idf.py -p (PORT) flash
or
 esptool.py --chip esp32 --port (PORT) --baud 921600 write_flash \
   --flash_mode dio --flash_size 4MB --flash_freq 40m \
   0x1000 build/bootloader/bootloader.bin \
   0x8000 build/partition_table/partition-table.bin \
   0x20000 build/ACRouter-project.bin

File di output del build (build/)

File principali nella directory build/:

ACRouter-project.bin – firmware principale
ACRouter-project.elf – file ELF con simboli (per il debug)
ACRouter-project.map – mappa di memoria (indirizzi delle funzioni)
bootloader/bootloader.bin – bootloader
partition_table/partition-table.bin – tabella delle partizioni

2.9 Problemi comuni di compilazione

Issue 1: Error "arduino-esp32 not found"

Soluzione:

bash

idf.py reconfigure
# Or manually:
cd managed_components
rm -rf espressif__arduino-esp32
idf.py reconfigure

Problema 2: Spazio flash insufficiente

Sintomo:

python

Error: app partition is too small for binary

Soluzione: Verifica partitions.csv — app0/app1 deve essere >= 0x190000 (1,6 MB)

Problema 3: Conflitto di versione ESP-IDF

Sintomo:

python

CMake Error: ESP-IDF version mismatch

Soluzione:

bash

# Check IDF version
idf.py --version

# Should be: ESP-IDF v5.5.1
# If different version - reinstall IDF 5.5.1

Issue 4: Error "NVS namespace too long"

Sintomo:

python

Error: NVS key exceeds 15 characters

Soluzione: Le chiavi NVS sono limitate a 15 caratteri. Usa abbreviazioni (vedi HardwareConfigManager.h).

Issue 5: Don't Want to Deal with Build Issues?

Soluzione: Usa i binari del firmware precompilati!

If you're experiencing persistent build problems or simply want to get started quickly:

Visita GitHub Releases
Scarica l'ultima versione del firmware
Estrai l'archivio contenente:
bootloader.bin
partition-table.bin
ACRouter-project.bin
ota_data_initial.bin
flash.bat / flash.sh (script di flash)
FLASH_README.txt (istruzioni)
Flasha con lo script incluso:
Windows: flash.bat COM5
Linux/Mac: ./flash.sh /dev/ttyUSB0

Nessuna installazione di ESP-IDF o compilazione richiesta!

← Guida hardware | Indice | Avanti: Struttura dell'applicazione →

Prodotti

In Evidenza

Inizia

Integrazioni

Guide e Articoli

ACRouter

Vetrina Progetti

Iniziare

Integrazioni

Dimmer AC

DimmerLink

ACRouter

GitHub

2. Requisiti di compilazione

2.1 Piattaforma e strumenti

Piattaforma principale

Framework e componenti

2.2 Librerie richieste

Dipendenze principali (tramite IDF Component Manager)

Componenti ESP-IDF integrati (usati automaticamente)

Componenti personalizzati (locali)

2.3 Configurazione del build (sdkconfig)

Parametri principali

Configurazioni chiave del progetto

Configurazione ADC

Configurazione WiFi

Flash e partizioni

2.4 Tabella delle partizioni

Descrizione delle partizioni

Mappa della memoria Flash (4 MB)

2.5 Comandi di compilazione e flash

Configurazione dell'ambiente (Windows)

Configurazione dell'ambiente (Linux/macOS)

Comandi principali di build

1. Installare le dipendenze (prima volta)

2. Configurazione del progetto (opzionale)

3. Compilare il progetto

4. Flash e monitoraggio

2.6 Comando di flash e indirizzi di memoria

Comando esptool.py (flash diretto)

Indirizzi dei file nel dump di memoria

Backup del flash

Ripristino da backup

2.7 Dimensione del firmware e utilizzo della memoria

Dimensioni tipiche dopo il build

Mappa di utilizzo del flash (dopo il flash)

Utilizzo della RAM (in esecuzione)

2.8 Verifica della compilazione riuscita

File di output del build (build/)

2.9 Problemi comuni di compilazione

Issue 1: Error "arduino-esp32 not found"

Problema 2: Spazio flash insufficiente

Problema 3: Conflitto di versione ESP-IDF

Issue 4: Error "NVS namespace too long"

Issue 5: Don't Want to Deal with Build Issues?