Fix parsing of Tuya electricity RAW values #157039

abelyliu · 2025-11-22T09:38:31Z

Proposed change

Add a unified parser for Tuya phase_a RAW payloads, supporting three protocol versions:
- v00 (legacy 8 bytes): Voltage 2B (0.1V), Current 3B (0.001A → mA), Active Power 3B (0.001kW → W).
- v01 (framed): [0x01][0x0F] + 15 bytes data.
- v02 (framed with sign): [0x02][0x0F] + 15 bytes data + 1 byte sign bitmap (bit0: current negative; bit1: active power negative; bit2: reactive negative; bit3: PF negative).
Correct unit scaling and sign handling:
- Voltage in V (0.1V scaling as per spec).
- Current parsed in mA (entity can suggest/display A).
- Active power parsed in W.
Keep backward compatibility: if a framed payload is not detected or parsing fails, fall back to the legacy fixed-offset logic (existing behavior).
Result: realistic values for devices (e.g., category dlq, product cnpkf4xdmd9v49iq) that report phase_a in v01/v02 formats. For example, a fixture previously showing 599.296 A (due to mis-parsing) now shows 0.072 A for the same payload, which matches the vendor protocol.

Type of change

Bugfix (non-breaking change which fixes an issue)
Dependency upgrade
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

Affected integration: tuya (category dlq, product example cnpkf4xdmd9v49iq).
Protocol references used in this change:
- v00 (8B): V(2B, 0.1V), I(3B, 0.001A), P(3B, 0.001kW); big-endian.
- v01: [01][0F] + 15B data (Voltage, Current, Active/Reactive/Apparent Power, PF).
- v02: [02][0F] + 15B data + 1B sign bitmap (bit0 current, bit1 active power, bit2 reactive, bit3 PF).
Example frames used for verification:
- v00: 08800003E8002710 → 217.6 V, 1.000 A, 10.000 kW (10,000 W).
- v01: 010F08800003E8002710000DAC0030D450 → 217.6 V, 1.000 A, 10,000 W.
- v02: 020F08800003E8002710000DAC0030D4500F → 217.6 V, -1.000 A, -10,000 W (sign bitmap applied).
Fixture illustrating the bug fix (used in tests):
- tests/components/tuya/fixtures/dlq_cnpkf4xdmd9v49iq.json has status["phase_a"] = "Ag8JJQAASAAACAAAAAAACGME" (v02). New parsing yields 0.072 A instead of the old 599.296 A.

This PR fixes or closes issue: (none)

This PR is related to issue: (none)

Link to documentation pull request: (none required; behavior is a correctness fix)

Checklist

I understand the code I am submitting and can explain how it works.
The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass.
There is no commented out code in this PR.
I have followed the development checklist.
I have followed the perfect PR recommendations.
The code has been formatted using Ruff (ruff format homeassistant tests).
Tests have been added to verify that the new code works.
Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly. (No manifest changes required in this PR.)
New or updated dependencies have been added to requirements_all.txt. (Not applicable)
For updated dependencies – a link to changelog or diff is added. (Not applicable)

I have reviewed two other open pull requests in this repository: (optional)

Notes for reviewers

Parsing changes are limited to homeassistant/components/tuya/sensor.py and only affect RAW phase_a fields.
When a framed payload (v01/v02) is detected, the parser uses precise offsets, endianness, and scaling as per spec; otherwise it falls back to legacy offsets used for v00.
Snapshot updates (if any) reflect corrected values for affected fixtures. Focused unit tests can be added in a follow-up commit if desired (e.g., a new tests/components/tuya/test_sensor_phase_parsing.py to assert v00/v01/v02 parsing and v02 sign handling).

How I tested locally

script/run-in-env.sh pytest tests/components/tuya/test_sensor.py -k test_platform_setup_and_discovery -vv
Verified diffs for dlq_cnpkf4xdmd9v49iq.json are consistent with the vendor protocol.
Then updated the snapshot for that test only: --snapshot-update.
Ran all Tuya tests: script/run-in-env.sh pytest tests/components/tuya -q.
Ran hassfest and lints:
- script/run-in-env.sh python -m script.hassfest
- script/run-in-env.sh pylint homeassistant/components/tuya -j 2

