Merge pull request #81 from AndrewDemsDS/hil/38-fault-validated

feat(diag): hardware-validate the f_e_* fault decode (closes #38)

Author: AndrewDemsDS

firmware/esp32-matter/main/diag_console.cpp

@@ -252,7 +252,7 @@ static int cmd_faults(int, char **)
            HISENSE_FAULT_BYTE_MODULE,  f.raw_module,
            HISENSE_FAULT_BYTE_OUTDOOR, f.raw_outdoor,
            HISENSE_FAULT_BYTE_PROTECT, f.raw_protect,
-           f.any ? "FAULT(S) PRESENT (decode confirmed; unseen vs a real fault -- cross-check `raw`)" : "all clear");
+           f.any ? "FAULT(S) PRESENT (decode confirmed vs real faults 2026-07-22 -- cross-check `raw`)" : "all clear");
     if (!f.any) {
         printf("  (all-zero is expected on a healthy unit and does NOT validate the map)\r\n");
         return 0;

firmware/src/rs485-driver/hisense_rs485.h

@@ -831,11 +831,10 @@ bool hisense_get_faults(HisenseFaults *out);
 // bytes and returns how many. 0 if nothing has been received yet.
 //
 // This exists because the fault map's byte/bit positions are CONFIRMED by disassembly (docs/10
-// 7.5: the extractor reads the same 66/00 status frame, and the firmware's own compiled-in
-// fault names map 1:1 onto bytes 39/40/64/66), but no bit has yet been seen SET against a unit
-// actually reporting a fault. A healthy unit reads all-zero, which confirms nothing on its own,
-// so being able to read the bytes directly is what makes the last (semantic) step falsifiable.
-// The fault-injection runbook is docs/10 7.6.
+// 7.5) AND validated against real faults (2026-07-22, docs/10 7.6): f_e_incom (byte 39 bit 0) and
+// f_e_intemp (byte 39 bit 7) each fired on their induced fault, named correctly, and cleared on
+// undo, with the other unit staying all-clear. The raw snapshot stays for bench inspection and to
+// map the remaining bytes (40/64/66) the same way if wanted.
 #define HISENSE_RAW_SNAPSHOT_LEN 160
 size_t hisense_get_last_status_frame(uint8_t *out, size_t cap);
 

firmware/src/sdk-edits/hisense_diag_console.h

@@ -154,7 +154,7 @@ static void diag_cmd_faults(int sock)
         HISENSE_FAULT_BYTE_MODULE,  f.raw_module,
         HISENSE_FAULT_BYTE_OUTDOOR, f.raw_outdoor,
         HISENSE_FAULT_BYTE_PROTECT, f.raw_protect,
-        f.any ? "FAULT(S) PRESENT (decode confirmed; unseen vs a real fault -- cross-check `raw`)" : "all clear");
+        f.any ? "FAULT(S) PRESENT (decode confirmed vs real faults 2026-07-22 -- cross-check `raw`)" : "all clear");
     diag_say(sock, b);
     if (!f.any) {
         diag_say(sock, "  (all-zero is expected on a healthy unit and does NOT validate the map)\r\n");
@@ -303,7 +303,7 @@ static void diag_handle_line(int sock, char *line)
             "commands: features | poll | faults | raw | link | sys | version | help | quit\r\n"
             "  features  cached 0x66/40 ProductType capability flags for THIS unit\r\n"
             "  poll      last decoded A/C status frame\r\n"
-            "  faults    decoded f_e_* fault bits (#38; decode confirmed, unseen vs a real fault)\r\n"
+            "  faults    decoded f_e_* fault bits (#38; decode confirmed vs real faults)\r\n"
             "  raw       hexdump the last status frame (what falsifies the map)\r\n"
             "  sys       downlink hand-off counter + free heap (why Matter attrs go stale)\r\n");
         return;

firmware/src/version.txt

@@ -1 +1 @@
-1.3.19
+1.3.20

reverse-engineering/docs/10-stock-fw-init-and-comms.md

@@ -694,11 +694,24 @@ CONFIRMED by two independent lines of disassembly (control-flow + offset math, a
 fault-name strings). What remains unproven is purely *semantic*: whether a genuinely faulted unit
 asserts these bits on the wire. That is the one gate left, and it needs hardware. See §7.6.
 
-### 7.6 Remaining gate: hardware fault-injection runbook
+### 7.6 Hardware validation [CONFIRMED 2026-07-22] and the fault-injection runbook
 
-Static RE cannot go further: a healthy unit reads all-clear, so "no faults" proves nothing about
-whether a real fault sets its predicted bit. Confirm one bit end-to-end on a debug-flavour unit
-(so the `:2323` console is reachable), cheapest step first:
+**Validated on real hardware, 2026-07-22** (office AmebaZ2, v1.3.19). Two faults were induced; each
+set exactly its predicted bit, named it correctly, stayed isolated to the affected unit, and cleared
+on undo:
+
+| fault | induced by | observed |
+|---|---|---|
+| `f_e_incom` | cut the indoor-to-outdoor comms line | byte 39 -> `0x01` (bit 0), `com=1`; back to `0x00` on reconnect |
+| `f_e_intemp` | unplug the indoor temp thermistor | byte 39 -> `0x80` (bit 7), `temp=1`; back to `0x00` on reconnect |
+
+The kitchen unit read all-clear the whole time (no false positive). Bit 0 and bit 7 are the two ends
+of byte 39, so both the byte offset and the within-byte bit decode are confirmed against live faults.
+That closes #38. Bytes 40/64/66 rest on the same extractor + compiled-name-string evidence (§7.5) but
+have not each been seen firing; the runbook below drives that if wanted.
+
+Confirm a bit end-to-end on a debug-flavour unit (so the `:2323` console is reachable), cheapest step
+first:
 
 1. **Baseline (captured live 2026-07-22).** `nc <unit> 2323`, then `faults` (expect `no faults`)
    and `raw` (hexdump). On a normal healthy unit bytes 39/40/64/66 read `00 00 00 00` (confirmed on