Update Dishwasher

Author: webosa

docs/smart-home/packages/dishwasher.md

@@ -2,82 +2,42 @@
 tags:
   - package
   - automated
+version: 1.0.0
 ---
 
 # Package: Dishwasher
 
-## Executive Summary
-This package manages the integration and automation logic for the LG Dishwasher (via SmartThinQ). It normalizes raw sensor data into friendly states ("Active", "Clean"), calculates a human-readable "Time Remaining" value, and tracks maintenance requirements.
+**Version:** 1.0.0  
+**Description:** Logic, sensors, flags, and automations for the LG Dishwasher. Handles normalization of LG ThinQ data and maintenance reminders.
 
-**Key Features:**
-- **State Normalization**: Converts various machine states (e.g., `running`, `rinsing`, `drying`) into a simple binary `active` sensor.
-- **Maintenance Tracking**: Uses an `input_boolean` to flag when a "Machine Clean" cycle is required, auto-resetting when the cycle is performed.
-- **Smart Notifications**:
-    - **Start**: Notifies when a cycle begins, including the estimated finish time.
-    - **End**: Notifies when finished with total run time. Triggers immediately on cycle end or if the door is opened while in 'end' state.
-
-## Architecture
-
-```mermaid
-sequenceDiagram
-    participant LG as LG ThinQ Integration
-    participant Pkg as Package Logic
-    participant HA as Home Assistant
-    participant User as User/Dashboard
-
-    Note over LG, Pkg: State Normalization
-    LG->>Pkg: Update sensor.dishwasher_current_status
-    Pkg->>HA: Update binary_sensor.dishwasher_active (On/Off)
-    Pkg->>HA: Update sensor.dishwasher_status_clean (Friendly Name)
-
-    Note over LG, Pkg: Time Calculation
-    LG->>Pkg: Update sensor.dishwasher_remaining_time
-    Pkg->>HA: Update sensor.dishwasher_remaining_time_human (HH:MM)
-
-    Note over Pkg, HA: Automation Flow
-    rect rgb(20, 50, 20)
-        LG->>Pkg: Status: Running
-        Pkg->>HA: Notify "Dishwasher Started" (Wait for time calc)
-    end
-    
-    rect rgb(20, 20, 50)
-        LG->>Pkg: Status: End
-        Pkg->>HA: Notify "Dishes are Clean" (with Run Time)
-    end
-
-    rect rgb(50, 20, 20)
-        LG->>Pkg: Machine Clean Reminder
-        Pkg->>HA: Turn On input_boolean.dishwasher_needs_cleaning
-        Pkg->>HA: Notify "Maintenance Needed"
-        User->>LG: Run "Machine Clean" Cycle
-        LG->>Pkg: Cycle: machine_clean
-        Pkg->>HA: Turn Off input_boolean.dishwasher_needs_cleaning
-    end
-```
-
-## Backend Configuration
-
-The specific logic and sensors are defined in `packages/dishwasher.yaml`.
+![Package Diagram](../../../assets/images/packages/dishwasher.png)
 
