Skip to content

Add a text platform for ZCL string attributes - #1023

Draft
zigpy-review-bot wants to merge 6 commits into
devfrom
zigpy-bot/text-platform
Draft

zigpy-review-bot wants to merge 6 commits into
devfrom
zigpy-bot/text-platform

Conversation

@zigpy-review-bot

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

Copy link
Copy Markdown
Collaborator

Summary

Adds a text entity platform, so a quirk can expose a writable string attribute as a Home Assistant text entity instead of users writing it with zha.set_zigbee_cluster_attribute. Tracked in zigpy/backlog#85. This covers ZCL attributes only; values that aren't attributes are left to the separate device-values work.

Changes

  • Platform.TEXT and EntityPlatform.TEXT (the latter is what quirk metadata uses).
  • zha/application/platforms/text: BaseText with a TextState carrying the value, the mode (text / password), native_min / native_max and an optional pattern, mirroring HA's TextEntity; TextConfigurationEntity, a config entity backed by a ZCL string attribute. It shows the cached value, updates on reads, reports and writes, and writes the attribute when HA sets a new value. Attributes typed as raw bytes (LVBytes and the like, as some manufacturer clusters use for labels) are decoded from and encoded to UTF-8. Without an explicit max_length (or a subclass's own limit), the limit is the attribute type's own (LimitedCharString(16) gives 16) or HA's 255. A device value that HA would refuse as a state (outside the length limits or not matching the pattern) is shown as unknown. A value the attribute type can't hold (a ZCL string holds at most 254 bytes) raises a ZHAException instead of zigpy's ValueError, which HA would show as an unknown error. In password mode a failed write raises without the value in the error.
  • No default entities use the platform yet, so no device snapshots change.

Testing

tests/test_platform_text.py covers the state, the options, updates from reports and writes, raw-byte attributes, values outside the limits, values too long for the attribute type, the support check and failed writes (100% line and branch coverage of the new module). The full suite passes locally, and pre-commit (ruff, mypy, codespell) is clean.

Related

Open items

  • ZCL string lengths count bytes, while HA's limits (and zigpy's LimitedCharString) count characters, so a non-ASCII value within native_max can still be too long for the device. zigpy sends it anyway (it only refuses more than 254 bytes, which the entity reports as a write error), and the device rejects or truncates it.
  • A successful write is cached and persisted by zigpy, so a write-only secret (a Wi-Fi password, say) would be shown by the entity, stored in zigbee.db, included in ZHA diagnostics and written to zigpy's and ZHA's debug logs. password mode only masks the input in the UI. Whether such attributes should be exposed at all is left open in [ZHA] Text entity support for quirks backlog#85.

Add `Platform.TEXT` and `EntityPlatform.TEXT`, a `BaseText` entity with
a `TextState` (value, mode, length limits and pattern), and a
`TextConfigurationEntity` that shows and writes a ZCL string attribute.
Attributes typed as raw bytes are decoded from and encoded to UTF-8.

No default entities use it yet; it is meant for quirks.
HA refuses a text state outside the length limits or pattern, so show
such a device value, and the ZCL invalid string, as unknown. Raise the
password-mode write error outside the except block so the original
error, which holds the value, is not attached to it.
zigpy rebuilds received values with the attribute type, which drops the
`invalid` flag, so the check only ever saw values set directly.
HA allows 255 characters, while a ZCL string holds 254 bytes at most,
and zigpy raises a ValueError for longer values that HA shows as an
unknown error. Turn it into a ZHAException (without the zigpy message in
password mode). Default the length limit to the attribute type's own
limit, such as `LimitedCharString(16)`, when none is given.
@zigpy-review-bot zigpy-review-bot added entities Issue or PR about (custom) entities new feature Adds new feature bot-watch: fix zigpy-review-bot follows this thread and also pushes fixes (review + fix) labels Nov 16, 2026
@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.51%. Comparing base (2da1a5b) to head (cc923cb).

Additional details and impacted files
@@            Coverage Diff             @@
##              dev    #1023      +/-   ##
==========================================
+ Coverage   97.48%   97.51%   +0.02%     
==========================================
  Files          61       63       +2     
  Lines       10870    10988     +118     
==========================================
+ Hits        10597    10715     +118     
  Misses        273      273              

☔ View full report in Codecov by Harness.
📢 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.

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) entities Issue or PR about (custom) entities new feature Adds new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant