MQTT Configuration
MQTT Configuration (Home Assistant Discovery)
The Pool Controller uses Home Assistant MQTT Discovery for automatic device registration. All devices appear automatically in Home Assistant without any manual configuration.
Note: The former Homie protocol support was removed in v3.3.0. The controller exclusively uses Home Assistant MQTT Discovery.
Configuration
Configure your MQTT broker connection via the Web UI (Settings → MQTT tab):
- MQTT Hostname/IP: Your MQTT broker address
- MQTT Port: Default 1883
- MQTT Username/Password: Optional authentication credentials
After saving and rebooting, all entities appear automatically in Home Assistant.
Via the REST API
The MQTT settings can also be configured programmatically:
curl -b "session=<session>" -X POST \
-d "type=mqtt&host=192.168.1.100&port=1883&username=mqtt_user&password=secret" \
http://<controller-ip>/api/configHome Assistant Entities
The controller publishes the following entities via MQTT Discovery, grouped by type with their standard HA entity category:
| Category | Display in HA |
|---|---|
| (none) | Main device page — primary measurements |
control | Controls section |
config | Configuration section |
diagnostic | Diagnostics section |
Sensors (read-only)
| Function | HA component/object-id | Entity Category | State topic |
|---|---|---|---|
| Solar temperature | sensor/solar-temp | — | homeassistant/sensor/pool-controller/solar-temp/state |
| Pool temperature | sensor/pool-temp | — | homeassistant/sensor/pool-controller/pool-temp/state |
| Controller temperature (ESP32) | sensor/controller-temp | diagnostic | homeassistant/sensor/pool-controller/controller-temp/state |
| Free Heap Space | sensor/heap | diagnostic | homeassistant/sensor/pool-controller/heap/state |
| Max Alloc Block | sensor/max-alloc | diagnostic | homeassistant/sensor/pool-controller/max-alloc/state |
| WiFi Signal Strength | sensor/rssi | diagnostic | homeassistant/sensor/pool-controller/rssi/state |
| System Uptime | sensor/uptime | diagnostic | homeassistant/sensor/pool-controller/uptime/state |
| Local Time | sensor/local-time | diagnostic | homeassistant/sensor/pool-controller/local-time/state |
| Timezone info | sensor/timezone-info | diagnostic | homeassistant/sensor/pool-controller/timezone-info/state |
| Log output | sensor/log | diagnostic | homeassistant/sensor/pool-controller/log/state |
| OTA status | sensor/ota-status | diagnostic | homeassistant/sensor/pool-controller/ota-status/state |
| Effective Runtime | sensor/effective-runtime | diagnostic | homeassistant/sensor/pool-controller/effective-runtime/state |
| Solar Sensor Found | sensor/solar-sensor-found | diagnostic | homeassistant/sensor/pool-controller/solar-sensor-found/state |
| Pool Sensor Found | sensor/pool-sensor-found | diagnostic | homeassistant/sensor/pool-controller/pool-sensor-found/state |
Controls
| Function | HA component/object-id | Entity Category | Command topic |
|---|---|---|---|
| Pool pump relay | switch/pool-pump | control | homeassistant/switch/pool-controller/pool-pump/set |
| Solar pump relay | switch/solar-pump | control | homeassistant/switch/pool-controller/solar-pump/set |
| Operation mode | select/mode | control | homeassistant/select/pool-controller/mode/set |
Configuration (settable via HA)
| Function | HA component/object-id | Entity Category | Command topic |
|---|---|---|---|
| Pool max temp | number/pool-max-temp | config | homeassistant/number/pool-controller/pool-max-temp/set |
| Solar min temp | number/solar-min-temp | config | homeassistant/number/pool-controller/solar-min-temp/set |
| Hysteresis | number/hysteresis | config | homeassistant/number/pool-controller/hysteresis/set |
| Circ. temp threshold | number/temp-circ-threshold | config | homeassistant/number/pool-controller/temp-circ-threshold/set |
| Circ. temp factor | number/temp-circ-factor | config | homeassistant/number/pool-controller/temp-circ-factor/set |
| Circ. max runtime | number/temp-circ-max-runtime | config | homeassistant/number/pool-controller/temp-circ-max-runtime/set |
| Timer start time | time/timer-start | config | homeassistant/time/pool-controller/timer-start/set |
| Timer end time | time/timer-end | config | homeassistant/time/pool-controller/timer-end/set |
| Timezone | select/timezone | config | homeassistant/select/pool-controller/timezone/set |
| NTP Server | text/ntp-server | config | homeassistant/text/pool-controller/ntp-server/set |
| Log level | select/log-level | config | homeassistant/select/pool-controller/log-level/set |
| Log to serial | switch/log-serial | config | homeassistant/switch/pool-controller/log-serial/set |
| Solar Sensor mapping | select/solar-sensor | config | homeassistant/select/pool-controller/solar-sensor/set |
| Pool Sensor mapping | select/pool-sensor | config | homeassistant/select/pool-controller/pool-sensor/set |
Buttons & Diagnostics
| Function | HA component/object-id | Entity Category | Command topic |
|---|---|---|---|
| OTA update trigger | button/ota-update | config | homeassistant/button/pool-controller/ota-update/set |
| Firmware | update/firmware-update | config | homeassistant/update/pool-controller/firmware-update/set |
| Pool Thermostat | climate/thermostat | config | (mode + temperature via climate topics) |
Entity Category Reference
| Category | Description |
|---|---|
| (none) | Primary measurements, shown on the device front page |
control | Primary controls (switches, mode selection) |
config | Configuration values and settings |
diagnostic | Device diagnostics and system information |
Features
All entities support:
- Temperature sensors (pool, solar, controller)
- Relay switches (pool pump, solar pump)
- Operation modes (auto, manual, boost, timer)
- Temperature-based circulation parameters (threshold, factor, max runtime)
- Configuration via MQTT
- State monitoring
Home Assistant Dashboard Example
A ready-to-use Lovelace dashboard example with:
- quick mode switching (
auto,timer,boost,manu) - highlighted pool and solar/storage temperatures
- a dedicated configuration view
- a combined history chart for switching times and temperatures
is available in:
Migration from Homie (Pre-v3.3.0)
If you’re upgrading from an older firmware that used the Homie protocol:
- The Homie protocol has been removed in v3.3.0 — the controller now uses Home Assistant MQTT Discovery exclusively
- After flashing the new firmware, delete stale retained Homie messages
from your MQTT broker to avoid confusion:
mosquitto_pub -h broker -t homie -n -r mosquitto_sub -t 'homie/#' -v | cut -d' ' -f1 | xargs -I{} mosquitto_pub -h broker -t {} -n -r - In Home Assistant, delete the old device entry (Settings → Devices & services → MQTT → Devices → pool-controller → Delete) — the new entities will appear automatically via MQTT Discovery
- Reboot the device to trigger fresh discovery announcements
Last updated on