home-assistant

Hi @abelyliu

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

home-assistant · 2025-11-22T09:38:36Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

home-assistant · 2025-11-22T09:38:39Z

Hey there @tuya, @zlinoliver, mind taking a look at this pull request as it has been labeled with an integration (tuya) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of tuya can trigger bot actions by commenting:

@home-assistant close Closes the pull request.
@home-assistant rename Awesome new title Renames the pull request.
@home-assistant reopen Reopen the pull request.
@home-assistant unassign tuya Removes the current integration label and assignees on the pull request, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

Stale

epenet · 2025-11-24T16:11:30Z

Can you provide a link to the specifications?

frenck · 2025-11-25T06:51:59Z

I've marked this PR a draft, awaiting the above question to be answered.

Please un-draft it once it is ready for review again by clicking the "Ready for review" button.

Thanks! 👍

../Frenck

Learn more about our pull request process.

abelyliu · 2025-11-26T03:17:30Z

Can you provide a link to the specifications?

The specifications are not available via a direct public link, but you can view them within the Tuya IoT Platform console. Here are the steps to access the definitions:

Log in to Tuya IoT Platform.

Navigate to: Product -> Create -> Energy -> Circuit Breaker -> TuyaOS -> Custom Solution.

You will see options for v0 and v2 versions. (Note: v1 existed previously but has been superseded by v2).

After creating a product, go to Function Definition.

Click "Edit" on Phase A, and you will find the detailed definition in the remark field.

epenet · 2025-11-26T08:40:05Z

Can you provide a link to the specifications?

The specifications are not available via a direct public link, but you can view them within the Tuya IoT Platform console. Here are the steps to access the definitions:

Log in to Tuya IoT Platform.

Navigate to: Product -> Create -> Energy -> Circuit Breaker -> TuyaOS -> Custom Solution.

You will see options for v0 and v2 versions. (Note: v1 existed previously but has been superseded by v2).

After creating a product, go to Function Definition.

Click "Edit" on Phase A, and you will find the detailed definition in the remark field.

Can you add a screenshot here for reference?

abelyliu · 2025-11-26T09:57:40Z

Can you provide a link to the specifications?

The specifications are not available via a direct public link, but you can view them within the Tuya IoT Platform console. Here are the steps to access the definitions:
Log in to Tuya IoT Platform.
Navigate to: Product -> Create -> Energy -> Circuit Breaker -> TuyaOS -> Custom Solution.
You will see options for v0 and v2 versions. (Note: v1 existed previously but has been superseded by v2).
After creating a product, go to Function Definition.
Click "Edit" on Phase A, and you will find the detailed definition in the remark field.

Can you add a screenshot here for reference?

Sure, here are the screenshots for reference.

Note on Language: Please note that even though my platform language is set to English, the raw protocol remarks inside the "Edit" view are hardcoded in Chinese by the platform.

epenet

I think all this logic would be better inside a class.
I have opened #157357 as a preliminary PR, and then from_bytes would be adjusted to handle the new structures.

epenet · 2025-11-27T08:22:11Z

@abelyliu I have been playing with it some more, and I have a come up with the attached diff file.
Can you try to apply it to your branch and see what you think?
raw_data_models.diff

home-assistant

Hi @qiaoerliu

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

home-assistant

Hi @qiaoerliu

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

abelyliu · 2025-11-27T10:14:48Z

@abelyliu I have been playing with it some more, and I have a come up with the attached diff file. Can you try to apply it to your branch and see what you think? raw_data_models.diff

I have applied your raw_data_models.diff to the branch and it looks correct.

Also, I noticed my previous commits were using the wrong email address (which caused the CLA failure). I have fixed the author info and force-pushed the updates. The CLA check should be passing now.

Stale

epenet

LGTM, but I'd like a second pair of eyes

frenck

Thanks, @abelyliu 👍

../Frenck

Blogging my personal ramblings at frenck.dev

epenet · 2025-11-27T11:50:54Z

homeassistant/components/tuya/raw_data_models.py

+    current: float
+    power: float
+    voltage: float


