Skip to content

TS004F existing smart-knob identities — qja6nq5z + 4fjiwweb separate gesture validation #1389

Open

Description

@migueleap

Prerequisites:

Before requesting a device addition, please ensure there is not already a request for the device among the open issues.

Make sure your Homey is upgraded to firmware v5 or higher.

You need a physical example of the device.

Device Information

Device Name: Tuya Smart Knob Switch

Device Model: TS004F

Device Description:
Smart Zigbee knob with tap, double tap, triple tap, long press and rotation gestures (clockwise / counter‑clockwise).
Homey currently identifies the device but does not expose any of the gesture capabilities.

Device Images:

Image Image

Device Interview

{
  "ids": {
    "modelId": "TS004F",
    "manufacturerName": "_TZ3000_qja6nq5z"
  },
  "endpoints": {
    "ieeeAddress": "6c:e4:a4:ff:fe:57:6f:26",
    "networkAddress": 40439,
    "modelId": "TS004F",
    "manufacturerName": "_TZ3000_qja6nq5z",
    "endpointDescriptors": [
      {
        "status": "SUCCESS",
        "endpointId": 1,
        "applicationProfileId": 260,
        "applicationDeviceId": 260,
        "inputClusters": [0,1,3,4,6,4096],
        "outputClusters": [25,10,3,4,5,6,8,4096]
      }
    ],
    "deviceType": "enddevice",
    "receiveWhenIdle": false
  }
}

Additional Comments

Homey identifies the device correctly as TS004F, but no gesture events are exposed (tap, double tap, triple tap, rotation).

This fingerprint _TZ3000_qja6nq5z is not included in the current driver:
drivers/smart_knob_switch/driver.compose.json

Other TS004F variants have been added previously and their issues were closed:

#441

#443

#595

This variant appears to use a different Tuya implementation and does not expose EF00 in the interview, so gesture mapping may require custom handling.

How to interview a device

Add the device as a generic Zigbee device in Homey

Navigate to https://developer.athom.com/tools/zigbee

Interview the device (button to the right of the device in the list)

Click the copy button/icon to capture the device information

Paste the copied information above

Note: To be able to add more devices to the Tuya Zigbee app, we rely on community members like you to provide interviews of the devices you want to be added. Thank you for your contribution.

