← Руководство по железу | Содержание | Далее: Структура приложения →

2. Требования к компиляции

💡 Не хотите компилировать? Готовые бинарные файлы прошивки доступны на странице GitHub Releases . Просто скачайте, распакуйте и прошейте с помощью прилагаемых скриптов — компиляция не нужна!

2.1 Платформа и инструменты

Основная платформа

Версия ESP-IDF: 5.5.1 (обязательно)
Микроконтроллер: ESP32 (классический, не ESP32-S2/S3/C3)
Архитектура: Xtensa dual-core LX6
Частота ЦП: 240 МГц
Минимальный Flash: 4 МБ
Минимальный RAM: 520 КБ (ESP32-WROOM-32 или ESP32-WROVER)

Фреймворки и компоненты

Arduino Core для ESP32: версия 3.x (через ESP-IDF Component Manager)
CMake: минимальная версия 3.16
Python: 3.8+ (для скриптов idf.py)

2.2 Необходимые библиотеки

Основные зависимости (через IDF Component Manager)

Определены в файле 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"

Встроенные компоненты ESP-IDF (используются автоматически)

nvs_flash — Non-Volatile Storage для конфигурации
esp_wifi — драйвер и протоколы WiFi
esp_http_server — асинхронный веб-сервер
esp_adc — драйвер ADC с поддержкой DMA
driver — драйверы GPIO, LEDC, Timer
freertos — операционная система реального времени

Кастомные компоненты (локальные)

Расположены в components/:

Компонент	Путь	Назначение
comm	`components/comm`	WiFi, WebServer, REST API, интерфейс Material UI
hal	`components/hal`	Уровень аппаратной абстракции (DimmerHAL, PowerMeterADC)
utils	`components/utils`	ConfigManager, HardwareConfigManager, SerialCommand
control	`components/control`	RouterController, алгоритмы управления
rbdimmer	`components/rbdimmer`	Библиотека RBDimmer (TRIAC-диммер)

2.3 Конфигурация сборки (sdkconfig)

Основные параметры

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

Ключевые конфигурации проекта

Конфигурация 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

Конфигурация 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 и разделы

ini

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

2.4 Таблица разделов

Файл: 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,

Описание разделов

Раздел	Тип	Размер	Смещение	Назначение
nvs	data (nvs)	24 КБ (0x6000)	0x9000	Конфигурация устройства (WiFi, RouterController, HardwareConfig)
otadata	data (ota)	8 КБ (0x2000)	0xf000	Метаданные OTA (какой app0/app1 активен)
app0	app (ota_0)	1.6 МБ (0x190000)	0x20000	Первый слот прошивки (OTA слот 0)
app1	app (ota_1)	1.6 МБ (0x190000)	0x1B0000	Второй слот прошивки (OTA слот 1)
spiffs	data (spiffs)	768 КБ (0xC0000)	0x340000	Файловая система для Web UI (HTML/CSS/JS)

Карта Flash-памяти (4 МБ)

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 Команды компиляции и прошивки

