← Hardware-Anleitung | Inhaltsverzeichnis | Weiter: Anwendungsstruktur →

2. Kompilierungsanforderungen

💡 Keine Lust zu kompilieren? Vorgefertigte Firmware-Binärdateien sind auf der Seite GitHub Releases verfügbar. Einfach herunterladen, entpacken und mit den mitgelieferten Skripten flashen — keine Kompilierung erforderlich!

2.1 Plattform und Werkzeuge

Hauptplattform

ESP-IDF-Version: 5.5.1 (erforderlich)
Mikrocontroller: ESP32 (klassisch, nicht ESP32-S2/S3/C3)
Architektur: Xtensa Dual-Core LX6
CPU-Taktfrequenz: 240 MHz
Minimaler Flash: 4 MB
Minimaler RAM: 520 KB (ESP32-WROOM-32 oder ESP32-WROVER)

Frameworks und Komponenten

Arduino Core für ESP32: Version 3.x (über ESP-IDF Component Manager)
CMake: Mindestversion 3.16
Python: 3.8+ (für idf.py-Skripte)

2.2 Erforderliche Bibliotheken

Hauptabhängigkeiten (über IDF Component Manager)

Definiert in der Datei 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"

Integrierte ESP-IDF-Komponenten (automatisch verwendet)

nvs_flash – Nichtflüchtiger Speicher für die Konfiguration
esp_wifi – WiFi-Treiber und -Protokolle
esp_http_server – Asynchroner Webserver
esp_adc – ADC-Treiber mit DMA-Unterstützung
driver – GPIO-, LEDC-, Timer-Treiber
freertos – Echtzeit-Betriebssystem

Benutzerdefinierte Komponenten (lokal)

Verzeichnis: components/:

Komponente	Pfad	Zweck
comm	`components/comm`	WiFi, WebServer, REST API, Material-UI-Oberfläche
hal	`components/hal`	Hardware-Abstraktionsschicht (DimmerHAL, PowerMeterADC)
utils	`components/utils`	ConfigManager, HardwareConfigManager, SerialCommand
control	`components/control`	RouterController, Steuerungsalgorithmen
rbdimmer	`components/rbdimmer`	RBDimmer-Bibliothek (TRIAC-Dimmer)

2.3 Build-Konfiguration (sdkconfig)

Hauptparameter

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

Wichtige Projektkonfigurationen

ADC-Konfiguration

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

WiFi-Konfiguration

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 & Partitionstabelle

ini

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

2.4 Partitionstabelle

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

Beschreibung der Partitionen

Partition	Typ	Größe	Offset	Zweck
nvs	data (nvs)	24 KB (0x6000)	0x9000	Gerätekonfiguration (WiFi, RouterController, HardwareConfig)
otadata	data (ota)	8 KB (0x2000)	0xf000	OTA-Metadaten (welche app0/app1 aktiv ist)
app0	app (ota_0)	1.6 MB (0x190000)	0x20000	Erster Firmware-Slot (OTA-Slot 0)
app1	app (ota_1)	1.6 MB (0x190000)	0x1B0000	Zweiter Firmware-Slot (OTA-Slot 1)
spiffs	data (spiffs)	768 KB (0xC0000)	0x340000	Dateisystem für Web-UI (HTML/CSS/JS)

Flash-Speicherkarte (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 Kompilierungs- und Flash-Befehle

Umgebung einrichten (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

Umgebung einrichten (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

Haupt-Build-Befehle

1. Abhängigkeiten installieren (erstmalig)

bash

idf.py set-target esp32
idf.py reconfigure

Dabei werden automatisch installiert:

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

2. Projektkonfiguration (optional)

bash

idf.py menuconfig

Verfügbare Einstellungen über menuconfig:

Serial flasher config → Flash-Größe (4 MB)
Serial flasher config → Flash-Frequenz (40 MHz)
Partition Table → Benutzerdefinierte Partitionstabelle CSV
Component config → FreeRTOS → Tick-Rate (1000 Hz)

3. Projekt kompilieren

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. Flashen und Überwachen

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 Flash-Befehl und Speicheradressen

esptool.py-Befehl (direktes Flashen)

Wenn Sie manuell über esptool.py flashen müssen (z. B. von einem anderen 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

Dateiadressen im Speicherabbild

Datei	Adresse	Größe	Beschreibung
bootloader.bin	0x1000	~28 KB	ESP32-Bootloader (zweite Stufe)
partition-table.bin	0x8000	~3 KB	Partitionstabelle
ACRouter-project.bin	0x20000	~1.6 MB	Haupt-Firmware (app0)
ota_data_initial.bin	0xf000	8 KB	Initiale OTA-Daten (optional)

Flash-Backup

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

Aus Backup wiederherstellen

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 Firmware-Größe und Speicherverbrauch

Typische Größen nach dem 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)
=====================================

Flash-Belegung (nach dem Flashen)

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

RAM-Verbrauch (Laufzeit)

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 Erfolgreichen Build überprüfen

Nach Ausführung von idf.py build sollte Folgendes angezeigt werden:

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

Build-Ausgabedateien (build/)

Wichtigste Dateien im Verzeichnis build/:

ACRouter-project.bin – Haupt-Firmware
ACRouter-project.elf – ELF-Datei mit Symbolen (zum Debuggen)
ACRouter-project.map – Speicherkarte (Funktionsadressen)
bootloader/bootloader.bin – Bootloader
partition_table/partition-table.bin – Partitionstabelle

2.9 Häufige Build-Probleme

Issue 1: Error "arduino-esp32 not found"

Lösung:

bash

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

Problem 2: Nicht genügend Flash-Speicher

Symptom:

python

Error: app partition is too small for binary

Lösung: Überprüfen Sie partitions.csv – app0/app1 sollte >= 0x190000 (1,6 MB) sein

Problem 3: ESP-IDF-Versionskonflikt

Symptom:

python

CMake Error: ESP-IDF version mismatch

Lösung:

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"

Symptom:

python

Error: NVS key exceeds 15 characters

Lösung: NVS-Schlüssel sind auf 15 Zeichen begrenzt. Verwenden Sie Abkürzungen (siehe HardwareConfigManager.h).

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

Lösung: Verwenden Sie vorgefertigte Firmware-Binärdateien!

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

Besuchen Sie GitHub Releases
Laden Sie die neueste Firmware-Version herunter
Entpacken Sie das Archiv mit folgenden Dateien:
bootloader.bin
partition-table.bin
ACRouter-project.bin
ota_data_initial.bin
flash.bat / flash.sh (Flash-Skripte)
FLASH_README.txt (Anleitung)
Flashen Sie mit dem mitgelieferten Skript:
Windows: flash.bat COM5
Linux/Mac: ./flash.sh /dev/ttyUSB0

Keine ESP-IDF-Installation oder Kompilierung erforderlich!

← Hardware-Anleitung | Inhaltsverzeichnis | Weiter: Anwendungsstruktur →

Produkte

Ausgewählt

Loslegen

Integrationen

Leitfäden & Artikel

ACRouter

Projektpräsentation

Erste Schritte

Integrationen

AC Dimmer

DimmerLink

ACRouter

GitHub

2. Kompilierungsanforderungen

2.1 Plattform und Werkzeuge

Hauptplattform

Frameworks und Komponenten

2.2 Erforderliche Bibliotheken

Hauptabhängigkeiten (über IDF Component Manager)

Integrierte ESP-IDF-Komponenten (automatisch verwendet)

Benutzerdefinierte Komponenten (lokal)

2.3 Build-Konfiguration (sdkconfig)

Hauptparameter

Wichtige Projektkonfigurationen

ADC-Konfiguration

WiFi-Konfiguration

Flash & Partitionstabelle

2.4 Partitionstabelle

Beschreibung der Partitionen

Flash-Speicherkarte (4 MB)

2.5 Kompilierungs- und Flash-Befehle

Umgebung einrichten (Windows)

Umgebung einrichten (Linux/macOS)

Haupt-Build-Befehle

1. Abhängigkeiten installieren (erstmalig)

2. Projektkonfiguration (optional)

3. Projekt kompilieren

4. Flashen und Überwachen

2.6 Flash-Befehl und Speicheradressen

esptool.py-Befehl (direktes Flashen)

Dateiadressen im Speicherabbild

Flash-Backup

Aus Backup wiederherstellen

2.7 Firmware-Größe und Speicherverbrauch

Typische Größen nach dem Build

Flash-Belegung (nach dem Flashen)

RAM-Verbrauch (Laufzeit)

2.8 Erfolgreichen Build überprüfen

Build-Ausgabedateien (build/)

2.9 Häufige Build-Probleme

Issue 1: Error "arduino-esp32 not found"

Problem 2: Nicht genügend Flash-Speicher

Problem 3: ESP-IDF-Versionskonflikt

Issue 4: Error "NVS namespace too long"

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