← Guide matériel | Sommaire | Suivant : Structure de l'application →

2. Prérequis de compilation

💡 Vous ne souhaitez pas compiler ? Des binaires de firmware pré-compilés sont disponibles sur la page GitHub Releases . Téléchargez, décompressez et flashez avec les scripts fournis — aucune compilation nécessaire !

2.1 Plateforme et outils

Plateforme principale

Version ESP-IDF : 5.5.1 (obligatoire)
Microcontrôleur : ESP32 (classique, pas ESP32-S2/S3/C3)
Architecture : Xtensa dual-core LX6
Fréquence CPU : 240 MHz
Flash minimum : 4 Mo
RAM minimum : 520 Ko (ESP32-WROOM-32 ou ESP32-WROVER)

Frameworks et composants

Arduino Core pour ESP32 : version 3.x (via ESP-IDF Component Manager)
CMake : version minimum 3.16
Python : 3.8+ (pour les scripts idf.py)

2.2 Bibliothèques requises

Dépendances principales (via IDF Component Manager)

Définies dans le fichier 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"

Composants ESP-IDF intégrés (utilisés automatiquement)

nvs_flash – Stockage non volatile pour la configuration
esp_wifi – Pilote et protocoles WiFi
esp_http_server – Serveur web asynchrone
esp_adc – Pilote ADC avec support DMA
driver – Pilotes GPIO, LEDC, Timer
freertos – Système d'exploitation temps réel

Composants personnalisés (locaux)

Situés dans components/:

Composant	Chemin	Fonction
comm	`components/comm`	WiFi, WebServer, REST API, interface Material UI
hal	`components/hal`	Couche d'abstraction matérielle (DimmerHAL, PowerMeterADC)
utils	`components/utils`	ConfigManager, HardwareConfigManager, SerialCommand
control	`components/control`	RouterController, algorithmes de contrôle
rbdimmer	`components/rbdimmer`	Bibliothèque RBDimmer (variateur TRIAC)

2.3 Configuration du build (sdkconfig)

Paramètres principaux

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

Configurations clés du projet

Configuration 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

Configuration 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 et partitions

ini

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

2.4 Table de partitions

Fichier : 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,

Description des partitions

Partition	Type	Taille	Offset	Fonction
nvs	data (nvs)	24 Ko (0x6000)	0x9000	Configuration de l'appareil (WiFi, RouterController, HardwareConfig)
otadata	data (ota)	8 Ko (0x2000)	0xf000	Métadonnées OTA (quel app0/app1 est actif)
app0	app (ota_0)	1,6 Mo (0x190000)	0x20000	Premier slot firmware (OTA slot 0)
app1	app (ota_1)	1,6 Mo (0x190000)	0x1B0000	Second slot firmware (OTA slot 1)
spiffs	data (spiffs)	768 Ko (0xC0000)	0x340000	Système de fichiers pour l'interface Web (HTML/CSS/JS)

Carte mémoire Flash (4 Mo)

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 Commandes de compilation et de flash

Configuration de l'environnement (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

Configuration de l'environnement (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

Commandes de build principales

1. Installer les dépendances (première fois)

bash

idf.py set-target esp32
idf.py reconfigure

Cela installera automatiquement :

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

2. Configuration du projet (optionnel)

bash

idf.py menuconfig

Paramètres disponibles via menuconfig :

Serial flasher config → Taille du flash (4 Mo)
Serial flasher config → Fréquence du flash (40 MHz)
Partition Table → Table de partitions personnalisée CSV
Component config → FreeRTOS → Fréquence du tick (1000 Hz)

3. Compiler le projet

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. Flasher et surveiller

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 Commande de flash et adresses mémoire

Commande esptool.py (flash direct)

Si vous devez flasher manuellement via esptool.py (par exemple, depuis un autre ordinateur) :

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

Adresses des fichiers dans l'image mémoire