+## Configuration
 ```yaml
+# ------------------------------------------------------------------------------
 # Package: Dishwasher
-# Description: Logic, Sensors, Flags, and Automations for the LG Dishwasher
-#
+# Version: 1.0.0
+# Description: Logic, sensors, flags, and automations for the LG Dishwasher. Handles normalization of LG ThinQ data and maintenance reminders.
 # Dependencies:
 #   - Integration: LG ThinQ (SmartThinQ LGE Sensors)
-#   - Script: script.notify_smart_master (Notification System Package)
-
+#   - Script: script.notify_smart_master
 # ------------------------------------------------------------------------------
+
+# ==============================================================================
 # 1. HELPERS
-# ------------------------------------------------------------------------------
+# ==============================================================================
 input_boolean:
+  # Flag: Tracks if the 'Machine Clean' cycle is due.
+  # Logic:
+  #   - Turned ON by automation when 'binary_sensor.dishwasher_machine_clean_reminder' goes high.
+  #   - Turned OFF by automation when a 'machine_clean' cycle is actually started.
   dishwasher_needs_cleaning:
     name: "Dishwasher Needs Cleaning"
     icon: mdi:spray-bottle
 
-# ------------------------------------------------------------------------------
+# ==============================================================================
 # 2. TEMPLATE SENSORS (Normalize the LG Data)
-# ------------------------------------------------------------------------------
+# ==============================================================================
 template:
   - binary_sensor:
       - name: "Dishwasher Active"
@@ -122,35 +82,39 @@ template:
             {% endif %}
           {% endif %}
 
-# ------------------------------------------------------------------------------
+# ==============================================================================
 # 3. AUTOMATIONS
-# ------------------------------------------------------------------------------
+# ==============================================================================
 automation:
   # --- DISHWASHER STARTED ---
+  # Notify when the dishwasher starts, with a wait for the time remaining sensor.
   - alias: "Notify: Dishwasher Started"
     id: notify_dishwasher_started_pkg
-    triggers:
+    description: Notify when dishwasher starts a cycle, waiting for time remaining to be available.
+    trigger:
       - entity_id: sensor.dishwasher_current_status
         from: initial
         to: running
-        trigger: state
+        platform: state
       - entity_id: sensor.dishwasher_current_status
         from: power_off
         to: running
-        trigger: state
-    actions:
+        platform: state
+    action:
+      # Wait up to 2 minutes for a valid time from the sensor.
       - wait_for_trigger:
-          - trigger: template
+          - platform: template
             value_template: >
               {{ states('sensor.dishwasher_remaining_time_human') not in ['unknown', 'unavailable', '--:--'] }}
         timeout:
           minutes: 2
         continue_on_timeout: true
 
-      - action: script.notify_smart_master
+      - service: script.notify_smart_master
         data:
           category: info
           title: 💦 Dishwasher Started
+          # Use a conditional message in case the wait timed out.
           message: >
             {% set remaining = states('sensor.dishwasher_remaining_time_human') %}
             {% if remaining not in ['unknown', 'unavailable', '--:--'] %}
@@ -164,19 +128,21 @@ automation:
     mode: single
 
   # --- DISHWASHER DONE ---
+  # Notify when dishwasher finishes. Triggers if door opens while status is 'end'.
   - alias: "Notify: Dishwasher Done"
     id: notify_dishwasher_done_pkg
-    triggers:
+    description: Notify when dishwasher finishes, including run time.
+    trigger:
       - entity_id: sensor.dishwasher_current_status
         to: end
         id: cycle_end
-        trigger: state
+        platform: state
       - entity_id: binary_sensor.dishwasher_door
         from: "off"
         to: "on"
         id: door_open
-        trigger: state
-    conditions:
+        platform: state
+    condition:
       - condition: or
         conditions:
           - condition: trigger
@@ -188,7 +154,8 @@ automation:
               - condition: state
                 entity_id: sensor.dishwasher_current_status
                 state: end
-    actions:
+    action:
+      # Calculate run time, handling unknown values safely.
       - variables:
           run_time_raw: "{{ states('sensor.dishwasher_total_time') }}"
           run_time: |-
@@ -197,7 +164,7 @@ automation:
             {% else %}
               Unknown time
             {% endif %}
-      - action: script.notify_smart_master
+      - service: script.notify_smart_master
         data:
           category: info
           title: ✨ Dishes are Clean
@@ -211,69 +178,47 @@ automation:
     mode: single
 
   # --- DISHWASHER MAINTENANCE ---
+  # Alerts when machine clean is needed and resets the flag when a clean cycle is started.
   - alias: "Notify: Dishwasher Maintenance"
     id: notify_dishwasher_maintenance_pkg
-    triggers:
+    description: Alerts when machine clean is needed and resets when done.
+    trigger:
       - entity_id: binary_sensor.dishwasher_machine_clean_reminder
         to: "on"
         id: needs_clean
-        trigger: state
+        platform: state
       - entity_id: sensor.dishwasher_current_cycle
         to: machine_clean
         id: clean_cycle_started
-        trigger: state
-    actions:
+        platform: state
+    action:
       - choose:
+          # Case 1: Reminder turns ON and we haven't acknowledged it yet.
           - conditions:
               - condition: trigger
                 id: needs_clean
               - condition: state
                 entity_id: input_boolean.dishwasher_needs_cleaning
                 state: "off"
             sequence:
-              - action: input_boolean.turn_on
+              - service: input_boolean.turn_on
                 target:
                   entity_id: input_boolean.dishwasher_needs_cleaning
-              - action: script.notify_smart_master
+              - service: script.notify_smart_master
                 data:
                   category: info
                   title: 🧼 Dishwasher Maintenance
                   message: The dishwasher needs a Machine Clean cycle.
                   tag: dishwasher_maintenance
                   sticky: true
+          # Case 2: A 'machine_clean' cycle is started, so we reset the flag.
           - conditions:
               - condition: trigger
                 id: clean_cycle_started
             sequence:
-              - action: input_boolean.turn_off
+              - service: input_boolean.turn_off
                 target:
                   entity_id: input_boolean.dishwasher_needs_cleaning
     mode: single
-```
-
-## Frontend Connection
-
-**Key Entities**:
-- `sensor.dishwasher_state`
-- `binary_sensor.kitchen_dishwasher_leak_sensor_water_leak` (Integration provided)
-
-**Dashboard Usage**:
-The dishwasher is monitored in the Development dashboard (`dashboard_dev2`), primarily tracked within area cards (likely Kitchen).
-
-**Card Configuration (Snippet)**:
-This snippet shows how the leak sensor and state are integrated into grid/area cards.
 
-```json
-// From lovelace.dashboard_dev2
-{
-  "device_3": "sensor.dishwasher_state",
-  "device_3_icon": "mdi:dishwasher",
-  "device_3_state": "Running",
-  "device_3_color": "blue",
-  "device_4": "binary_sensor.kitchen_dishwasher_leak_sensor_water_leak",
-  "device_4_icon": "mdi:dishwasher-alert",
-  "device_4_state": "on",
-  "device_4_color": "red",
-  "device_4_animation": "blink"
-}
 ```