A DIY ESP32-S3 controller for bringing your pool pump, equipment relays, and optional sensors into Matter.
This is the local-only firmware for a pool controller built around the Waveshare ESP32-S3 Relay 6CH. It talks to a Pentair IntelliFlo-compatible pump over RS-485, gives you six relay outputs, and can read temperature, water-level, and flow sensors.
Pair it with Apple Home, Alexa, Google Home, or another Matter controller and run your pool gear from the same place as the rest of your home. There is no cloud account, subscription, or internet connection required after setup.
This is a sample layout for planning the panel. Match the contactors, wire sizes, breakers, and equipment connections to the gear you are actually using.
Jump to: Shopping list | Build the panel | Firmware setup | Flash and pair
- Pump speed control for Pentair IntelliFlo-compatible and Jandy ePump-compatible variable-speed pumps over RS-485. Select the protocol at compile time and the firmware handles the rest.
- Six Matter relay switches for equipment such as an SWG, heater, valves, or landscape lights. Each relay gets fixed names, icons, and roles via a local configuration header.
- Optional water-level, flow, and DS18B20 temperature sensors, each configurable on a per-port basis in the sensor config header.
- A physical factory reset button for setup and recovery.
- A setup that starts with every relay off.
- New: Jandy ePump driver and a pump protocol abstraction layer. Switch
between Pentair and Jandy with a single compile-time constant in
state.h.
flowchart LR
Home["Matter home"] <-->|"Wi-Fi"| Bridge["Pool controller"]
Bridge <-->|"RS-485"| Pump["Pentair / Jandy pump"]
Sensors["Flow, level, temperature"] --> Bridge
Bridge --> Relays["24 V control relays"]
Relays --> Swg["SWG control"]
Relays --> Heater["Heater control"]
Relays --> Lights["Landscape lights"]
| Part | What to get it for | Where to get it |
|---|---|---|
| Waveshare ESP32-S3 Relay 6CH | The controller itself: ESP32-S3, six relays, and RS-485 in one board. | Amazon |
| VEVOR weatherproof junction box | A 13.78 x 9.84 x 5.90 inch box that fits the build well. Do not go smaller than 11 x 8 inches. | VEVOR |
| Two 35 mm DIN rails | One is for the low-voltage side and controller wiring. The other is for your contactors and 120 V / 240 V wiring. | Amazon |
| 24 V, 2.5 A DIN-rail power supply | Powers the ESP32 relay board, contactor coils, and 24 V gear like valves. | Amazon |
| 18/10 sprinkler cable | Great for sensors and 24 V relay-control wiring. It is thicker than Ethernet and gives you extra conductors to work with. | Amazon or Lowe's |
| Contactors | Use a DC 24 V coil, normally open, 2-pole DIN contactor. It needs to be DC and normally open, so it turns off when 24 V is removed. | Amazon |
| RS-485 wiring for the pump | Connects the controller to the Pentair pump communication bus. | Amazon |
You do not need any sensors for the controller to work. Add one, all three, or none at all.
| Sensor | What to check | Where to get it |
|---|---|---|
| Water temperature | A DS18B20 one-wire probe. | Amazon: waterproof DS18B20 temperature sensor |
| Water level | A low-voltage dry-contact switch; the Flowline Switch-Tek LV10 is a useful reference. | Amazon: vertical float switch 24V dry contact |
| Water flow | Rated for your plumbing and pressure; the Gems FS-550 shows the kind of switch to look for. | Amazon: inline water flow switch 24V dry contact |
You can add other kinds of sensors too. The public firmware is meant to be changed; the sensor development guide walks through adding a new sensor type from GPIO wiring through its Matter endpoint. The sensors below are possible, but I haven't had a need to implement them yet:
| Sensor | What to check | Where to get it |
|---|---|---|
| pH | An analog pH kit that you can read with an ADC-capable input and calibrate in the driver. | DFRobot Gravity industrial analog pH meter |
| ORP | An analog ORP kit that you can read to tell water cleanliness. Although, ORP and it's effectiveness are highly contested in the pool community | DFRobot Gravity industrial analog ORP meter |
Start with the enclosure. The VEVOR box above is large enough for two DIN rails, a 24 V power supply, the controller, and a clean split between the low-voltage and higher-voltage sides. That extra room matters once you start adding contactors and wiring.
Put the controller, 24 V power supply, sensor wiring, and relay-control wiring on one side. Put the contactors and their load wiring on the other. The 24 V power supply feeds the ESP32 relay board, contactor coils, and any 24 V gear you are adding.
Keep the board relays on the low-voltage side of the job. They are for 24 V control circuits, control inputs, and contactor coils. For anything that runs on 120 V or 240 V, like an SWG, pump, heater, or landscape transformer, use the right external contactor or control input for that equipment. The controller tells that gear what to do; it does not carry the 120 V or 240 V load.
These are the pins used by the firmware. You mainly need this table when you are checking wiring or moving to a different board.
| What | Pins |
|---|---|
| RS-485 pump bus | RX GPIO 18, TX GPIO 17 |
| Relay outputs | GPIO 46, 45, 42, 41, 2, 1 |
| Sensor inputs | GPIO 4, 5, 6, 7 |
| Boot button | GPIO 0 |
| Buzzer | GPIO 21 |
| RGB status LED | GPIO 38 |
Before you flash a board, open main/board/board_identity.h. Give it its own
BOARD_DEVICE_ID, Matter setup PIN, and discriminator. The values in the repo
are development defaults, so do not reuse them for every board.
The Matter vendor and product IDs in main/matter/matter_setup.cpp are also
placeholders. If you are making and selling controllers, get real assigned IDs
first.
Sensors are configured in the source, not from a web page. Open
main/board/board_sensor_config.h, pick the sensor type for the port you used,
give it a name, then rebuild and flash.
For example, this makes the second sensor port a flow switch named Pump Flow
and stops relay commands when the switch is open:
{Type::FlowSwitch, "Pump Flow", true},Leave unused ports as Disabled. Use one port for each sensor type: one flow
switch, one float switch, and one temperature probe.
This project uses ESP-IDF 6.0.2 and esp-matter. The included env.sh assumes
they are installed here:
~/.espressif/v6.0.2/esp-idf
~/esp/esp-matter
Install ESP-IDF for the ESP32-S3 first, then follow Espressif's esp-matter setup guide.
If yours live somewhere else, update env.sh. Then, from this folder:
. ./env.sh
idf.py set-target esp32s3
idf.py build
idf.py flash monitorOn its first boot, the controller prints its Matter pairing information. Add it to your Matter home from there.
main/app/ Startup and the main loop
main/board/ Board pins, device identity, and sensor setup
main/io/ Relays, sensors, LEDs, buzzer, and reset button
main/matter/ Matter bridge and devices
main/platform/ ESP-IDF compatibility bits
main/pump/ Pentair and Jandy protocol drivers, pump control, and protocol abstraction
docs/ARCHITECTURE.md More detail about how the pieces fit together
The module guide and architecture guide are there if you want to change the firmware instead of just configure it.
Please read CONTRIBUTING.md before sending a pull request.
Keep certificates, keys, generated sdkconfig files, build folders, and your
personal commissioning values out of Git. Use SECURITY.md for
security reports.
This public firmware is the complete local-only controller. The private Pool Conductor Cloud Edition adds features that depend on a hosted backend and aren't practical without a cloud service:
| Feature | Public | Cloud Edition |
|---|---|---|
| Pentair IntelliFlo pump control | ✓ | ✓ |
| Jandy ePump pump control | ✓ | ✓ |
| Six relay channels with Matter | ✓ | ✓ |
| Flow, level, and temperature sensors | ✓ | ✓ |
| Hayward, Emaux, Century VGreen, Speck Neo, and Nidec Neptune pump protocols | — | ✓ |
| Automatic protocol detection from pump model | — | ✓ |
| Web dashboard with live telemetry | — | ✓ |
| Energy, flow, and temperature history graphs | — | ✓ |
| Remote firmware updates (OTA via AWS IoT) | — | ✓ |
| Relay and sensor configuration from a browser | — | ✓ |
| Cloud-backed controller logs | — | ✓ |
| Apple Sign In authentication | — | ✓ |
| Fleet provisioning (zero-touch device onboarding) | — | ✓ |
| Account management and multi-controller support | — | ✓ |
| Support for 76+ pump models! | — | ✓ |
| Opt-in cloud connectivity (can be disabled from the web dashboard) | — | ✓ |
| Pump scheduling with offline execution (runs locally once downloaded) | — | ✓ |
The cloud edition firmware lives in a private downstream repository and is not part of this open-source release. Cloud connectivity is optional — you can turn it off from the advanced settings page of the web dashboard. When disabled, the controller runs entirely local with no MQTT connection, no telemetry, and no remote access. A physical factory reset is required to re-enable it.
This repo is the complete local-only firmware. If you would rather buy a ready-to-install controller with a hosted dashboard, history, remote updates, and diagnostics, take a look at Pool Conductor. That helps support work on this open-source version too.