Universal Tuya docsHomeSupported devicesRequest a deviceFAQChangelogArchitectureKnowledge baseCreditsSourcesContributing

Button event router (P2926) — 2026-10-21

Goal

A button press must fire its Flow once, whatever path it arrives on.

Modules

Scene mode

Native paths

They are unchanged and stay mandatory. Nothing is removed, and no capability or couple changes.

Credits (rewritten, not copied)

P2926b — follow-up (2026-10-21)

  1. All 27 _triggerPhysicalFlow call sites in PhysicalButtonMixin now carry a path (tuya_fd, zcl_onoff, level_step, raw, raw_scene, scene_recall, multistate, ef00_dp, onoff_attr, e000, e001, emulated). A test fails if a new call site is left untagged.
  2. Custom drivers: smart_knob and smart_knob_switch already extend ButtonDevice (the coverage regex missed them). wall_switch_2gang_1way goes through the mixin gate. wall_switch_4_gang_tuya now tags ef00_dp.
  3. Bind on wake: on multi-endpoint pure remotes whose driver declares a native onOff binding, endpoints >1 get onOff.bind(). A failure re-arms the next wake window.
  4. Battery wake window: any received frame means the device is awake. Bind and the first-pair mode read run then, at most once every 6 h.
  5. DP cross-check: EF00 reporting/response DPs are recorded per mfr/pid/firmware (at most 5 identities × 32 DPs). If the profile declares dpButtons, an unexpected DP is logged. Record only, nothing fires.
  6. Backlight is already wired in UnifiedSwitchBase (backlight_mode → DP15 / onOff 0x8001). Scene DPs go through the ef00_dp path and the cross-check. No new DP number was invented.
  7. Scene recall (0x0005) in ButtonDevice goes through the router. A copy of a press already delivered by 0xFD or onOff is not fired again, and scene recall marks the mode as scene. 0xFD raw scene frames are tagged raw.
  8. Emulation: _finalizeClickDetection skips software double/triple once the device has sent that type natively. E001 0xD020=1 sets the relay_decoupled store and router flag (Z2M switch_mode scene).
  9. button_mode: onAdded flags new devices. For TS004F, 0x8004 is read (2.5 s timeout, Homey timer) and button_mode is set to scene or dimmer. On failure the fallback stays and the next wake retries. Existing devices never carry the flag.

Remaining

Coverage (node scripts/ci/button-path-coverage.js)

driverbasededuppaths
blaster_remotePhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
button_emergency_sosPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
button_wirelessButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_1ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_2ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_3ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_4ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_6ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_8ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_fingerbotPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
button_wireless_plugPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
button_wireless_sceneButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_smartButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_switchPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
button_wireless_usbPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
button_wireless_valveButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
button_wireless_wallButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
dimmer_wall_1gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
dimmer_wall_plugPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
dimmer_wall_switchPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
dimmer_wall_waterPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
handheld_remote_4_buttonsButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_button_emergency_sosButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_button_wirelessButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_button_wireless_fingerbotPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
remote_button_wireless_handheldButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_button_wireless_plugPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
remote_button_wireless_sceneButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_button_wireless_smartButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_button_wireless_usbPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
remote_button_wireless_valveButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_button_wireless_wallButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
remote_dimmerPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
scene_switch_1ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
scene_switch_2ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
scene_switch_3ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
scene_switch_4ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
scene_switch_6ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
scene_switch_6chButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
scene_switch_wallButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
smart_button_switchPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
smart_knobButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
smart_knob_rotaryPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
smart_knob_switchButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
smart_remote_1_buttonButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
smart_remote_1_button_2ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
smart_remote_4_buttonsButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
smart_scene_panelPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
switch_wallPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
switch_wall_5gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
switch_wall_6gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
switch_wall_7gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
switch_wall_8gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_remote_1_gangButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
wall_remote_2_gangButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
wall_remote_3_gangButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
wall_remote_4_gangButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
wall_remote_4_gang_2PhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_remote_4_gang_3ButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
wall_remote_6_gangButtonDevicerouter-dynamicdp_crosscheck, e000, e001, ef00_dp, level_step, mode_8004_d020, multistate, onoff_attr, raw, scene_recall, tuya_fd, unknown_capture, wake_bind, zcl_onoff
wall_switch_1_gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_1_gang_tuyaPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_1gang_1wayPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_2_gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_2gang_1wayPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_3_gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_3gang_1wayPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_4_gangPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_4_gang_tuyaPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_4gang_1wayPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_5_gang_tuyaPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff
wall_switch_6_gang_tuyaPhysicalButtonMixinrouter-dynamice000, ef00_dp, level_step, multistate, raw, tuya_fd, zcl_onoff

← Knowledge base index · source