ts0601_energy_meter quirk for Tuya power meter devices

[jeverley]

Proposed change

Adds support for Tuya Energy Meter devices in 1 and 2 clamp configurations.

Uses zigbee2Mqtt https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/devices/tuya.ts as reference for device datapoints (with amendments from community testing in the respective device support issues).

Meter devices providing power direction will report signed values for their supported attributes in accordance with the Zigbee cluster spec (instantaneous demand, active power and reactive power specifically).

Provides control over metering sensor configuration:

• The quirk allows the user to control the endpoint 3 power calculation on 2 clamp devices using the "channel_configuration" attribute value (calculated as either a+b or a-b).
  • a+b should be used when measuring total consumption from two power sources.
  • a-b should be used to derive a second power value from input power and consumption i.e. clamp A on grid input, clamp B measuring power into the consumer unit.

Some devices report an a+b total natively, however in testing this value is often incorrect due to delay in detecting power direction change on the device.

In the real world when measuring both grid and production an a + b < 0 value would be atypical.
This is mitigated using the power_flow_preempt filter on device readings, this is optionally is enabled by setting 'power_flow_preempt' to True.

The quirk aims to make adding new devices simpler by utilising device specific dp_to_attribute mappings which feed into common core reporting clusters.

Addresses device support requests:

2 bidirectional clamps:

• [Device Support Request] _TZE204_81yrt3lo TS0601 Zigbee power meter with clamp #2549 (_TZE204_81yrt3lo)
• [Device Support Request] PC311-Z-TY Single-Phase Power Clamp Zigbee model 'TS0601' and manufacturer name '_TZE200_rks0sgb7 #2650 (_TZE200_rks0sgb7)

1 bidirectional clamp:

• [Device Support Request] _TZE204_ac0fhfiq TS0601 BiDirectional ZigBee Energy Meter with 150A Clamp Current Sensor #2420 (_TZE204_ac0fhfiq)

1 clamp:

• [Device Support Request] TUYA DIN ENERGY METERING #1973 (_TZE204_cjbofhxw)

@jmuf I've just spotted that in parallel you've also been working on #2870 for _TZE200_rks0sgb7, shall we pool ideas?

Additional information

Associated with merged pre-requisite ZHA metering and electrical measurement changes:

• Fix ZHA handling of power factor ElectricalMeasurement attribute sensor home-assistant/core#107641
• Add ZHA metering summation received sensor home-assistant/core#107576
• Add missing ZHA metering device types home-assistant/core#109126

Checklist

• The changes are tested and work correctly
• pre-commit checks pass / the code has been formatted using Black
• Tests have been added to verify that the new code works

[codecov]

Codecov Report

Attention: Patch coverage is 52.80289% with 261 lines in your changes are missing coverage. Please review.

Project coverage is 85.92%. Comparing base (9ccb69a) to head (4b9aac3).

Files	Patch %	Lines
zhaquirks/tuya/ts0601_energy_meter.py	52.80%	261 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #2961      +/-   ##
==========================================
- Coverage   87.90%   85.92%   -1.99%     
==========================================
  Files         300      301       +1     
  Lines        9222     9775     +553     
==========================================
+ Hits         8107     8399     +292     
- Misses       1115     1376     +261     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jmuf]

@jmuf I've just spotted that in parallel you've also been working on #2870 for _TZE200_rks0sgb7, shall we pool ideas?

sure, tell me what I should do. Your "quirk" looks more complete, my "quirk" is a one-off (and "my first quirk".. ).

• I had to resort to several "replacement clusters" to get the 3x same set of metrics (and buses to route data from the TUYA cluster to go there), that "feels wrong"
• also have still an issue with naming (all 3 measurements have same user-friendly name, didn't find way to label as Clamp1/Clamp2/Total)

Things I like in "mine":

• using the constant from ElectricalMeasurement, Metering (instead of random HEX values in the quirk)
• my quirk (or my meter?) seems to happily report negative values, so your complicated configuration (a+b / a-b) seems not required (also a user could just turn around the clamp to reverse the reading?)
• double-digit precision on "Watt" sounds not what these meters are made for. Mine says ±2W <100W, else ±2% accuracy

[jeverley]

sure, tell me what I should do. Your "quirk" looks more complete, my "quirk" is a one-off (and "my first quirk".. ).

• I had to resort to several "replacement clusters" to get the 3x same set of metrics (and buses to route data from the TUYA cluster to go there), that "feels wrong"
• also have still an issue with naming (all 3 measurements have same user-friendly name, didn't find way to label as Clamp1/Clamp2/Total)

Things I like in "mine":

• using the constant from ElectricalMeasurement, Metering (instead of random HEX values in the quirk)
• my quirk (or my meter?) seems to happily report negative values, so your complicated configuration (a+b / a-b) seems not required (also a user could just turn around the clamp to reverse the reading?)
• double-digit precision on "Watt" sounds not what these meters are made for. Mine says ±2W <100W, else ±2% accuracy

Appreciate the feedback @jmuf , I've started to incorporate some changes based on your thoughts.

Changes so far:

• Switched to contestants for the attribute IDs
• Amend power divisor to report 1 decimal place (one of the meters reports that level of precision)

Outstanding:

• also have still an issue with naming (all 3 measurements have same user-friendly name, didn't find way to label as Clamp1/Clamp2/Total)
  I like the idea, looking at the core integration code I think we need to make some amendments to ZHA's sensor functionality to support this.
• my quirk (or my meter?) seems to happily report negative values, so your complicated configuration (a+b / a-b) seems not required (also a user could just turn around the clamp to reverse the reading?)
  • Ah that's useful to know yours reports the signed integers natively.
    The other devices report power as an unsigned integer, so we need to apply the direction locally. I can make that logic only apply for the uint devices.
  • On the add/subtract point, that's a fair challenge, it does add additional complexity.
    I still think there's benefit in a-b for non-bidirectional 2 clamp devices because that would be the only way of deriving export to the grid (i.e. consumption minus solar, since both should clamps should always be positive).

[Xesc1714]

Hi,
Some ZHA quirks to setup and work with this device TZ3000_zrm3oxsh TS011F

thank you

[pantonvich]

Hey thanks for this quirk! I have the _TZE204_81yrt3lo but with only one clamp - some how I managed to order it with only one clamp - lol. My question is that there doesn't appear to be a difference between the power and instantaneous demand so why are both needed? I set mine up on the A and did have to flip my clamp to not get negative watts.

[Vladdy65]

Following. Just acquired one of the dual clamp _TZE204_81yrt3lo units and would dearly like to get it working. Happy to help with any testing.

[jeverley]

Following. Just acquired one of the dual clamp _TZE204_81yrt3lo units and would dearly like to get it working. Happy to help with any testing.

Your help would be much appreciated @Vladdy65.
I think we're nearly there functionality wise if you wanted to give the current version in the PR a go on your end.

Current observations indicate that you probably won't see all sensors show up until after a restart of the zigbee integration due to how home assistant currently determines if a sensor is available - something I plan to tackle.

I'm also still making some final corrections to how the sensor calculates the grid summation values in the consumption minus production configuration, hoping this coming week I have time to address these remaining pieces.

[Vladdy65]

@jeverley sure thing.

I used the following quirks file: https://github.com/jeverley/zha-device-handlers/blob/ts0601_energy_meter/zhaquirks/tuya/ts0601_energy_meter.py downloaded in the wee hours of this morning.
I use the SkyConnect v1.0 zigbee dongle.

Setup procedure:

• Ensured my configuration.yaml included the following:

zha: database_path: /config/zigbee.db enable_quirks: true custom_quirks_path: /config/custom_zha_quirks/

• Removed device from HA Zigbee Home Automation (ZHA)
• Deleted all quirks files and pycache folder from config/custom_zha_quirks/ folder
• Restarted HA
• Dropped the ts0601_energy_meter.py file in the config/custom_zha_quirks/ folder
• Restarted HA
• Added the Dual Channel Smart Meter to ZHA (ADD DEVICE, hold button on unit for 5s)

Got no Sensors only the Configuration and Diagnostic panels.

• Rebooted HA

Success!!
Got the below (having also enabled the RSSI Diagnostic sensor):

At this point it was under my desk with the clamps not connected to anything.

• Mounted the unit in the distribution cabinet and connected the clamps, following the arrow directions inside pointing from supply side to each of my two consumer cabinets incoming Live wires.

After a moment I got the below:

Fantastic work so far @jeverley !

A few observations.

• Sign for power 'received' from mains supply in my view is correct and should be negative (-) Power, it is power that has been consumed vs. power that has been generated, say from solar which logically should be a positive number. Suspect some will not fancy plotting their consumption as a -ve number and I'm not sure how this plays with the HA Power components. Not had time to test.
• The Summation delivered of 0.06kWh is probably due to me having one of the clamps the wrong way round for a short period of time.
• The Unknown AC frequency and Voltage are probably surplus as from what I understand the device only measures this off its own supply feed, not the clamps.
• The same probably applies to the Unknown Current as this is only measured off the two clamps, unless you have plans to make this the sum of the A+B channels.
• The third Unknown Power factor, again, seems redundant. Power factor is measured as the shift in the phase of the current vector (as phase of the voltage signal from each clamp) vs the phase of the voltage signal on the unit's power supply. So there can only be two measurements. Unless I'm missing something.

My ZHA diagnostic file attached:
config_entry-zha-1602f4cec172a9c30a09aa4ae0e5f2a0 (1).json

Let me know if yo need anything else tested.

[jeverley]

Thanks very much @Vladdy65, please could you give the version in branch https://github.com/jeverley/zha-device-handlers/tree/ts0601_energy_meter_devices a try?

File linked directly:
https://github.com/zigpy/zha-device-handlers/blob/ts0601_energy_meter_devices/zhaquirks%2Ftuya%2Fts0601_energy_meter.py

That one has my more recent changes including the different configurable summation methods and support for similar device models.

[reef-actor]

power 'received' from mains supply

The terminology is refering to the load (aka your house). When you are using electricity it is being "delivered" to your house, when you are producing it is being "received" from your house.

[Vladdy65]

@jeverley

File linked directly:
https://github.com/zigpy/zha-device-handlers/blob/ts0601_energy_meter_devices/zhaquirks%2Ftuya%2Fts0601_energy_meter.py

The link gives me a 404 error.

Could you confirm again correct file path please.

[jeverley]

Sorry about that, here you go:

https://raw.githubusercontent.com/jeverley/zha-device-handlers/ts0601_energy_meter_devices/zhaquirks/tuya/ts0601_energy_meter.py

[Vladdy65]

The terminology is refering to the load (aka your house). When you are using electricity it is being "delivered" to your house, when you are producing it is being "received" from your house.

@reef-actor
The way I interpreted it is, using 'House' as the subject in the sentence:

• House 'received' power from grid;
• House 'delivered' power to grid - e.g. when you have solar and you are selling it back to the grid;

I tried but struggled to make sentences using 'House' as the subject with the terms the other way round.
I came up with:

• House has power 'delivered' to it from the grid;

So I asked our friendly AI (Copilot) about it, this is the conversation 🤔:

You
Please explain the semantics of this sentence with respect of the nouns and verbs and who is the subject: House has power 'delivered' to it from the grid
Copilot
Certainly! Let’s break down the semantics of the sentence:

Subject:
The subject of the sentence is “House.”
The subject is the entity that the sentence is primarily about.
Verbs:
The main verb in the sentence is “has delivered.”
The auxiliary verb is “has.”
The verb phrase “has delivered” indicates an action or state related to the subject.
Nouns:
The nouns in the sentence are:
“House”: Refers to a building or dwelling where people live.
“power”: Refers to electrical energy.
“grid”: Refers to the electrical power distribution network.
Semantics:
The sentence conveys that the “House” receives or obtains “power” from the “grid.”
The action of delivering power is attributed to the grid.
In other words, the grid supplies electricity to the house.
In summary, the subject (house) benefits from the action of power delivery facilitated by the grid. 🏠⚡️

[reef-actor]

A better reference might be the zigbee standard (Page 217) 😜

[Vladdy65]

A better reference might be the zigbee standard (Page 217) 😜

@reef-actor I stand humbled by my ignorance. 😔

[Vladdy65]

@jeverley
With:

https://raw.githubusercontent.com/jeverley/zha-device-handlers/ts0601_energy_meter_devices/zhaquirks/tuya/ts0601_energy_meter.py

No change on first adding the device:

After restarting HA:

Seems like some weird stuff is going on now I'm afraid.
At first I thought HA was doing something odd, so re-did the whole exercise and made sure I renamed the device (I'd given it the same name as before initially), but same outcome.
Let me know when you need further help.

[jeverley]

If you go into Manage Device, please could you read the values of the attributes:

• channel_configuration
• power_flow
• power_flow_ch_b
• power_flow_preempt
• suppress_reverse_flow
• suppress_reverse_flow_ch_b

From the TuyaEnergyMeterManufCluster?

[Vladdy65]

What I have is:

• Clusters
  TuyaEnergyMeterManufCluster_2CHB_MatSeePlus (Endpoint id: 1, Id: 0xef00, Type: in)

• channel_configuration (id: 0x5000)
  ChannelConfiguration_2CHB.GRID_PLUS_PRODUCTION

• power_flow (id: 0x0266)
  PowerFlow.REVERSE

• power_flow_ch_b (id: 0x0268)
  PowerFlow.REVERSE

• power_flow_preempt (id: 0x5020)
  Bool.true

• suppress_reverse_flow (id: 0x5010)
  None

• suppress_reverse_flow_ch_b (id: 0x5011)
  None

[jeverley]

What I have is:

• Clusters
  TuyaEnergyMeterManufCluster_2CHB_MatSeePlus (Endpoint id: 1, Id: 0xef00, Type: in)

• channel_configuration (id: 0x5000)
  ChannelConfiguration_2CHB.GRID_PLUS_PRODUCTION

• power_flow (id: 0x0266)
  PowerFlow.REVERSE

• power_flow_ch_b (id: 0x0268)
  PowerFlow.REVERSE

• power_flow_preempt (id: 0x5020)
  Bool.true

• suppress_reverse_flow (id: 0x5010)
  None

• suppress_reverse_flow_ch_b (id: 0x5011)
  None

Thanks @Vladdy65, do you definitely have the arrow inside the clamps facing in the direction of delivered power, and the red cables of the clamps connected to their corresponding S1 terminal on the module?

[Vladdy65]

Thanks @Vladdy65, do you definitely have the arrow inside the clamps facing in the direction of delivered power, and the red cables of the clamps connected to their corresponding S1 terminal on the module?

@jeverley double checked the wiring. Also made sure I had the LIVE cables (brown in UK).
To confirm, I followed this guidance:

In my case the arrow is inside the clamp, K->L, as in the image inset, and is pointing to the loads as follows:

Wiring:

[jeverley]

Appreciate the thoroughness, if you flip the orientation of the clamps does the flow direction change?

[reef-actor]

I have a different meter model with a single clamp (CT-2101A) that is labelled as "S1.Black, S2.Red", does your manual say the other way round? I have tried looking up how these clamps work and I am not sure they would do anything at all if they were the wrong way round, but I thought I would mention it.

[Vladdy65]

I have a different meter model with a single clamp (CT-2101A) that is labelled as "S1.Black, S2.Red", does your manual say the other way round? I have tried looking up how these clamps work and I am not sure they would do anything at all if they were the wrong way round, but I thought I would mention it.

No mention of it in my manual.

[Vladdy65]

Appreciate the thoroughness, if you flip the orientation of the clamps does the flow direction change?

Before, with clamps pointing to Load:

After, with clamps in opposite direction:

Only significant change I see is in the Power Factor. I had to ponder this and brush up on my power factor equations, but I am no wiser as to what just happened. Other than a PF of 39% is not good. I could accept it on channel B where the current is only 0.2A and thus probably close to measurement limits (it is an 80A clamp), but that it flipped and now shows it on channel A is surprising.

[jeverley]

Hmm that's odd, I'd have expected a flow reversal in that scenario - are you able to read the app_version attribute value from the Basic cluster?
That should show if we're running the same firmware version, I've got 74 (or 0x4a).

I can add some debug lines in the quirk to write out the raw reported data point values, possible your device is behaving differently to my own.

[Vladdy65]

This morning the picture looked different, and more in line with expectations of signs changing. I've left the clamps on 'backward' pointing away from Load. I'm now wondering if it needed some time to 'settle' after changing the clamp direction before taking the 'After' screenshot last night.
As for app_version attribute value from the Basic cluster, I get no response.

and it has been taking readings through the night as I had a history graph going to confirm. But now it is frozen. I've removed it but cannot add it back again....

Is there any way to factory reset these devices?

[Vladdy65]

Its back...
Basic (Endpoint id: 1, Id: 0x0000, Type: in)
app_version (id: 0x0001)
74
Same as yours.

[decrouxtom]

Thanks for the answer @reef-actor for #2420 (comment)
Power seems ok:

With the new quirk, total energy seems wrong: