This Home Assistant add-on integrates tank monitoring systems into your Home Assistant instance. While currently supporting EcoFrog systems through the proteus-sensor.de service, the integration is designed to be extensible to other providers in the future. It automatically fetches data from all devices associated with your account and creates sensors for monitoring fill levels, volumes, temperatures, and battery status.
This add-on uses Playwright to automate browser-based authentication with the Proteus cloud service. This approach means, that you do not need to contact the provider for API access.
In the future it is also planned to directly speak with the api, if access was given by the provider.
EcoFrog devices by proteus currently refresh every 6 hours. This addon does the same. Checks for min(last_update) and sleeps until it should have been updated. If it hasen't been updated yet, the addon will check every 5 minutes until the update arrives.
- Automated Authentication: Browser-based login automation using Playwright
- Device Discovery: Automatic detection of all tanks in your account
- Dynamic Updates: Smart refresh based on tank data update times
- Comprehensive Monitoring: Multiple metrics per tank
- Debug Mode: Detailed logging for troubleshooting
- Token Management: Automatic handling of authentication tokens
- Error Handling: Robust error recovery and retry mechanisms
For each tank, the add-on creates sensors for:
- Fill Level (%)
- Current Volume (L)
- Temperature (°C)
- Battery Level (V)
- Last Update timestamp
Additional configuration data exposed:
- Tank Type
- Tank Form
- Maximum Volume
- Medium Type
- Physical Dimensions (height, floor level, offset)
- Add this repository to your Home Assistant add-on store
- Install the "EcoFrog Cloud Integration" add-on
- Configure your Proteus cloud username and password
- Clone this repository
- Use the deploy script to copy files to your Home Assistant instance:
# Using defaults ([email protected]:/addons) ./deploy.sh # Custom host/user ./deploy.sh -u admin -h 192.168.1.100 # Show all options ./deploy.sh --help
- After deployment:
- Go to Home Assistant UI
- Navigate to Settings -> Add-ons
- Click "Check for Updates" to detect the new/updated add-on
- Install and start the add-on
username: your_proteus_username
password: your_proteus_password
debug: false # Optional, set to true for detailed loggingSensors are created using the following naming pattern:
ecofrog_[provider]_[type]_[serial_number]_[metric]
For example, with provider proteus for a tank with type "TANK" and serial number "12345":
- ecofrog_proteus_tank_12345_fill_level
- ecofrog_proteus_tank_12345_current_volume
- ecofrog_proteus_tank_12345_temperature
- ecofrog_proteus_tank_12345_battery
- ecofrog_proteus_tank_12345_last_update
This naming scheme identifies both the device brand (EcoFrog) and the cloud provider (Proteus) for clarity and future extensibility.
- Enable debug mode in the add-on configuration
- Check the add-on logs for detailed information
- Verify your Proteus credentials
- Ensure your Home Assistant instance has internet access
Contributions to improve and expand this integration are welcome! The project aims to grow with:
This integration is designed to support multiple tank monitoring providers. Currently, it supports the Proteus cloud service (proteus-sensor.de), but the architecture can accommodate other providers. If you have an EcoFrog with another provider like E-SENSORIX would like to help expand support, please open an issue!
- Support for additional tank monitoring providers
- For bug reports or feature requests, open an issue on GitHub
- Pull requests are welcome for:
- Bug fixes
- New features
- Documentation improvements
- Code optimization
For issues and feature requests, please open an issue on the GitHub repository.