Universal Tuya docsHomeSupported devicesRequest a deviceFAQChangelogArchitectureKnowledge baseCreditsSourcesContributing

How other apps handle unknown commands, fallbacks, polling, magic packets, time sync and reporting (P3017)

Studied 2026-10-24 (Europe/Paris). Facts are rewritten in our own words; no code was copied. Commit and branch pointers are in KB_SOURCES.md.

projectunknown / unsupported commandsfallbackspollingmagic packet / dataQuerytime syncreporting quirkswhat we adopted (where)
Zigbee2MQTT / zigbee-herdsman-convertersUnknown DP: logged with type and value (tuya.ts "datapoint not defined"). Private chatter is dropped with fz.ignore_* convertersOne converter per model. Generic tuya.fz.datapoints + tuyaDatapoints lookup per coupleonEvent poll for TS011F/metering when the device does not report (interval option)configureMagicPacket (Basic read of 0x0004/0x0000/0x0001/0x0005/0x0007/0xFFFE) and dataQuery 0x03 at configureanswers mcuSyncTime (0x24) with UTC + local seconds; some models also need a periodic pushtuya.configureMagicPacket before binding. Reporting is skipped on models that reject itDP-name catalogue (604 couples) → semantic in the interpreter; ignore rules; magic-query tier; poll tier
ZHA (zha-device-handlers, zha)Quirks remove unsupported attributes and clusters (quirks v2 .removes()), Tuya private clusters typed (0xE000/0xE001/0xED00)TuyaNewManufCluster maps DP → attribute. Data-point handlers fall back to the raw valuepoll_control. HA polls the "main" attribute when reporting failsTuyaQuirkBuilder.tuya_enchantment() = the same Basic magic readtime request answered by TuyaTimePayloadSame TSN on button frames is sent twice: the quirk keeps the first oneTSN dedup (UnknownCommandEngine), 0xFC value 2 = stop/release, E001 setOptions1-3, private cluster catalogue
deCONZ (DDF)Unknown attribute logged in debug. Items without a parser are not exposedPer-item read function: zcl:attr, tuya, ias:zonestatus with explicit fallback itemsrefresh.interval per item (seconds), i.e. read on a timer when no report arrivesDDF "md:" + Tuya "tuya" read on jointuya time itemPer-item "refresh.interval" replaces broken reportingOrdered read tiers + timer re-read (poll tier); bounded intervals (backoff)
tuya-local / localtuya / hass-localtuya / tinytuya (Wi-Fi)Unknown DPs exposed as raw entities with their type (tuya-local "unsupported" list, localtuya config UI)Per-device YAML DP maps with alternative DP ids per productHeartbeat + updatedps / DP refresh when values go staleDP_QUERY (0x0A) / UPDATEDPS (0x12), the Wi-Fi twin of Zigbee dataQuery 0x03— (cloud time)Devices only send changed DPs; a refresh is needed after connectUnknown DP kept with type in the interpreter; dataQuery after startup; per-couple DP maps
Hubitat (kkossev drivers)Unknown clusters/commands logged with logDebug "unprocessed"; DP table per modelModel profiles with fallbacks to generic Tuya handlingrefresh() + health check (ping) every N minutes, offline after 3 missesTuya magic spell (Basic attributes read) on configureanswers 0x24 time requestconfigure() falls back to polling when bind/report failsHealth-check style re-probe with bounded backoff, 2-timeout demotion
SmartThings Edge (SmartThingsEdgeDrivers)Unhandled messages ignored silently; per-fingerprint sub-driversSub-driver can_handle chain: the first match wins, default handlers afterhealth check: read the main attribute when no report for a periodTuya sub-drivers send the magic readTuya sub-drivers answer time requestsconfigure with a default reporting config; polling when the device lacks reportingRemembered winner per device (first working method sticks)
ioBroker.zigbeeUses Z2M converters; unknown keys shown as raw statesSame as Z2MPolling option per deviceSame as Z2MSame as Z2MSame as Z2M(via Z2M)
Domoticz / Domoticz-ZigbeeUnknown cluster/attribute logged, "Unknown" widget in debugPer-model JSON configPolling per cluster (PollingSomeOnOff, etc.)Tuya magic in model configTuya time answeredReporting re-armed periodicallyPer-cluster polling as fallback tier
Tasmota (Zigbee2Tasmota)Every unknown attribute is logged raw {"0006/F000":...} with typePlugin files (.zb) map attributes; raw otherwiseZbRead on a timer via rulesZbSend Basic read on demandAnswers Time cluster readsZbConfig reporting; falls back to rules pollingRaw cluster/attr in the unknown pattern (f:epX:0xCCCC:cmd:payload) and diag
ESPHome (tuya component)Unknown DPs logged with type and raw value at bootExplicit DP mapping per componentupdate_interval pollingHeartbeat + DP query (QUERY_DATAPOINTS) at startMCU time sync (time_id)—DP query at startup = magic-query tier
Johan Bendz app (+ forks)Unknown frames end up in the SDK default response; issues report DP logs (e.g. #619)One driver per model, DP switch/caseSome drivers poll electrical attributesSome drivers read Basic attributesSome TRVs answer time sync—Couple-exact decoders sourced from issues (#619)

Adopted, with the place in our code

  1. Ordered method chain with failover and remembered winner: lib/zigbee/MethodChain.js (Z2M/ZHA/deCONZ/SmartThings).
  2. Re-probe with bounded backoff (15 min → 24 h) and timeout demotion after 2 misses: MethodChain (kkossev health check, deCONZ refresh.interval).
  3. Magic-query tier (dataQuery 0x03 / queryAllDatapoints) only on EF00 devices: MethodChain.standardReadSteps (Z2M, ESPHome, tuya-local).
  4. Derived values from sibling capabilities as the last tier, never written back: MethodCoverage.DERIVED.
  5. TSN dedup of repeated button frames: UnknownCommandEngine.handleFrame (ZHA).
  6. DP-name catalogue per couple → semantic: lib/zigbee/data/unknown-dp-catalog.json + UnknownCommandInterpreter step 1b (Z2M tuyaDatapoints).
  7. Unknown kept with type and raw payload, plus a teach action: UnknownCommandFlowCards (tuya-local, Tasmota, ESPHome).
  8. Clear "not an error" log for frames the SDK cannot parse but we forward (EF00, Tuya Basic): ZclFrameHeader.describeFrame (Z2M ignore converters, #560 logs).

P3019 review of the "not applicable" cells (2026-10-24)

Every n/a cell of METHOD_COVERAGE.md was checked again for a real, sourced use. Where one exists it is added as an optional extra layer: never needed at pairing, removes nothing, and the old path stays first.

familymethodchangesourceour code
Buttons and remotesM3 private-cluster readn/a → yesZ2M TS004F tuyaOperationMode (attr 0x8004 on genOnOff), ZHA TuyaSmartRemoteOnOffClusterlib/buttons/attachButtonPaths.initModeForNewDevice
Buttons and remotesM9 attribute write instead of a commandn/a → yessame (write 0x8004 to switch event/dimmer mode)lib/zigbee/DeviceOperatingMode.writeOperationMode
Garden valvesM10 manufacturer-specific writen/a → yes (opt-in setting)Z2M tuya.ts HZ-WT02 (_TZ3000_kz1anoi8 TS0049): cluster 0xE001 command 0xFE, payload 0x0B + countdown seconds (u32 BE)lib/tuya/Ts0049Countdown.js, water_valve_garden setting ts0049_water_countdown

Kept n/a, with the reason in METHOD_COVERAGE.md: M7 everywhere (deriving alarm_battery from measure_battery would put both capabilities on one device, which the project forbids); soil M8 (writing calibration through two paths risks a double offset); contact/water/smoke M8–M9 (sensors only, nothing to write); M10 for DIN meters, sirens, fans, TRVs and locks (no sourced private write found in Z2M, ZHA, deCONZ, kkossev or SmartThings Edge).

Writing through another endpoint: evaluated, not added. The only safe case would be a single-gang device whose command lands on a different endpoint than the one it reports on; no source shows such a device needing it, and on multi-gang devices it could switch the wrong gang.

Ideas logged by the daily KB refresh

dateidea (our words)sourcestatus
2026-10-25Write before the first report: if a DP was never seen, pick its wire type from the function (speed = value, oscillation = bool) and show the requested state optimistically until the device echoes itesphome/esphome#18525 (bkbartk)idea only; our chain already re-reads after a write
2026-10-25RSSI packed in a long raw DP is a signed int8make-all/tuya-local 0002e83 (K-Rain KRX8, Wi-Fi)rule noted; apply when a Zigbee raw block with RSSI is sourced

← Knowledge base index · source