A Home Assistant custom component to monitor washing machines via smart sockets, learn power profiles, and estimate completion time using shape-correlation matching.
Caution
ELECTRICAL SAFETY WARNING: Using smart plugs such as Shelly or Sonoff with high-amperage appliances (washing machines, dryers, dishwashers) carries significant risk.
- Fire Hazard: Cheap or low-rated smart plugs may overheat, melt, or catch fire under sustained high loads (heating/drying phases).
- Rating Check: Ensure your smart plug is rated for the maximum peak power of your appliance (often >2500W). Standard 10A plugs may fail; 16A+ or hardwired modules are recommended.
- Use at Your Own Risk: The authors of this integration are not responsible for any electrical damage or fires caused by improper hardware usage. inspect your hardware regularly.
- Multi-Device Support: Track Washing Machines, Dryers, Washer-Dryer Combos, Dishwashers, Coffee Machines, Electric Vehicles (EV), Air Fryers, Heat Pumps, Bread Makers, and Pumps/Sump Pumps — each with device-specific defaults and phases.
- Smart Cycle Detection: Automatically detects starts/stops with Predictive End logic. Includes End Spike Protection for dishwashers to capture final pump-outs.
- Power Spike Filtering: Ignores brief boot spikes to prevent false starts.
- Shape-Correlation Matching: Uses
numpy.corrcoefwith Confidence Boosting to distinguish similar cycles. - Manual Training: You define your profiles (e.g., "Cotton", "Quick") once; the system learns to recognize them thereafter. Integration does not auto-create profiles.
- Smart Time Estimation: "Phase-aware" prediction detects variance (e.g., heating) and locks the countdown to prevent erratic jumps.
- Changeable Power Sensor: Switch plugs without losing history.
- Tile Card (Minimal Status Card): Optional custom Lovelace card.
- Manual Program Override: Select the correct program manually if detection is uncertain; the system learns from your input.
- Manual Profile Creation: Create profiles even without historical cycles by specifying a baseline duration (e.g., "Eco Mode - 3h").
- Unified Phase Catalog: Manage phase vocabulary across all supported device types from one catalog view.
- Scoped Phase Assignment: Phase assignment dialogs show only phases relevant to the configured device type.
- Ghost Cycle Suppression: Intelligent filtering with "Suspicious Window" (20 mins) prevents end-spikes from triggering duplicate cycles. Now Persistent: Remembers cycle history across HA restarts to prevent ghost detections after reboots.
- Robust vNext State Machine: Advanced filtering with
start_energyandend_energygates prevents false starts/ends. - Multi-Stage Matching Pipeline: Uses Fast Reject -> Core Similarity -> DTW-Lite tie-breaking for superior accuracy.
- Local Only: No cloud dependency, no external services. All data stays in your Home Assistant.
- Notifications: Integrated alerts for cycle start, finish, and pre-completion (e.g., 5 mins before finish).
- Self-Learning: Gradually adjusts expected durations based on your confirmed historical data.
- Realistic Variance: Handles natural cycle duration variations with configurable tolerance.
- Progress Tracking: Clear cycle progress indicator with automatic reset after unload.
- Auto-Maintenance: Nightly cleanup - removes broken profiles, merges fragmented cycles (Empty/New profiles are safely preserved).
- Export/Import: Full configuration backup/restore with all settings and profiles via JSON. Import also accepts HA diagnostics download files directly.
- User-Triggered Pause/Resume: Pause and resume active cycles via button entities or HA services. Elapsed time and time-remaining estimates automatically exclude the paused duration. Optional Cut Power When Pausing toggle for appliances that maintain their position after a power cut.
- Door Sensor & Clean State: Optional binary sensor integration that sets verified pause when the door opens mid-cycle (add-clothes support), and tracks a Clean state after cycle end until the door is opened to remind you laundry is waiting.
Designed for new users to get up and running quickly.
This integration is a default repository in HACS.
-
Click the button below to open the repository in HACS:
-
Click Download.
-
Restart Home Assistant.
Alternatively, open HACS > Integrations > Explore & Download Repositories > Search for "WashData".
- Download the
custom_components/ha_washdatafolder from the latest release. - Copy it to your Home Assistant
custom_componentsdirectory. - Restart Home Assistant.
Follow these steps to get accurate results quickly.
- Go to Settings > Devices & Services > Add Integration > WashData.
- Name: Name your appliance (e.g., "Washing Machine").
- Device Type: Select the type (Washer, Dryer, etc.) - this sets smart defaults for the internal logic.
- Power Sensor: Select your smart plug's power entity (Watts). Note: The system is now optimized for polling intervals of 30-60 seconds (defaults adjusted automatically).
- Initial Profile (Optional): If you know your standard program (e.g. "Cotton"), create it now.
If you are using Zigbee2MQTT with smart plugs, ensure your device reporting is responsive enough for accurate matching:
- Reporting Intervals: Decrease the reporting intervals in Z2M (e.g., Min: 1s-10s, Max: 1200s).
- Power Threshold: Decrease the minimum updating threshold (e.g., from 5W to 1W or 2W) to ensure small power changes are captured promptly.
- Note: These changes may slightly increase Zigbee network traffic.
WashData does not come with pre-built profiles because every machine model is different. You must teach it what your cycles look like.
This gives you the cleanest data.
- Go to Settings > Devices & Services > WashData > Configure.
- Open Record Cycle (Manual), then start your machine.
- When finished, go to Manage Cycles and find the recording.
- Then open Manage Profiles and create a profile from that recording.
If you prefer to just use it and label later:
- Run a Cycle: Use your machine as normal. WashData will track it as an "Unknown" cycle.
- Label It: After the cycle finishes:
- Go to Manage Cycles (via the Configure button or the Tile Card).
- Find the recent "Unknown" cycle.
- Open Manage Profiles, click Create Profile, name it (e.g., "Cotton 40"), and Save.
- Repeat: Do this for your 2-3 most common programs.
WashData matches cycles using power-consumption shape, cycle duration, and total energy - not temperature or spin-speed settings directly. This affects how granular your profile library should be.
Programs with clearly different durations or power patterns are always distinguished well:
| Example pair | Why it works |
|---|---|
| Quick Wash (~20 min) vs Cotton (~3 h) | Huge duration gap - no ambiguity |
| Wash-only vs Wash+Dry | Drying adds 100–200 min and significant extra energy |
| Cotton vs Delicates | Different agitation/heating patterns and often different durations |
Programs that differ only in temperature or spin speed (e.g. Cotton 40°C vs Cotton 60°C) often produce similar power shapes and durations. The matcher will attempt to distinguish them using correlation and energy differences, but:
- On first run the system may assign the wrong variant - use the Learning Feedbacks menu to correct it.
- With a few confirmed corrections the system learns; 3–5 corrections per variant pair is usually enough.
- If your machine's power draw barely changes between temperatures, the variants may remain hard to distinguish automatically. In that case, selecting the program manually via the Program Selector dropdown remains reliable.
Create separate profiles for every wash+dry combination you use regularly (e.g. "Cotton 40°C Wash", "Cotton 40°C + Cupboard Dry"). The drying phase adds so much duration and energy that wash-only vs wash+dry is one of the easiest distinctions for the matcher to make.
Start with a small set of your most-used and most-different programs, then add temperature/spin variants gradually as you accumulate history.
Once profiles are created, WashData starts matching new cycles automatically.
- Feedback: If a match is found but confidence is moderate, you may get a "Verify Cycle" notification.
- Refinement: Go to Configure > Learning Feedbacks to Confirm or Correct the detection.
- Self-Improving: Confirming a cycle helps the system refine its duration models.
If "Auto-Detect" isn't working perfectly, use Advanced Settings to tune the logic for your specific machine.
📊 Click here for a Visual Guide to these settings - Graphs explaining what the numbers actually do.
| Problem | Likely Cause | Solution |
|---|---|---|
| Cycle Starts Too Early | Smart plug reports brief power spikes during boot/standby. | Increase Start Energy Threshold (e.g., to 2 Wh). This forces the machine to consume actual energy before stating "Running". |
| Cycle Ends Too Early | Machine pauses (soaking) or has long low-power intervals. | Increase Off Delay. Give it more time (e.g. 5 mins) to wait before deciding the cycle is truly finished. |
| False "Ghost" Cycles | High-power usage at the very end (e.g. anti-crease or pump-out) triggers a new start. | Increase Minimum Off Gap (e.g. to 120s). Forces a mandatory cooldown period between cycles. |
| "Unknown" Matches | Your profiles are too strict or variance is high. | Increase Duration Tolerance (e.g. 0.25). Allows ±25% duration difference when matching. |
| Notifications Too Late | You want to know before it finishes. | Set Notify Before End Minutes (e.g. 5). Get an alert 5 minutes before the estimated finish time. |
| Persistent 'Running' State | Integration stays locked to a long profile after a short cycle diverged. | Adjust Matching Stability Thresholds in const.py. Divergence detection now automatically reverts to "Detecting..." if confidence drops below 60% of the peak score. |
Pro Tip: Use the Apply Suggestions button in Settings. It analyzes your history and calculates the perfect text-book values for your specific machine.
WashData exposes a diagnostic sensor: sensor.<name>_suggested_settings.
0means there are currently no actionable recommendations.> 0means recommendations are ready to review.
When this sensor is above 0:
- Go to Settings > Devices & Services > WashData > Configure > Advanced Settings.
- Enable Apply Suggested Values.
- Review the change summary step.
- Confirm to stage values, then save only the changes you agree with.
Suggested values are optional and are never forced automatically.
Phases are descriptive labels for distinct power stages within a cycle (e.g., "Pre-Wash", "Heating", "Spin").
- Manage Phase Catalog: Go to Configure > Manage Phase Catalog to add, edit, or remove phase labels for each device type.
- Assign Phases to a Profile: In Manage Profiles, select Assign Phase Ranges and use the phase range editor to map time regions to phase labels.
- Phases are scoped to your device type - only relevant phases appear in the assignment dialog.
- 📗 IMPLEMENTATION.md - Deep dive into NumPy matching, State Machine logic, and Learning algorithms.
- 🧪 TESTING.md - How to test with the virtual socket.
📸 Screenshots (Click to expand)
All your WashData-monitored appliances appear as devices with sensors and controls.
The central hub for managing your appliance - access all features from here.
Configure power sensor, device type, off delay, and notification preferences.
Fine-tune detection thresholds, matching parameters, and timeout values for your specific appliance.
View, create, edit, or delete learned power profiles for different wash programs.
Browse cycle history, label unknown cycles, merge fragments, or delete bad data.
Confirm or correct the system's profile matches to improve learning accuracy.
Run database cleanup, repair corrupted data, and export/import configurations.
sensor.<name>_state: Current status (Idle / Running / Detecting... / Clean).sensor.<name>_program: Best-matched profile name.sensor.<name>_time_remaining: Smart countdown (locks during high-variance phases).sensor.<name>_total_duration: Total predicted duration (Elapsed + Remaining). Ideal fortimer-bar-card.sensor.<name>_cycle_progress: 0–100% (resets after unload timeout).sensor.<name>_cycle_count: Total completed cycles stored — use in automations to schedule maintenance by cycle count.sensor.<name>_current_phase: Active cycle phase label (e.g. "Rinsing", "Spin").sensor.<name>_pump_runs_today: (Pump device type only) Completed pump cycles in a rolling 24-hour window.binary_sensor.<name>_running: Simple on/off running state.button.<name>_pause_cycle: Pause the active cycle (available while Running/Starting/Ending and not already paused).button.<name>_resume_cycle: Resume a user-paused cycle.button.<name>_force_end_cycle: Force-terminate a stuck cycle.switch.<name>_auto_maintenance: Toggle nightly database cleanup.
Most management is done via the Interactive UI (Configure > Manage Data), but services are available for automation:
ha_washdata.export_config: Full JSON backup of all settings, profiles, and cycle history.ha_washdata.import_config: Restore from a JSON backup. Accepts regular WashData exports and HA diagnostics download files.ha_washdata.pause_cycle: Pause the active cycle programmatically (e.g. from an energy-tariff automation).ha_washdata.resume_cycle: Resume a user-paused cycle.
ha_washdata.record_start / record_stop:
Manually start/stop a recording. Useful for automations (e.g. triggering from a physical button or separate sensor).
service: ha_washdata.record_start
data:
device_id: "washer_device_id"ha_washdata.label_cycle: Assign a profile to a cycle in history programmatically.
The more real-world cycle data WashData has, the smarter its detection becomes - across different appliance brands, ages, and programs.
If you'd like to help, you can submit a diagnostics export directly from Home Assistant. It takes less than 2 minutes and requires no technical knowledge.
How to export:
- Open Home Assistant and go to** Settings → Devices & Services**
- Find your WashData integration and click on it
- Open device you want to submit data for
- Navigate left, to "Device info" section
- Select "Download diagnostics"
- A .json file will be downloaded to your device
🔒 Privacy: The export contains your appliance's power data and integration settings. It does not include your name, home details, location, or any other personal information.
💡 Tip: The same diagnostics file you download here can be pasted directly into Configure → Diagnostics & Maintenance → Export/Import JSON to restore profiles and settings on a different HA instance — no manual format conversion needed.
All contributions are used solely to improve the WashData integration.
🇬🇧 English • 🇨🇿 Čeština • 🇩🇰 Dansk • 🇩🇪 Deutsch • 🇬🇷 Ελληνικά • 🇪🇸 Español • 🇪🇪 Eesti • 🇫🇮 Suomi • 🇫🇷 Français • 🇭🇷 Hrvatski • 🇭🇺 Magyar • 🇮🇹 Italiano • 🇯🇵 日本語 • 🇱🇹 Lietuvių • 🇱🇻 Latviešu • 🇳🇴 Norsk • 🇳🇱 Nederlands • 🇧🇪 Nederlands (BE) • 🇵🇱 Polski • 🇵🇹 Português • 🇷🇴 Română • 🇸🇰 Slovenčina • 🇸🇮 Slovenščina • 🇷🇸 Srpski • 🇸🇪 Svenska • 🇺🇦 Українська • 🇨🇳 简体中文
Non-commercial use only. See LICENSE file.
