⚠️ WARNING: This project involves 230V AC mains voltage!
- Only proceed if you have basic electronics knowledge.
- Always use a Residual Current Device (RCD/FI circuit breaker) for the pump circuit.
- Disconnect power before working on the circuit.
- Keep low-voltage (sensor) wiring separate from mains wiring.
- If in doubt, consult a qualified electrician.
- This project is NOT certified (no CE/UL mark). For personal use only!
Manage your swimming pool the smart way - enjoy it in a comfortable and affordable (less than 100€) way with professional-grade reliability.
🔗 Discussions: GitHub Discussions
New to the project? Start here:
- 📖 Quick Start Guide – Step-by-step setup for beginners (recommended!)
- ❓ Frequently Asked Questions (FAQ) – Troubleshooting common issues
- ✅ Timed circulation for cleaning
- ✅ Solar heating control via additional pump
- ✅ Multiple operation modes: Auto, Manual, Boost, Timer
- ✅ Temperature-based automation (e.g., disable solar heating if pool is too hot)
- ✅ Home Assistant MQTT Discovery – Native HA integration (v3.3.0+)
- ✅ Independent of specific smart home servers
- ✅ Home Assistant via MQTT Discovery
- ✅ openHAB via MQTT (manual configuration required)
- ✅ State Persistence – All settings survive reboots and power failures
- Operation mode, temperatures, timer settings automatically restored
- ESP32 NVS storage
- ✅ System Health Monitoring – Continuous health checks
- Memory monitoring every 10 seconds
- Auto-reboot at critical memory threshold (8KB)
- Hardware watchdog timer (30s timeout)
- ✅ Memory Optimization – Efficient resource usage
- 90% reduction in heap fragmentation
- 2,880-28,800 fewer allocations per day
- Fixed millis() overflow for operation beyond 49.7 days
- ✅ Automatic Recovery – Self-healing capabilities
- Auto-recovery from memory exhaustion
- Watchdog timer prevents system hangs
- Sensor auto-recovery with fast re-polling
- Boot-loop detection with Safe Mode
- NTP graceful degradation (3-stage)
- Zero manual intervention required
- ✅ Full Web Dashboard – Direct device management without Home Assistant
- AP Mode: Connects as
Pool-Controller-SetupWiFi hotspot at192.168.4.1 - STA Mode: Web server on port 80 at the device's local IP
- REST API for programmatic access (
/api/status,/api/config, etc.) - Password-protected with session management (cookie-based, SHA-256)
- Tabs: Dashboard, WiFi Setup, MQTT Settings, Configuration, Security & Update
- OTA firmware update via web interface
- AP Mode: Connects as
- ✅ Over-The-Air (OTA) Updates – Remote firmware updates via WiFi
- No physical access required for updates
- Password-protected secure updates
- mDNS discovery support
- ✅ Time sync via NTP (configurable server, default: pool.ntp.org)
- ✅ Configurable timezone with DST support (10 major timezones available)
- ✅ Logging information via MQTT
- ✅ Modern libraries (ArduinoJson 7.3.0, NTPClient 3.2.1)
- ✅ Clean, formatted code following project standards
| Guide | Description | For |
|---|---|---|
| Quick Start Guide | Step-by-step setup for beginners | 🆕 New users |
| FAQ | Troubleshooting common issues | ❓ All users |
| Users Guide | Web dashboard, operation modes, MQTT | 🎛️ Intermediate users |
| Hardware Guide | Assembly, wiring, parts list | 🔧 Builders |
| MQTT Configuration | Home Assistant Discovery, entity reference | 🌐 Smart home integrators |
| State Persistence | How settings are saved across reboots | 💾 Advanced users |
| OTA Updates | Remote firmware updates | 📡 Developers |
| ESP32 Schematic Optimization (DE) | Pin assignment and optimization | 🔌 Hardware experts |
- Codebase is now ESP32-only — cleaner, faster, more reliable
- Removed all
#ifdef ESP8266conditional compilation - Platform: esp32dev (ESP32 DevKit V1)
- P7: Fast Sensor Recovery — DallasTemperatureNode polls every 5s (instead of 300s) when sensor reads NaN
- P8: Boot-Loop Detection — NVS-based boot counter, Safe Mode after 4 consecutive short boots (<5 min), all relays forced OFF
- P9: Configurable Fallback Times — ConfigManager settings
time-loss-green-hoursandtime-loss-red-hoursreplace hardcoded NTP thresholds
- Critical Bug Fixes
- Fixed critical logging bug (vsnprintf buffer initialization)
- Fixed millis() overflow for reliable operation beyond 49.7 days
- Added buffer validation and overflow detection
- New Features
- State persistence across reboots and power failures
- Home Assistant MQTT Discovery support
- System health monitoring with auto-reboot
- Hardware watchdog timer (ESP32)
- Performance Improvements
- Eliminated 10+ String allocations per measurement cycle
- Reduced heap fragmentation by ~90%
- Optimized memory usage for 24/7 operation
See CHANGELOG.md for complete details.
- Configurable NTP Server (currently hardcoded: europe.pool.ntp.org)
- Smart learning: Improved pool pump circulation optimization
- Two separate circulation cycles
- Temperature-based cleaning circulation time
- Improved operation without WiFi connection
- Display and button setup interface
- See also the issue list
Configure your preferred MQTT protocol in the device settings:
mqtt-protocol = "homeassistant"- Home Assistant native discovery (only option in v3.3.0+)
See docs/mqtt-configuration.md for setup details.
All controller states are automatically saved and restored:
- Operation modes and settings
- Temperature thresholds
- Timer configurations
- Relay states
See docs/state-persistence.md for details.
We welcome contributions! Before submitting a pull request, please:
- Read the coding guidelines:
.github/CODING_GUIDELINES.md - Run local linting:
make lint-fix && make lint - Test your changes:
make build(builds for ESP32) - Check for issues: See
.github/QUICK_REFERENCE.mdfor common fixes
All code must pass the same Super-Linter checks run in CI (cpplint for C/C++, EditorConfig, and Markdown/YAML/JSON validation) before merge.
- Lübbe Onken for
TimeClientHelper - All contributors for their valuable input!
MIT License – Free to use, modify, and share.
- Discussions: GitHub Discussions
- Home Assistant Community: community.home-assistant.io
- Reddit: r/homeassistant
If you encounter issues:
- Check the FAQ for common problems.
- Search the Discussions.
- Open a new issue with:
- A detailed description of the problem.
- Screenshots (e.g., serial monitor output, Web Dashboard).
- Your hardware setup (ESP32 model, relay module, sensors).
- Firmware version (check Web Dashboard or serial monitor).
