Refactor Aqara Roller Driver E1 as v2 quirk for more entities #3686

jeverley · 2025-01-08T11:06:18Z

Proposed change

This PR refactors the existing Aqara Roller Driver E1 quirk into the new v2 structure to expose the configuration and status attributes, below is a summary of changes:

Refactor into v2 quirk format
- Refactor clusters to use AttributeDefs format
Expose attributes as entities:
- Motor speed (select)
- Charging status (binary sensor)
- Calibration status (binary sensor)
Represent the device as a Rollershade WindowCoveringType rather than Drapery
Device cluster attribute handling:
- Reads/reports of AnalogOutput: present_value (current position) are replicated into WindowCovering: current_position_lift_percentage
- Writes to AnalogOutput: present_value (go to position) do not update the WindowCovering: current_position_lift_percentage
- Reads of WindowCovering: current_position_lift_percentage are redirected to AnalogOutput: present_value
Window Covering command handling:
- up_open, down_close, stop are handled by MultistateOutput: present_value
- go_to_lift_percentage value is written to AnalogOutput: present_value
- The current_position_lift_percentage is read prior to returning command response, this ensures the correct state is shown following a change in direction

Functional enhancements

Users can change the Speed using the select entity
Users can see if the device is Charging
Users can see if the device is Calibrated
The cover uses the Rollershade type
The redundant number entity for current position is disabled by default
The redundant switch entity is disabled by default

Additional information

Depends on the following PRs for binary_sensor value conversion:

Depends on the following PR for disabling the redundant entities:

Associated PRs:

Fixes cover handling of Rollershade device class (for the correct icon) Improve cover entity handling zha#376

Whilst I've validated that is works with my own E1 roller shade devices, I'd like to ensure other users do not encounter any regressions with this refactor.
@dmulcahey / @schwickster / @javicalle / @badrpc / @TheJulianJES I can see in the past you've previously contributed for this device, if you still use it would you mind checking if this updated quirk works as expected without introducing regressions?

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 · 2025-01-08T13:49:00Z

Codecov Report

Attention: Patch coverage is 98.76543% with 1 line in your changes missing coverage. Please review.

Project coverage is 91.17%. Comparing base (79df5ec) to head (df0b755).
Report is 1 commits behind head on dev.

Files with missing lines	Patch %	Lines
zhaquirks/xiaomi/aqara/roller_curtain_e1.py	98.76%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #3686      +/-   ##
==========================================
+ Coverage   91.13%   91.17%   +0.03%     
==========================================
  Files         334      334              
  Lines       10796    10856      +60     
==========================================
+ Hits         9839     9898      +59     
- Misses        957      958       +1

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jeverley · 2025-01-08T18:31:44Z

Have identified an issue with the cover state not reliably changing to open/closed. Investigating this currently.

jeverley · 2025-01-08T23:59:15Z

Edit: zigpy/zha#376 now raised to address the below.

@TheJulianJES, @dmulcahey looking at the code in https://github.com/zigpy/zha/blob/dev/zha/application/platforms/cover/__init__.py
it looks to me like the _determine_state function and stored target positions might be the cause of the issue, I'm seeing similar issues reported for other devices which would appear to have the same root cause as below:

ewand cover not reporting open/close state correctly through ZHA home-assistant/core#93836
ZHA : Cover states stays as Opening or Closing when using Set position home-assistant/core#98933
[Device Support Request] Insta GmbH Nexentro Blinds Actuator Mini #1397

There was a PR against the old core ZHA repo to try and address this but that looks abandoned home-assistant/core#105467

I've tested the following scenarios:

1. go_to_lift_percentage has never been called, down_close is called, then the device reports position_or_tilt of 0
_target_lift_position == None
position_or_tilt == 0
returns STATE_CLOSED

2. go_to_lift_percentage has never been called, up_open is called, then the device reports position_or_tilt of 100
_target_lift_position == None
position_or_tilt == 100
returns: STATE_OPEN

3. go_to_lift_percentage is called (go to 0), then the device reports position_or_tilt of 0
_target_lift_position == 0
position_or_tilt == 0
returns STATE_CLOSED

4. go_to_lift_percentage is called (go to 100), then the device reports position_or_tilt of 100
_target_lift_position == 100
position_or_tilt == 100
returns STATE_OPEN

5. go_to_lift_percentage is called (go to 50), then the device reports position_or_tilt of 50
_target_lift_position == 50
position_or_tilt == 50
returns STATE_OPEN

6. go_to_lift_percentage has previously been called (stored value is 50), down_close is called, then the device reports position_or_tilt of 0
_target_lift_position == 50
position_or_tilt == 0
returns STATE_CLOSED

7. go_to_lift_percentage has previously been called (stored value is 50), up_open is called, then the device reports position_or_tilt of 100
_target_lift_position == 50
position_or_tilt == 100
returns None, state remains as STATE_OPENING

8. go_to_lift_percentage has previously been called (stored value is 50) and current position is 100, stop is called
_target_lift_position == 100 (the function async_stop_cover sets it to the current cover position)
position_or_tilt == 100
returns STATE_OPEN

I'd suggest we can handle this in one of 3 ways:

set the stored _target_lift_position to 100 or 0 when calling the up_open or down_close commands respectively
clear the stored _target_lift_position when calling the up_open or down_close commands
modify the _determine_state function to return STATE_OPEN when self.is_opening == True and position_or_tilt == 100 is true

Below is the current function for reference:

    def _determine_state(self, position_or_tilt, is_lift_update=True) -> None:
        """Determine the state of the cover.

        In HA None is unknown, 0 is closed, 100 is fully open.
        In ZCL 0 is fully open, 100 is fully closed.
        Keep in mind the values have already been flipped to match HA
        in the WindowCovering cluster handler
        """
        if is_lift_update:
            target = self._target_lift_position
            current = self.current_cover_position
        else:
            target = self._target_tilt_position
            current = self.current_cover_tilt_position

        if position_or_tilt == 0:
            self._state = (
                STATE_CLOSED
                if is_lift_update
                else STATE_OPEN
                if self.current_cover_position is not None
                and self.current_cover_position > 0
                else STATE_CLOSED
            )
            return
        if target is not None and target != current:
            # we are mid transition and shouldn't update the state
            return
        self._state = STATE_OPEN

jeverley · 2025-01-10T21:45:32Z

I've been working on changes to the ZHA cover entity hander to address the underlying status issue outlined above (it also affects the existing v1 quirk code for this and other devices).

I'll raise a bug and PR to address these over the weekend, current WIP code here:
https://github.com/jeverley/zha/blob/cover-platform-entity-status/zha/application/platforms/cover/__init__.py

jeverley · 2025-01-27T12:26:49Z

@TheJulianJES if I'm reading zigpy/zigpy#1540 I believe I should be able to use the proposed attribute_converter functionality to remap the Aqara values for the charging binary_sensor?

If so I'll remove the custom converter I've implemented in this quirk once your PR is merged.

jeverley · 2025-01-27T12:45:53Z

@TheJulianJES the AnalogOutput cluster present_value on this device is used to write the intended target position, whereas reads/reports on the attribute report the device current position.

Right now ZHA exposes this as a separate number entity in addition to the cover entity.
In the UI the number entity is redundant since interactions & current position can all be handled through the cover.

When adding custom entities in a v2 quirk we're able to mark them as disabled by default, do you think it would be beneficial to extend this to regular cluster attributes?
This would allow us to present devices more uniformly, without exposing redundant entities arising from manufacturers' non-standard implementations.

Critically this would be different to entirely removing the cluster/marking an attribute as unsupported in the cluster, since we'd still want to remap attribute updates/writes from the cover commands to the cluster.

TheJulianJES · 2025-01-27T12:48:19Z

When adding custom entities in a v2 quirk we're able to mark them as disabled by default, do you think it would be beneficial to extend this to regular cluster attributes?

With zigpy/zigpy#1535, that should be allowed in the future. Do note that the ZHA part wasn't PR'd yet, so it won't do anything for now.
attribute_converter support also isn't merged, yet.

- Refactor into v2 quirk - Refactor clusters to use AttributeDefs format - Represent the device as a Rollershade rather than Drapery - Refresh current position after a stop command is issued - Expose attributes as entities: - Motor speed (select) - Charging status (binary sensor) - Calibration status (binary sensor) - Reads to current_position_lift_percentage are redirected to AnalogOutput present_value - Writes to AnalogOutput present_value from go_to_lift_percentage commands do not prematurely update the current_position_lift_percentage

The AnalogOutput cluster is used to write target position to the device. The present_value reported/read provides the current position/starting position when the device is in motion. Both of these functions are re-mapped into the ZCL WindowCovering cluster, so the number entity created is redundant. This also pre-emptively hides the MultistateOutput cluster, though there is currently no cluster handler implemented for this. Apply pre-commit auto fixes

Depends on the following PRs: - zigpy/zigpy#1540 - zigpy/zha#360

The `MultistateOutput: present value` only ever reports the last written command (even if the device has since stopped/changed direction).

