[Device support change]: Handle truncated ac_frequency payloads for Tongou TO-Q-SYS-JZT (_TZE284_6ocnqlhn
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 15.7k
- Forks
- 2k
- Avg merge
- 18h 55m
- Merged PRs (30d)
- 35
Description
What happened?
There is an open bug report in zigbee-herdsman-converters (#12993) regarding erratic frequency spikes for the Tongou TO-Q-SYS-JZT meter.
After reviewing the history, PR #11875 previously removed the divideBy100 scaling factor to address a separate discussion (zigbee2mqtt #31603) where users complained about getting 0.5 Hz readings. However, removing the divisor broke standard readings (now spiking to 5000+ Hz).
The root cause is not the scaling factor itself, but an erratic behavior in how the Tuya MCU transmits the data packet for Datapoint 32:
- Standard Packet (95% of the time): Sends centihertz as a 4-digit integer (e.g.,
5001or4998). This requires thedivideBy100converter to display correctly as50.01 Hzor49.98 Hz. - Truncated Packet (Intermittent): When the grid frequency stabilizes exactly on an integer, the device transmits a truncated 2-digit packet (e.g.,
50or49).
When divideBy100 is active, the 2-digit packet turns into 0.5 Hz (which triggered the old issue). When it is disabled, the 4-digit packet turns into 5000 Hz (which triggered the current bug).
Device details
- Device Model: Tongou TO-Q-SYS-JZT
- Manufacturer ID: _TZE284_6ocnqlhn
What did you expect to happen?
The zigbee-herdsman-converters scaling needs to be reverted to divideBy100.
Zigbee2MQTT needs a mechanism to either:
- Ignore/discard Datapoint 32 payloads if the raw value length is less than 3-4 digits (filtering the truncated drop).
- Dynamically check the raw value: if it is
<= 60, treat it as already scaled to whole Hertz and do not apply the divisor (or multiply it by 100 before passing it to the converter).
How to reproduce it (minimal and precise)
No response
Zigbee2MQTT version
2.13.0
Adapter firmware version
20240710
Adapter
Silicon Labs CP2102N USB to UART Bridge
Setup
docker container koenkk/zigbee2mqtt
Device database.db entry
No response
Debug log
sensor.pia1_ac_frequency, 50, 2026-08-22T19:11:17.633Z <-- Truncated integer report from MCU
sensor.pia1_ac_frequency, 5002, 2026-08-22T19:11:18.094Z <-- Standard centihertz report
Notes
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing Datapoint 32 handling for the Tongou TO-Q-SYS-JZT and the divideBy100 conversion, using zigbee-herdsman-converters issue #12993 and PR #11875 for context. Done means standard four-digit reports display correctly as centihertz values while intermittent two-digit reports are filtered or handled without producing 0.5 Hz or 5000+ Hz readings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- embedded-iot
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100