Tuya Zigbee и ZHA — что работает и что делать сразу

Коротко: некоторые Tuya Zigbee‑устройства работают в ZHA «из коробки», но большая часть использует proprietary datapoints/мануфактурные кластеры и потребует quirk или конвертер. Ниже — практические шаги для диагностики, подключения и принятия решения.

Что такое проблема в двух предложениях

Tuya часто передаёт команды и состояние через собственный мануфактурный кластер (datapoints), а не через стандартные ZCL-кластеры. ZHA на базе zigpy распознаёт стандартные устройства автоматически; для нестандартных нужен quirk — локальный обработчик, который «переводит» datapoints в сущности Home Assistant.

Практическая пошаговая инструкция подключения и диагностики

1. Подготовка:
   • Используйте стабильный координатор (CC26x2/CC13x2 рекомендуются). Установите ZHA и включите quirks (enable_quirks: true). При необходимости укажите custom_quirks_path.
2. Пара и первичный осмотр:
   • Добавьте устройство в режим «Add device». Если pairing успешен, но сущностей нет — соберите ZHA diagnostics.
3. Что смотреть в diagnostics:
   • modelID, manufacturerName, endpoints и список кластеров. Особое внимание — modelID вида TS0601 и manufacturerName, начинающееся с _TZE200/_TZE204 и т.п. — типичная «проблемная» сигнатура.
4. Дальше — варианты:
   • Поиск: сначала проверьте zha‑device‑handlers и базу Zigbee2MQTT — возможно, уже есть поддержка.
   • Если нет — для ZHA создайте custom quirk (файл с signature и обработчиками) или переключитесь на Zigbee2MQTT и добавьте converter, описывающий datapoints.
5. Тестирование:
   • Переподключите устройство, проверьте команды, отчёт батареи и частоту сообщений. Следите за «флудом» и проблемами маршрутизации.

Чем ZHA и Zigbee2MQTT отличаются для Tuya (коротко)

• ZHA (zigpy + quirks): глубже интеграция в HA, удобнее сущности, но многие Tuya требуют написания quirk.
• Zigbee2MQTT: гибкие конвертеры и активное сообщество, часто быстрее добавляют поддержку Tuya, но требует MQTT и отдельной настройки.
• Официальный Tuya‑хаб: простой и стабильный способ работы с Tuya, но чаще облачный и не локальный.

Быстрая таблица выбора

Частые ошибки и как их исправить

• Устройство парится, но нет сущностей
  • Действие: получить diagnostics → проверить modelID/manufacturerName → поиск quirk.
• Quirk не применяется
  • Действие: сверить signature в quirk с diagnostics, проверить путь custom_quirks_path, полностью перезапустить HA.
• Частые отвали/флуд в сети
  • Действие: переместить устройство ближе к координатору/роутеру, проверить качество модуля; при постоянных проблемах заменить устройство.
• Несоответствие datapoints
  • Действие: изучить raw datapoints в логах, перенести логи в шаблон quirk/converter.

FAQ

• Нужно ли всегда писать quirk для Tuya?
  • Нет. Простые лампы, розетки и переключатели иногда работают «из коробки». Но многие TRV и мульти‑датчики — да, потребуют quirk.
• Где взять шаблон для quirk?
  • В репозиториях zha‑device‑handlers есть примеры signature/handlers; используйте их как основу и подставьте данные из diagnostics.
• Что быстрее — писать quirk или перейти на Zigbee2MQTT?
  • Для одного устройства проще поискать готовый конвертер в Zigbee2MQTT. Если у вас много устройств и нужен MQTT — Zigbee2MQTT часто быстрее.

Заключение и рекомендации

Если хотите стабильную локальную систему — ориентируйтесь на устройства с проверенной поддержкой ZCL. Для Tuya будьте готовы:

• собрать diagnostics,
• искать готовый quirk/converter,
• при необходимости создать custom quirk или использовать Zigbee2MQTT.

Могу помочь конкретно: пришлите modelID и manufacturerName из ZHA diagnostics — подготовлю проверку поддержки и шаблон quirk для вашей модели.