Настройка среды (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

Настройка среды (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

Основные команды сборки

1. Установить зависимости (первый раз)

bash

idf.py set-target esp32
idf.py reconfigure

Будет автоматически установлено:

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

2. Конфигурация проекта (опционально)

bash

idf.py menuconfig

Настройки доступны через menuconfig:

Serial flasher config → Flash size (4 МБ)
Serial flasher config → Flash frequency (40 МГц)
Partition Table → Custom partition table CSV
Component config → FreeRTOS → Tick rate (1000 Гц)

3. Сборка проекта

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. Прошивка и монитор

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 и дамп памяти

Команда esptool.py (прямая прошивка)

Если нужно прошить вручную через esptool.py (например, с другого компьютера):

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

Адреса файлов в дампе памяти

Файл	Адрес	Размер	Описание
bootloader.bin	0x1000	~28 КБ	Загрузчик ESP32 (второй этап)
partition-table.bin	0x8000	~3 КБ	Таблица разделов
ACRouter-project.bin	0x20000	~1.6 МБ	Основная прошивка (app0)
ota_data_initial.bin	0xf000	8 КБ	Начальные данные OTA (опционально)

Резервное копирование 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

Восстановление из резервной копии

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 Размер прошивки и использование памяти

Типичные размеры после сборки

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 (после прошивки)

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 (в процессе работы)

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 Проверка успешной сборки

После выполнения idf.py build должно появиться:

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

Основные файлы в директории build/:

ACRouter-project.bin — основная прошивка
ACRouter-project.elf — ELF-файл с символами (для отладки)
ACRouter-project.map — карта памяти (адреса функций)
bootloader/bootloader.bin — загрузчик
partition_table/partition-table.bin — таблица разделов

2.9 Типичные проблемы при сборке

Issue 1: Error "arduino-esp32 not found"

Решение:

bash

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

Проблема 2: Недостаточно места в Flash

Симптом:

python

Error: app partition is too small for binary

Решение: Проверьте partitions.csv — разделы app0/app1 должны быть >= 0x190000 (1.6 МБ)

Проблема 3: Конфликт версий ESP-IDF

Симптом:

python

CMake Error: ESP-IDF version mismatch

Решение:

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"

Симптом:

python

Error: NVS key exceeds 15 characters

Решение: Ключи NVS ограничены 15 символами. Используйте сокращения (см. HardwareConfigManager.h).

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

Решение: Используйте готовые бинарные файлы прошивки!

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

Перейдите на GitHub Releases
Скачайте последний выпуск прошивки
Распакуйте архив, содержащий:
bootloader.bin
partition-table.bin
ACRouter-project.bin
ota_data_initial.bin
flash.bat / flash.sh (скрипты прошивки)
FLASH_README.txt (инструкции)
Прошейте с помощью прилагаемого скрипта:
Windows: flash.bat COM5
Linux/Mac: ./flash.sh /dev/ttyUSB0

Установка ESP-IDF и компиляция не требуются!

← Руководство по железу | Содержание | Далее: Структура приложения →

Продукты

Рекомендуемые

Начать

Интеграции

Руководства и статьи

ACRouter

Презентация проекта

Начало работы

Интеграции

AC Диммеры

DimmerLink

ACRouter

GitHub

2. Требования к компиляции

2.1 Платформа и инструменты

Основная платформа

Фреймворки и компоненты

2.2 Необходимые библиотеки

Основные зависимости (через IDF Component Manager)

Встроенные компоненты ESP-IDF (используются автоматически)

Кастомные компоненты (локальные)

2.3 Конфигурация сборки (sdkconfig)

Основные параметры

Ключевые конфигурации проекта

Конфигурация ADC

Конфигурация WiFi

Flash и разделы

2.4 Таблица разделов

Описание разделов

Карта Flash-памяти (4 МБ)

2.5 Команды компиляции и прошивки

Настройка среды (Windows)

Настройка среды (Linux/macOS)

Основные команды сборки

1. Установить зависимости (первый раз)

2. Конфигурация проекта (опционально)

3. Сборка проекта

4. Прошивка и монитор

2.6 Адреса команды flash и дамп памяти

Команда esptool.py (прямая прошивка)

Адреса файлов в дампе памяти

Резервное копирование Flash

Восстановление из резервной копии

2.7 Размер прошивки и использование памяти

Типичные размеры после сборки

Карта использования Flash (после прошивки)

Использование RAM (в процессе работы)

2.8 Проверка успешной сборки

Файлы результата сборки (build/)

2.9 Типичные проблемы при сборке

Issue 1: Error "arduino-esp32 not found"

Проблема 2: Недостаточно места в Flash

Проблема 3: Конфликт версий ESP-IDF

Issue 4: Error "NVS namespace too long"

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