RFC: Handling physical actuator hardware anomalies & protection lockouts via Home Assistant Repairs (Ref PR #593)

[GreenGrassBlueOcean]

Updated 2026-10-01: PR #593 has been reworked from a light-only repair into a gateway-level device health tracker. The sections below describe the current design; the open questions are at the end.

Purpose & Context

This discussion is about how and if the MyHOME integration should detect, show and trace physical actuator faults on the SCS bus: missing wiring, open circuits, protective lockouts. Maintainer and community input is welcome.

Companion PR: #593, refactor(repairs): track device faults per gateway and raise them as self-clearing repair issues.

---

The Real-World Motivating Case (Light 74)

Modular actuators can enter an internal protection lockout. One live installation shows it reproducibly:

• On site: an actuator at address 74 (A=7, PL=4) with a load wire missing from its output terminal; its front LED blinks red.
• On the bus (MH200, catalogued as EVID-MH200-WHAT19-FAULT in the OpenWebNet Encyclopedia):

  *1*19*74##                                  status reply: WHAT 19
  *#1001*74*11*111110111111111111110111##     WHO 1001 DIMENSION 11 autodiagnostic mask
  

• What the evidence supports, and what it does not:
  • WHAT 19 is absent from WHO_1.pdf, the Encyclopedia and OPEN.db, so it is an undocumented status.
  • OPEN.db calls WHO 1001 DIMENSION 11 a 24-bit autodiagnostic mask sent "when there are problems hardware/software", but gives no meaning per bit. openwebnet-mcp also flags DIMENSION 11 as undocumented for WHO 1001. The Encyclopedia warns not to carry the WHO 1004 active-low fault labels over to WHO 1001.
  • An earlier version of this post read bits 6 and 21 as an open-circuit/fuse fault. That reading is not supported. A healthy MyHomeServer1 device interview in our captures answers *#1001*0*7*111111111111111101101111##, so zero bits do not by themselves mean a fault.
• History in MyHOME: before fix(light): keep the last state when a light reports an unknown WHAT #456 any status 1..31 counted as "on", so the light stuck on. Since fix(light): keep the last state when a light reports an unknown WHAT #456 the entity shows unknown with unknown_state: 19, but the user is not told why.

---

The Implementation in PR #593

One tracker per gateway (device_health.py) is the only code that creates or deletes per-device fault issues in Settings → System → Repairs:

1. Fed from the bus, not from entities: every frame passes through the tracker. Lights and switches with no entity still raise their issue. On a shared bus, only the gateway that owns WHO 1 raises lighting faults; WHO 1001 follows WHO 1.
2. Lighting rule: a WHO 1 status outside the published table raises unmapped_device_status, which shows the address and the code.
3. The WHO 1001 mask is evidence, never a trigger: a mask seen within 10 s for the same address is attached to the issue exactly as received (unmapped_device_status_autodiag). It is not decoded and does not raise an issue on its own.
4. Self-clearing:
   • the next normal status (on, off or a level) withdraws the issue;
   • so does deleting the device's entity;
   • an unload/reload clears it, and the next setup raises it again if the fault is still there.
   • An issue is written once per change, so a stuck actuator answering every poll does not rewrite the registry.
5. Neutral wording (en/fr/it/nl): it asks the owner to check the status LED, the load and its wiring, and to report the code if the device works normally. It makes no claims about specific models, fuses or open loads.
6. One mechanism for entity-side faults: the climate "heating zone no longer answers" issue now uses the same tracker. Diagnostics list the active faults.

---

Coverage: how we know it does not cry wolf

The PR replays every capture we hold through the tracker:

• 63 files from MH200, MH200N, MH201, MH202, F454, F461, H4890 and MyHomeServer1, with about 1000 WHO 1 status frames and 164 WHO 1001 frames.
• Only the two captures of the faulty address 74 may raise a fault. Every other plant must raise nothing.
• No frame of the Encyclopedia golden corpus may raise one.
• Every published WHO 1 WHAT (0–18, 20–29, 30, 31) must not count as a fault, and values outside the table must.

This proves the absence of false positives on healthy plants. It does not prove that WHAT 19 is the general fault signature: we have one faulty actuator on one gateway firmware.

---

Collecting fault traces

Hardware failures are hard to catch in the wild, so the proposal is to cause them on a bench and record them with the trace recorder:

1. Pick an actuator per family (F411 relay, F414 and F418U2 dimmers, a shutter actuator), behind an MH200, MH200N, F454 and MyHomeServer1 where possible.
2. Record the healthy baseline: *#1*WHERE## and *#1001*WHERE*7##.
3. Remove the load (or the wire) and record the same two requests. Then restore the load and record them once more.
4. File each run as an Encyclopedia evidence record, and add it to the replay test with its expected outcome.

That tells us whether WHAT 19 is universal or model- and firmware-specific. Comparing faulty and healthy masks of the same model is the only route towards ever giving a mask bit a meaning.

---

Open Questions

1. Repairs and/or a diagnostic entity: should the same tracker also drive a binary_sensor (PROBLEM, EntityCategory.DIAGNOSTIC) per affected device, so faults can trigger automations and have history? The tracker makes this a small addition.
2. Availability: the PR keeps the entity available with state unknown; unavailable would hide the last state seen on the bus. Is that the right call?
3. Next classifiers: WHO 1004 central-unit and zone faults and WHO 18 DIMENSION 250 Stop&Go breakers are specified in the published docs, so they are the strongest candidates. Our corpus has no frames of either yet. Captures from anyone with a 3550/4695 central unit or a Stop&Go breaker would unblock them.
4. WHO 1001 bit meanings: until bench captures exist, the mask stays raw evidence. Does anyone hold documentation or captures that tie individual bits to causes?

[GreenGrassBlueOcean]

@anotherjulien tagging you here as our most trusted openwebnet expert. I am mostly concerned how we are going to implement this as traces for hardware failure are difficult to collect