jeverley · 2025-02-05T13:57:58Z

@TheJulianJES I think this should be ready for merging, I'll raise a PR for the zha cover status issue outlined in #3686 (comment) separately (it's not a pre-req for this change).

puddly · 2025-02-05T14:56:17Z

zhaquirks/xiaomi/aqara/roller_curtain_e1.py

+    .prevent_default_entity_creation(
+        endpoint_id=1, cluster_id=MultistateOutput.cluster_id
+    )
+    .removes(OnOff.cluster_id)


For this use case, why remove the cluster entirely? I'm hoping to replace uses of removes with prevent_default_entity_creation.

As far as I can tell this cluster is non-functional.

Interacting with the switch results in an error, so there would be no benefit exposing it.
If it's an optional entity a user might be tempted to enable it and raise a bug report that the switch doesn't work.

I think removes(OnOff.cluster_id) can be replaced with prevent_default_entity_creation(cluster_id=OnOff.cluster_id). Removing the cluster prevent prevents automatic entity discovery, which is more explicit with prevent_default_entity_creation and would allow you to still interact with the OnOff cluster via cluster commands if necessary.

I'd usually agree, but the device itself is responding with the below error to any command to OnOff:

Failed to perform the action zha/issue_zigbee_cluster_command. Failed to issue cluster command with status: <Status.UNSUPPORTED_CLUSTER: 195>

@puddly if we're planning to deprecate removes then happy to change this to use prevent_default_entity_creation.

I've updated the PR to use prevent_default_entity_creation 872442a

Hi @puddly, did you have any other feedback on these changes?

Not at the moment, sorry. The above method depends on zigpy/zha#365 to be finished and there were a few hiccups getting it merged.

…tion_lift_percentage updates

jeverley · 2025-02-09T15:53:08Z

I've now raised zigpy/zha#376 to address the ZHA logic issues I outlined in #3686 (comment).
This isn't a pre-requisite for merging this PR.

@puddly

Per @puddly 's recommendation in zigpy#3686 (comment)

jeverley · 2025-03-05T18:13:39Z

Will update the tests following 9e5b67a later this evening.

Edit: fixed and ready with d342b64

The current_position_lift_percentage now is read prior to returning command responses to ensure that ZHA has the correct position during changes in direction/stopping. Apply pre-commit auto fixes and fix tests.

TheJulianJES

Not sure if I'm a huge fan of the is_write/WriteAwareUpdateAttribute stuff and RedirectAttributes (we do need a good way of doing this in general), but it seems to look fine. Since the ZHA PR is in, we should probably get this in as well.

I'm assuming that you have tested it quite a bit. Unfortunately, I don't have any cover devices, so unable to test anything. Again, looks fine, so I'll quickly correct the two small things I noted and get it in for the beta tomorrow. If there are any huge issues, we can always fix them during the beta or revert if necessary.

TheJulianJES · 2025-03-22T19:36:51Z

zhaquirks/xiaomi/aqara/roller_curtain_e1.py

+        attribute_converter=lambda x: True
+        if x == AqaraRollerDriverCharging.true
+        else False,


Suggested change

attribute_converter=lambda x: True

if x == AqaraRollerDriverCharging.true

else False,

attribute_converter=lambda x: x == AqaraRollerDriverCharging.true,

TheJulianJES · 2025-03-26T05:32:01Z

zhaquirks/xiaomi/aqara/roller_curtain_e1.py

+    true = 0x01
+    false = 0x02


This should really be (upper-case) True and False, but that would conflict.
Maybe something like Charging and Unplugged? (assuming "not charging" => "unplugged").

Technically, we don't even need this at all, as we could just parse x == 1 for the charging binary sensor and have no enum.

jeverley marked this pull request as ready for review January 8, 2025 13:58

TheJulianJES added Xiaomi Request/PR regarding a Xiaomi device needs review This PR should be reviewed soon, as it generally looks good. labels Jan 8, 2025

jeverley force-pushed the lumi.curtain.acn002-v2-quirk branch from 6e88fde to fb55985 Compare January 13, 2025 16:50

jeverley force-pushed the lumi.curtain.acn002-v2-quirk branch 4 times, most recently from defc02d to c4135cd Compare February 5, 2025 12:16

jeverley added 6 commits February 5, 2025 13:40

Replace bool conversion function with attribute_converter

aea4334

Depends on the following PRs: - zigpy/zigpy#1540 - zigpy/zha#360

Remove non-applicable blocked status

ed7b956

The `MultistateOutput: present value` only ever reports the last written command (even if the device has since stopped/changed direction).

