https://github.com/cobra91/wifipool-ha-mqtt
Connect WiFiPool pool devices (pH probes, dosing pumps, relais) to Home Assistant via local MQTT. Replaces cloud dependency and REST polling with real-time MQTT discovery
https://github.com/cobra91/wifipool-ha-mqtt
diy esp8266 home-assistant home-assistant-configuration homeautomation iot mosquitto mqtt pool smart-home tasmota wifipool
Last synced: 18 days ago
JSON representation
Connect WiFiPool pool devices (pH probes, dosing pumps, relais) to Home Assistant via local MQTT. Replaces cloud dependency and REST polling with real-time MQTT discovery
- Host: GitHub
- URL: https://github.com/cobra91/wifipool-ha-mqtt
- Owner: cobra91
- License: mit
- Created: 2026-06-07T17:21:57.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-06-08T19:49:40.000Z (21 days ago)
- Last Synced: 2026-06-08T21:23:18.637Z (21 days ago)
- Topics: diy, esp8266, home-assistant, home-assistant-configuration, homeautomation, iot, mosquitto, mqtt, pool, smart-home, tasmota, wifipool
- Language: Python
- Homepage:
- Size: 17.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# WiFiPool → Home Assistant — Local MQTT Integration
**Disconnect your WiFiPool devices from the cloud and switch to real-time local MQTT.**
This project provides everything you need to connect [WiFiPool](https://play.google.com/store/apps/details?id=wifipool.mobile) pool equipment (pH probes, dosing pumps, relays) to [Home Assistant](https://www.home-assistant.io/) via a local [Mosquitto](https://mosquitto.org/) MQTT broker — replacing REST polling and eliminating cloud dependency.
## Why this project?
The WiFiPool app ships custom Tasmota firmware on ESP8266-based modules for pool management (pH monitoring, relay control, dosing pumps). This firmware:
- Publishes to the WiFiPool cloud MQTT broker
- Does not support standard Tasmota MQTT discovery (SetOption19)
- Uses a custom FullTopic with a fixed hash prefix
- Disables several standard Tasmota commands (`Version`, `MqttTopic` → `"Unknown"`)
This project reverse-engineers these quirks and provides a complete MQTT integration with Home Assistant.
## Architecture
```
┌─────────────┐ MQTT (real-time) ┌──────────────────┐
│ pH Probe │ ────────────────────────────► │ │
│ (ESP8266) │ │ Mosquitto │
│ Sonde │ │ (local broker) │
└─────────────┘ │ port 1883 │
│ │
┌─────────────┐ MQTT (real-time) │ │
│ Dosing Pump │ ────────────────────────────► │ │
│ (Shelly) │ ◄──────────────────────────── │ │
│ Pompe │ (ON/OFF commands) │ │
└─────────────┘ └────────┬─────────┘
│
MQTT Discovery
│
┌────────▼─────────┐
│ Home Assistant │
│ - 10 sensors │
│ - 1 switch │
│ - automations │
└──────────────────┘
```
## What you get
| Entity | Type | MQTT Topic Source |
|--------|------|-------------------|
| WiFiPool pH ADC | sensor (raw) | `stat//STATUS10` → `StatusSNS.ANALOG.A0` |
| WiFiPool pH | sensor (pH) | `stat//STATUS10` → calibration formula |
| WiFiPool Probe Uptime | sensor (s) | `stat//STATUS11` → `Status.UptimeSec` |
| WiFiPool Probe RSSI | sensor (dBm) | `stat//STATUS11` → `Status.Wifi.RSSI` |
| WiFiPool Probe Heap | sensor (KB) | `stat//STATUS11` → `Status.Heap` |
| Pump Power | sensor (W) | `stat//STATUS10` → `StatusSNS.ENERGY.Power` |
| Pump Voltage | sensor (V) | `stat//STATUS10` → `StatusSNS.ENERGY.Voltage` |
| Pump Uptime | sensor (s) | `stat//STATUS11` → `Status.UptimeSec` |
| Pump RSSI | sensor (dBm) | `stat//STATUS11` → `Status.Wifi.RSSI` |
| Pump State | sensor | `stat//STATUS11` → `Status.Power` |
| Pump Control | switch (outlet) | `cmnd//POWER` ↔ `stat//RESULT` |
## Prerequisites
- **Home Assistant** 2024.12+ (native MQTT discovery, no YAML legacy platform support)
- **Mosquitto broker add-on** installed and running in HA
- **WiFiPool devices** accessible on your local network (IPs known)
- **Python 3.10+** with `paho-mqtt` (for the setup script)
## Quick Start
### 1. Install Mosquitto
In Home Assistant → **Settings → Add-ons → Mosquitto broker** → Install.
Add a login in the add-on configuration:
```json
{
"logins": [
{
"username": "tasmota",
"password": "YOUR_PASSWORD_HERE"
}
]
}
```
Save and restart the add-on.
### 2. Configure your WiFiPool devices
Replace values with your own IPs, usernames and passwords.
```bash
# pH Probe
IP_PROBE="192.168.1.XXX"
USER_PROBE="admin"
PASS_PROBE="YOUR_PASSWORD"
# Pump / Relay
IP_PUMP="192.168.1.YYY"
USER_PUMP="admin"
PASS_PUMP="YOUR_PASSWORD"
# Local MQTT broker
MQTT_HOST="192.168.1.ZZZ" # Your HA / Raspberry Pi IP
MQTT_USER="tasmota"
MQTT_PASS="YOUR_PASSWORD"
```
### 3. Point devices to your local MQTT broker
```bash
# pH Probe
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=MqttHost%20${MQTT_HOST}"
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=MqttPort%201883"
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=MqttUser%20${MQTT_USER}"
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=MqttPassword%20${MQTT_PASS}"
# Pump
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=MqttHost%20${MQTT_HOST}"
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=MqttPort%201883"
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=MqttUser%20${MQTT_USER}"
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=MqttPassword%20${MQTT_PASS}"
```
### 4. Disable Tasmota safety rules
WiFiPool firmware enables rules that cut relays on MQTT/WiFi disconnect. If you manage safety via HA automations, disable them:
```bash
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=Rule1%20off"
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=Rule2%20off"
```
### 5. Get your custom FullTopic
WiFiPool firmware uses a custom FullTopic. Retrieve it:
```bash
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=FullTopic"
# Response: {"FullTopic":"/%prefix%/%topic%/"}
```
Note the `` (16 hex characters) and the device topics (`1024EE`, `81AC17`, etc.).
### 6. Configure Tasmota polling rules
WiFiPool firmware does NOT auto-publish sensor data on `tele/` topics. You must set a Tasmota rule to poll `Status 10` and `Status 11` periodically:
```bash
# pH Probe — poll every minute
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=Rule1%20ON%20Time%23Minute%20DO%20Backlog%20Status%2010%3B%20Status%2011%20ENDON"
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=Rule1%201"
# Pump — poll every minute
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=Rule1%20ON%20Time%23Minute%20DO%20Backlog%20Status%2010%3B%20Status%2011%20ENDON"
curl "http://${IP_PUMP}/cm?user=${USER_PUMP}&password=${PASS_PUMP}&cmnd=Rule1%201"
```
This publishes `stat//STATUS10` (sensor data) and `stat//STATUS11` (device state) every minute.
### 7. Run the setup script
```bash
pip install paho-mqtt
python3 scripts/setup.py \
--mqtt-host 192.168.1.ZZZ \
--mqtt-user tasmota \
--mqtt-pass YOUR_PASSWORD \
--prefix "YOUR_FULLTOPIC_HASH" \
--topic-sonde "1024EE" \
--topic-pompe "81AC17"
```
The script publishes MQTT discovery configs to your broker. Home Assistant auto-detects the entities.
### 8. Restart Home Assistant
If entities don't appear immediately, restart HA.
## pH Calibration
The default calibration formula assumes a typical WiFiPool pH probe:
```
pH = 10.1 + (ADC × (3.42 - 10.1) / 1024)
```
Calibration points:
- **pH 10.1** → ADC = 0
- **pH 3.42** → ADC = 1024
**Calibrate with your own probe!** Use pH 4.0 and pH 7.0 buffer solutions:
1. Measure ADC at pH 4.0 → `adc_low`
2. Measure ADC at pH 7.0 → `adc_high`
3. Formula: `pH = 7.0 + (adc - adc_high) × (4.0 - 7.0) / (adc_low - adc_high)`
You can pass custom calibration points to the setup script:
```bash
python3 scripts/setup.py --ph-high 10.1 --ph-low 3.42 ...
```
## Automations (optional)
Example automations are provided in `ha-examples/`:
- **Auto dosing** — activates pump when pH exceeds target range
- **Safety shutdown** — cuts pump if pH drops too low
- **Critical alert** — immediate notification for out-of-range pH
- **Offline detection** — alerts when a device stops publishing
- **Filtration safety** — prevents dosing without active filtration
## Troubleshooting
### Devices "not authorised" in Mosquitto logs
Devices are connecting without credentials. Make sure `MqttUser` and `MqttPassword` are set on each device, and the credentials match a login in the Mosquitto add-on configuration.
### Entities with weird names (`sonde_ph_wifipool_...`)
HA prefixes entity names with the device name. Edit the entity registry in HA to rename them, or use the `--object_id` mapping in the setup script.
### Switch doesn't stay ON
WiFiPool firmware has Tasmota rules (Rule1/Rule2) that cut relays on connection loss. Disable them (see step 4).
### Data not updating
Default `Teleperiod` is 60 seconds. You can reduce it:
```bash
curl "http://${IP_PROBE}/cm?user=${USER_PROBE}&password=${PASS_PROBE}&cmnd=Teleperiod%2030"
```
## WiFiPool Firmware Technical Details
| Property | Detail |
|----------|--------|
| **Base** | Tasmota (custom build) |
| **FullTopic** | `0632c57610d90cb8e169d9f487747890/%prefix%/%topic%/` (fixed hash) |
| **Topic format** | `%06X_%06X` (uppercase hex MAC address) |
| **FriendlyName** | "WifiPool IoT" (×8 slots) |
| **SetOption19** | Accepts ON/OFF but standard discovery does NOT work |
| **Disabled commands** | `Version`, `MqttTopic`, `MqttRestart` → `"Unknown"` |
| **SleepMode** | Dynamic, Sleep=50 |
| **Cloud topic** | `@` (WiFiPool cloud broker format) |
See [`docs/FIRMWARE_NOTES.md`](docs/FIRMWARE_NOTES.md) for the full reverse-engineering details.
## License
MIT — Free to use, modify, and redistribute.