Init
This commit is contained in:
187
docs/Build system details.md
Normal file
187
docs/Build system details.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Спецификация системы сборки: ESP-IDF для ESP32-C6
|
||||
**Версия документа:** 1.0
|
||||
**Статус:** Одобрено (Release)
|
||||
**Область применения:** Настройка окружения, конфигурация сборки, управление зависимостями и автоматизация команд для проектов на ESP32-C6 (включая Zigbee-приложения).
|
||||
|
||||
---
|
||||
|
||||
## 1. Введение
|
||||
|
||||
Официальным фреймворком для ESP32-C6 является **ESP-IDF** (начиная с версии v5.1+). Современный ESP-IDF использует **CMake** и систему сборки **Ninja**, управление которыми осуществляется через утилиту командной строки `idf.py`.
|
||||
|
||||
Использование традиционного GNU Make в качестве основной системы сборки в ESP-IDF отключено, однако `Makefile` часто применяется на верхнем уровне как **удобная оболочка (wrapper)** для автоматизации рутинных задач, CI/CD пайплайнов и стандартизации команд в команде разработчиков.
|
||||
|
||||
---
|
||||
|
||||
## 2. Структура проекта
|
||||
|
||||
Стандартная структура директорий проекта для ESP32-C6 выглядит следующим образом:
|
||||
|
||||
```text
|
||||
my_esp32c6_project/
|
||||
├── CMakeLists.txt # Главный файл конфигурации CMake
|
||||
├── Makefile # Оболочка (Wrapper) для быстрых команд
|
||||
├── sdkconfig.defaults # Базовые настройки конфигурации (для Git)
|
||||
├── idf_component.yml # Манифест зависимостей проекта (Registry)
|
||||
├── main/
|
||||
│ ├── CMakeLists.txt # Конфигурация сборки исходников
|
||||
│ ├── main.c # Точка входа приложения (app_main)
|
||||
│ └── idf_component.yml # Зависимости конкретного компонента
|
||||
└── components/ # Локальные компоненты (драйверы, библиотеки)
|
||||
└── custom_sensor/
|
||||
├── CMakeLists.txt
|
||||
├── include/
|
||||
└── custom_sensor.c
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Структура оболочки Makefile (Wrapper)
|
||||
|
||||
Так как прямой вызов `make` больше не поддерживается фреймворком напрямую, мы создаем `Makefile`, который транслирует привычные команды в вызовы `idf.py`.
|
||||
|
||||
**Пример файла `Makefile` в корне проекта:**
|
||||
|
||||
```makefile
|
||||
# Makefile wrapper для ESP-IDF (ESP32-C6)
|
||||
|
||||
# Настройки по умолчанию
|
||||
PORT ?= /dev/ttyUSB0
|
||||
BAUD ?= 460800
|
||||
TARGET ?= esp32c6
|
||||
|
||||
.PHONY: all build flash monitor clean menuconfig set-target full
|
||||
|
||||
all: build
|
||||
|
||||
# Установка целевого микроконтроллера
|
||||
set-target:
|
||||
idf.py set-target $(TARGET)
|
||||
|
||||
# Вызов графического конфигуратора
|
||||
menuconfig:
|
||||
idf.py menuconfig
|
||||
|
||||
# Сборка проекта
|
||||
build:
|
||||
idf.py build
|
||||
|
||||
# Прошивка устройства
|
||||
flash:
|
||||
idf.py -p $(PORT) -b $(BAUD) flash
|
||||
|
||||
# Открытие последовательного монитора
|
||||
monitor:
|
||||
idf.py -p $(PORT) monitor
|
||||
|
||||
# Прошивка и запуск монитора одной командой
|
||||
full:
|
||||
idf.py -p $(PORT) -b $(BAUD) flash monitor
|
||||
|
||||
# Очистка артефактов сборки
|
||||
clean:
|
||||
idf.py clean
|
||||
|
||||
# Полное удаление директории build и sdkconfig (Hard reset)
|
||||
distclean:
|
||||
idf.py fullclean
|
||||
rm -rf build/ dependencies.lock
|
||||
```
|
||||
|
||||
**Использование:**
|
||||
Вместо ввода длинных команд, разработчик может использовать:
|
||||
* `make build` — для компиляции.
|
||||
* `make PORT=/dev/ttyACM0 full` — для сборки, прошивки и открытия логов.
|
||||
|
||||
---
|
||||
|
||||
## 4. Конфигурация ESP-IDF (CMake и sdkconfig)
|
||||
|
||||
### 4.1. Главный `CMakeLists.txt`
|
||||
Располагается в корне проекта. Его задача — инициализировать фреймворк и объявить проект.
|
||||
|
||||
```cmake
|
||||
# Минимально требуемая версия CMake
|
||||
cmake_minimum_required(VERSION 3.16)
|
||||
|
||||
# Подключение базового скрипта сборки ESP-IDF
|
||||
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
|
||||
|
||||
# Имя проекта
|
||||
project(esp32c6_zigbee_node)
|
||||
```
|
||||
|
||||
### 4.2. Конфигурация компонентов (`main/CMakeLists.txt`)
|
||||
Определяет исходные файлы приложения и их зависимости от других модулей ESP-IDF.
|
||||
|
||||
```cmake
|
||||
idf_component_register(
|
||||
SRCS "main.c" "zigbee_handler.c"
|
||||
INCLUDE_DIRS "." "include"
|
||||
REQUIRES nvs_flash esp_timer freertos
|
||||
PRIV_REQUIRES esp_zigbee_gateway # Приватная зависимость от Zigbee
|
||||
)
|
||||
```
|
||||
|
||||
### 4.3. Настройки SDK (`sdkconfig` и `sdkconfig.defaults`)
|
||||
Файл `sdkconfig` генерируется автоматически и **не должен** добавляться в систему контроля версий (Git).
|
||||
Вместо этого используется файл `sdkconfig.defaults`, в котором фиксируются только те параметры, которые отличаются от стандартных.
|
||||
|
||||
**Пример `sdkconfig.defaults` для Zigbee-проекта на ESP32-C6:**
|
||||
|
||||
```ini
|
||||
# Установка целевого чипа
|
||||
CONFIG_IDF_TARGET="esp32c6"
|
||||
|
||||
# Настройки FreeRTOS (частота тиков)
|
||||
CONFIG_FREERTOS_HZ=1000
|
||||
|
||||
# Использование кастомной таблицы разделов (Partition Table)
|
||||
CONFIG_PARTITION_TABLE_CUSTOM=y
|
||||
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
|
||||
|
||||
# Включение поддержки IEEE 802.15.4 (Zigbee/Thread)
|
||||
CONFIG_ZB_ENABLED=y
|
||||
CONFIG_ZB_RADIO_NATIVE=y
|
||||
|
||||
# Оптимизация размера прошивки (полезно для OTA)
|
||||
CONFIG_COMPILER_OPTIMIZATION_SIZE=y
|
||||
```
|
||||
|
||||
> **Примечание:** При выполнении сборки (`idf.py build`), система автоматически применит настройки из `sdkconfig.defaults` и сгенерирует финальный файл `sdkconfig`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Управление зависимостями
|
||||
|
||||
ESP-IDF v5.x использует продвинутый менеджер компонентов (**ESP-IDF Component Manager**), который скачивает библиотеки из [ESP Component Registry](https://components.espressif.com/).
|
||||
|
||||
### 5.1. Файл манифеста (`idf_component.yml`)
|
||||
Для добавления внешних библиотек (например, официального стека ESP-Zigbee) создается файл `idf_component.yml` в директории `main/`.
|
||||
|
||||
**Пример `main/idf_component.yml`:**
|
||||
|
||||
```yaml
|
||||
version: "1.0.0"
|
||||
description: "Main application component for ESP32-C6 Zigbee Node"
|
||||
|
||||
dependencies:
|
||||
# Зависимость от официального SDK Espressif для Zigbee
|
||||
espressif/esp-zigbee-lib: "^1.0.0"
|
||||
|
||||
# Зависимость от библиотеки парсинга JSON
|
||||
jsmn: "~1.1.0"
|
||||
|
||||
# Пример подключения компонента из локальной директории или Git
|
||||
custom_driver:
|
||||
path: ../components/custom_driver
|
||||
```
|
||||
|
||||
### 5.2. Разрешение зависимостей
|
||||
Во время выполнения `idf.py build` (или `make build`) происходит следующее:
|
||||
1. Менеджер компонентов анализирует `idf_component.yml`.
|
||||
2. Скачивает нужные версии библиотек в директорию `managed_components/` (которая должна быть добавлена в `.gitignore`).
|
||||
3. Создает файл `dependencies.lock`, фиксирующий точные версии загруженных библиотек. *Этот файл рекомендуется коммитить в Git для обеспечения воспроизводимости сборок на CI/CD.*
|
||||
|
||||
### 5.3. Локальные компоненты
|
||||
Если вы разрабатываете собственные драйверы, размещайте их в папке `components/` в корне проекта. ESP-IDF автоматически сканирует эту папку, и любой валидный компонент (с файлом `CMakeLists.txt`) будет доступен в `main` через директиву `REQUIRES` или автоматически, если менеджер сам разрешит пути.
|
||||
Reference in New Issue
Block a user