fix(diag): byte 66 bit 7 is a mode flag, not a fault

Engaging 8 C frost-guard heat made `faults` report FAULT(S) PRESENT on a
perfectly healthy unit.

Byte 66 bit 7 sets while frost-guard is engaged and clears when it is released,
observed on hardware during the t_8heat bring-up. Byte 66 is mapped as fault
group 0x33, and HisenseFaults.any deliberately ORs the RAW bytes so that an
unnamed bit still counts as a fault. That rule is right, but it made a mode flag
read as a fault.

Masked with HISENSE_FAULT_NONFAULT_PROTECT, and the console's unnamed-bit
reporting aligned to match.

The mask is deliberately narrow: ONLY bits proven not to be faults belong in it.
Unnamed bits stay counted, because a bit we cannot name is still the A/C
reporting something, and answering 'healthy' because we lack a name for it is
the worst failure a diagnostics feature can have. This is an exception to that
rule, not a relaxation of it, and the tests pin that distinction: bit 7 alone
does not raise a fault, bit 4 still does, the two together still do, and any
OTHER unnamed bit in the same byte still does.

Worth noting how this was caught: the frame-diff tool prints UNNAMED for bits it
has no name for rather than ignoring them. A tool that reported only known bits
would have hidden it, and the false alarm would have shipped.

Tests: 316 codec (was 310).
Assisted-by: AI

Author: AndrewDemsDS

firmware/esp32-matter/main/diag_console.cpp

@@ -267,7 +267,10 @@ static int cmd_faults(int, char **)
     };
     for (auto &x : named) if (x.v) printf("  FAULT: %s\r\n", x.n);
     // A set bit with no name still matters: warn rather than imply we understood the byte.
-    uint8_t known[4] = { 0xFF, 0xF8, 0x78, 0x10 };
+    // Byte 66 bit 7 is a mode flag, not a fault, so it must not be reported as an unnamed
+    // fault bit either (see HISENSE_FAULT_NONFAULT_PROTECT).
+    uint8_t known[4] = { 0xFF, 0xF8, 0x78,
+                         (uint8_t)(0x10 | HISENSE_FAULT_NONFAULT_PROTECT) };
     uint8_t rawb[4]  = { f.raw_indoor, f.raw_module, f.raw_outdoor, f.raw_protect };
     int off[4] = { HISENSE_FAULT_BYTE_INDOOR, HISENSE_FAULT_BYTE_MODULE,
                    HISENSE_FAULT_BYTE_OUTDOOR, HISENSE_FAULT_BYTE_PROTECT };

firmware/src/rs485-driver/hisense_rs485.cpp

@@ -325,7 +325,12 @@ bool hisense_parse_faults(const uint8_t *buf, size_t len, HisenseFaults *out)
     // `any` deliberately ORs the RAW bytes, not the named bits: an undocumented bit in
     // one of these bytes is still the A/C reporting something wrong, and reporting
     // "healthy" because we lack a name for it would be the worst possible failure.
-    out->any = (out->raw_indoor | out->raw_module | out->raw_outdoor | out->raw_protect) != 0;
+    //
+    // The one exception is byte 66 bit 7, which is a MODE flag (set while 8 C frost-guard
+    // heat is engaged), proven on hardware. Without masking it, running frost-guard made
+    // this report a fault on a healthy unit. See HISENSE_FAULT_NONFAULT_PROTECT.
+    out->any = (out->raw_indoor | out->raw_module | out->raw_outdoor
+                | (uint8_t)(out->raw_protect & ~HISENSE_FAULT_NONFAULT_PROTECT)) != 0;
     out->valid = true;
     return true;
 }

firmware/src/rs485-driver/hisense_rs485.h

@@ -588,6 +588,19 @@ static inline bool hisense_setpoint_in_range(int8_t setpoint, bool fahrenheit)
 #define HISENSE_FAULT_BYTE_OUTDOOR 64   /* payload 0x31 */
 #define HISENSE_FAULT_BYTE_PROTECT 66   /* payload 0x33 */
 
+/* Bits in a fault byte that are NOT faults.
+ *
+ * Byte 66 bit 7 sets while 8 C frost-guard heat is ENGAGED and clears when it is released
+ * (observed on hardware 2026-07-19 during the t_8heat bring-up). It is a mode flag sharing
+ * the byte, not a fault. Counting it made `faults` report FAULT(S) PRESENT on a perfectly
+ * healthy unit that happened to be in frost-guard mode.
+ *
+ * Only bits PROVEN not to be faults belong here. Unnamed bits stay counted on purpose: a
+ * bit we cannot name is still the A/C reporting something, and answering "healthy" because
+ * we lack a name for it is the worst failure a diagnostics feature can have. This mask is
+ * the narrow exception to that rule, not a relaxation of it. */
+#define HISENSE_FAULT_NONFAULT_PROTECT 0x80
+
 typedef struct {
     bool    valid;        // a long-enough status frame was parsed
     bool    any;          // true if ANY fault bit is set (cheap "is it healthy")

firmware/src/version.txt

@@ -1 +1 @@
-1.2.23
+1.2.24

firmware/test/test_codec.cpp

@@ -491,6 +491,28 @@ int main() {
             CHECK(fl.any, "%s also raises any", c.name);
         }
 
+        // Byte 66 bit 7 is a MODE flag (8 C frost-guard engaged), not a fault. Observed on
+        // hardware setting and clearing with the mode. Counting it reported a fault on a
+        // healthy unit in frost-guard, which is the diagnostics feature crying wolf.
+        make_status(s, true, HISENSE_MODE_HEAT, 22, 25, 0x01, 0x00, 0x00, 0x00, 40, 30);
+        s[HISENSE_FAULT_BYTE_PROTECT] = 0x80;
+        CHECK(hisense_parse_faults(s, 160, &fl), "frost-guard frame parses");
+        CHECK(!fl.any, "byte66 bit7 alone does NOT report a fault (it is 8C heat engaged)");
+        CHECK(fl.raw_protect == 0x80, "raw byte still preserved for inspection");
+        // ...but a REAL fault in the same byte must still register, and so must the
+        // combination of the mode flag and a real fault.
+        s[HISENSE_FAULT_BYTE_PROTECT] = 0x10;
+        CHECK(hisense_parse_faults(s, 160, &fl) && fl.any && fl.over_temp,
+              "byte66 bit4 still reports over-temp");
+        s[HISENSE_FAULT_BYTE_PROTECT] = 0x90;
+        CHECK(hisense_parse_faults(s, 160, &fl) && fl.any && fl.over_temp,
+              "mode flag + real fault together still reports the fault");
+        // An unnamed bit in that byte OTHER than bit 7 must still count: the mask is a
+        // narrow proven exception, not a blanket relaxation.
+        s[HISENSE_FAULT_BYTE_PROTECT] = 0x01;
+        CHECK(hisense_parse_faults(s, 160, &fl) && fl.any,
+              "other unnamed bits in byte66 still raise any");
+
         // An UNNAMED bit must still raise `any`. Reporting "healthy" because we have no
         // name for a bit would be the worst possible failure of a diagnostics feature.
         make_status(s, true, HISENSE_MODE_COOL, 22, 25, 0x01, 0x00, 0x00, 0x00, 40, 30);