\u26a0\ufe0f 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!
The Pool Controller is an ESP32-based control unit that automates your swimming pool management. It provides intelligent circulation, solar heating control, and comprehensive monitoring via MQTT integration with Home Assistant and other smart home systems.
Key Features:
- \u2705 Timed circulation for water cleaning
- \u2705 Solar heating control via additional pump
- \u2705 Multiple operation modes: Auto, Manual, Boost, Timer
- \u2705 Temperature-based automation
- \u2705 Home Assistant MQTT Discovery (v3.3.0+)
- \u2705 Built-in web interface with REST API
- \u2705 State persistence across reboots
- \u2705 System health monitoring with auto-recovery
- \u2705 OTA firmware updates
Cost: ~45\u201375\u20ac (excluding pumps and pool infrastructure)
New to the project? Begin with these resources:
- \ud83d\udcd6 Quick Start Guide \u2013 Step-by-step setup for beginners
- \u2753 Frequently Asked Questions \u2013 Troubleshooting common issues
- \ud83c\udf10 MQTT Configuration \u2013 Home Assistant integration
| Component | Qty | Approx. Cost | Notes |
|---|---|---|---|
| ESP32 Development Board | 1 | 10\u201315\u20ac | 4MB+ flash required |
| DS18B20 Temperature Sensor (waterproof) | 2 | 8\u201312\u20ac | Pool + solar collector |
| 2-Channel 5V Relay Module | 1 | 5\u20138\u20ac | With optocoupler isolation |
| Resistor 4.7k\u03a9 | 2 | < 1\u20ac | Pull-up for OneWire |
| USB Power Supply 5V/\u22651A | 1 | 5\u201310\u20ac | For ESP32 |
| Total | ~45\u201375\u20ac | Without pumps |
Recommended Shops: Amazon, AliExpress, Reichelt, Pollin, Conrad (DE/AT/CH)
# Clone the repository
git clone https://github.com/smart-swimmingpool/pool-controller.git
cd pool-controller
# Build the firmware (first build downloads dependencies)
pio run
# Flash to device
pio run --target upload
# Monitor serial output
pio run --target monitorPlatform: ESP32 DevKit V1 (esp32dev)
- Homie for ESP8266/ESP32 (MQTT framework)
- OneWire (DS18B20 sensor communication)
- DallasTemperature (temperature sensor library)
- ArduinoJson (JSON processing for MQTT)
- NTPClient (time synchronization)
- ESPmDNS (mDNS discovery)
The Pool Controller supports native Home Assistant MQTT Discovery (v3.3.0+). Devices and entities are automatically discovered and added to your Home Assistant instance.
MQTT Protocol: homeassistant (only option in v3.3.0+)
| System | Integration Method | Status |
|---|---|---|
| Home Assistant | MQTT Discovery | \u2705 Native support |
| openHAB | MQTT Binding | \u2705 Manual configuration |
| Node-RED | MQTT nodes | \u2705 Works with any MQTT broker |
| ioBroker | MQTT adapter | \u2705 Works with any MQTT broker |
MQTT Topics: See MQTT Configuration Guide for complete topic reference.
All settings survive reboots and power failures:
- Operation mode, temperatures, timer settings
- ESP32 NVS storage
- Automatic restoration on boot
- Memory monitoring every 10 seconds
- Auto-reboot at critical memory threshold (8KB)
- Hardware watchdog timer (30s timeout)
- Boot-loop detection with Safe Mode
- 90% reduction in heap fragmentation
- 2,880\u201328,800 fewer allocations per day
- Fixed millis() overflow for operation beyond 49.7 days
| Guide | Description | Audience |
|---|---|---|
| Quick Start Guide | Step-by-step setup for beginners | \ud83c\udd95 New users |
| FAQ | Troubleshooting common issues | \u2753 All users |
| Users Guide | Web dashboard, operation modes, MQTT | \ud83c\udf9b\ufe0f Intermediate users |
| Hardware Guide | Assembly, wiring, parts list | \ud83d\udd27 Builders |
| MQTT Configuration | Home Assistant Discovery, entity reference | \ud83c\udf10 Smart home integrators |
| State Persistence | How settings are saved across reboots | \ud83d\udcbe Advanced users |
| OTA Updates | Remote firmware updates | \ud83d\udce1 Developers |
| Software Guide | Development environment, build process | \ud83d\udd27 Developers |
| ESP32 Schematic Optimization | Pin assignment and optimization | \ud83d\udd0c Hardware experts |
- ESP8266 support removed (ESP32-only)
- Phase 3: Proactive Resilience
- Fast sensor recovery (5s polling on NaN)
- Boot-loop detection with Safe Mode
- Configurable fallback times
- Critical bug fixes (logging, millis() overflow)
- State persistence across reboots
- Home Assistant MQTT Discovery support
- System health monitoring
- Hardware watchdog timer
Full Changelog: CHANGELOG.md
- Configurable NTP Server
- 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: Issue List
We welcome contributions! Please follow these steps:
- Read the guidelines: CONTRIBUTING.md
- Fork the repository and create a feature branch
- Make your changes following project standards
- Test thoroughly and update documentation
- Run quality checks:
make lint-fix && make lint - Submit a Pull Request
Quality Gates:
- \u2705 Super-Linter (code quality)
- \u2705 PlatformIO CI (build verification)
- \u2705 Manual review by maintainers
MIT License \u2013 Free to use, modify, and share.
- Discussions: GitHub Discussions
- Website: smart-swimmingpool.com
- Home Assistant Community: community.home-assistant.io
Need Help?
- Check the FAQ
- Search Discussions
- Open a new issue
| Module | Description |
|---|---|
| Pool Controller | Main control unit (this repository) |
| Pool Monitor | Solar-powered wireless temperature display |
| Grafana Dashboard | Visualization dashboard |
| openHAB Config | openHAB configuration files |
| Water Quality Monitor | Water quality monitoring (pH, chlorine) |
| Website | Project documentation website |
Made with \u2764\ufe0f by the Smart Swimming Pool community
