Poupool is an overflow swimming pool control software
Poupool is an advanced, fully automated overflow swimming pool control software. Unlike standard skimmer pools where the water level sits below the edge and surface debris is drawn into wall-mounted openings, an overflow pool keeps the water level perfectly flush with the surrounding deck. The water continuously spills over the edge into a perimeter gutter and flows into a dedicated buffer tank. This provides superior surface skimming, better water circulation, and a stunning “infinity edge” aesthetic. Poupool is explicitly designed to handle the complex valve and pump orchestration required to manage this buffer tank, alongside filtration, chemical disinfection (pH and ORP monitoring with empty canister detection), heating (via a heat pump), the pool cover, underwater lights, multiple temperature sensors, and a variable-speed counter-current swimming pump.
All the hardware is COTS (commercial off-the-shelf) based on a Raspberry Pi 3 as the central brain, connected to an Arduino for real-time hardware interaction, relay boards, and standard electronic components easily available online.
Poupool is distributed across a main computer (Raspberry Pi) and a microcontroller (Arduino).
graph TD
PI[Raspberry Pi 3<br>Main Controller & UI] -->|I2C / Serial| ARD[Arduino<br>Real-time Hardware]
PI -->|Sensors| TEMP[Temperature Sensors]
PI -->|Relays| PUMPS[Dosing Pumps pH/Cl]
ARD -->|Relays| VALVES[Motorized Valves]
ARD -->|Relays| VSPEED[Variable Speed Filtration]
ARD -->|Relays| COVER[Roller Cover]
ARD -->|Sensors| TANK[Tank Level Sensor]
Poupool uses the concept of modes to switch between functions. Some modes are only reachable via other modes and a requested mode might not be triggered if some pre-conditions are not met. You can always check the current mode in the user interface.
The modes can be split in two categories: the main modes which are most often used and the advanced modes which are used for special purposes.
This is the standard mode when the pool is not in use. In this mode, the filtration and disinfection will run automatically at given intervals and heating will be activated if required.
This mode is internally subdivided into several states. The standard flow is first to wait, then to filter the pool and finally to filter the tank. Those steps are repeated several times a day based on your configuration. The main settings are the total amount of hours of filtration per day and the number of periods.
stateDiagram-v2
[*] --> eco_waiting
eco_waiting --> eco_normal : Start period
eco_normal --> eco_tank : Filter pool done
eco_tank --> eco_waiting : Filter tank done
The Stand-by mode is used when the pool cover is open, but the pool is not actively overflowing into the buffer tank. Water circulation is redirected through the gravity line directly from the pool.
The Overflow mode is similar to Stand-by, but the water actively overflows into the surrounding gutters and into the buffer tank. This provides the classic “infinity” look and is excellent for skimming the surface.
Comfort mode is designed for when you are actively swimming.
overflow_in_comfort setting, the pool will either overflow to the tank or use the gravity line.Sweep mode is intended for intensive cleaning, typically when using a manual vacuum hose or a suction-side robot cleaner.
Sand filters need to be periodically backwashed to flush trapped dirt out to the drain. Poupool automates this complex valve orchestration.
Wintering protects the pool infrastructure from catastrophic freezing damage when temperatures drop.
only_below threshold (e.g., 2°C), the system periodically wakes up and stirs the water at a set speed for a few minutes. Moving water is significantly harder to freeze than still water.Halt mode is the emergency or maintenance stop.
Poupool manages the pool temperature using a connected heat pump, orchestrated by a robust state machine.
Pool Temp < Setpoint - Hysteresis Down. It stops when Pool Temp > Setpoint + Hysteresis Up. This prevents the heat pump from short-cycling on and off repeatedly around the setpoint.Disinfection is fully automated via proportional PWM controllers and incorporates intelligent empty chemical canister detection.
stateDiagram-v2
[*] --> waiting
waiting --> running_adjusting
running_adjusting --> running_treating : Calculate Dose & Sample Duty Cycle
running_treating --> running_adjusting : Inject and Wait
PH_PWM_PERIOD.CL_PWM_PERIOD.security_duration limit (default 7200s, configurable in config.ini). If either pump exceeds this cumulative run time in a single day, dosing shuts down to prevent accidental massive chemical dumping caused by probe faults.Corrosive chemicals like sulfuric acid (pH-) and liquid chlorine make physical float sensors inside canisters prone to failure. Instead, Poupool uses a software sensor that detects empty canisters by monitoring dosing pump duty cycle trends across filtration cycles.
canister_cycles = 3 in config.ini, roughly 12–18 hours of filtration)./status/disinfection/ph/canister_empty and /status/disinfection/cl/canister_empty) and mapped to binary problem sensors in Home Assistant for mobile notifications. State is restored across Poupool reboots.The buffer tank stores the water displaced by swimmers and provides the necessary volume for the overflow effect.
Halt, Fill, Low, Normal, and High.Eco mode, the tank is kept relatively empty to catch rainwater and reduce evaporation. In Overflow mode, the target level is raised higher to provide the necessary head pressure for the overflow edge.too_low threshold, Poupool opens the main municipal water valve to refill the tank, implementing a hysteresis gap to prevent the valve from fluttering.The swimming pump powers the counter-current swimming jets.
timed (auto-shutoff after a specified duration) or continuous.Underwater pool lights are controlled via a simple toggle relay. The system switches between on and halt states to activate the illumination.
To fully understand how Poupool manages your pool, it’s helpful to grasp a few core chemical and control engineering concepts.
pH is a scale used to specify the acidity or basicity of an aqueous solution. It ranges from 0 to 14:
In a swimming pool, maintaining a pH between 7.0 and 7.4 is critical. If the pH is too high, the chlorine loses its effectiveness and scale can form on the pool walls. If it’s too low, the water becomes corrosive to equipment and irritating to swimmers. Poupool automatically injects “pH minus” (acid) to lower the pH whenever it creeps above the target setpoint.
ORP stands for Oxidation-Reduction Potential, measured in millivolts (mV). While testing for “free chlorine” tells you how much chlorine is physically in the water, ORP tells you how effective that chlorine is at killing bacteria and oxidizing contaminants. A higher ORP means the water is actively sanitizing. A typical target for a clean, safe pool is around 600 mV to 700 mV. If the ORP drops below your setpoint, Poupool activates the chlorine dosing pump.
Poupool uses Proportional controllers (a simplified version of PID controllers) to manage chemical dosing smoothly.
Instead of simply turning a chemical pump on and leaving it on until the target is reached (which often leads to an overshoot, injecting too much chemical), a P-controller calculates an error: Error = Setpoint - Current Value.
The injection pump is driven using Pulse Width Modulation (PWM) where the duration the pump is turned ON is proportional to the error. If the pool is far from the target pH, the pump runs longer. As it gets closer to the target, it injects smaller and smaller doses, ensuring perfectly balanced water.