Zigbee LED Controller

Zigbee-контроллер для Алисы на ESP32-C6

Открытый проект Zigbee 3.0-устройств на ESP32-C6 для Алисы, Яндекс Станции и умного дома Яндекса. Первая рабочая цель — контроллер света, который определяется как стандартное Zigbee-устройство и управляется из приложения «Дом с Алисой» и голосом через умную колонку Алиса.

Проект не ограничивается одним светильником: в дальнейшем здесь могут появиться простые кнопки, датчики, реле и другие Zigbee-устройства. Это не заявка на большую закрытую экосистему, а небольшой набор понятных и воспроизводимых устройств, которые можно собрать самостоятельно.

[!IMPORTANT] Текущая beta-версия — 0.1.0-beta.6. Прошивка и карта endpoint'ов ещё могут меняться. Сейчас проект предназначен для разработки и безопасных низковольтных экспериментов, а не для готового сетевого или силового изделия.

Проект независимый и не связан с компаниями Яндекс или Espressif. «Алиса», «Яндекс Станция» и «Дом с Алисой» упоминаются только для описания совместимости.

Что уже работает

Полный актуальный список задач и критериев готовности находится в TASKS.md. Наблюдённые результаты собраны в docs/compatibility.md.

Основной профиль

2 Dimmable + 1 Addressable RGB:

Оба силовых выхода сразу представлены Алисе как диммируемые. Значение яркости 0 выключает канал, поэтому отдельные On/Off endpoint'ы не нужны. Адресная RGB-лента использует один цифровой DATA-выход, а не три PWM-линии. Эта карта одинакова для отладочной nanoESP32-C6 и собственной компактной PCB. Endpoint 3 поддерживает включение, отдельную регулировку яркости, цвет XY и цветовую температуру примерно 2000–6500 K. Все три карточки подтверждены в приложении «Дом с Алисой» с Яндекс Станцией 2.

Минимальный MVP

Один стандартный Home Automation On/Off Light (0x0100) на endpoint 1. Это самый простой проверенный пример для первого подключения к Яндекс Станции 2.

Как это устроено

flowchart LR
    A[Алиса / приложение<br>«Дом с Алисой»] --> B[Яндекс Станция 2<br>Zigbee-координатор]
    B <-->|Zigbee 3.0| C[ESP32-C6<br>Zigbee End Device]
    C --> D[Стандартные Zigbee endpoint'ы]
    D --> E[GPIO20/21<br>2 × PWM 25 кГц]
    D --> F[GPIO22<br>Addressable RGB DATA]
    G[GPIO0/1/2<br>локальные кнопки] --> C
    H[BOOT / GPIO9<br>commissioning] --> C

ESP32-C6 самостоятельно работает как Zigbee End Device. Для управления не нужны Wi-Fi, MQTT, Raspberry Pi, внешний сервер или дополнительный микроконтроллер. Яндекс-специфичных кластеров и обходных решений в прошивке нет: обнаружение и управление строятся на стандартных Zigbee-кластерах.

Не любая колонка с Алисой является Zigbee-координатором. Нужна Яндекс Станция или отдельный хаб с поддержкой Zigbee. На данный момент фактически проверена только Яндекс Станция 2; совместимость с другими моделями пока не заявлена.

Два аппаратных варианта

Проект развивается сразу по двум практичным направлениям:

1. Готовая отладочная плата ESP32-C6. Быстрый и недорогой способ повторить проект без изготовления PCB. Сейчас используется nanoESP32-C6 V1.0/V1711 с модулем ESP32-C6-WROOM-1-N16.
2. Собственная компактная PCB в разработке. Вариант для законченного устройства с рассчитанным питанием, GPIO/PWM или релейными выходами, защитой, кнопками и проверенной тепловой и EMC-частью.

Отладочная плата не станет устаревшим вариантом после появления собственной PCB: обе ветки останутся полезными для разных сценариев. Подробнее — в docs/hardware.md.

Требования

• Windows 10/11 и PowerShell 5.1 или PowerShell 7;
• плата ESP32-C6 с доступным USB Serial/JTAG или USB-UART;
• USB-кабель с передачей данных;
• Яндекс Станция 2 для повторения подтверждённого Zigbee-теста;
• интернет при первом запуске скрипта установки инструментов.

Скрипты используют проект-локальные Arduino CLI и Arduino-ESP32. Системная установка Arduino IDE не обязательна.

Быстрый старт

1. Клонирование и подготовка

git clone https://github.com/VlasovLabTech/Zigbee-ESP32-C6-Alice.git
Set-Location Zigbee-ESP32-C6-Alice
.\scripts\setup.ps1

2. Сборка

Проверка окружения и простого RGB-примера:

.\scripts\build.ps1 -Target smoke

Проверенный одноканальный Zigbee MVP:

.\scripts\build.ps1 -Target mvp

Основной профиль 2 Dimmable + 1 Addressable RGB для отладочной платы:

.\scripts\build.ps1 -Target universal

Проверка сборки того же профиля для компактной PCB:

.\scripts\build.ps1 -Target universal-pcb

3. Безопасное определение платы

Не выбирайте COM-порт по старой записи или наугад.

1. Отключите плату и запомните текущий список последовательных устройств.
2. При первом стирании подключите плату в ROM download mode: обычно нужно удерживать BOOT, кратко нажать RESET, отпустить RESET, затем BOOT.
3. Найдите только что появившийся порт.
4. Выполните неразрушающую идентификацию и убедитесь, что инструмент сообщает именно ESP32-C6.
5. Если появилось несколько новых устройств или идентификация неоднозначна — остановитесь и проверьте подключение вручную.

Команды определения, первого стирания и загрузки описаны в docs/build-and-test.md. Полное стирание уничтожает прошивку и NVS выбранной платы, поэтому оно не выполняется автоматически.

4. Подключение к Алисе

1. Соберите и загрузите mvp или основной universal-профиль.
2. Откройте Serial Monitor на скорости 115200.
3. Если устройство уже было добавлено, удалите из умного дома Яндекса весь старый физический Zigbee-узел или все его логические карточки. Убедитесь, что две Dimmable-лампы и прежняя RGB-карточка исчезли из раздела «Свет».
4. В приложении «Дом с Алисой» нажмите + → Устройство умного дома → Поиск Zigbee → Найти одно устройство для Яндекс Станции 2.
5. Если плата уже помнит сеть, после обычной загрузки нажмите и удерживайте штатную кнопку BOOT 5 секунд, затем отпустите. Нажимать её нужно только после запуска прошивки: удержание BOOT во время RESET включает ROM download mode.
6. Прошивка очистит только привязку Zigbee, перезапустится и автоматически начнёт commissioning. Состояния каналов при этом сохраняются.
7. Для основного universal-профиля дождитесь появления трёх устройств в приложении; для минимального mvp появится одна лампа. Затем проверьте строку zigbee=connected в ответе Serial-команды status.

Поиск хаба ограничен по времени, поэтому сначала запускайте его в приложении, а затем удерживайте и отпускайте BOOT. Актуальный интерфейс приложения описан в официальной инструкции Яндекса.

Если Zigbee-сети в NVS ещё нет, Zigbee.begin() начинает commissioning сразу, поэтому кнопку при самой первой чистой прошивке нажимать не требуется. Если сеть сохранена, устройство возвращается только в неё и не остаётся постоянно доступным для нового подключения.

Если Алиса голосом сообщает, что устройство найдено, но новые карточки не появляются, чаще всего хаб повторно использует старую запись того же физического узла. Удалите старые карточки полностью, затем очистите привязку на ESP командой zigbee-reset или удержанием и отпусканием BOOT и повторите поиск.

Резервный способ перевода MVP в новое сопряжение через Serial Monitor:

factory-reset

Для универсальной прошивки используется команда:

zigbee-reset

Она очищает только состояние Zigbee-сети и перезагружает устройство. Пользовательское состояние каналов хранится отдельно. Команда factory-reset универсальной прошивки сбрасывает и Zigbee-сеть, и пользовательское состояние.

[!WARNING] На отладочной плате сервисной кнопкой временно служит BOOT/GPIO9. Она не заменяет отдельную защищённую SERVICE-кнопку будущей PCB. Полный сброс пользовательского состояния по-прежнему выполняется только командой factory-reset, чтобы его нельзя было вызвать случайным нажатием.

Настройка универсальной прошивки

Публичные настройки находятся в firmware/universal_zigbee_device/UserConfig.h. По умолчанию выбран профиль 2 Dimmable + 1 Addressable RGB и backend для nanoESP32-C6 V1.0/V1711.

При включении индикатор GPIO8 вспыхивает три раза, затем делает одну короткую вспышку каждые 5 секунд. На отладочной плате цвет фиолетовый; обычный одноцветный светодиод компактной PCB повторяет тот же ритм без управления цветом.

По умолчанию задано 93 пикселя; пользователь может изменить число от 1 до 300 в UserConfig.h. Число пикселей и порядок цветовых байтов задаются через ZD_ADDRESSABLE_RGB_LED_COUNT и ZD_ADDRESSABLE_RGB_COLOR_ORDER. Стартовый стендовый рисунок удалён: после включения лента восстанавливает сохранённое состояние, а системную индикацию выполняет только отдельный GPIO8.

Основные Serial-команды:

help
status
key <1..3>
set dim <1..2> <on|off> <0..255>
set rgb <on|off> <r> <g> <b> <level>
all-off
save-now
reboot
zigbee-reset
factory-reset

Команда key 1…key 3 имитирует короткое нажатие соответствующей локальной клавиши и остаётся удобной для диагностики без физического подключения.

Точный список и примеры приведены в docs/build-and-test.md. Команда status намеренно не выводит сетевые ключи, адреса и другие приватные данные.

Сохранение состояния и безопасность

• выходы переходят в безопасное состояние до чтения NVS;
• Zigbee callback не пишет flash и не выполняет медленные операции;
• изменения состояния объединяются и сохраняются с задержкой;
• неизменившиеся snapshot'ы повторно не записываются;
• карта endpoint'ов защищена версией, fingerprint и CRC32;
• сброс Zigbee-сети отделён от сброса пользовательского состояния;
• Wi-Fi и MQTT не инициализируются.

Встроенный адресный RGB-светодиод nanoESP32-C6 подключён к GPIO8 и используется только как индикатор состояния, а не как отдельный управляемый канал. Отсутствие свечения само по себе не доказывает отказ Zigbee: проверяйте Serial-команду status и сообщения [status-led].

GPIO20…GPIO22 являются только логическими выходами 3,3 В. Не подключайте к ним ленту, реле, MOSFET-затвор с большой ёмкостью, 12 В или сетевое напряжение без проверенного драйвера. Для WS2812 с питанием 5 В нужен подходящий level shifter, общее соединение GND и отдельное рассчитанное питание ленты.

Структура репозитория

firmware/
  led_smoke_test/             проверка встроенного RGB-светодиода
  zigbee_on_off_light/        минимальный подтверждённый On/Off MVP
  universal_zigbee_device/    основной профиль и два аппаратных backend'а
docs/
  build-and-test.md           сборка, загрузка и проверка
  compatibility.md            только наблюдённые результаты
  hardware.md                 отладочная плата и будущая PCB
  troubleshooting.md          диагностика типовых проблем
scripts/
  setup.ps1                   локальная установка инструментов
  build.ps1                   воспроизводимая сборка целей
TASKS.md                       живой план и критерии готовности
ROADMAP.md                     направления развития

Локальные настройки, журналы, дампы и рабочие материалы следует хранить в .local/ или output/. Эти каталоги исключены через .gitignore и не попадут в GitHub. Никогда не добавляйте в репозиторий Zigbee network key, PAN ID, IEEE/MAC-адреса, учётные данные, полный flash/NVS dump или персональные логи.

Документация

• Сборка и тестирование
• Совместимость
• Аппаратная архитектура
• Архитектура прошивки
• Требования к надёжности прошивки
• Диагностика проблем
• Живой список задач
• План развития
• Журнал изменений

Участие в проекте

Сообщения о воспроизводимых ошибках, результаты совместимости с другими Яндекс Станциями и Zigbee-хабами, исправления документации и проверенные аппаратные предложения приветствуются. Перед публикацией удалите из журналов все сетевые и персональные идентификаторы. Правила описаны в CONTRIBUTING.md, а конфиденциальные уязвимости следует сообщать по инструкции из SECURITY.md.

Лицензия

Прошивка и документация распространяются по лицензии MIT. Лицензия будущих исходников PCB будет отдельно зафиксирована до их публикации.