Skip to content

[Experiment] Number, switch, select and binary sensor entities on device values - #1030

Draft
zigpy-review-bot wants to merge 1 commit into
zigpy-bot/device-value-entitiesfrom
zigpy-bot/writable-device-values
Draft

zigpy-review-bot wants to merge 1 commit into
zigpy-bot/device-value-entitiesfrom
zigpy-bot/writable-device-values

Conversation

@zigpy-review-bot

@zigpy-review-bot zigpy-review-bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

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

  • DeviceValueWriter in zha.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 raises ZHAException if the device has no store). DeviceValueSensor now builds on it, and the deprecated endpoint property [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 of NumberConfigurationEntity (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, as ConfigurableAttributeSwitch.
  • DeviceValueSelect: the members of an int enum as options, as ZCLEnumSelectEntity; 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 raises ZHAException. Home Assistant's restored state is ignored, since the store holds the value.
  • DeviceValueBinarySensor: on by truth or through a value converter; read-only.
  • A value of an unexpected type (the store is untyped at rest) reads as unknown for the number and select and as off for the switch and binary sensor, as an absent attribute does, instead of raising.

Design choices

  • One writer per value, given by the quirk (P8.2 in its smallest form). The handler shape of P8.2, one writer for a group of values receiving all changes at once, is not built; Tuya datapoints that pack several values (dp_converter) are handled inside the Tuya writer by reading the siblings from the store.
  • The writer sets the store, not the entity. The transport decides when and whether a written value is stored. Without a writer there is no transport, so the entity stores the value.
  • Optimistic, not assumed. For Tuya the value is stored when the command is built and stays stored if the send fails, as the attribute path updates the cache today. P8.2's assumed flag, confirmed or reverted by the echo, needs the ZHA value runtime and is not built.
  • One class per platform, like DeviceValueSensor, rather than a pluggable source on the ZCL quirk entities (P8.4). The state classes mirror the ZCL ones, minus the attribute names: DeviceValueSwitchState has no attribute_name or invert_attribute_name, and the binary sensor's state has no attribute_name.
  • Rejected: an inverting attribute for the switch (it would be a second value with its own declaration; no Tuya quirk uses one) and an enum sensor on a device value (not needed by the converted quirk; it would be a fifth class).

Limits

  • No assumed state and no serialisation of writes in ZHA; actions (P8.3) are not part of this PR.
  • Entity filters of quirks that match by endpoint or cluster do not match these device-bound entities.
  • Diagnostics fixtures do not restore the store, so snapshot tests cover the entities' creation, not their values.

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 deprecated endpoint of every class, unique IDs <ieee>-1-<name> through a quirk, and values surviving a rebuild of the ZHA device.
  • pytest tests against the zigpy branch with the released zha-quirks: 1809 passed.
  • With the zha-quirks PR of this series installed: 1805 passed, 4 failed, the expected snapshot changes: the three Tuya fingerbot fixtures (tz3210-*-ts0001-*; its six settings, two selects, three numbers and a switch, change class to the DeviceValue* 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.
  • mypy on 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, options and the number's limits, step, mode and unit from their state, and device_class from the entity; the converted entities keep their translation keys. Its groupable device list reads entity.endpoint of every entity, which the deprecated endpoint property 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).

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bot-watch: fix zigpy-review-bot follows this thread and also pushes fixes (review + fix) new feature Adds new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant