Expose water filter expiry date and remaining gallons (#101)

* Expose water filter expiry date and remaining gallons

* Modify tests with new keys.  This may be a bad approach of the exemplar appliances lack these keys

* modify CI for fork PRs

Author: mwbourgeois

.github/workflows/ci.yml

@@ -59,13 +59,19 @@ jobs:
           EOF
 
       - name: Patch package refs for CI
+        env:
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
         run: |
           # Point package refs to the code under test instead of a published tag.
-          # PRs: use the source branch name. Pushes: use the commit SHA.
+          # PRs: use the head repo + source branch name (supports fork PRs).
+          # Pushes: stay on the default repo and use the commit SHA.
           # Use # as sed delimiter — branch names may contain / (so | was used
           # before), but extended-regex alternation also needs |, which GNU
           # sed eats as the delimiter. # is safe in both pattern and replacement.
           REF="${GITHUB_HEAD_REF:-$GITHUB_SHA}"
+          REPO="${HEAD_REPO:-$GITHUB_REPOSITORY}"
+          sed -i -E "s#url: https://github.com/[^[:space:]]+#url: https://github.com/${REPO}#" \
+            cove-minimal-dishwasher.yaml wolf-minimal-range.yaml wolf-minimal-fridge.yaml
           sed -i -E "s#ref: (v[0-9]+\.[0-9]+\.[0-9]+|main)#ref: ${REF}#" \
             cove-minimal-dishwasher.yaml wolf-minimal-range.yaml wolf-minimal-fridge.yaml
 
@@ -112,11 +118,15 @@ jobs:
           EOF
 
       - name: Patch package refs for CI
+        env:
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
         run: |
           # Use # as sed delimiter — branch names may contain / (so | was used
           # before), but extended-regex alternation also needs |, which GNU
           # sed eats as the delimiter. # is safe in both pattern and replacement.
           REF="${GITHUB_HEAD_REF:-$GITHUB_SHA}"
+          REPO="${HEAD_REPO:-$GITHUB_REPOSITORY}"
+          sed -i -E "s#url: https://github.com/[^[:space:]]+#url: https://github.com/${REPO}#" "${{ matrix.file }}"
           sed -i -E "s#ref: (v[0-9]+\.[0-9]+\.[0-9]+|main)#ref: ${REF}#" "${{ matrix.file }}"
 
       - name: Compile ${{ matrix.file }}

components/subzero_appliance/__init__.py

@@ -63,6 +63,7 @@
     DEVICE_CLASS_DURATION,
     DEVICE_CLASS_PROBLEM,
     DEVICE_CLASS_TEMPERATURE,
+    DEVICE_CLASS_TIMESTAMP,
     ENTITY_CATEGORY_CONFIG,
     ENTITY_CATEGORY_DIAGNOSTIC,
     STATE_CLASS_MEASUREMENT,
@@ -401,6 +402,31 @@
         },
         "hide_water_filter",
     ),
+    (
+        "water_filter_gal",
+        "Water Filter Gallons Remaining",
+        "set_water_filter_gal_sensor",
+        {
+            CONF_UNIT_OF_MEASUREMENT: "gal",
+            "state_class": STATE_CLASS_MEASUREMENT,
+            "accuracy_decimals": 1,
+            CONF_ICON: "mdi:water",
+        },
+        "hide_water_filter",
+    ),
+]
+
+FRIDGE_TEXT_SENSORS = [
+    (
+        "water_filter_end_date",
+        "Water Filter Expires",
+        "set_water_filter_end_date_sensor",
+        {
+            CONF_DEVICE_CLASS: DEVICE_CLASS_TIMESTAMP,
+            CONF_ICON: "mdi:calendar-clock",
+        },
+        "hide_water_filter",
+    ),
 ]
 
 # Writable numbers — entry shape: (suffix, name_suffix, setter, property_key,
@@ -1120,7 +1146,7 @@ async def to_code(config):
     if type_ == "fridge":
         bs_list = FRIDGE_BINARY_SENSORS
         s_list = FRIDGE_SENSORS
-        ts_list = []
+        ts_list = FRIDGE_TEXT_SENSORS
         sw_list = FRIDGE_WRITABLE_SWITCHES
         n_list = FRIDGE_WRITABLE_NUMBERS
     elif type_ == "dishwasher":

components/subzero_appliance/appliance.h

@@ -81,6 +81,12 @@ class FridgeAppliance : public ApplianceBase {
   void set_water_filter_pct_sensor(esphome::sensor::Sensor *s) {
     bus_.water_filter_pct = s;
   }
+  void set_water_filter_gal_sensor(esphome::sensor::Sensor *s) {
+    bus_.water_filter_gal = s;
+  }
+  void set_water_filter_end_date_sensor(esphome::text_sensor::TextSensor *s) {
+    bus_.water_filter_end_date = s;
+  }
 
 protected:
   SubzeroHub *hub() override { return &hub_; }

components/subzero_protocol/dispatch.h

@@ -104,6 +104,10 @@ inline void dispatch_fridge(const FridgeState &s, Bus &bus) {
     bus.publish_air_filter_pct(*s.air_filter_pct_remaining);
   if (s.water_filter_pct_remaining)
     bus.publish_water_filter_pct(*s.water_filter_pct_remaining);
+  if (s.water_filter_gal_remaining)
+    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);
 }
 
 template <typename Bus>

components/subzero_protocol/dispatch_esphome.h

