Cizí Zigbee zařízení v ZHA: tři případy s custom quirky

mmWave senzor přítomnosti MTD085-ZB (červenec 2026)

Senzor přítomnosti Wenzhi / LeapMMW MTD085-ZB (TS0225, _TZ321C_fkzihax8). Cíl: plně funkční ZHA custom quirk, který detekuje přítomnost, nechá nastavit všechny známé Tuya parametry přímo z Home Assistantu, co nejvíc odpovídá chování Zigbee2MQTT a nepoužívá workaroundy ani falešné defaulty.

Výchozí stav

Fungovala jen IAS detekce pohybu (binary_sensor) přes vlastní polling. Nefungovaly žádné nastavovací entity, Tuya DP, čtení konfigurace, Z2M magic packet ani zpětné reportování DP.

Co se zjistilo

• ▸ IAS část: zařízení správně odpovídá na IAS Zone cluster 0x0500, atribut 0x0002, ale samo neposílá spolehlivé IAS reporty. Vyřešeno interním pollingem v quirku.
• ▸ Tuya EF00: query_data, setData i sendData původně nefungovaly. Problém nebyl v DP mapě, ale v inicializaci.
• ▸ Z2M magic packet: Zigbee2MQTT při configure čte z Basic clusteru manufacturer, zcl_version, app_version, model, power_source a 0xfffe a teprve pak pokračuje v konfiguraci. Totéž bylo doplněno do Basic clusteru.
• ▸ Basic init: zápis 0xffde = 13 a manufacturer 0x1141 je bezpečný a byl přidán.
• ▸ sendData – zásadní zlom: po Basic init a Z2M magic read začalo TUYA_SEND_DATA fungovat bez dalších hacků. Zápis se ověřil na DP114 (LED indication) – LED skutečně reaguje. Tím se potvrdila cesta Home Assistant → quirk → sendData → MCU.

DP mapa a entity

DP mapa byla kompletně přenesena z Tuya Cloud. Přidané entity:

• ▸ Number: sensitivity_trig, distance_trig, disap_time, confirm_time, blockade_time, main_sensitivity, near_distance, far_distance.
• ▸ Sensor: illuminance, debug_distance, debug_cntdown, Cline, target_distance.
• ▸ Select: debug_mode, scene_mode, sensor_ctrl, led_sta, device_sta, range_report_mode.

Nepřidané: presence_state a device_type – není známé jejich DP.

Co se opravovalo

• ▸ Přechod na TuyaQuirkBuilder V2: původní V1 přístup narážel na novější ZHA. Nové zigpy vyžaduje translation_key, bez něj builder entity odmítne vytvořit.
• ▸ device_class() byl použit špatně a vyvolával AssertionError v CustomDeviceV2. Byl odstraněn.
• ▸ fallback_name: generické názvy (distance_trig) nahrazeny čitelnými (Range – trigger distance).
• ▸ Falešné defaulty: po restartu se objevovalo 50 %, 1.0 m, 0.3 m, i když zařízení nic neposlalo. Odstraněno. Nové pravidlo: pokud zařízení nic neposlalo, hodnota je unknown nebo z HA cache.
• ▸ query_data vracelo UNSUP_CLUSTER_COMMAND – firmware ho nepodporuje. Odstraněno z produkce.

RCA

Z logů odchází OUT sendData správně (DP101, DP102, DP104, DP105, DP108, DP111, DP112, DP114, DP115, DP116, DP117, DP120). Nebyl ale nalezen jediný IN DP report. Zápis funguje, čtení zpět ne – senzor se pro většinu DP chová jako write-only.

Produkční řešení

Ponechat IAS polling, Basic init, Z2M magic read a Tuya sendData; žádné query_data, žádné falešné hodnoty; Select entity pro enum DP a čitelnější názvy.

Otevřené směry: zjistit, jak konfiguraci načítá Tuya Gateway (sniff komunikace Gateway ↔ senzor), porovnat s Zigbee2MQTT, doplnit presence_state a device_type po zjištění jejich DP a ověřit, zda firmware posílá DP reporty za jiných podmínek (announce, restart, pairing).

Termostatická hlavice MOES TV02 (25. září 2025)

Tři shodné hlavice MOES TV02 (TS0601 / _TZE200_kds0pmmv) v ZHA. Cíl: rozchodit párování a nefunkční Child lock / Boost přes entity, které vytváří custom quirk.

Nastavení a zjištění

