Repository navigation
[Experiment] Number, switch, select and binary sensor entities on device values - #1030
Draft
zigpy-review-bot wants to merge 1 commit into
Draft
zigpy-review-bot wants to merge 1 commit into
zigpy-review-bot wants to merge 1 commit into
Conversation
Quirks set most device settings through numbers, switches and selects, and a read-only device value often wants a binary sensor. `DeviceValueSensor` is the only entity on device values so far, so these still need invented ZCL attributes. `DeviceValueEntity` holds what they share: the value declaration, following the value through the store's change callbacks, and the write path. A writable entity takes an optional async writer, `writer(device, value)` with the zigpy device, typed as `DeviceValueWriter` in `zha.zigbee.store` so quirks can import it. The writer sends the value and decides when it is stored (Tuya's when it builds the command, like its attribute path; a transport with acknowledgements may store after them), and its errors reach the caller. Without a writer, the value is a setting only the host keeps and the entity sets it in the store itself. The classes take the options of the ZCL quirk entities they mirror: - `DeviceValueNumber`: min, max, step, mode, unit, device class and multiplier. The value is kept unscaled and a set value is divided by the multiplier and rounded to an int, as `NumberConfigurationEntity` writes an attribute, so what is stored is what a device receives. - `DeviceValueSwitch`: on and off values and a forced inversion. An inverting attribute has no counterpart, as it would be a second value. - `DeviceValueSelect`: the members of an int enum as options; a member is written as itself, an unknown option raises `ZHAException`. Home Assistant's restored state is ignored, as the store has the value. - `DeviceValueBinarySensor`: on by truth or by a converter, read-only. The store is untyped at rest, so a value of an unexpected type reads as unknown (number, select) or off (switch, binary sensor) instead of raising. `DeviceValueSensor` now builds on the shared base, which also carries the deprecated `endpoint` property Home Assistant's groupable device list reads, so every device value entity has it.
This was referenced Nov 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Experiment, not for merging yet. Part of a series of draft PRs exploring a generic store for zigpy, ZHA and zha-quirks, opened to show the approach end to end and to collect feedback. The design, names and API can still change. Design notes: https://gist.github.com/zigpy-review-bot/44488203c57a4054607477de477d1b63 (index); what was built and why is in section P11 of https://gist.github.com/zigpy-review-bot/0543692721ba9a5c12a347fae2372c70.
Summary
#1027 added device values and a read-only
DeviceValueSensor. Quirks expose most device settings as numbers, switches and selects, so those still need attributes invented on a cluster. This PR adds the entities for them, and a write path: a quirk gives a writable entity an async writer that sends the value to the device, or no writer for a setting only the host keeps.Stacked on #1027 (at 889ce43). Needs a zigpy release with the store; until then CI fails as for #1027 (zha still pins a zigpy without
zigpy.store). The first user is the zha-quirks PR of this series, which writes Tuya datapoints through it.Changes
DeviceValueWriterinzha.zigbee.store:async writer(device, value), with the zigpy device. The writer sends the value and decides when it is set in the store: the Tuya writer stores it when it builds the command, like its attribute path; a transport with acknowledgements may store after them. Its errors propagate to the caller, so Home Assistant shows a failed write.DeviceValueEntity, the device-bound base (no endpoint or cluster): it holds the value declaration, follows the value through the store's change callbacks, and writes through the writer, or into the store directly when there is none (and raisesZHAExceptionif the device has no store).DeviceValueSensornow builds on it, and the deprecatedendpointproperty [Experiment] Add sensors for device values kept in the device's store #1027 gave the sensor moves to the base, so every device value entity has it.DeviceValueNumber: the options ofNumberConfigurationEntity(min, max, step, mode, unit, device class, multiplier), and its scaling: the value is kept unscaled, and a set value is divided by the multiplier and rounded to an int, so what is stored is what a device receives. A setting with fractions uses a multiplier (0.5 for halves).DeviceValueSwitch: on and off values and a forced inversion, asConfigurableAttributeSwitch.DeviceValueSelect: the members of an int enum as options, asZCLEnumSelectEntity; a member is written as itself and stored as its int value. An enum that is not an int enum is refused (TypeError), an unknown option raisesZHAException. Home Assistant's restored state is ignored, since the store holds the value.DeviceValueBinarySensor: on by truth or through a value converter; read-only.Design choices
dp_converter) are handled inside the Tuya writer by reading the siblings from the store.assumedflag, confirmed or reverted by the echo, needs the ZHA value runtime and is not built.DeviceValueSensor, rather than a pluggable source on the ZCL quirk entities (P8.4). The state classes mirror the ZCL ones, minus the attribute names:DeviceValueSwitchStatehas noattribute_nameorinvert_attribute_name, and the binary sensor's state has noattribute_name.Limits
assumedstate and no serialisation of writes in ZHA; actions (P8.3) are not part of this PR.Testing
tests/test_device_values.py: each class reading, options, values of unexpected types, writing with and without a writer, rounding (also of large values), a failing writer that stores nothing (error reaches the caller, value unchanged), no store, unknown options and non-int enums, the deprecatedendpointof every class, unique IDs<ieee>-1-<name>through a quirk, and values surviving a rebuild of the ZHA device.pytest testsagainst the zigpy branch with the released zha-quirks: 1809 passed.tz3210-*-ts0001-*; its six settings, two selects, three numbers and a switch, change class to theDeviceValue*classes and lose their endpoint, with unique IDs unchanged) and the TS0207 rain sensor from [Experiment] Keep Tuya datapoints as device values instead of invented attributes zha-device-handlers#5730. These snapshots are updated with the zha-quirks bump.zha/against the zigpy branch reports no errors in the changed files.Home Assistant
No change: Home Assistant wraps library entities per platform and reads
is_on,native_value,current_option,optionsand the number's limits, step, mode and unit from their state, anddevice_classfrom the entity; the converted entities keep their translation keys. Its groupable device list readsentity.endpointof every entity, which the deprecatedendpointproperty of the base class answers.Series
zha, as a GitHub stack: #1026 (entity state restore) → #1027 (device value sensors) → #1030 (this PR).
zigpy: zigpy/zigpy#1974 (per-device store), zigpy/zigpy#1975 (network store). zha-quirks: zigpy/zha-device-handlers#5730, and the Tuya writes that use these entities (zigpy/zha-device-handlers#5731).