Skip to content

Secondary MCU (Tuya MCU over UART), AVATTO ZDMS16-2 dimmer - #558

Open
patapovich wants to merge 1 commit into
romasku:mainfrom
patapovich:secondary-mcu-dimmer
Open

patapovich wants to merge 1 commit into
romasku:mainfrom
patapovich:secondary-mcu-dimmer

Conversation

@patapovich

Copy link
Copy Markdown

This continues #484 by @charliesjc, with work from @Gabrielguadag, flattened into one commit on top of current main and extended. Both are co-authors of the commit. #484 has been quiet since September and no longer merges cleanly, so I'm opening this as its successor; if you would rather continue in #484, I'm happy to close this one.

What it does

Many TS0601 boards have a second microcontroller that drives the outputs and reads the inputs; the Zigbee module only talks to it over UART with the Tuya MCU protocol. This adds that link and maps Tuya datapoints to standard Zigbee clusters, configured from the config string (tokens documented in docs/contribute/porting.md):

  • UART link: one frame in flight with an ack timeout and a write queue, reports with several DPs, status dumps larger than 64 bytes, resync on damaged frames, UART reinit when writes keep failing. The module starts the conversation after boot, because not every MCU asks for the network status.
  • Relays (RT), touch/scene keys as switch inputs (ST), power-on behaviour (PT), datapoints written at boot (IT), settings datapoints as Basic cluster attributes (dp_attributes in device_db.yaml).
  • Dimmers (DM, P, U, DR) on the Level Control cluster: on, off, move, step, move to level, OnLevel.
  • MCU firmware version (Tuya command 0x0B) as a Basic cluster attribute, shown in Z2M as mcu_version.
  • Boards: AVATTO ZDMS16-2 (_TZE284_jtbgusdc, _TZE204_jtbgusdc), NovaDigital 6 gang (_TZE204_tdhnhhiy), NovaDigital TPZ-2 / Moes SFL02-Z-2 (_TZE200_hktk6hze).

Changes compared to #484

  • Dimmer: "on" goes to the MCU before the level, because the ZDMS16-2 MCU drops a level written while the channel is off. Levels are scaled to the MCU's min/max brightness in both directions. OnLevel is applied as soon as the wall switch turns the light on.
  • Move from a bound remote ramps in the firmware and Step changes the level once, with one write to the MCU in flight at a time. In Secondary mcu with dimmer support #484 a held remote was emulated with increments, which sometimes restarted the module.
  • Link: a command answered with the same command (e.g. the version query) frees the slot at once instead of waiting for the timeout.
  • Standard Tuya dimmer DPs by default (1–5, 7–11, power-on 14), so the ZDMS16-2 config is jtbgusdc;TS0601-ZDMS16-2;DM2;M;. P and U still override.
  • The ZDMS16-2 model token is TS0601-ZDMS16-2 instead of plain TS0601, which made the generated converter claim every TS0601 without a fingerprint definition.
  • stock_converter_manufacturer/stock_converter_model are AVATTO/ZDMS16-2, the stock Z2M definition of this board; TS0601_switch never got the OTA extension, so the update from stock was not offered.
  • _TZE204_jtbgusdc is the same board and has its own entry.
  • The module button of a dimmer module resets the device.
  • Docs: the secondary MCU tokens, dp_attributes, and the changelog entry moved under Upcoming.

Related PRs

Tested

  • Four AVATTO ZDMS16-2 (two _TZE284_jtbgusdc, two _TZE204_jtbgusdc) updated from stock with Z2M OTA, in daily use since 2026-11-16: wall switch, control from Z2M and Home Assistant, OnLevel, power-on behaviour, min/max brightness. After the update from stock, the device needs a reconfigure in Z2M so the reporting binds are made.
  • Compared with the stock firmware, the modules are much more stable, answer Zigbee commands faster and report state changes at once, including those made with the wall switch. The MCU acknowledges a datapoint write in 3–5 ms, and with OnLevel set, the wall switch turns the light on at that level without a round trip to the network.
  • The four dimmers run an earlier build of this branch, without the version query and with link diagnostics that are not part of this PR. On a bench unit with this exact build, mcu_version showed 1.0.7, and on, level and off from Z2M round-tripped through the MCU.
  • The NovaDigital boards come from Secondary mcu with dimmer support #484; I have not tested them myself.
  • pytest tests: 312 passed. Telink build of the ZDMS16-2 image in CI on my fork.

Open questions

  • Token naming: U (dimmer power-on DP) and PT (relay power-on DP) do the same job for different outputs, and IT uses the Tuya type numbers 1/2/4 while dp_attributes use B/E/V. Happy to unify them if you have a preference.
  • The UART link lives in src/zigbee/; it could move to src/base_components/.

Many TS0601 boards have a second microcontroller that drives the outputs
and reads the inputs; the Zigbee module only talks to it over UART with
the Tuya MCU protocol. This adds that link and maps Tuya datapoints to
standard Zigbee clusters, configured from the config string (tokens in
docs/contribute/porting.md):

- UART link: one frame in flight, ack timeout and write queue, reports
  with several DPs, status dumps larger than 64 bytes, resync on damaged
  frames, UART reinit when writes keep failing. The module starts the
  conversation after boot (not every MCU asks for the network status).
- Relays (RT), touch/scene keys as switch inputs (ST), power-on
  behaviour (PT), datapoints written at boot (IT), settings datapoints
  as Basic cluster attributes (dp_attributes in device_db).
- Dimmers (DM, P, U, DR) on the Level Control cluster: on, off, move,
  step, move to level, OnLevel. "On" goes to the MCU before the level,
  levels are scaled to the MCU's min/max brightness both ways, wall
  switch type and power-on behaviour from the MCU, OnLevel applied as
  soon as the wall switch turns the light on. Standard Tuya dimmer DPs by
  default (1..5, 7..11, power-on 14).
- MCU firmware version (0x0B) as a Basic cluster attribute, shown in Z2M
  as mcu_version.
- The module button of a dimmer module resets the device.
- Boards: AVATTO ZDMS16-2 (_TZE284_jtbgusdc, _TZE204_jtbgusdc), NovaDigital
  6 gang (_TZE204_tdhnhhiy), NovaDigital TPZ-2 / Moes SFL02-Z-2
  (_TZE200_hktk6hze).
- Stub tests for the link, the dimmer, DP attributes and the config.

Based on romasku#484 by charliesjc, with work by Gabrielguadag, flattened and
extended.

Co-authored-by: charliesjc <charliesjc@gmail.com>
Co-authored-by: Gabriel Guadagnin <gabrielguadag@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant