Skip to content

This is a Home Assistant Addon for EcoFrog tank monitoring devices.

License

Notifications You must be signed in to change notification settings

razem-io/ha-ecofrog-cloud

Repository files navigation

Home Assistant EcoFrog Cloud Integration

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.

How It Works

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.

Data Refresh Mechanism

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.

Features

  • 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

Exposed Data

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)

Installation

Production Installation

  1. Add this repository to your Home Assistant add-on store
  2. Install the "EcoFrog Cloud Integration" add-on
  3. Configure your Proteus cloud username and password

Development Installation

  1. Clone this repository
  2. 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
  3. 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

Configuration

username: your_proteus_username
password: your_proteus_password
debug: false  # Optional, set to true for detailed logging

Sensor Naming Convention

Sensors 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.

Troubleshooting

  1. Enable debug mode in the add-on configuration
  2. Check the add-on logs for detailed information
  3. Verify your Proteus credentials
  4. Ensure your Home Assistant instance has internet access

Contributing

Contributions to improve and expand this integration are welcome! The project aims to grow with:

Future Providers

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!

Future Plans

  • Support for additional tank monitoring providers

How to Contribute

  1. For bug reports or feature requests, open an issue on GitHub
  2. Pull requests are welcome for:
    • Bug fixes
    • New features
    • Documentation improvements
    • Code optimization

Support

For issues and feature requests, please open an issue on the GitHub repository.

About

This is a Home Assistant Addon for EcoFrog tank monitoring devices.

Resources

License

Stars

Watchers

Forks

Packages

No packages published