# Fridge Filter Reminder — send a push notification when the LG fridge's
# own water filter sensor reports the filter needs replacing.
#
# The fridge already exposes its filter condition via the LG ThinQ
# integration as a ``sensor`` (states like "good" / "replace"); it just
# doesn't notify anyone. The recipe resolves a single required role,
# ``water_filter_status``, and fires a notification when that sensor leaves
# a healthy state.
#
# An optional second role, ``water_filter_used``, is the months-in-use
# sensor some models expose. When selected, the recipe adds a proactive
# reminder once usage passes ``remind_after_months``. min_count 0 — leave
# it empty and the recipe relies on the status sensor alone.
slug: fridge-filter-reminder
version: 1.0.0
title: "LG Fridge: Filter Reminder"
tagline: Get a push notification the moment your LG fridge's own water filter sensor says the filter needs replacing.
description: >-
  The fridge already reports its water filter status; this recipe turns
  that into a Home Assistant push notification so you are told the moment it
  stops reading good, instead of having to notice it in the app or on a
  dashboard. Optionally add the months-in-use sensor for an earlier
  heads-up. Built around the LG ThinQ integration.
author: Selora AI
released: "2026-07-08"
min_integration_version: "0.12.0"
tags: [kitchen, fridge, lg-thinq, maintenance]
roles:
  # Water filter status sensor — the LG ThinQ "Water filter" entity that
  # reports good / needs-replacing. Single-select (min 1, max 1): a fridge
  # has one water filter status. This is the recipe's primary trigger.
  # ``match`` narrows past integration+kind (LG exposes several sensors) to
  # the water-filter status specifically: the entity_id ends ``water_filter``
  # (name "Water filter"), while the months-in-use and remain-percent
  # siblings end differently, so they're excluded.
  - id: water_filter_status
    title: Water filter status sensor
    kind: sensor
    integration: lg_thinq
    match: "water[ _]filter$"
    min_count: 1
    max_count: 1
    selection: required
    description: >-
      The fridge's water filter status sensor. On an LG fridge this is the
      "Water filter" entity that reports good while the filter is healthy
      and a replace state when it is due.
  # Months-in-use sensor — optional. The LG ThinQ "Water filter used" entity
  # counts months since the last change. When selected, adds a proactive
  # reminder at ``remind_after_months``. min_count 0: not every model
  # exposes it, and the status sensor alone is enough.
  - id: water_filter_used
    title: Water filter months-in-use sensor
    kind: sensor
    integration: lg_thinq
    match: "water[ _]filter[ _]used$"
    min_count: 0
    max_count: 1
    selection: required
    description: >-
      Optional. The sensor that counts months since the water filter was
      last replaced (LG's "Water filter used"). Select it to get an early
      reminder before the filter is fully spent. Leave empty to rely on the
      status sensor alone.
inputs:
  # Age, in months, at which the proactive reminder fires. Only used when
  # ``water_filter_used`` is selected. 6 months is a common LG replacement
  # interval; feeds straight into the numeric_state trigger's ``above``.
  - id: remind_after_months
    type: number
    label: Remind after (months)
    description: >-
      How many months of use before the early reminder fires. Only applies
      when a months-in-use sensor is selected. Six months is a common
      replacement interval.
    default: 6
package_files:
  - package/automations/filter_check.yaml.j2

{# Fridge Filter Reminder — notify when the water filter needs replacing.

   Primary automation: watch the LG "Water filter" status sensor. It reports
   a healthy string ("good") while the filter is fine and a different string
   when it is due. We trigger on any state change and let a template
   condition decide, so the recipe doesn't have to hard-code every LG replace
   state — anything outside the healthy set (and not unknown/unavailable)
   counts as "replace".

   The condition requires a genuine transition that LEAVES a healthy state:
   the previous state must have been healthy and the new one must not be. A
   bare state trigger also fires on attribute-only updates and on
   unavailable/unknown -> replace reconnects; checking from_state stops those
   from re-alerting while the filter is already flagged.

   Optional second automation: only rendered when the homeowner also selected
   the months-in-use sensor. Fires proactively once usage passes the
   configured month threshold, before the fridge itself flags the filter.

   Every template stays on a single quoted line so the renderer's trim_blocks
   can't swallow following YAML at an end-of-line tag. #}
automation:
  - id: selora_recipe_{{ slug | replace('-', '_') }}_filter_status
    alias: "LG Fridge Filter Reminder — filter needs replacing"
    description: >-
      When the fridge's water filter status leaves a healthy state, send a
      push notification that it is time to replace the filter.
    mode: single
    trigger:
      - platform: state
        entity_id: {{ roles.water_filter_status[0] }}
    condition:
      # Fire only when the filter LEAVES a healthy state: the previous state
      # must have been healthy and the new one must be a replace state (not
      # healthy, and not a momentary unknown/unavailable a reload produces).
      # Requiring a healthy from_state stops attribute-only updates and
      # unavailable -> replace reconnects from re-alerting while it's flagged.
      - condition: template
        value_template: "{% raw %}{{ trigger.from_state is not none and (trigger.from_state.state | lower) in ['good', 'normal', 'ok', 'clean'] and (trigger.to_state.state | lower) not in ['good', 'normal', 'ok', 'clean', 'unknown', 'unavailable', 'none'] }}{% endraw %}"
    action:
      - service: notify.notify
        data:
          title: "Fridge water filter"
          message: "{% raw %}The fridge water filter now reports '{{ trigger.to_state.state }}'. Time to replace it.{% endraw %}"
{% if roles.water_filter_used %}
  - id: selora_recipe_{{ slug | replace('-', '_') }}_filter_months
    alias: "LG Fridge Filter Reminder — filter aging"
    description: >-
      When the water filter has been in use longer than the configured
      number of months, send an early reminder to order a replacement.
    mode: single
    trigger:
      - platform: numeric_state
        entity_id: {{ roles.water_filter_used[0] }}
        above: {{ inputs.remind_after_months }}
    action:
      - service: notify.notify
        data:
          title: "Fridge water filter"
          message: "{% raw %}The fridge water filter has been in use for over {% endraw %}{{ inputs.remind_after_months }}{% raw %} months. Order a replacement soon.{% endraw %}"
{% endif %}