188 lines
9.0 KiB
Markdown
188 lines
9.0 KiB
Markdown
# Спецификация системы сборки: 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` или автоматически, если менеджер сам разрешит пути.
|