@@ -140,6 +140,8 @@ struct FridgeBus : CommonBus {
   esphome::sensor::Sensor *crisp_set_temp = nullptr;
   esphome::sensor::Sensor *air_filter_pct = nullptr;
   esphome::sensor::Sensor *water_filter_pct = nullptr;
+  esphome::sensor::Sensor *water_filter_gal = nullptr;
+  esphome::text_sensor::TextSensor *water_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); }
@@ -167,6 +169,12 @@ struct FridgeBus : CommonBus {
   void publish_water_filter_pct(float v) {
     detail::publish_if(water_filter_pct, v);
   }
+  void publish_water_filter_gal(float v) {
+    detail::publish_if(water_filter_gal, v);
+  }
+  void publish_water_filter_end_date(const std::string &v) {
+    detail::publish_if(water_filter_end_date, v);
+  }
 };
 
 struct DishwasherBus : CommonBus {

components/subzero_protocol/protocol.cpp

@@ -265,6 +265,19 @@ FridgeState parse_fridge(const std::string &json) {
   state.air_filter_pct_remaining = opt_float(data["air_filter_pct_remaining"]);
   state.water_filter_pct_remaining =
       opt_float(data["water_filter_pct_remaining"]);
+  state.water_filter_gal_remaining =
+      opt_float(data["water_filter_gal_remaining"]);
+  // Appliance sends a date-only string (e.g. "2027-05-10"). Promote to a
+  // fully-qualified ISO8601 timestamp so HA's timestamp device_class accepts
+  // it. Pass-through any value that already contains a 'T' separator.
+  if (auto raw = opt_str(data["water_filter_end_date"])) {
+    const std::string &v = *raw;
+    if (v.size() == 10 && v[4] == '-' && v[7] == '-') {
+      state.water_filter_end_date = v + "T00:00:00+00:00";
+    } else {
+      state.water_filter_end_date = v;
+    }
+  }
   return state;
 }
 

components/subzero_protocol/protocol.h

@@ -55,6 +55,11 @@ struct FridgeState {
   std::optional<bool> air_filter_on;
   std::optional<float> air_filter_pct_remaining;
   std::optional<float> water_filter_pct_remaining;
+  std::optional<float> water_filter_gal_remaining;
+  // Raw date string from the appliance (observed as "YYYY-MM-DD"). Converted
+  // 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;
 };
 
 struct DishwasherState {

tests/cpp/dispatch_test.cpp

@@ -71,6 +71,10 @@ struct FridgeRecorder : CommonRecorder {
   void publish_crisp_set_temp(float v) { floats["crisp_set_temp"] = v; }
   void publish_air_filter_pct(float v) { floats["air_filter_pct"] = v; }
   void publish_water_filter_pct(float v) { floats["water_filter_pct"] = v; }
+  void publish_water_filter_gal(float v) { floats["water_filter_gal"] = v; }
+  void publish_water_filter_end_date(const std::string &v) {
+    strings["water_filter_end_date"] = v;
+  }
 };
 
 struct DishwasherRecorder : CommonRecorder {

tests/cpp/protocol_test.cpp

@@ -109,6 +109,8 @@ json fridge_to_json(const FridgeState &s) {
   OPT_PUT(o, s, air_filter_on);
   OPT_PUT(o, s, air_filter_pct_remaining);
   OPT_PUT(o, s, water_filter_pct_remaining);
+  OPT_PUT(o, s, water_filter_gal_remaining);
+  OPT_PUT(o, s, water_filter_end_date);
   return o;
 }
 
@@ -289,6 +291,32 @@ TEST(ProtocolTest, StatusNonZeroIsInvalid) {
   EXPECT_FALSE(f.valid);
 }
 
+TEST(ProtocolTest, FridgeWaterFilterGallonsAndEndDate) {
+  auto f = parse_fridge(R"({"status":0,"resp":{
+    "water_filter_pct_remaining": 50,
+    "water_filter_gal_remaining": 162.5,
+    "water_filter_end_date": "2027-05-10"
+  }})");
+  ASSERT_TRUE(f.valid);
+  ASSERT_TRUE(f.water_filter_gal_remaining.has_value());
+  EXPECT_FLOAT_EQ(*f.water_filter_gal_remaining, 162.5f);
+  ASSERT_TRUE(f.water_filter_end_date.has_value());
+  // Date-only input is promoted to a full ISO8601 timestamp so HA's
+  // `timestamp` device_class accepts the string.
+  EXPECT_EQ(*f.water_filter_end_date, "2027-05-10T00:00:00+00:00");
+}
+
+TEST(ProtocolTest, FridgeWaterFilterEndDatePreservesFullTimestamp) {
+  // If a future firmware ever sends a full timestamp, pass it through
+  // unmodified.
+  auto f = parse_fridge(R"({"status":0,"resp":{
+    "water_filter_end_date": "2027-05-10T12:34:56Z"
+  }})");
+  ASSERT_TRUE(f.valid);
+  ASSERT_TRUE(f.water_filter_end_date.has_value());
+  EXPECT_EQ(*f.water_filter_end_date, "2027-05-10T12:34:56Z");
+}
+
 TEST(ProtocolTest, FridgeDoorFallsBackToGenericDoor) {
   auto f =
       parse_fridge(R"({"seq":1,"props":{"door_ajar":true},"msg_types":2})");

tests/fixtures/fridge_back_2028_d5_full.expected.json

@@ -8,6 +8,8 @@
   "air_filter_on": true,
   "air_filter_pct_remaining": 0,
   "water_filter_pct_remaining": 0,
+  "water_filter_gal_remaining": 107,
+  "water_filter_end_date": "2023-10-04T00:00:00+00:00",
   "common": {
     "sabbath_on": false,
     "service_required": false,