A Home Assistant integration for EcoWater's HydroLink connected water softeners. Monitor your water softener's performance, water usage, salt levels, and more directly in Home Assistant with real-time updates and comprehensive analytics.
This integration is a Home Assistant custom component adapted from the original Hydrolink-Home-Status project, enhanced with improved data organization, reliability, and Home Assistant best practices.
- 🔄 Real-time monitoring via WebSocket connections
- 📊 30+ sensors across 8 comprehensive categories
- 🔧 Service calls for manual regeneration control
- 🏠 Full Home Assistant integration with proper device modeling
- 📈 Historical data tracking and analytics
- 🚨 Alert notifications for system issues
- 🔒 Secure authentication with EcoWater cloud services
- 📱 Mobile-friendly interface
- Online Status, Model, Device Name, Serial Number
- Current Flow, Daily/Weekly/Monthly Usage, Peak Flow Statistics
- Salt Level, Days Remaining, Usage Statistics, Efficiency Tracking
- Capacity Remaining, Water Hardness, Treatment Statistics
- Current Status, History, Scheduling, Manual Control
- Low Salt Warnings, System Errors, Flow Anomalies, Leak Detection
- WiFi Strength, Connection Quality, Network Status
- Service Reminders, Operation Statistics, System Health
- Ensure you have HACS installed in your Home Assistant instance
- Search for "EcoWater HydroLink" in HACS
- Click Install
- Restart Home Assistant
- Add the integration via the Home Assistant UI:
- Go to Settings → Devices & Services
- Click the "+ ADD INTEGRATION" button
- Search for "EcoWater HydroLink"
- Enter your HydroLink credentials when prompted
- Download the latest release from the GitHub repository
- Copy the
custom_components/hydrolinkdirectory to your Home Assistant'scustom_componentsdirectory - Restart Home Assistant
- Go to Settings → Devices & Services in Home Assistant
- Click "Add Integration"
- Search for "HydroLink"
- Enter your HydroLink email and password
- Click "Submit"
📋 For complete sensor documentation, see SENSORS.md
🔍 For data verification and live sensor testing, see SENSOR_VERIFICATION.md
The integration automatically discovers all available sensors from your HydroLink API. All properties are exposed as sensors (typically 40+ sensors), and you can enable/disable individual sensors based on your needs:
- Go to Settings → Devices & Services → HydroLink → Entities
- Click on any sensor to enable/disable it
- Sensors marked with "Default Enabled" are enabled automatically
Below is a summary of the main sensors available:
| Sensor | Description | Unit |
|---|---|---|
| Current Water Flow | Current water flow rate | GPM |
| Water Used Today | Today's water consumption | Gallons |
| Average Daily Usage | Average daily water usage | Gallons |
| Total Treated Water | Total treated water volume | Gallons |
| Peak Water Flow | Peak water flow rate | GPM |
| Available Treated Water | Available treated water | Gallons |
| Sensor | Description | Unit |
|---|---|---|
| Salt Level | Current salt level | % |
| Days Until Salt Needed | Estimated days until salt refill | Days |
| Average Salt Per Regeneration | Salt used per regeneration cycle | lbs |
| Total Salt Used | Total salt consumption | lbs |
| Sensor | Description | Unit |
|---|---|---|
| Remaining Capacity | Remaining treatment capacity | % |
| Operating Capacity | System operating capacity | Grains |
| Water Hardness | Current water hardness level | Grains |
| Hardness Removed (Recent) | Hardness removed since last recharge | lbs |
| Daily Average Hardness Removed | Average daily hardness removal | lbs |
| Total Hardness Removed | Total lifetime hardness removal | lbs |
| Sensor | Description | Unit |
|---|---|---|
| Regeneration Status | Current regeneration state | - |
| Days Since Last Regeneration | Time since last regeneration | Days |
| Total Regenerations | Total regeneration cycles | Count |
| Manual Regenerations | Manual regeneration count | Count |
| Remaining Regeneration Time | Time left in current cycle | Minutes |
| Sensor | Description | Unit |
|---|---|---|
| Low Salt Alert | Salt level warning status | - |
| Error Code Alert | System error indicator | - |
| Flow Monitor Alert | Abnormal flow warning | - |
| Water Usage Alert | Excessive usage warning | - |
| Leak Detector Alert | Water leak warning | - |
| Service Reminder | Maintenance reminder | - |
| Sensor | Description | Unit |
|---|---|---|
| Online Status | Device connectivity | - |
| WiFi Signal Strength | Signal strength | dBm |
| Signal Quality | WiFi signal bars | Count |
| Days in Operation | System operation time | Days |
| Power Outage Count | Number of power failures | Count |
| Service Due | Months until service | Months |
-
Cannot Connect Error
- Check your internet connection
- Verify your HydroLink credentials
- Ensure the HydroLink service is operational
-
Authentication Failed
- Double-check your email and password
- Try logging out and back in to the HydroLink app
- Reset your HydroLink password if needed
-
No Data Updates
- Check your device's connection to HydroLink
- Verify the integration is properly configured
- Restart Home Assistant
To enable debug logging for the integration:
- Add the following to your
configuration.yaml:
logger:
default: info
logs:
custom_components.hydrolink: debug- Restart Home Assistant
- Check the logs for detailed information
Contributions are welcome! Please feel free to submit a Pull Request.
🎯 Current Release: v1.2.0 - Stable release with comprehensive documentation
✅ Test Status: 35 tests passing across Python 3.9, 3.10, 3.11
📊 Coverage: 60% test coverage with robust error handling
🔧 CI/CD: GitHub Actions fully operational with multi-version testing
📚 Documentation: Comprehensive inline documentation and comments
🏠 Home Assistant: Compatible with HA 2023.1+ through 2024.10+
This integration maintains high code quality standards:
- Black code formatting with 88-character line length
- Pylint & Ruff linting for code quality assurance
- Type hints throughout the codebase
- Comprehensive test suite with pytest and HACS validation
- Multi-version compatibility testing with tox
- Pre-commit hooks for automated quality checks
- API Client (
api.py): Secure HydroLink cloud communication with WebSocket support - Data Coordinator (
coordinator.py): Centralized data management and updates - Config Flow (
config_flow.py): User-friendly setup and configuration - Sensor Platform (
sensor.py): 30+ sensors across 8 comprehensive categories - Service Platform (
services.py): Manual regeneration control and actions
- Enhanced Documentation & Comments: Comprehensive inline documentation added
- Improved Test Coverage: Version-agnostic ConfigEntry compatibility across HA versions
- Multi-Version Testing: Proper tox configuration for Python 3.9-3.11 compatibility
- Enhanced Stability: Fixed import errors and API compatibility issues
- CI/CD Improvements: GitHub Actions passing on all supported Python versions
- Code Quality: Enhanced error handling and logging throughout codebase
- Cross-Version Compatibility: Support for Home Assistant 2023.1+ through 2024.10+
- ConfigEntry API Fixes: Version-agnostic handling of API differences
- Test Infrastructure: Comprehensive pytest suite with 35+ tests
- Package Structure: Proper Python package organization for tests
- Initial HACS-compatible release
- Complete restructure for HACS compatibility
- Updated to MIT license
- Added comprehensive testing setup
- Improved documentation and translations
- Added proper branding assets
- Configured CI/CD with GitHub Actions
- Updated minimum Home Assistant version to 2024.10.0
This project is licensed under the MIT License - see the LICENSE file for details.
- Thanks to EcoWater for providing the HydroLink platform
- Based on the original Hydrolink-Home-Status project
This project is not affiliated with, endorsed by, or connected to EcoWater Systems LLC. EcoWater, HydroLink, and any related logos are trademarks of EcoWater Systems LLC. These trademarks are used solely for the purpose of identifying compatibility with EcoWater products. All trademarks are the property of their respective owners.
- Thanks to the Home Assistant community for their support and feedback