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