Note: in a follow-up PR, maybe you could parse the extra values and make the sensors available

current: float power: float voltage: float reactive_power: float | None = None apparent_power: float | None = None power_factor: float | None = None

home-assistant bot previously requested changes Nov 22, 2025

View reviewed changes

home-assistant bot added bugfix cla-needed has-tests integration: tuya labels Nov 22, 2025

home-assistant bot marked this pull request as draft November 22, 2025 09:38

home-assistant bot added the Quality Scale: No score label Nov 22, 2025

home-assistant bot added cla-recheck cla-signed and removed cla-recheck cla-needed labels Nov 22, 2025

abelyliu marked this pull request as ready for review November 24, 2025 01:31

frenck marked this pull request as draft November 25, 2025 06:52

abelyliu marked this pull request as ready for review November 26, 2025 03:19

epenet mentioned this pull request Nov 26, 2025

Move Tuya RAW parsing to separate module #157357

Closed

21 tasks

epenet reviewed Nov 26, 2025

View reviewed changes

epenet marked this pull request as draft November 26, 2025 15:49

home-assistant bot previously requested changes Nov 27, 2025

View reviewed changes

home-assistant bot added the cla-needed label Nov 27, 2025

home-assistant bot previously requested changes Nov 27, 2025

View reviewed changes

Tuya: Support phase_a RAW v01/v02 (sign bitmap)

66980e6

abelyliu added 2 commits November 27, 2025 18:08

Update snapshot

c7c7a7f

Refactor Tuya sensor electricity data parsing logic

d36339e

abelyliu force-pushed the tuya-dlq-phase-raw-v01-v02 branch from 8b944c6 to d36339e Compare November 27, 2025 10:11

home-assistant bot removed the cla-needed label Nov 27, 2025

abelyliu marked this pull request as ready for review November 27, 2025 10:15

epenet changed the title ~~Tuya dlq phase raw v01 v02~~ Fix parsing of Tuya electricity RAW values Nov 27, 2025

epenet added this to the 2025.12.0 milestone Nov 27, 2025

epenet approved these changes Nov 27, 2025

View reviewed changes

epenet added the second-opinion-wanted Add this label when a reviewer needs a second opinion from another member. label Nov 27, 2025

frenck reviewed Nov 27, 2025

View reviewed changes

frenck removed the second-opinion-wanted Add this label when a reviewer needs a second opinion from another member. label Nov 27, 2025

frenck merged commit ec69efe into home-assistant:dev Nov 27, 2025
36 checks passed

frenck added the cherry-picked label Nov 27, 2025

frenck pushed a commit that referenced this pull request Nov 27, 2025

Fix parsing of Tuya electricity RAW values (#157039)

28b7ebe

epenet reviewed Nov 27, 2025

View reviewed changes

github-actions bot locked and limited conversation to collaborators Nov 28, 2025

Uh oh!

Fix parsing of Tuya electricity RAW values #157039

Fix parsing of Tuya electricity RAW values #157039

Conversation

abelyliu commented Nov 22, 2025

Proposed change

Type of change

Additional information

Checklist

Notes for reviewers

How I tested locally

Uh oh!

home-assistant bot left a comment

Choose a reason for hiding this comment

Uh oh!

home-assistant bot commented Nov 22, 2025

Uh oh!

home-assistant bot commented Nov 22, 2025

Uh oh!

epenet commented Nov 24, 2025

Uh oh!

frenck commented Nov 25, 2025

Uh oh!

abelyliu commented Nov 26, 2025

Uh oh!

epenet commented Nov 26, 2025

Uh oh!

abelyliu commented Nov 26, 2025

Uh oh!

epenet left a comment

Choose a reason for hiding this comment

Uh oh!

epenet commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

home-assistant bot left a comment

Choose a reason for hiding this comment

Uh oh!

home-assistant bot left a comment

Choose a reason for hiding this comment

Uh oh!

abelyliu commented Nov 27, 2025

Uh oh!

epenet left a comment

Choose a reason for hiding this comment

Uh oh!

frenck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

epenet Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

epenet commented Nov 27, 2025 •

edited

Loading