Negative test scenarios for WriteAwareUpdateAttribute class

fc3da6a

Handle unsupported commands cleanly

7ac94ef

jeverley force-pushed the lumi.curtain.acn002-v2-quirk branch from 35d2776 to 7ac94ef Compare February 5, 2025 13:42

puddly reviewed Feb 5, 2025

View reviewed changes

Improve docstring annotations and use t.uint8_t type for current_posi…

ad03e30

…tion_lift_percentage updates

jeverley mentioned this pull request Feb 7, 2025

Improve cover entity handling zigpy/zha#376

Merged

Use prevent_default_entity_creation instead of removes for OnOff

872442a

Per @puddly 's recommendation in zigpy#3686 (comment)

jeverley force-pushed the lumi.curtain.acn002-v2-quirk branch from b6909c5 to 9e5b67a Compare March 5, 2025 18:03

Read current position after issuing commands

d342b64

The current_position_lift_percentage now is read prior to returning command responses to ensure that ZHA has the correct position during changes in direction/stopping. Apply pre-commit auto fixes and fix tests.

jeverley force-pushed the lumi.curtain.acn002-v2-quirk branch from 1138ed4 to d342b64 Compare March 5, 2025 22:27

Apply pre-commit auto fixes

57a459f

puddly mentioned this pull request Mar 10, 2025

Bump ZHA to 0.0.52 home-assistant/core#140325

Merged

19 tasks

TheJulianJES approved these changes Mar 26, 2025

View reviewed changes

TheJulianJES added 2 commits March 26, 2025 06:38

Rename AqaraRollerDriverCharging values, improve attribute_converter

92fac1e

Merge branch 'dev' into lumi.curtain.acn002-v2-quirk

df0b755

TheJulianJES changed the title ~~Refactor Aqara Roller Driver E1 as v2 quirk to expose configuration and status entities~~ Refactor Aqara Roller Driver E1 as v2 quirk for more entities Mar 26, 2025

TheJulianJES merged commit b325c01 into zigpy:dev Mar 26, 2025
9 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor Aqara Roller Driver E1 as v2 quirk for more entities #3686

Refactor Aqara Roller Driver E1 as v2 quirk for more entities #3686

jeverley commented Jan 8, 2025 •

edited

Loading

codecov bot commented Jan 8, 2025 •

edited

Loading

jeverley commented Jan 8, 2025

jeverley commented Jan 8, 2025 •

edited

Loading

jeverley commented Jan 10, 2025 •

edited

Loading

jeverley commented Jan 27, 2025

jeverley commented Jan 27, 2025

TheJulianJES commented Jan 27, 2025 •

edited

Loading

jeverley commented Feb 5, 2025

puddly Feb 5, 2025

jeverley Feb 5, 2025 •

edited

Loading

puddly Feb 5, 2025

jeverley Feb 5, 2025

jeverley Feb 9, 2025

jeverley Feb 13, 2025

jeverley Feb 26, 2025

puddly Feb 26, 2025

jeverley commented Feb 9, 2025 •

edited

Loading

jeverley commented Mar 5, 2025 •

edited

Loading

TheJulianJES left a comment

TheJulianJES Mar 22, 2025

TheJulianJES Mar 26, 2025

Refactor Aqara Roller Driver E1 as v2 quirk for more entities #3686

Refactor Aqara Roller Driver E1 as v2 quirk for more entities #3686

Conversation

jeverley commented Jan 8, 2025 • edited Loading

Proposed change

Additional information

Checklist

codecov bot commented Jan 8, 2025 • edited Loading

Codecov Report

jeverley commented Jan 8, 2025

jeverley commented Jan 8, 2025 • edited Loading

jeverley commented Jan 10, 2025 • edited Loading

jeverley commented Jan 27, 2025

jeverley commented Jan 27, 2025

TheJulianJES commented Jan 27, 2025 • edited Loading

jeverley commented Feb 5, 2025

Choose a reason for hiding this comment

jeverley Feb 5, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeverley commented Feb 9, 2025 • edited Loading

jeverley commented Mar 5, 2025 • edited Loading

TheJulianJES left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeverley commented Jan 8, 2025 •

edited

Loading

codecov bot commented Jan 8, 2025 •

edited

Loading

jeverley commented Jan 8, 2025 •

edited

Loading

jeverley commented Jan 10, 2025 •

edited

Loading

TheJulianJES commented Jan 27, 2025 •

edited

Loading

jeverley Feb 5, 2025 •

edited

Loading

jeverley commented Feb 9, 2025 •

edited

Loading

jeverley commented Mar 5, 2025 •

edited

Loading