Universal Tuya docsHomeSupported devicesRequest a deviceFAQChangelogArchitectureKnowledge baseCreditsSourcesContributing

Unknown commands, clusters and DPs: what they mean and how we handle them (P3016)

All text below is rewritten for this project. Sources are credited per row; nothing is copied.

Pipeline

BoundCluster unknown cmd ─> UnknownCommandSink.record ─┐
                                                       ├─> UnknownCommandEngine
Tuya DP not mapped ─────> UnknownDPLogger.logUnknownDP ┘        │
                                                                ├─ UnknownCommandInterpreter
                                                                │    1. exact per-couple decoder (COUPLE_DP)
                                                                │    2. exact ZCL / Tuya frame decoders
                                                                │    3. family decoders (button / meter / thermostat / radar)
                                                                │    4. heuristics by wire type (low confidence)
                                                                ├─ UnknownLearning (per device, 40 patterns, LRU, store key unknown_learned)
                                                                └─ Flow cards (only when declared in the manifest)

Harvest: commands observed in this project (diag mails, logs, repo data)

Command / DPDevices (couple)MeaningSourceImplemented?
EF00 DP6 raw, 8 bytes_TZE284_6ocnqlhn / TS0601 (Tongou TO-Q-SYS-JZT, din_rail_meter)Phase struct: V = u16 BE / 10, I = u24 BE mA, P = u24 BE W. Sample 098a0007fb0001a1 decodes to 244.2 V, 2.043 A, 417 WZ2M tuya.ts [6, null, tuya.valueConverter.phaseVariant2] for this couple; Homey diag mails 09-10/2026Yes, exact. Also fixed in DpByteArrayProfiles.parseTongouToqSysJztDp6, which used a wrong 7-byte layout
EF00 DP36 uint8 0/1wall_thermostat couplesrunning_state heat/idle. The polarity differs per coupleZ2M tuya.ts uses both lookups ({idle:1,heat:0} and {heat:1,idle:0})Family decoder (state, 0.55). Already mapped in UnifiedThermostatBase
EF00 DP113/115/116/117 uint8, DP104 uint32, DP105presence_sensor_radar (couple not identifiable in diag)Radar parameter echoes (gates, thresholds, modes). They are re-sent every ~60 sZ2M tuya.ts radars MTD285-ZB / MTD085-ZB / ZY-M100 (DP1xx = settings)Family decoder (config_echo, 0.45). Already internal in presence_sensor_radar/configs.js. Flows fire only on change
genBasic 0x0000 cmd ? (EP1)radarTuya private basic report with no functionZ2M fz.ignore_basic_reportYes (ignore)
EF00 cmd 0x01/0x02/0x05/0x06smart_rcbo and all TS0601dataResponse / dataReport / activeStatusReport(Alt)Z2M zigbee-herdsman cluster manuSpecificTuyaYes, exact (dp)
EF00 cmd 0x11 / 0x13 / 0x15TS0601MCU version response / OTA block request / OTA resultzigbee-herdsman manuSpecificTuyaYes, exact (version, ota)
EF00 cmd 0x24TS0601 (clocks, TRVs, meters)mcuSyncTime: the device asks for the timezigbee-herdsman; Tuya Zigbee serial protocolYes, exact (time_request). Answered elsewhere (TuyaTimeSync)
EF00 cmd 0x25 / 0x60TS0601Gateway connection status request / weather requestzigbee-herdsman manuSpecificTuyaYes, exact
EF00 cmd 0x25 reply framing (2026-10-26 check)TS0601Our answer to the gateway-status request is a plain cluster command (no manufacturer code in the ZCL header) carrying 00 01 01 (size u16 = 1, status 1 = connected). Z2M sends the same bytes; ZHA now also sends it without a manufacturer code and puts the request's MCU sequence byte first instead of 00Z2M zhc 7462b54 tuya.ts (mcuGatewayConnectionStatus payloadSize 1 / payload 1); ZHA quirks d54cf9e zhaquirks/tuya/mcu (mcu_connection_status_rsp, manufacturer_code None, TuyaConnectionStatus tsn + LV status)Yes, aligned with Z2M. Echoing the sequence byte the ZHA way is a lead only, no field case yet
0xED00 segmented DP transfer (cmds 0x00-0x05)Moes ZM7LT3 _TZE284_cf4b5ktf, _TZE28C1000000_cf4b5ktf; ZM6LT1 _TZE284_2fnssffc, _TZE284_y7hpvgypLarge Tuya DP frames split over the Zosung cluster: chunks of 0x38 bytes with a per-chunk byte-sum check; once reassembled the payload holds packed DPs from offset 2 as dp, type, u16 BE length, data. 3-phase data DP is 18 bytes behind a 02 0f header; DP17 = alarm thresholds (id 1 over-current, id 3 over-voltage 230-300 V, id 4 under-voltage 90-190 V)Z2M zhc 7462b54 src/devices/moes.ts + src/lib/tuya.tsNot implemented (no Homey diag for these couples yet). Provisional tier; implement on master first with tests when a field frame arrives
0xED00smart_rcboZosung IR / Tuya private extra cluster, registered as ZosungIRTransmitClusterregisterClusters.js; Ef00OnlyInterviewLogged; heuristic only
genOnOff 0xFD [0/1/2]TS0041/42/43/44, TS004F, scene remotesTuya button press: single / double / hold. Endpoint = buttonZ2M fz.tuya_on_off_action (tuyaAction); ZHA TuyaSmartRemote quirksYes, exact (0.95)
genOnOff 0xFC [0/1]TS004F knobs (scene mode)Rotate right / leftZ2M fz.tuya_multi_action (tuyaAction2)Yes, exact
genOnOff 0x00/0x01/0x02/0x40/0x41/0x42remotes in command modeoff / on / toggle / offWithEffect / onWithRecall / onWithTimedOffZCL spec 3.8Yes, exact
genLevelCtrl 0x00-0x07dimmer remotes, TS004F command modemoveToLevel = value, move = hold, step = rotate, stop = releaseZCL spec 3.10; Z2M fz.command_move/step/stopYes, exact
genScenes 0x05 recallscene remotes (TS0044 scene mode, Lidl)Recall: group u16 LE + scene u8ZCL spec 3.7; Z2M fz.command_recallYes, exact. Mapped with ButtonEventRouter.sceneToButton
lightingColorCtrl 0x01/02/04/05/08/09/0A/41/42/47/4B/4CRGB/CCT remotesHue/sat/color/temp move and step. Mode 1 = up, 3 = down, 0 = stop. 0x47 = stopMoveStepZCL spec 5.2Yes, exact (mode-bearing commands). Moves with X/Y rates are read as long/rotate at 0.6
E000 0xF7/0xF8/0xFBTuya switches (manuSpecificTuya4)Random timing / cycle timing / inching echoZ2M tuya.ts manuSpecificTuya4Yes (config_echo)
E000 otherTS0042/TS0046 (ZHA TuyaZBE000Cluster)Private button event. The press byte layout is not confirmedZHA quirks tuya ts0042/ts0046Heuristic (0.45)
E001 attr 0xD030Tuya switch modulesExternal switch type: 0 toggle, 1 state, 2 momentaryZHA TuyaZBExternalSwitchTypeClusterAlready handled by switch drivers (config)
genOnOff 0xFC [2]TS004F knobs (scene mode)Rotation stopped (release)ZHA TuyaSmartRemoteOnOffCluster rotate_type 2 = stopYes, exact (release, 0.9) — P3017
genOnOff 0xF0Tuya switchestuyaCountdown echoZ2M tuya.ts genOnOff privateYes (config_echo) — P3017
genLevelCtrl 0xF0Tuya dimmersmoveToLevelTuya: level u16 LE + transition timeZ2M tuya.ts genLevelCtrl privateYes, exact (value) — P3017
lightingColorCtrl 0xE0/0xE1/0xF0/0xF9/0xFA/0xFBTuya RGB/CCT bulbs (TS0505B…)min brightness / hue+sat+brightness u16 LE / RGB mode / power-on state / do-not-disturb / on-off transition (BE u24)Z2M tuya.ts lightingColorCtrl private commandsYes, exact (0xE1 decoded, others config_echo) — P3017
E001 0xE5/0xE6/0xE7Tuya switches (manuSpecificTuya3)setOptions1/2/3 echoZ2M tuya.ts manuSpecificTuya3Yes, exact (config_echo) — P3017
genBasic 0xF0many Tuya devicestuyaSetup, no functionZ2M fz.ignore_* / tuya.ts genBasicYes (ignore) — P3017
0xE002 / 0x1888 (any cmd)climate sensors (E002), unknown 0x1888 vendorE002 = alarm thresholds; 0x1888 not documentedZ2M manuSpecificTuya2 (E002); 0x1888: no sourceconfig_echo 0.4 (opaque) — P3017. 0x1888 is an open lead
EF00 DP101 enum 0/1/2_TZ3210_cwamkvua TS0202 (LKMSZ001)Scene button single/double/holdJohanBendz#619Yes, exact (couple) — P3017
EF00 DP102 enum 0/1_TZ3210_cwamkvua TS0202Illuminance dark / brightJohanBendz#619Yes, exact (couple) — P3017
EF00 any DP on 604 known couplesall TS0601 couples in Z2M tuyaDatapoints / project researchDP name → semantic (press / state / alarm / config / measure, gang suffix)Z2M tuyaDatapoints (zigbee-herdsman-converters @eb823146c7) + data/dp_couple_knowledge.jsonCatalog step (0.85, exact semantic) — P3017
EF00 cmd 0x02 shown as "unknown cmd" in logsall TS0601 (#560 log)dataReport; the SDK cannot parse it, we forward it to the DP pathzigbee-herdsman manuSpecificTuyaLog now says "forwarded to EF00 DP path (not an error)" — P3017

Rules for adding a decoder

  1. A decoder is exact only when a converter or spec row confirms it for that couple or cluster. Add it to COUPLE_DP (DP) or to the frame decoders (cluster). Add a unit test with a real sample.
  2. Family decoders cover device classes. Keep their confidence below 0.75.
  3. Heuristics stay at or below 0.4. Learning can reinforce a pattern, but it never overrides an exact decoder or a user-taught entry.
  4. Never invent manufacturer ids. Never move a couple between drivers here; one couple belongs to one driver.
  1. A user-taught mapping (Flow action "Teach unknown command") always wins. Remove it with "Forget unknown command".
  2. Repeated button frames with the same ZCL transaction number within 2 s count once (ZHA behaviour).

Leads (P3019 review, 2026-10-24)

Resolved, one reliable source each:

Still open (typed fallback kept: the frame is decoded by type, logged with raw payload, and can be taught):

The morning KB refresh keeps looking for both: scripts/kb/open-leads.js (run by scripts/kb/refresh.sh) greps every mirror with the patterns and web queries in data/leads/open-protocol-leads.json and flags files not yet read.

See also CROSS_APP_METHODS.md and METHOD_COVERAGE.md.

Harvest log

Credits

Koenkk/zigbee2mqtt and zigbee-herdsman-converters (tuya.ts, fromZigbee), zigpy/zha-device-handlers (tuya quirks), the ZCL specification r8 (Connectivity Standards Alliance), and the Tuya Zigbee serial protocol docs. Field diagnostics come from Homey users (anonymised).

← Knowledge base index · source