feat: map BLE notif_type pushes to Notification Event sensor (#99)

Adds a Notification Event text sensor on every appliance that surfaces
push notifications (washer cycle complete, fridge door left open, oven
preheat reached, water/air filter expired, etc.) as human-readable
event names HA automations can trigger on.

Mappings come from issue #69, where users captured BLE traffic during
each Sub-Zero iOS app push notification. Coverage:
- Fridge (101, 102, 106-109): door open + setpoint changes + filter expiry
- Range (201, 203, 205, 207-211, 213, 215, 218): preheat, probe, timers,
  timed cook, oven door
- Dishwasher (301, 302, 304, 306, 307): cycle started/complete/cancelled,
  rinse aid low

Unknown codes fall back to "<appliance>_event_<n>" so they remain
observable in HA. Also fixes parser rejection of msg_types:4
notification-only pushes (which fridge fw 2.27 sends for filter/door
events) — these were previously logged as "Parse failed or status!=0,
skipping". 12 new tests (9 unit + 3 fixture pairs from real captures).

Closes #69. Supersedes #96.

Co-authored-by: ManjunathByadagi <ManjunathByadagi@users.noreply.github.com>
Co-authored-by: mwbourgeois <mwbourgeois@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 4 people

components/subzero_appliance/__init__.py

@@ -216,6 +216,12 @@
             CONF_ENTITY_CATEGORY: ENTITY_CATEGORY_DIAGNOSTIC,
         },
     ),
+    (
+        "notif_event",
+        "Notification Event",
+        "set_notif_event_sensor",
+        {CONF_ICON: "mdi:bell-ring"},
+    ),
 ]
 
 # Buttons — same across all appliance types.

components/subzero_appliance/appliance_base.h

@@ -97,6 +97,9 @@ class ApplianceBase : public esphome::Component,
   void set_board_version_sensor(esphome::text_sensor::TextSensor *s) {
     common_bus()->board_version = s;
   }
+  void set_notif_event_sensor(esphome::text_sensor::TextSensor *s) {
+    common_bus()->notif_event = s;
+  }
 
   // ---- ESPHome lifecycle ----
 

components/subzero_protocol/dispatch.h

@@ -62,6 +62,8 @@ inline void dispatch_common(const CommonFields &c, Bus &bus) {
 template <typename Bus>
 inline void dispatch_fridge(const FridgeState &s, Bus &bus) {
   dispatch_common(s.common, bus);
+  if (s.notif_event)
+    bus.publish_notif_event(*s.notif_event);
   // Fridge / Freezer
   if (s.ref_set_temp)
     bus.publish_set_temp(*s.ref_set_temp);
@@ -107,6 +109,8 @@ inline void dispatch_fridge(const FridgeState &s, Bus &bus) {
 template <typename Bus>
 inline void dispatch_dishwasher(const DishwasherState &s, Bus &bus) {
   dispatch_common(s.common, bus);
+  if (s.notif_event)
+    bus.publish_notif_event(*s.notif_event);
   if (s.door_ajar)
     bus.publish_door_ajar(*s.door_ajar);
   if (s.wash_cycle_on)
@@ -148,6 +152,8 @@ inline void dispatch_dishwasher(const DishwasherState &s, Bus &bus) {
 template <typename Bus>
 inline void dispatch_range(const RangeState &s, Bus &bus) {
   dispatch_common(s.common, bus);
+  if (s.notif_event)
+    bus.publish_notif_event(*s.notif_event);
   if (s.door_ajar)
     bus.publish_door_ajar(*s.door_ajar);
   // Primary cavity

components/subzero_protocol/dispatch_esphome.h

@@ -74,6 +74,10 @@ struct CommonBus {
   esphome::text_sensor::TextSensor *os_version = nullptr;
   esphome::text_sensor::TextSensor *rtapp_version = nullptr;
   esphome::text_sensor::TextSensor *board_version = nullptr;
+  // Latest notif_type → human-readable event name (e.g. "fridge_door_open").
+  // Updated only on push messages that carry a notif_type; HA automations
+  // can trigger on state-changes here.
+  esphome::text_sensor::TextSensor *notif_event = nullptr;
 
   void publish_sabbath_on(bool v) { detail::publish_if(sabbath_on, v); }
   void publish_svc_required(bool v) { detail::publish_if(svc_required, v); }
@@ -107,6 +111,9 @@ struct CommonBus {
   void publish_board_version(const std::string &v) {
     detail::publish_if(board_version, v);
   }
+  void publish_notif_event(const std::string &v) {
+    detail::publish_if(notif_event, v);
+  }
 };
 
 struct FridgeBus : CommonBus {

components/subzero_protocol/protocol.cpp

@@ -66,6 +66,94 @@ JsonObjectConst extract_data(JsonObjectConst root, bool &is_poll) {
   return JsonObjectConst();
 }
 
+// Format the unknown-code fallback used when notif_type is present but not
+// recognized by the per-appliance mapping. Surfaces the raw integer to HA
+// (as e.g. "fridge_event_142") so users can observe and report new codes
+// without us hard-coding a placeholder name.
+std::string unknown_notif_event(const char *appliance, int notif_type) {
+  char buf[40];
+  std::snprintf(buf, sizeof(buf), "%s_event_%d", appliance, notif_type);
+  return buf;
+}
+
+// notif_type → human-readable event name. Mappings come from issue #69
+// debug captures, cross-referenced against the official Sub-Zero iOS app's
+// push notification text. Codes not in the table fall through to
+// "<appliance>_event_<n>" so unknown codes are still observable.
+std::optional<std::string> fridge_notif_event(JsonObjectConst root) {
+  auto t = opt_int(root["notif_type"]);
+  if (!t)
+    return std::nullopt;
+  switch (*t) {
+  case 101:
+    return std::string("fridge_door_open");
+  case 102:
+    return std::string("freezer_door_open");
+  case 106:
+    return std::string("fridge_setpoint_changed");
+  case 107:
+    return std::string("freezer_setpoint_changed");
+  case 108:
+    return std::string("water_filter_expired");
+  case 109:
+    return std::string("air_filter_expired");
+  default:
+    return unknown_notif_event("fridge", *t);
+  }
+}
+
+std::optional<std::string> dishwasher_notif_event(JsonObjectConst root) {
+  auto t = opt_int(root["notif_type"]);
+  if (!t)
+    return std::nullopt;
+  switch (*t) {
+  case 301:
+    return std::string("wash_cycle_started");
+  case 302:
+    return std::string("wash_cycle_complete");
+  case 304:
+    return std::string("rinse_aid_low");
+  case 306:
+    return std::string("wash_cycle_interrupted");
+  case 307:
+    return std::string("wash_cycle_cancelled");
+  default:
+    return unknown_notif_event("dishwasher", *t);
+  }
+}
+
+std::optional<std::string> range_notif_event(JsonObjectConst root) {
+  auto t = opt_int(root["notif_type"]);
+  if (!t)
+    return std::nullopt;
+  switch (*t) {
+  case 201:
+    return std::string("oven_preheat_complete");
+  case 203:
+    return std::string("oven_probe_in_use");
+  case 205:
+    return std::string("oven_probe_temp_reached");
+  case 207:
+    return std::string("kitchen_timer_ended");
+  case 208:
+    return std::string("kitchen_timer2_ended");
+  case 209:
+    return std::string("kitchen_timer_1min_remaining");
+  case 210:
+    return std::string("kitchen_timer2_1min_remaining");
+  case 211:
+    return std::string("timed_cook_ended");
+  case 213:
+    return std::string("timed_cook_1min_remaining");
+  case 215:
+    return std::string("oven_probe_within_10deg");
+  case 218:
+    return std::string("oven_door_opened");
+  default:
+    return unknown_notif_event("range", *t);
+  }
+}
+
 void fill_version(JsonObjectConst v, Version &out) {
   out.fw = opt_str(v["fw"]);
   out.api = opt_str(v["api"]);
@@ -133,12 +221,26 @@ FridgeState parse_fridge(const std::string &json) {
     return state;
   if (!doc.is<JsonObject>())
     return state;
+  JsonObjectConst root = doc.as<JsonObjectConst>();
+  // Extract notif_event from root first — `notif_type` lives at the root of
+  // push messages, alongside `seq`/`timestamp`, NOT inside `props`.
+  auto notif_event = fridge_notif_event(root);
   bool is_poll = true;
-  JsonObjectConst data = extract_data(doc.as<JsonObjectConst>(), is_poll);
-  if (data.isNull())
+  JsonObjectConst data = extract_data(root, is_poll);
+  if (data.isNull()) {
+    // msg_types:4 notification-only push: no `props`/`resp`, just notif_type
+    // at root. Mark valid so the bus can publish the event; leave data
+    // fields empty.
+    if (notif_event) {
+      state.valid = true;
+      state.is_poll = false;
+      state.notif_event = std::move(notif_event);
+    }
     return state;
+  }
   state.valid = true;
   state.is_poll = is_poll;
+  state.notif_event = std::move(notif_event);
   capture_keys(data, state.data_keys);
   fill_common(data, state.common);
 
@@ -173,13 +275,21 @@ DishwasherState parse_dishwasher(const std::string &json) {
     return state;
   if (!doc.is<JsonObject>())
     return state;
-  bool is_poll = true;
   JsonObjectConst root = doc.as<JsonObjectConst>();
+  auto notif_event = dishwasher_notif_event(root);
+  bool is_poll = true;
   JsonObjectConst data = extract_data(root, is_poll);
-  if (data.isNull())
+  if (data.isNull()) {
+    if (notif_event) {
+      state.valid = true;
+      state.is_poll = false;
+      state.notif_event = std::move(notif_event);
+    }
     return state;
+  }
   state.valid = true;
   state.is_poll = is_poll;
+  state.notif_event = std::move(notif_event);
   capture_keys(data, state.data_keys);
   fill_common(data, state.common);
 
@@ -220,12 +330,21 @@ RangeState parse_range(const std::string &json) {
     return state;
   if (!doc.is<JsonObject>())
     return state;
+  JsonObjectConst root = doc.as<JsonObjectConst>();
+  auto notif_event = range_notif_event(root);
   bool is_poll = true;
-  JsonObjectConst data = extract_data(doc.as<JsonObjectConst>(), is_poll);
-  if (data.isNull())
+  JsonObjectConst data = extract_data(root, is_poll);
+  if (data.isNull()) {
+    if (notif_event) {
+      state.valid = true;
+      state.is_poll = false;
+      state.notif_event = std::move(notif_event);
+    }
     return state;
+  }
   state.valid = true;
   state.is_poll = is_poll;
+  state.notif_event = std::move(notif_event);
   capture_keys(data, state.data_keys);
   fill_common(data, state.common);
 

components/subzero_protocol/protocol.h

@@ -38,6 +38,7 @@ struct FridgeState {
   // Top-level keys present in the data object (resp or props), in order.
   // Populated on every parse; the lambdas log these when debug mode is on.
   std::vector<std::string> data_keys;
+  std::optional<std::string> notif_event;
   CommonFields common;
   std::optional<float> ref_set_temp;
   std::optional<bool> door_ajar;
@@ -60,6 +61,7 @@ struct DishwasherState {
   bool valid = false;
   bool is_poll = false;
   std::vector<std::string> data_keys;
+  std::optional<std::string> notif_event;
   CommonFields common;
   std::optional<bool> door_ajar;
   std::optional<bool> wash_cycle_on;
@@ -82,6 +84,7 @@ struct RangeState {
   bool valid = false;
   bool is_poll = false;
   std::vector<std::string> data_keys;
+  std::optional<std::string> notif_event;
   CommonFields common;
   std::optional<bool> door_ajar;
 

tests/cpp/dispatch_test.cpp

@@ -51,6 +51,7 @@ struct CommonRecorder {
   void publish_board_version(const std::string &v) {
     strings["board_version"] = v;
   }
+  void publish_notif_event(const std::string &v) { strings["notif_event"] = v; }
 };
 
 struct FridgeRecorder : CommonRecorder {