{"id":28316594,"url":"https://github.com/rolandort/water-tank","last_synced_at":"2025-10-23T22:25:24.070Z","repository":{"id":261941917,"uuid":"885783054","full_name":"rolandort/water-tank","owner":"rolandort","description":"Water tank monitoring with ESP32-C6 and an ultrasonic distance sensor.","archived":false,"fork":false,"pushed_at":"2025-03-28T11:17:34.000Z","size":489,"stargazers_count":6,"open_issues_count":9,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-01T11:58:55.330Z","etag":null,"topics":["esp32","esphome","ultrasonic-sensor"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rolandort.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-09T11:41:04.000Z","updated_at":"2025-04-16T18:42:34.000Z","dependencies_parsed_at":"2024-11-09T12:32:18.338Z","dependency_job_id":"dc2b7fa0-9c1a-428e-9cdd-20d4dcc9371f","html_url":"https://github.com/rolandort/water-tank","commit_stats":null,"previous_names":["dumboxp/water-tank","rolandort/water-tank"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rolandort/water-tank","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolandort%2Fwater-tank","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolandort%2Fwater-tank/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolandort%2Fwater-tank/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolandort%2Fwater-tank/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rolandort","download_url":"https://codeload.github.com/rolandort/water-tank/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolandort%2Fwater-tank/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261620085,"owners_count":23185456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","esphome","ultrasonic-sensor"],"created_at":"2025-05-25T02:12:00.316Z","updated_at":"2025-10-23T22:25:24.060Z","avatar_url":"https://github.com/rolandort.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Water Tank Level Sensor\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![ESPHome](https://img.shields.io/badge/Made%20for-ESPHome-000000.svg?style=flat\u0026logo=esphome)](https://esphome.io/)\n[![Version](https://img.shields.io/badge/Version-2025.08.06.001-blue.svg)](https://github.com/username/water-tank)\n\nA smart water level monitoring system for underground rainwater tanks using ESPHome on an ESP32-C6 microcontroller. This project measures water level using an ultrasonic distance sensor, temperature, and humidity, and sends the data to a cloud dashboard.\n\n## Table of Contents\n- [Quick Start](#quick-start)\n- [Overview](#overview)\n- [Requirements](#requirements)\n  - [Hardware](#hardware)\n  - [Software](#software)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Wiring](#wiring)\n- [Project Structure](#project-structure)\n- [Dashboard](#dashboard)\n- [Troubleshooting](#troubleshooting)\n- [Power Considerations](#power-considerations)\n- [Contributing](#contributing)\n- [Resources](#resources)\n- [Contact](#contact)\n- [License](#license)\n\n## Quick Start\n```bash\n# Clone the repository\ngit clone https://github.com/username/water-tank.git\ncd water-tank\n\n# Configure your settings\ncp common/secrets-template.yaml common/secrets.yaml\n# Edit secrets.yaml with your WiFi credentials\n\n# Install dependencies\npip install esphome\n\n# Validate and flash\nesphome config water-tank.yaml\nesphome run water-tank.yaml\nesphome logs water-tank.yaml\n\nor \n\nesphome compile water-tank.yaml \nesphome upload water-tank.yaml \n```\n\n## Overview\n\nThis system monitors:\n- Water level and volume in an underground rainwater tank (e.g. Graf Regenwassertank/Zisterne)\n- Temperature and humidity\n- Battery voltage\n- WiFi signal strength\n\n\u003e **Note:** For detailed documentation with additional images and technical specifications, see the [detailed documentation](docs/README.md).\n\n![Water Tank](/docs/images/water-tank.png \"Water-Tank\")  \n*ESP32-C6 board with sensors and DataCake dashboard visualization*\n\n## Requirements\n\n### Hardware \n\n- ESP32 programmable chip: [Seeed XIAO ESP32-C6 8MB](https://www.seeedstudio.com/Seeed-Studio-XIAO-ESP32C6-p-5884.html) (~$6)\n- Ultrasonic distance sensor: JSN-RS04t or [AJ-SR04M](https://www.amazon.com/dp/B07S1KPYVT) (~$10) (Note: AJ-SR04M only works with JSN-SR04T mode)\n- Temperature \u0026 humidity sensor: [AM2302/DHT22](https://www.adafruit.com/product/393) (~$10)\n- Battery: 3.7V LiPo battery with JST connector (optional for portable use)\n- Breadboard and jumper wires for prototyping\n\n### Software \n\n- Python 3.7 or higher\n- [PlatformIO](https://platformio.org/) - Development environment\n- [Espressif ESP-IDF](https://www.espressif.com/en/products/socs/esp32) - ESP32 framework\n- [ESPHome](https://esphome.io/) - Firmware creation tool\n\n## Installation\n\n1. Clone this repository\n2. Copy `/common/secrets-template.yaml` to `/common/secrets.yaml` and configure your WiFi credentials\n3. Install ESPHome and dependencies:\n   ```bash\n   pip install esphome\n   ```\n4. Validate the configuration:\n   ```bash  \n   esphome config water-tank.yaml\n   ```\n5. Connect your ESP32-C6 to your computer via USB\n6. Flash the firmware:\n   ```bash\n   esphome run water-tank.yaml\n   ```\n7. Compile and upload the firmware:\n   ```bash\n   esphome compile water-tank.yaml\n   esphome upload water-tank.yaml\n   ```\n8. View logs:\n   ```bash\n   esphome logs water-tank.yaml\n   ```\n## Webinterface\n\nAccess the web interface at:\n```\nhttp://\u003cdevice_ip\u003e:80\n```\n\n## Usage\n\nOnce installed, the device will:\n1. Wake up at configured intervals to take measurements\n2. Send data to your configured dashboard (DataCake)\n3. Go back to deep sleep to conserve battery power\n\nYou can adjust the measurement frequency and other parameters in the `water-tank.yaml` configuration file:\n\n```yaml\n# Example configuration changes\ndeep_sleep:\n  run_duration: 30s\n  sleep_duration: 60min  # Change to adjust measurement frequency\n```\n\n## Wiring\n\n![Breadboard of Water Tank Level](/docs/images/breadboard-water-tank-level.png \"Breadboard\")  \n*Breadboard wiring of the water tank level sensor setup*\n\n### Pin Configuration\n\nThe following pins are used in this project:\n```yaml\n  pin_battery_voltage: GPIO0  # GPIO0 D0\n  pin_wakeup:          GPIO1  # GPIO1 left/bottom (only pins 0, 1, 2, 3, 4, 5, 6, 7 may support wakeup)\n  pin_dht:             GPIO2  # GPIO2 D2\n  pin_ultrasonic_tx:   GPIO18 # GPIO18 Tx/Echo\n  pin_ultrasonic_rx:   GPIO20 # GPIO20 Rx/Trig\n```\n\n## Enclosure\n\n![Enclosure of Water Tank Level](/docs/images/esp32-in-enclosure.png \"Enclosure\")  \n*Enclosure of the water tank level sensor setup*\n\nFor additional enclosure and mounting details, see the [detailed documentation](docs/README.md#enclosure-and-installation).\n\n## Project Structure\n\n```\nwater-tank/\n├── common/\n│   ├── secrets-template.yaml  # Template for WiFi and API credentials\n│   ├── secrets.yaml           # Your actual credentials (gitignored)\n│   ├── esp32c6.yaml           # ESP32-C6 specific configuration\n│   └── base.yaml              # Base ESPHome configuration\n├── docs/\n│   ├── images/               # Project images and diagrams\n│   └── README.md             # Detailed documentation with all images\n├── water-tank.yaml            # Main ESPHome configuration\n├── README.md                  # This documentation\n└── LICENSE                    # MIT License\n```\n\n## Dashboard\n\nThe dashboard was realized using [DataCake](https://datacake.co/) which displays the current and past water level, battery level and the temperature and humidity.\n\n![Dashboard](/docs/images/datacake-dashboard.png)  \n*DataCake Dashboard showing water level, temperature, and battery status*\n\n### Setting Up Your Own Dashboard\n\n1. Create a free account on [DataCake](https://datacake.co/)\n2. Create a new device type \"Water Tank Monitor\"\n3. Add the following fields:\n   - Water Level (%)\n   - Water Volume (L)\n   - Temperature (°C)\n   - Humidity (%)\n   - Battery Voltage (V)\n   - Battery Level (%)\n   - WiFi Signal (dBm)\n4. Update your configuration with the DataCake API endpoint (a sample endpoint is already included in the configuration)\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n| Problem | Possible Cause | Solution |\n|---------|---------------|----------|\n| **Inaccurate readings** | Sensor obstruction or misalignment | Ensure the ultrasonic sensor is properly positioned and not obstructed |\n| **Battery drains quickly** | Insufficient deep sleep | Check the deep sleep configuration in your YAML file, increase `sleep_duration` |\n| **Connection issues** | Poor WiFi signal | Verify WiFi credentials and signal strength at the installation location |\n| **No data on dashboard** | API configuration issue | Check your DataCake API key and endpoint in `secrets.yaml` |\n| **Sensor not detected** | Wiring issue | Double-check pin connections according to the wiring diagram |\n| **ESPHome build fails** | Missing dependencies | Run `pip install -r requirements.txt` to install all dependencies |\n\n### Debug Mode\n\nTo enable debug logging:\n\n```yaml\n# In water-tank.yaml\nlogger:\n  level: DEBUG\n```\n\n## Power Considerations\n\n- **Battery Life**: With default settings (60-minute intervals), expect approximately 3-4 months of battery life using a 2000mAh LiPo battery.\n- **Solar Option**: For extended operation, consider adding a small solar panel (5V/1W) with a charging circuit.\n- **Power Consumption**:\n  - Active mode: ~80mA\n  - Deep sleep: ~0.1mA\n  - Measurement cycle: ~5 seconds\n- **Battery Voltage Range**:\n  - Full charge: 4.2V\n  - Minimum operating voltage: 3.3V\n\n## Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add some amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\nPlease make sure to update tests and documentation as appropriate.\n\n## Resources\n\n- [Getting Started with Seeed Studio XIAO ESP32C6](https://wiki.seeedstudio.com/xiao_esp32c6_getting_started/)\n- [ESPHome Documentation](https://esphome.io/)\n- [DataCake Documentation](https://docs.datacake.de/)\n- [Ultrasonic Sensor Guide](https://randomnerdtutorials.com/complete-guide-for-ultrasonic-sensor-hc-sr04/)\n- [Battery Optimization Techniques](https://randomnerdtutorials.com/power-saving-esp32-arduino-deep-sleep-mode/)\n\n## Contact\n\n- Author: Roland Ortner\n- Date: 2025-07-25\n- LinkedIn: [https://www.linkedin.com/in/roland-ortner/](https://www.linkedin.com/in/roland-ortner/)\n- Reports: battery voltage, WiFi signal, level and volume in water tank\n- Icons: [https://pictogrammers.com/library/mdi/](https://pictogrammers.com/library/mdi/)\n\n## License\n\nThis project is open source and available under the [MIT License](LICENSE).\n\n\u003cimg src=\"docs/images/made-for-esphome-white-on-black.png\" title=\"Made for ESPHome\" alt=\"Made for ESPHome Logo\" width=150\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frolandort%2Fwater-tank","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frolandort%2Fwater-tank","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frolandort%2Fwater-tank/lists"}