feat(#72): runtime capability gating wiring (ESP32 + AmebaZ2) (#101)

* feat(#72): ESP32 runtime capability gating wiring [BENCH-PENDING, do not merge yet]

Wires the shared gate predicates (matter_aircon_map.h, PR #100) into the ESP32
features callback so a per-unit A/C hides the surfaces it lacks:
  power_save -> eco ep, fan_mute -> quiet ep, power_display -> display ep
    via esp_matter::endpoint::enable/disable (the CHIP ember emberAfEndpointEnable-
    Disable is declared but NOT linked in esp-matter's data model -- confirmed at
    link time -- so the esp_matter-native per-endpoint API is used instead);
  cool_heat -> Thermostat FeatureMap (35 Heat+Cool+Auto vs 2 Cool-only) via
    attribute::update of the global FeatureMap attribute.

Strategy: retroactive-correct. Endpoints created at boot (stable IDs, contiguous;
never skip endpoint::create) then hidden from on_features once the 0x66 reply lands.
Runs in bus-task context under the CHIP stack lock; ordering is safe (bus task runs
after esp_matter::start()/enable_all()). Diff-guarded off the known boot layout so an
all-present unit (every unit we own) makes ZERO ember/attribute calls.

Compiles + links clean (debug, 15% flash free). Bumps PROJECT_VER 1.1.8 -> 1.1.9.

NOT FOR MERGE until validated on a bench (user rule + #64): needs a flag-ABSENT unit
or a spoofed 0x66 reply to exercise the hide path (all our units report every
capability present), AND matter-server confirmation that HA drops the entity /
re-derives HVAC modes on a live PartsList/FeatureMap change vs. a manual re-interview.
Compare the exposed model against firmware/../72-baseline.json. AmebaZ2 wiring
(matter_drivers.cpp, emberAfEndpointEnableDisable + FeatureMap::Set) still to write.

Assisted-by: AI

* chore(#72): bump esp32 to 1.1.10 (clean build deployed to node 35 after forced-gate validation)

Node 35 validated the gating (endpoint::disable removes ep3 from PartsList, matter-
server picks it up) then was reverted to this clean gating build (eco re-enabled,
matches baseline). Still BENCH-PENDING / not for merge.

Assisted-by: AI

* feat(#72): AmebaZ2 runtime capability gating wiring

Mirrors the ESP32 gating on the AmebaZ2 path (matter_drivers.cpp features callback),
using the same shared predicates (matter_aircon_map.h):
  power_save->eco / fan_mute->quiet / power_display->display via emberAfEndpointEnable-
  Disable -- which LINKS on AmebaZ2 (ember static .zap data model, attribute-storage.cpp),
  unlike esp-matter where it is declared-but-unlinked. It flips the isEnabled bit on the
  existing endpoint slot: no removal, no renumber, so the {0..10} contiguity boot-fault
  rule is untouched.
  cool_heat -> Thermostat FeatureMap (35 vs 2) via ThermAttr::FeatureMap::Set (ep1 is a
  composite endpoint, cannot be endpoint-disabled).
Diff-guarded off the boot layout (all-present unit = zero calls); bus-task context so it
takes the CHIP stack lock. Builds + links clean (--debug, serial 11426). Bumps
version.txt 1.3.25 -> 1.3.26.

Same retroactive-correct strategy + caveats as the ESP32 side (validated on node 35):
endpoint disable propagates to matter-server but HA leaves a runtime-hidden entity
lingering; the clean path is gating at commissioning (persist-at-boot follow-up).

Assisted-by: AI

Author: AndrewDemsDS

firmware/esp32-matter/CMakeLists.txt

@@ -2,7 +2,7 @@
 #   . ~/esp/esp-idf-v5.5.4/export.sh && . $ESP_MATTER_PATH/export.sh
 #   idf.py set-target esp32 && idf.py build flash monitor
 cmake_minimum_required(VERSION 3.16)
-set(PROJECT_VER "1.1.8")
+set(PROJECT_VER "1.1.10")
 
 # Unified versioning (issue #77): the Matter softwareVersion INT is DERIVED from PROJECT_VER --
 # MAJOR*10000+MINOR*100+PATCH -> a readable, strictly-monotonic uint32. This keeps the human

firmware/esp32-matter/main/app_main.cpp

@@ -692,12 +692,67 @@ static void on_status(const HisenseState *st)
     // lk (ScopedChipStackLock) releases the CHIP stack lock here at scope exit.
 }
 
-// 0x66/40 ProductType feature-flags (bus-task context) -> log. Bit positions RE'd from the
-// stock firmware; decoded in the shared driver, not surfaced to HA (capability flags are static).
+/* #72 runtime capability gating. Hide the Matter surfaces a per-unit A/C does not support, decided
+ * by the SHARED predicates (matter_aircon_map.h) so this path and the AmebaZ2 one cannot drift:
+ *   power_save -> eco ep, fan_mute -> quiet ep, power_display -> display ep (endpoint enable/disable);
+ *   cool_heat  -> Thermostat FeatureMap (35 Heat+Cool+Auto vs 2 Cool-only).
+ *
+ * STRATEGY (first cut): retroactive-correct. Endpoints are created at boot (stable IDs, contiguous
+ * table -- we NEVER skip endpoint::create, a renumber would hard-fault the AmebaZ2 boot table) and
+ * default-enabled; this hides the absent ones once the 0x66 features reply lands. Runs in bus-task
+ * context, so it takes the CHIP stack lock (like on_link). Ordering is safe: esp_matter::start()
+ * calls endpoint::enable_all() which would clobber a pre-start disable, but the bus task only runs
+ * AFTER start(), so on_features always fires post-start.
+ *
+ * The guards are seeded to the KNOWN boot layout (all enabled; FeatureMap default 35), so an
+ * all-present unit -- every unit we own -- makes ZERO ember/attribute calls and never churns
+ * Descriptor/FeatureMap change reports on the ~60s features refresh.
+ *
+ * BENCH-PENDING, DO NOT SHIP UNVALIDATED (#64 lesson): needs (a) a flag-ABSENT unit or a spoofed
+ * 0x66 reply to exercise the hide path (all our units report every capability present), and
+ * (b) matter-server validation that HA actually drops the entity / re-derives HVAC modes on a live
+ * PartsList/FeatureMap change vs. requiring a manual re-interview. KNOWN CAVEAT: a unit commissioned
+ * DURING the boot window (before the first 0x66 reply) captures the full layout into HA's interview
+ * snapshot and needs a manual re-interview to reflect a later correction; persist-and-gate-at-boot
+ * is the follow-up if that matters. Compare the exposed PartsList/FeatureMap against 72-baseline.json. */
+static void apply_capability_gates(const HisenseFeatures *f)
+{
+    static int8_t  g_eco = 1, g_quiet = 1, g_display = 1;
+    static uint32_t g_fm = MATTER_THERMOSTAT_FEATUREMAP_FULL;
+
+    const int8_t   eco = matter_gate_eco(f), quiet = matter_gate_quiet(f), display = matter_gate_display(f);
+    const uint32_t fm  = matter_thermostat_featuremap(f);
+    if (eco == g_eco && quiet == g_quiet && display == g_display && fm == g_fm) return;   // common case: no-op
+
+    lock::ScopedChipStackLock lk(portMAX_DELAY);
+    // esp_matter's native per-endpoint enable/disable (the CHIP ember emberAfEndpointEnableDisable
+    // is declared but NOT linked in esp-matter's data model). endpoint::get(id) resolves the handle.
+    auto gate_ep = [](uint16_t id, int8_t want, int8_t *cur, const char *name) {
+        if (want == *cur) return;
+        endpoint_t *ep = endpoint::get(id);
+        if (!ep) return;
+        (want ? endpoint::enable(ep) : endpoint::disable(ep));
+        *cur = want;
+        ESP_LOGW(TAG, "#72 gate: %s ep%u %s", name, id, want ? "shown" : "HIDDEN");
+    };
+    gate_ep(s_ep_eco,     eco,     &g_eco,     "eco");
+    gate_ep(s_ep_mute,    quiet,   &g_quiet,   "quiet");
+    gate_ep(s_ep_display, display, &g_display, "display");
+    if (fm != g_fm)        {
+        esp_matter_attr_val_t v = esp_matter_bitmap32(fm);
+        attribute::update(s_ep_id, Thermostat::Id, chip::app::Clusters::Globals::Attributes::FeatureMap::Id, &v);
+        g_fm = fm;
+        ESP_LOGW(TAG, "#72 gate: thermostat FeatureMap -> %u (%s)", (unsigned) fm,
+                 fm == MATTER_THERMOSTAT_FEATUREMAP_FULL ? "Heat+Cool+Auto" : "Cool-only");
+    }
+}
+
+// 0x66/40 ProductType feature-flags (bus-task context). Log, then gate the per-unit capabilities (#72).
 static void on_features(const HisenseFeatures *f)
 {
     ESP_LOGI(TAG, "A/C features (0x66/40): ai=%d display=%d swing8=%d eco=%d mute=%d purify=%d",
              f->ai, f->power_display, f->swing_dir_8, f->power_save, f->fan_mute, f->purify);
+    apply_capability_gates(f);
 }
 
 // Bus link lost/restored (#56). On loss, null every liveness attribute (LocalTemperature +

firmware/esp32-matter/sdkconfig.defaults

@@ -46,8 +46,8 @@ CONFIG_CUSTOM_DEVICE_INFO_PROVIDER=y
 # so it (and the fallback NUMBER) MUST stay equal to PROJECT_VER or the device reports a stale
 # softwareVersionString. Edit PROJECT_VER in CMakeLists.txt, then update both lines below.
 # esp32-lint.sh enforces this equality (fails the commit/CI if they drift).
-CONFIG_DEVICE_SOFTWARE_VERSION_NUMBER=10108
-CONFIG_DEVICE_SOFTWARE_VERSION_STRING="1.1.8"
+CONFIG_DEVICE_SOFTWARE_VERSION_NUMBER=10110
+CONFIG_DEVICE_SOFTWARE_VERSION_STRING="1.1.10"
 # --- OTA hardening (faster + reliable on marginal Wi-Fi) ---
 # Delta OTA: ship a diff (tens of KB) instead of the full ~1.5MB image over BDX.
 CONFIG_ENABLE_DELTA_OTA=y

firmware/src/sdk-edits/matter_drivers.cpp

@@ -37,6 +37,7 @@ static void hisense_breakglass_start(void);
 #include <app-common/zap-generated/ids/Attributes.h>
 #include <app-common/zap-generated/ids/Clusters.h>
 #include <app/util/attribute-table.h>
+#include <app/util/endpoint-config-api.h>       // #72 emberAfEndpointEnableDisable (runtime endpoint gating)
 #include <protocols/interaction_model/StatusCode.h>
 #include <app/server/Server.h>                 // Server / fabric table / commissioning window (F1 "77")
 #include <app/server/CommissioningWindowManager.h>
@@ -480,6 +481,39 @@ static void matter_driver_on_recommission(uint8_t reason)
 // Driver feature-flags callback (bus-task context): log the A/C's 0x66/40 ProductType
 // capability/state flags each time they're parsed. Not surfaced to HA (capability flags
 // are static per model); available in-driver via hisense_get_features().
+/* #72 runtime capability gating (mirrors the ESP32 path; shared decision predicates in
+ * matter_aircon_map.h). AmebaZ2 uses the ember STATIC .zap data model, so emberAfEndpointEnable-
+ * Disable -- which LINKS here (attribute-storage.cpp), unlike esp-matter -- flips the isEnabled bit
+ * on the existing endpoint slot: no removal, no renumber, so the {0..10} contiguity boot-fault rule
+ * is untouched. cool_heat gates the composite ep1's Thermostat FeatureMap (35 Heat+Cool+Auto vs 2
+ * Cool-only) via the generated Set accessor (ep1 cannot be endpoint-disabled). Diff-guarded off the
+ * boot layout so an all-present unit makes ZERO calls. Bus-task context -> take the CHIP stack lock.
+ *
+ * BENCH note (validated on the ESP32 side, #72): the endpoint disable propagates to matter-server,
+ * but HA leaves a runtime-hidden entity lingering (unavailable) until a reload; the clean case is a
+ * unit gated at commissioning. The FeatureMap runtime change's HA re-derivation is still unproven. */
+static void apply_capability_gates(const HisenseFeatures *f)
+{
+    static int8_t   g_eco = 1, g_quiet = 1, g_display = 1;
+    static uint32_t g_fm  = MATTER_THERMOSTAT_FEATUREMAP_FULL;
+
+    const int8_t   eco = matter_gate_eco(f), quiet = matter_gate_quiet(f), display = matter_gate_display(f);
+    const uint32_t fm  = matter_thermostat_featuremap(f);
+    if (eco == g_eco && quiet == g_quiet && display == g_display && fm == g_fm) return;   // common case: no-op
+
+    chip::DeviceLayer::PlatformMgr().LockChipStack();
+    if (eco != g_eco)        { emberAfEndpointEnableDisable(kEcoEp, eco);         g_eco = eco;
+        ChipLogProgress(DeviceLayer, "#72 gate: eco ep%d %s", kEcoEp, eco ? "shown" : "HIDDEN"); }
+    if (quiet != g_quiet)    { emberAfEndpointEnableDisable(kMuteEp, quiet);      g_quiet = quiet;
+        ChipLogProgress(DeviceLayer, "#72 gate: quiet ep%d %s", kMuteEp, quiet ? "shown" : "HIDDEN"); }
+    if (display != g_display){ emberAfEndpointEnableDisable(kDisplayEp, display); g_display = display;
+        ChipLogProgress(DeviceLayer, "#72 gate: display ep%d %s", kDisplayEp, display ? "shown" : "HIDDEN"); }
+    if (fm != g_fm)          { ThermAttr::FeatureMap::Set(kAirconEp, fm);         g_fm = fm;
+        ChipLogProgress(DeviceLayer, "#72 gate: thermostat FeatureMap -> %u (%s)", (unsigned) fm,
+                        fm == MATTER_THERMOSTAT_FEATUREMAP_FULL ? "Heat+Cool+Auto" : "Cool-only"); }
+    chip::DeviceLayer::PlatformMgr().UnlockChipStack();
+}
+
 static void matter_driver_on_features(const HisenseFeatures *f)
 {
     ChipLogProgress(DeviceLayer,
@@ -495,6 +529,7 @@ static void matter_driver_on_features(const HisenseFeatures *f)
         ChipLogProgress(DeviceLayer,
             "A/C features (ext): unknown -- reply %uB, need >39B", (unsigned)f->reply_len);
     }
+    apply_capability_gates(f);   // #72: hide the per-unit unsupported surfaces
 }
 
 // Driver link-health callback (#56, bus-task context) -> latch the state and post one

firmware/src/version.txt

@@ -1 +1 @@
-1.3.25
+1.3.26