Клапан полива GIEX GX-02 не дает в ZHA (штатной Zigbee-интеграции Home Assistant) рабочего управления, пока для него не установлен свой quirk - обработчик устройства под конкретную модель. Пользователям помогал quirk с точным идентификатором _TZE284_7ytb3h8u и перезапуск Home Assistant: у этого решения 4 отчета об успехе в 3 ветках форума и ни одного неудачного. По той же схеме в этих ветках решали вопрос и с другими устройствами Tuya на TS0601, которые ZHA показывает без сущностей или с неполным набором.
Как выглядит проблема
Так ведут себя несколько устройств Tuya на базе TS0601. Случаи отмечены на Home Assistant 2025.2.4, в том числе на установке Core.
| Устройство | Что видит пользователь в ZHA |
|---|---|
Клапан полива GIEX GX-02 (_TZE284_7ytb3h8u) | Рабочего управления нет без своего quirk |
Термостат Tuya TS0601 (_TZE204_ltwbm23f) | Видна только сущность обновления прошивки, сущности климата нет |
Сирена Tuya TS0601 (_TZE284_nlrfgpny) | Сущностей нет вообще |
Отдельного текста ошибки в сообщениях об этой проблеме нет: устройство просто остается без нужных сущностей. Если то же устройство работает через Zigbee2MQTT, смотрите страницу про ошибку устройство is NOT supported.
Предполагаемая причина
Одно и то же объяснение встречается во всех 3 ветках форума, но прямого подтверждения из документации у этой формулировки нет, поэтому это предположение. С ним согласуется README репозитория zha-device-handlers: идентификаторы в quirk должны до символа совпадать с тем, что сообщает устройство, иначе zigpy (библиотека Zigbee, на которой работает ZHA) не сопоставит их.
| Причина | Как проверить | Что сделать |
|---|---|---|
| В ZHA нет quirk под точный идентификатор производителя и модели конкретного устройства | Сверить manufacturer и model, которые сообщает устройство, со строками в MODELS_INFO в signature quirk | Установить свой quirk с точными идентификаторами и перезапустить Home Assistant |
Установка своего quirk
Единственное решение с подтверждениями - поставить свой quirk и перезапустить Home Assistant. В 3 ветках форума о нем 4 отчета об успехе, неудачных нет.
Шаг 1. Подготовьте файл quirk, где в signature указан точный идентификатор производителя и модели устройства. Для клапана GIEX используют класс GiexValveVar02, фрагмент из ветки (класс целиком, импорты и кластеры - в файле ts0601_valve.py, на который ссылался автор quirk):
class GiexValveVar02(CustomDevice):
"""GiEX valve device, variant 2."""
signature = {
MODELS_INFO: [
("_TZE284_7ytb3h8u", "TS0601"),
],
ENDPOINTS: {
# <SimpleDescriptor endpoint=1 profile=260 device_type=0x0051
# input_clusters=[0x0000, 0x0004, 0x0005, 0xed00, 0xef00]
# output_clusters=[0x000a, 0x0019]>
1: {
PROFILE_ID: zha.PROFILE_ID,
DEVICE_TYPE: zha.DeviceType.SMART_PLUG,
INPUT_CLUSTERS: [
Basic.cluster_id,
Groups.cluster_id,
Scenes.cluster_id,
0xed00,
GiexValveManufCluster.cluster_id,
],
OUTPUT_CLUSTERS: [Time.cluster_id, Ota.cluster_id],
}
},
}
replacement = {
ENDPOINTS: {
1: {
DEVICE_TYPE: zha.DeviceType.ON_OFF_SWITCH,
INPUT_CLUSTERS: [
Basic.cluster_id,
Groups.cluster_id,
Scenes.cluster_id,
TuyaOnOffNM,
TuyaPowerConfigurationCluster,
TuyaValveWaterConsumed,
GiexValveManufCluster,
],
OUTPUT_CLUSTERS: [Time.cluster_id, Ota.cluster_id],
}
}
}Для сирены _TZE284_nlrfgpny quirk строится через TuyaQuirkBuilder("_TZE284_nlrfgpny", "TS0601").
Шаг 2. Положите файл в отдельный каталог и укажите путь к нему опцией custom_quirks_path в конфигурации ZHA:
zha:
custom_quirks_path: /config/custom_zha_quirks/Шаг 3. Перезапустите Home Assistant и проверьте сущности устройства.
Если не помогло
Замена строки модели в чужом quirk не гарантирует результата. Один пользователь поменял в quirk из туториала идентификатор _TZE204 на _TZE284 - не сработало. Почему не сработало, в ветке не сказано.
Два варианта пока без подтверждений:
- Pull request 3769 в репозитории zha-device-handlers. Один пользователь предложил его попробовать, итог остался неизвестным.
- Стандартный quirk ZHA, который теперь распознает сирену
_TZE284_nlrfgpny. Результат у одного пользователя частичный, подробностей нет.
Частые вопросы
Что такое quirk в ZHA?
Quirk - это обработчик устройства: файл с кодом, в котором описаны сигнатура (производитель, модель, endpoints и кластеры) и замена для кластеров. Для нестандартных устройств Tuya на TS0601, таких как клапан GIEX GX-02, подходящего обработчика в ZHA может не быть. Тогда сущности не создаются или создаются не полностью, и проблему закрывают своим quirk.
Куда положить файл quirk?
В отдельный каталог, путь к которому задан опцией custom_quirks_path в конфигурации ZHA. В примере из веток форума это /config/custom_zha_quirks/. Опция указывается в YAML в секции zha. После установки файла Home Assistant перезапускают.
Подойдет ли способ для термостата _TZE204_vjpaih9f?
Этот термостат упомянут среди устройств этих веток, и общая схема та же: нужен quirk с точным идентификатором _TZE204_vjpaih9f в signature. Отдельных подтверждений именно для него в ветках нет. В ветке дана ссылка на поиск по issues репозитория zha-device-handlers по этому идентификатору.
Нужно ли перезапускать Home Assistant?
Да, перезапуск входит в само решение: 4 отчета об успехе относятся к порядку «установить quirk и перезапустить Home Assistant». Сообщений о том, что новый quirk подхватывается без перезапуска, в ветках нет.
