docs: HA diagnostics-exposure design (#39) + live-confirmed fault runbook (#38) - #79
Merged
Conversation
…book (#38) #39: add docs/14, the researched, live-verified architecture for exposing all four diagnostics (compressor Hz, capability flags, link health, per-fault) in HA. Key finding: patching matter-server's custom_clusters.py is inert here (HA 2026.6.4 migrated its client to matter-python-client; native rendering needs hardcoded discovery schemas), but matter-server stores any device-reported attribute at a raw numeric path with no registration, so the clean no-upstream-PR path is: compile the attrs into the existing ep1 mfg cluster (GUI attribute-add, no new endpoint) + read them raw from a HACS integration. Phased plan + task split + dead ends documented. Corrected counts: 18 fault bits, 15 capability fields. #38: correct the fault runbook baseline to the live-observed 00 00 00 00 (byte 66 is 0x80 only in frost-guard), and make it a turnkey two-fault plan with automated :2323 read-back. Assisted-by: AI
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
1 participant
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.
Summary
Follow-up docs after PRs #77/#78, addressing the two diagnostics issues (both stay open):
#39 -
docs/14: how to expose all diagnostics in HA (researched + live-verified)Answers "expose everything in HA" with an architecture verified against the live Pi stack (HA 2026.6.4 + python-matter-server 8.1.0), not assumed. Key findings:
custom_clusters.py) is inert here: HA 2026.6.4 migrated its Matter client tomatter-python-client(matter-js), so that container's registry no longer feeds HA; and native rendering needs hardcodedMatterDiscoverySchema(no generic custom-cluster fallback).EPM.Frequency,GeneralDiagnostics.Active*Faults,OperationalError.labelwere all checked against the installedmatter/sensor.pyand are dead ends too.<ep>/4294048768/{0,1,2,3}in the node store). So the clean, no-upstream-PR path is: compile the attributes into the existing ep1 mfg cluster (a ZAP GUI attribute-add, no new endpoint) and read them raw from our own HACS integration.Phased plan (Phase 1 link-health + FeatureMap are ~free; Phase 2 firmware+GUI attrs; Phase 3 HACS integration), the exact GUI/firmware/Pi task split, and the documented dead ends are all in the doc. Corrected counts: 18 fault bits, 15 capability fields.
#38 - fault runbook made turnkey (live data)
Corrected the healthy baseline to the live-observed
00 00 00 00(byte 66 is0x80only while frost-guard is engaged), and turned §7.6 into a two-fault plan with automated:2323read-back for the at-home injection session. #38 stays open until a bit is observed firing.Test
bash/host QA unaffected. Markdown em-dash-clean (stop-slop).Assisted-by: AI