ZBFun: открытая архитектура для устройств ZigBee без обязательного облака
Инженер ZolAnd представил проект ZBFun - архитектуру для работы с устройствами ZigBee без обязательной привязки к облаку. Изначально он искал библиотеку на Python для ESP32-C6, но готового решения не нашёл. Существующая библиотека esp-zigbee-lib от Espressif написана на C, а сопоставимого инструмента на Python или MicroPython для этой платформы нет.
При попытке написать собственную библиотеку выяснилась более серьёзная проблема: стандарт ZigBee Cluster Library (ZCL) существует только в виде PDF на 1213 страниц без машиночитаемой версии. Сверка официального текста с реальными SDK и устройствами выявила расхождения, из-за которых устройство может работать неправильно. Например, атрибут MeasuredValue кластера Temperature Measurement в ESP-IDF SDK описан как беззнаковый байт, хотя проверенная на тысячах устройств библиотека zigpy и официальный текст ZCL указывают знаковое 16-битное целое.
Если довериться SDK буквально, датчик температуры будет отправлять значения как беззнаковый байт с диапазоном 0-255, и отрицательные температуры превратятся в мусор. Автор проекта отмечает, что многие самодельные проекты совершают эту ошибку, копируя примеры из SDK без проверки. Поэтому первым шагом стало создание системы провенанса - базы знаний, где у каждой записи есть источник и вес доверия к нему.
Источники ранжированы по надёжности: официальный текст стандарта ZCL_SPEC имеет максимальный вес 5/5, zigpy и ZHA/Z2M - 4/5, ESP_SDK - 3/5, ручные дополнения - 2/5, пользовательские данные - 1/5. При конфликте побеждает источник с большим весом именно для конкретного поля, а не «источник вообще лучше». Всё, что не удаётся разрешить автоматически, попадает в очередь ручной проверки.
Результатом гармонизации стала база zb_zcl.db: 95 кластеров, 1879 атрибутов, 329 команд. У каждой записи можно посмотреть, откуда она взята и почему победила именно эта версия при конфликте. Отдельно создан zb_catalog.db - каталог реальных устройств от вендоров, сейчас в нём 568 записей, парсинг ещё нескольких тысяч из Z2M/ZHA продолжается.
Первая база отвечает на вопрос «что должно быть по стандарту», вторая - «что реально делают производители». Производители, как выяснилось, соблюдают стандарт не всегда. Эти две базы стали фундаментом для всех остальных компонентов ZBFun.
Архитектура ZBFun построена на идее контрактов: каждый шаг пайплайна получает на входе строго описанный формат и отдаёт на выходе строго описанный формат. Это позволяет менять реализацию любого звена, не трогая соседние. На некоторых этапах инструмент можно подменить человеком или нейросетью, если контракт соблюдён.
Первый компонент - Designer, визуальный конструктор дерева устройства: конечные точки, кластеры, атрибуты. Он опирается на zb_zcl.db и zb_catalog.db, подсказывая допустимые кластеры, обязательные атрибуты и их типы. На выходе Designer формирует JSON-спецификацию - контракт, описывающий структуру модели устройства независимо от платформы.
Поскольку контракт формализован и документирован, спецификацию можно получить не только через графический интерфейс, но и вручную - написав JSON по документации - или сгенерировать нейросетью. Designer в этом смысле не единственный источник спецификаций, а один из возможных инструментов их создания.
Второй компонент - постпроцессоры, которые берут JSON-спецификацию и отдают готовую прошивку под конкретную платформу. Сейчас реализован один постпроцессор - ESP32Builder, генерирующий C-код для ESP32-C6 на базе esp-zigbee-lib. Соответствие «атрибут кластера - вызов API SDK» вычисляется автоматически на основе сканирования заголовков SDK и базы zb_zcl.db, а не описывается вручную для каждого кластера.
Ручное описание API каждого кластера - гарантированный источник рассинхронизации при обновлении SDK. Автоматическое сопоставление, завязанное на единую базу знаний, оказалось надёжнее. Формат контракта на входе постпроцессора не меняется, поэтому в будущем можно реализовать постпроцессоры под другие платформы и языки, не трогая ни Designer, ни базы знаний.
Третий компонент - прикладная логика, которую пишет сам разработчик. Прошивка даёт устройству базовый API для работы с его деревом ZigBee, но не решает, что именно устройство должно делать при получении команды или изменении атрибута. Критерий для выбора места размещения логики: переживёт ли она обрыв связи с хабом.
Если логика переживает обрыв связи, она обязана быть на устройстве, иначе автономность превращается в пустые слова. Если логика принципиально межустройственная, например зависит от состояния нескольких приборов сразу, ей место на хабе. Между этими случаями есть серая зона - логика, которая технически может быть реализована в обоих местах, и решение отдаётся на усмотрение разработчика.
Четвёртый компонент - Composer, локальное облако для оркестрации сценариев между разными устройствами. Здесь же - статистика, конфигурация сети и, при необходимости, общение с внешним миром. Облако в ZBFun не обязательный элемент системы, а опциональная надстройка над локальным хабом, который полностью работоспособен без выхода в интернет.
Автор сравнивает ZBFun с существующими решениями. ESPHome использует YAML-файл для описания железа и логики, Python-слой валидирует конфигурацию и превращает её в C++. В версии 2026.5.0 появился визуальный Device Builder, но по архитектуре это надстройка над тем же YAML: графический интерфейс генерирует тот же текстовый DSL, а не создаёт независимый от синтаксиса промежуточный контракт.
Zigbee2MQTT и ZHA вообще не занимаются прошивками устройств. Вся поддержка нестандартных девайсов - это JS-конвертеры или Python-надстройки, написанные вручную мейнтейнерами под каждую конкретную вендорскую железку. Подход отлично работает для интеграции готовых устройств, но не помогает, если нужно спроектировать собственное с нуля.
В следующей статье автор планирует разобрать устройство ESP32Builder, включая три реальных бага, которые всплыли только на первой настоящей компиляции сгенерированного кода. Также он объяснит, почему автоматическое сканирование заголовков SDK оказалось надёжнее ручного описания API каждого кластера.