• ▸ Všechny TRV používají quirk ts0601_trv.ZonnsmartTV01_ZG; ZHA ho zobrazuje jako Zvláštnost. Quirk vytváří tři generické spínače: spinac_1 → Boost, spinac_2 → Child lock, spinac_3 → Online mode.
• ▸ Tuya manufacturer-specific komunikace potřebuje cluster 0xEF00 a manufacturer 0x1002 (4098 dec). Quirk adresuje funkce složeným command_id (horní bajt je datový typ, dolní Tuya DP): Child lock 296 (0x0128, DP 40), Boost 613 (0x0265, DP 101), Online 371 (0x0173, DP 115).

Hlavní problém

U jedné hlavice fungovaly Child lock i Boost přes standardní ZHA switch entity. U zbylých dvou – stejné zařízení, stejný quirk, prakticky stejné nastavení – switche reálně neovládaly nic. Přitom ruční command přes ZONNSMARTManufCluster / 0xEF00 fungoval. Tím se vyloučilo vadné rádiové spojení i samotná funkce Child lock / Boost v TRV. Debug u Child lock ukázal:

set_data(... command_id=296, function=0, data=1)
...
Default_Response(... status=SUCCESS)
...
get_data(... command_id=296 ... data=[1,1])

TRV tedy příkaz přijalo a stav reportovalo zpět.

Online režim se řešil přes online_set (0x0173), online (0x0473) a EP3 switch. Po sjednocení byly kuchyň i ložnice nastavené stejně (online = 1, EP3 ON), ale shodné diagnostické hodnoty nevysvětlily, proč ZHA switch funguje jen u některého kusu.

Zlom

U jedné z nefunkčních proběhlo Reconfigure → odebrání zařízení → nové spárování. Home Assistant zařízení poznal podle stejného IEEE a obnovil stejné entity i entity ID – po re-pairu tedy není nutné entity znovu vytvářet ani přejmenovávat. Po novém spárování začal Child lock switch fungovat.

To ukazuje, že problém nebyl v HW, modelu ani firmwaru, ale ve stavu / inicializaci zařízení v ZHA nebo v napojení clusteru a quirku po původním interview. Test: opravená hlavice ponechána bez zásahů. Když Child lock funguje i po delší době a spánku TRV, padá podezření na chybný původní interview. Když přestane, je potřeba porovnat debug funkčního a nefunkčního stavu na cestě ZONNSMARTChildLock → ZONNSMARTManufCluster a stav online_set / sleep.

Vedlejší úprava

Generické názvy spínačů se přeložily přes customize_glob, aby platily pro všechny shodné TRV: Boost (rychlé přitopení), Dětský zámek, Online režim. Samotný quirk kvůli názvům měnit netřeba.

Tlačítko IKEA SOMRIG (19. října 2025)

Tlačítko IKEA of Sweden SOMRIG shortcut button má dvě tlačítka, každé na vlastním endpointu, a používá vlastní ShortcutV2Cluster (64640). Bez device handleru z něj ZHA nedostane použitelné automation triggery.

Řešení

Custom device (CustomDevice) s podpisem dvou endpointů (profil 260, device type REMOTE_CONTROL). replacement dosadí PowerConfig1AAACluster a ShortcutV2Cluster. Klíčem jsou device_automation_triggers – každé z obou tlačítek (endpoint 1 a 2) mapuje pět akcí:

device_automation_triggers = {
    (PRESSED, BUTTON_1): {ENDPOINT_ID: 1, COMMAND: COMMAND_M_INITIAL_PRESS},
    (SHORT_PRESS, BUTTON_1): {ENDPOINT_ID: 1, COMMAND: COMMAND_M_SHORT_RELEASE},
    (DOUBLE_PRESS, BUTTON_1): {ENDPOINT_ID: 1, COMMAND: COMMAND_M_MULTI_PRESS_COMPLETE},
    (LONG_PRESS, BUTTON_1): {ENDPOINT_ID: 1, COMMAND: COMMAND_M_LONG_PRESS},
    (LONG_RELEASE, BUTTON_1): {ENDPOINT_ID: 1, COMMAND: COMMAND_M_LONG_RELEASE},
    # totéž pro BUTTON_2 na ENDPOINT_ID: 2
}

Po nasazení quirku vystaví ZHA pro obě tlačítka triggery stisk, krátký a dlouhý stisk, uvolnění i dvojstisk, na které se pak váží automatizace.

_Každá sekce nese datum, kdy případ vznikl; poslední aktualizace textu je červenec 2026._