Activity

  1. dlnraja commented on May 31, 2026

    @dlnraja

    I see these fingerprints are mapped in the Tuya Unified Zigbee app(https://github.com/dlnraja/com.tuya.zigbee) v8.1.53: _TZ3000_qja6nq5z+TS004F → smart_knob, _TZ3000_ → button_wireless, custom → generic_diy, example → radiator_controller.

    Grab it here: https://homey.app/a/com.dlnraja.tuya.zigbee/test/

    Remove and re-pair after installing. If something's off, drop a diagnostic report ID on the forum thread.

  2. dlnraja commented on Jun 29, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.147:

    • _TZ3000_qja6nq5z -> button_wireless

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  3. dlnraja commented on Jun 29, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.147:

    • _TZ3000_qja6nq5z -> button_wireless

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  4. dlnraja commented on Jun 29, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.147:

    • _TZ3000_qja6nq5z -> button_wireless

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  5. dlnraja commented on Jun 29, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.147:

    • _TZ3000_qja6nq5z -> button_wireless

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  6. dlnraja commented on Jul 2, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.165:

    • _TZ3000_qja6nq5z -> smart_knob_rotary

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  7. dlnraja commented on Jul 2, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.167:

    • _TZ3000_qja6nq5z -> smart_knob_rotary

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  8. dlnraja commented on Jul 5, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.190:

    • _TZ3000_qja6nq5z -> smart_knob_rotary

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  9. migueleap commented on Jul 6, 2026

    @migueleap
    Author

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.190:

    • _TZ3000_qja6nq5z -> smart_knob_rotary

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/ Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

    Hi @dlnraja,

    Thank you for adding support for this model!

    I have tested it using the latest test version of the Unified Smart Home Engine app, but unfortunately, it is still not working.

    When I pair the device, it is recognized, but when I press the physical button or try to interact with it in Homey, nothing happens. Instead, a red error bar pops up in the Homey app with a warning triangle and an exclamation mark inside, showing the following message:

    Missing Capability Listener: button.press

    I have also tried switching the device between "Scene Mode" and "Dimmer Mode" (by triple-clicking the button, which makes the back green LED light up for a second) and pairing it again, but the result is exactly the same. It seems the driver is missing the listener to handle the button press events for this specific manufacturer ID (_TZ3000_qja6nq5z).

    Let me know if you need me to run any more tests or provide further logs!

  10. dlnraja commented on Jul 12, 2026

    @dlnraja

    Auto-resolved by Diagnostic Resolver

    All fingerprints in this issue found in Tuya Unified Zigbee v9.0.192:

    • _TZ3000_qja6nq5z -> smart_knob_rotary

    Install: https://homey.app/a/com.dlnraja.tuya.zigbee/test/
    Remove and re-pair your device after installing.

    Troubleshooting: https://github.com/dlnraja/com.tuya.zigbee/wiki/Troubleshooting

    Detected protocols: zcl

  11. JohanBendz commented on Sep 30, 2026

    @JohanBendz
    Owner

    2026 backlog triage: duplicate #1420 is another physical _TZ3000_qja6nq5z / TS004F MOES Smart Knob (ERS-10TZBVX-AA) with the same endpoint profile. Keeping #1389 canonical because it also contains the historical behavior discussion. Current 0.3.1 includes this fingerprint but still needs physical verification.

  12. changed the title [-]Device Request – Tuya Smart Knob Switch – _TZ3000_qja6nq5z / TS004F[/-] [+]TS004F existing smart-knob identities — qja6nq5z + 4fjiwweb separate gesture validation[/+] on Oct 3, 2026
  13. JohanBendz commented on Oct 3, 2026

    @JohanBendz
    Owner

    Batch 107 — two separately interviewed TS004F identities ALREADY matched in our app, individual physical action verification pending (2026-10-03)

    Keep this still-OPEN canonical as existing-driver behavior/physical acceptance, NOT an unsupported fingerprint implementation ticket, for TWO physical Homey interview sources:

    • Original TS004F existing smart-knob identities — qja6nq5z + 4fjiwweb separate gesture validation #1389 MOES rotary smart knob _TZ3000_qja6nq5z / TS004F: EP1 input [Basic0, Power1, Identify3, Groups4, OnOff6, Touchlink4096], output including [OTA25, Time10, Identify3, Groups4, Scenes5, OnOff6, Level8, Touchlink4096]. Reporter describes single/double/triple click, long-press and clockwise/counterclockwise gestures and Scene versus Dimmer Mode switch. One contributor physically tested a DIFFERENT app/fork and observed "Missing Capability Listener: button.press" on that app; this is not proven a bug in our frozen smart_knob_switch runtime, so preserve the user report as an external warning / validation lead, not a claimed fix.
    • New source #1269, SHUAIGUO smart knob/button _TZ3000_4fjiwweb / TS004F: separately FULL original physical Homey EP1 appDeviceId260 input the same core [0,1,3,4,6,4096], output [25,10,3,4,5,6,8,4096]. The retail description "Zigbee Smart Button" by itself does NOT establish that every rotary or triple-click action is physically emitted by this unit; capture actual supported actions individually. Prior alternative-fork auto-comments repeatedly change driver classification and are NOT authoritative for this repo.

    Exact generated-manifest verification Batch107: BOTH literal manufacturer pairs already belong to the SAME existing smart_knob_switch Compose driver on BOTH frozen modernize-2026-issues v0.3.1 and develop-0.4. Neither needs a new identity merely to pair. Independently public 0.3.1 or subsequent 0.4 Test: physically re-pair, gather raw button/rotation command/endpoints, supported single/double/triple, hold/release, cw/ccw as genuinely emitted; validate no missing capability listener in OUR app, Flow-event mapping, command mode vs scene mode, deduplication and battery. For #1269 don't invent features absent from hardware. Keep user history/diagnostics in source.

    Important exclusion: #1079 is the SEPARATE missing-pairing/validation issue for _TZ3000_402vrq2i and _TZ3000_gwkzibhs (absent from frozen/current manifests), not this existing-code regression ticket. #1365 _TZ3000_kaflzta4 / TS004F is another physically different SINGLE scene button with additional E001/57345 and different command outputs, also separate. #1418 four-endpoint TS0044 frame-dedup bug stays separate. Source #1269 may close duplicate PARALLEL TRACKING only after full exact-row preservation + backlinks; existing pairing does NOT establish actions physically pass. No app code, release or branch changes.

  14. added
    bugSomething isn't working
    and removed on Oct 8, 2026
  15. JohanBendz commented on Oct 8, 2026

    @JohanBendz
    Owner

    0.3.3 physical regression report / root cause confirmed

    A user running 0.3.3 reports that _TZ3000_qja6nq5z / TS004F stopped working after the recent updates. This is now a confirmed existing-driver regression, not a new-device request.

    Root cause is the 2026-09-30 smart-knob refactor (9045a3c, fix(knob): use bound clusters for press and rotation). The refactor correctly moved On/Off and Level Control handling to BoundCluster, but then fetched the raw Homey Zigbee node and replaced node.handleFrame for the legacy Color Control path.

    Athom zigbee-clusters@2.4.1 creates ZCLNode by assigning node.handleFrame = this.handleFrame.bind(this). Replacing that function after ZCL initialization bypasses ZCLNode entirely, so the On/Off and Level Control bound clusters never receive their frames.

    Fix now applied to release-0.3.3, develop-0.4 and develop-0.4.1:

    • preserve the existing ZCL handleFrame function;
    • forward every non-Color-Control frame to it;
    • intercept only cluster 0x0300 for the existing legacy hold-left/hold-right raw parsing;
    • add regression coverage that requires the raw wrapper to forward back into ZCL.

    This preserves the intended bound-cluster migration while retaining the legacy Color Control path. 0.3.3 CI is running again; keep this issue open until _TZ3000_qja6nq5z is physically re-tested on the corrected build.

  16. JohanBendz commented on Oct 8, 2026

    @JohanBendz
    Owner

    Validation update:

    • corrected release-0.3.3 source: full CI SUCCESS (run 37817204977);
    • develop-0.4: full CI SUCCESS (run 37817221163);
    • develop-0.4.1: full CI SUCCESS (run 37817242501).

    Because 0.3.3 is already in users' hands, the distributable hotfix will be 0.3.4 built from the pre-regression-fix 0.3.3 release baseline, not a silent replacement of 0.3.3.

  17. JohanBendz commented on Oct 8, 2026

    @JohanBendz
    Owner

    0.3.4 hotfix branch and validation PR are now prepared from the actual published 0.3.3 baseline (130854f).

    • branch: release-0.3.4
    • PR: Hotfix 0.3.4: restore Smart Knob Switch actions #1525
    • runtime diff: only drivers/smart_knob_switch/device.js
    • regression coverage updated in test/repository.test.js
    • package/Composer/generated manifest versions aligned to 0.3.4
    • 0.3.3 changelog kept faithful to the published curtain hotfix; 0.3.4 gets the Smart Knob fix entry.

    Awaiting the full publish-validation workflow on the exact 0.3.4 head.

  18. JohanBendz commented on Oct 8, 2026

    @JohanBendz
    Owner

    0.3.4 release CI is GREEN at 21b60ce (run 37817724828).

    The hotfix is ready for Test publication. No re-pair should be required for existing smart_knob_switch devices because the driver manifest already included On/Off and Level Control bindings before this regression; the bug was in local frame dispatch after app startup.

    Physical acceptance request for _TZ3000_qja6nq5z / TS004F: verify press, clockwise, counter-clockwise and press+rotate/hold actions on 0.3.4. Keep this issue open until confirmed.

  19. JohanBendz commented on Oct 26, 2026

    @JohanBendz
    Owner

    0.3.4 Homey Test feedback, Oct 18 (Cam), and 0.4.0 targeted repair

    New physical regression report for exact _TZ3000_qja6nq5z / TS004F: In 0.3.4, top-button Flow execution works when played manually, but pressing the hardware button can activate the same Flow more than once (light fades on then off); dial rotation no longer fires. This supersedes the earlier assumption that the 0.3.4 frame-forwarding hotfix fully restored actions. Keep issue OPEN.

    Source review of actual zigbee-clusters@2.4.1 and historical 0.2.76 driver:

    1. Standard Level Control step carries mode, while move carries moveMode. The current bound-cluster callback used payload.mode for both and silently treated missing mode as clockwise.
    2. The exact TS004F hardware family also emits proprietary On/Off 0xFC rotation (0 right/1 left) and 0xFD press variants (0/1/2) in its other operation mode. Stock OnOffCluster has no 0xFC/0xFD commands; forwarding those frames into ZCL does not yield knob Flow actions. Independent physical source: https://forum.phoscon.de/t/moes-tuya-zigbee-smart-knob/3331.

    Implementation: PR #1537 merged into frozen develop-0.4. It restores the two exact 4-byte proprietary On/Off frame paths, uses the correct mode/moveMode per command, rejects unknown directions, and preserves the original ZCL forwarding, old Color Control raw path, Flow IDs, and current 250ms press-only duplicate suppression. It includes behavioural regression tests for Scene Mode, standard step/move, invalid frames and forwarding; full CI passed. 0.4.0 release integration PR #1539 is under validation.

    Acceptance still PENDING (do not close): The extra press may come from a sequence of events >250ms apart; we do not yet have the actual paired-device frame timestamps/cluster IDs/commands to establish the cause. Rather than invent a longer debounce that could suppress intentional quick clicks, gather 0.4.0 Homey Test results in both Scene and Dimmer modes:

    • one physical click, double click, long click: count and timing of exact Flow triggers;
    • unpressed clockwise/counter-clockwise rotation, multiple rapid steps;
    • press+rotate/hold-left/hold-right;
    • if still double-firing, sanitized raw Zigbee command IDs and approximate timestamps (avoid publishing private IEEE addresses).
      Any needed follow-up belongs to a narrowly scoped 0.4.x Test correction, not an untested global Zigbee change.

    The 0.3.3 curtain regression and 0.3.4 ZCL forwarding correction remain intact; main and published Homey Test remain unchanged at this checkpoint.

  20. JohanBendz commented on Oct 26, 2026

    @JohanBendz
    Owner

    Reviewed 0.4.0 correction carried forward to 0.4.1 (2026-10-26)

    PR #1541 is merged into develop-0.4.1 at 4ba407b. The Smart Knob runtime is exactly the already reviewed PR #1537 / 0.4.0 blob 03804baae3b09d499cdfc8ef206f68d8ac99f359: Scene Mode 0xFC/0xFD routing and the correct Step mode / Move moveMode fields. Existing Flow IDs, Color Control holds, normal ZCL forwarding and 250 ms press-only suppression are retained.

    The four original behavioral cases were imported unchanged, plus one real-Buffer case for scene actions, standard packets, metadata and unchanged bytes. Before the runtime carry-forward, three of the original four cases failed on the 0.4.1 source. All five now pass; full suite: 204 tests, 201 pass, 0 fail, 3 existing TODO. PR CI and merged-head CI passed through Compose reproducibility and Homey publish validation.

    Keep #1389 OPEN. Both operation modes, gesture/Flow counts and each exact manufacturer remain physical public-Test acceptance work. The reported extra press in a longer-than-250 ms sequence remains unproven; this carry-forward adds no guessed debounce interval and no #1079 identities. No Store publication or main/dev/develop-0.4 change occurred in this batch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions