Expose air filter expiry date as HA timestamp sensor

Parses air_filter_end_date from fridge BLE payloads, promotes YYYY-MM-DD
to ISO8601, and surfaces it as a text_sensor with device_class: timestamp.
Gated by the existing hide_air_filter config flag.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mwbourgeois

components/subzero_appliance/__init__.py

@@ -427,6 +427,16 @@
         },
         "hide_water_filter",
     ),
+    (
+        "air_filter_end_date",
+        "Air Filter Expires",
+        "set_air_filter_end_date_sensor",
+        {
+            CONF_DEVICE_CLASS: DEVICE_CLASS_TIMESTAMP,
+            CONF_ICON: "mdi:calendar-clock",
+        },
+        "hide_air_filter",
+    ),
 ]
 
 # Writable numbers — entry shape: (suffix, name_suffix, setter, property_key,

components/subzero_appliance/appliance.h

@@ -87,6 +87,9 @@ class FridgeAppliance : public ApplianceBase {
   void set_water_filter_end_date_sensor(esphome::text_sensor::TextSensor *s) {
     bus_.water_filter_end_date = s;
   }
+  void set_air_filter_end_date_sensor(esphome::text_sensor::TextSensor *s) {
+    bus_.air_filter_end_date = s;
+  }
 
 protected:
   SubzeroHub *hub() override { return &hub_; }

components/subzero_protocol/dispatch.h

@@ -108,6 +108,8 @@ inline void dispatch_fridge(const FridgeState &s, Bus &bus) {
     bus.publish_water_filter_gal(*s.water_filter_gal_remaining);
   if (s.water_filter_end_date)
     bus.publish_water_filter_end_date(*s.water_filter_end_date);
+  if (s.air_filter_end_date)
+    bus.publish_air_filter_end_date(*s.air_filter_end_date);
 }
 
 template <typename Bus>

components/subzero_protocol/dispatch_esphome.h

@@ -142,6 +142,7 @@ struct FridgeBus : CommonBus {
   esphome::sensor::Sensor *water_filter_pct = nullptr;
   esphome::sensor::Sensor *water_filter_gal = nullptr;
   esphome::text_sensor::TextSensor *water_filter_end_date = nullptr;
+  esphome::text_sensor::TextSensor *air_filter_end_date = nullptr;
 
   void publish_door_ajar(bool v) { detail::publish_if(door_ajar, v); }
   void publish_frz_door_ajar(bool v) { detail::publish_if(frz_door_ajar, v); }
@@ -175,6 +176,9 @@ struct FridgeBus : CommonBus {
   void publish_water_filter_end_date(const std::string &v) {
     detail::publish_if(water_filter_end_date, v);
   }
+  void publish_air_filter_end_date(const std::string &v) {
+    detail::publish_if(air_filter_end_date, v);
+  }
 };
 
 struct DishwasherBus : CommonBus {

components/subzero_protocol/protocol.cpp

@@ -278,6 +278,14 @@ FridgeState parse_fridge(const std::string &json) {
       state.water_filter_end_date = v;
     }
   }
+  if (auto raw = opt_str(data["air_filter_end_date"])) {
+    const std::string &v = *raw;
+    if (v.size() == 10 && v[4] == '-' && v[7] == '-') {
+      state.air_filter_end_date = v + "T00:00:00+00:00";
+    } else {
+      state.air_filter_end_date = v;
+    }
+  }
   return state;
 }
 

components/subzero_protocol/protocol.h

@@ -60,6 +60,7 @@ struct FridgeState {
   // to an ISO8601 timestamp ("YYYY-MM-DDT00:00:00+00:00") by the parser so
   // Home Assistant's timestamp device_class accepts it.
   std::optional<std::string> water_filter_end_date;
+  std::optional<std::string> air_filter_end_date;
 };
 
 struct DishwasherState {

tests/cpp/dispatch_test.cpp

@@ -75,6 +75,9 @@ struct FridgeRecorder : CommonRecorder {
   void publish_water_filter_end_date(const std::string &v) {
     strings["water_filter_end_date"] = v;
   }
+  void publish_air_filter_end_date(const std::string &v) {
+    strings["air_filter_end_date"] = v;
+  }
 };
 
 struct DishwasherRecorder : CommonRecorder {

tests/cpp/protocol_test.cpp

@@ -111,6 +111,7 @@ json fridge_to_json(const FridgeState &s) {
   OPT_PUT(o, s, water_filter_pct_remaining);
   OPT_PUT(o, s, water_filter_gal_remaining);
   OPT_PUT(o, s, water_filter_end_date);
+  OPT_PUT(o, s, air_filter_end_date);
   return o;
 }
 

tests/fixtures/fridge_back_2028_d5_full.expected.json

@@ -10,6 +10,7 @@
   "water_filter_pct_remaining": 0,
   "water_filter_gal_remaining": 107,
   "water_filter_end_date": "2023-10-04T00:00:00+00:00",
+  "air_filter_end_date": "2024-05-11T00:00:00+00:00",
   "common": {
     "sabbath_on": false,
     "service_required": false,

tests/fixtures/fridge_pro3650g_d4_full.expected.json

@@ -11,6 +11,7 @@
   "water_filter_pct_remaining": 100,
   "water_filter_gal_remaining": 220,
   "water_filter_end_date": "2027-04-26T00:00:00+00:00",
+  "air_filter_end_date": "2027-04-16T00:00:00+00:00",
   "common": {
     "sabbath_on": false,
     "service_required": false,