Fichier	Adresse	Taille	Description
bootloader.bin	0x1000	~28 Ko	Bootloader ESP32 (deuxième étape)
partition-table.bin	0x8000	~3 Ko	Table de partitions
ACRouter-project.bin	0x20000	~1,6 Mo	Firmware principal (app0)
ota_data_initial.bin	0xf000	8 Ko	Données OTA initiales (optionnel)

Sauvegarde du 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

Restauration depuis une sauvegarde

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 Taille du firmware et utilisation de la mémoire

Tailles typiques après compilation

python

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

Utilisation du flash (après flashage)

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%)

Utilisation de la RAM (en fonctionnement)

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 Vérification de la réussite de la compilation

Après l'exécution de idf.py build, vous devriez voir :

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

Fichiers générés (build/)

Fichiers principaux dans le répertoire build/ :

ACRouter-project.bin – firmware principal
ACRouter-project.elf – fichier ELF avec symboles (pour le débogage)
ACRouter-project.map – carte mémoire (adresses des fonctions)
bootloader/bootloader.bin – bootloader
partition_table/partition-table.bin – table de partitions

2.9 Problèmes de compilation courants

Issue 1: Error "arduino-esp32 not found"

Solution :

bash

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

Problème 2 : Espace flash insuffisant

Symptôme :

python

Error: app partition is too small for binary

Solution : Vérifiez partitions.csv — app0/app1 doit être >= 0x190000 (1,6 Mo)

Problème 3 : Conflit de version ESP-IDF

Symptôme :

python

CMake Error: ESP-IDF version mismatch

Solution :

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"

Symptôme :

python

Error: NVS key exceeds 15 characters

Solution : Les clés NVS sont limitées à 15 caractères. Utilisez des abréviations (voir HardwareConfigManager.h).

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

Solution : Utilisez les binaires de firmware pré-compilés !

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

Rendez-vous sur GitHub Releases
Téléchargez la dernière version du firmware
Décompressez l'archive contenant :
bootloader.bin
partition-table.bin
ACRouter-project.bin
ota_data_initial.bin
flash.bat / flash.sh (scripts de flash)
FLASH_README.txt (instructions)
Flashez avec le script fourni :
Windows : flash.bat COM5
Linux/Mac : ./flash.sh /dev/ttyUSB0

Aucune installation d'ESP-IDF ni compilation nécessaire !

← Guide matériel | Sommaire | Suivant : Structure de l'application →

Produits

En Vedette

Commencer

Intégrations

Guides & Articles

ACRouter

Vitrine de Projets

Commencer

Intégrations

Variateurs AC

DimmerLink

ACRouter

GitHub

2. Prérequis de compilation

2.1 Plateforme et outils

Plateforme principale

Frameworks et composants

2.2 Bibliothèques requises

Dépendances principales (via IDF Component Manager)

Composants ESP-IDF intégrés (utilisés automatiquement)

Composants personnalisés (locaux)

2.3 Configuration du build (sdkconfig)

Paramètres principaux

Configurations clés du projet

Configuration ADC

Configuration WiFi

Flash et partitions

2.4 Table de partitions

Description des partitions

Carte mémoire Flash (4 Mo)

2.5 Commandes de compilation et de flash

Configuration de l'environnement (Windows)

Configuration de l'environnement (Linux/macOS)

Commandes de build principales

1. Installer les dépendances (première fois)

2. Configuration du projet (optionnel)

3. Compiler le projet

4. Flasher et surveiller

2.6 Commande de flash et adresses mémoire

Commande esptool.py (flash direct)

Adresses des fichiers dans l'image mémoire

Sauvegarde du flash

Restauration depuis une sauvegarde

2.7 Taille du firmware et utilisation de la mémoire

Tailles typiques après compilation

Utilisation du flash (après flashage)

Utilisation de la RAM (en fonctionnement)

2.8 Vérification de la réussite de la compilation

Fichiers générés (build/)

2.9 Problèmes de compilation courants

Issue 1: Error "arduino-esp32 not found"

Problème 2 : Espace flash insuffisant

Problème 3 : Conflit de version ESP-IDF

Issue 4: Error "NVS namespace too long"

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