From 6a595cdaf10465cc86ca3ddb130e6e244db25ea1 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 21:59:02 +0000 Subject: [PATCH 1/3] docs: complete the missing sections of the user manual Added comprehensive descriptions for all remaining modes (Stand-by, Overflow, Comfort, Sweep, Backwash, Wintering, Halt) and system components (Heating, Disinfection, Tank, Swimming pump, Light) based on the codebase logic in controller module. Co-authored-by: lostcontrol <983305+lostcontrol@users.noreply.github.com> --- docs/README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/README.md b/docs/README.md index edb00a2..30aabc3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -29,23 +29,66 @@ This mode is internally subdivided into several states. The standard flow is fir * Overflow #### Stand-by +The Stand-by mode is used when the pool is open but not actively being used or overflowing. In this mode, the water circulates through the gravity line rather than overflowing into the tank. Filtration and disinfection can run depending on your settings. It is possible to activate a boost for increased circulation. + +##### Pool status +* Pool is open (cover rolled up) +* Water circulates via the gravity line (no overflow) +* Filtration pump speed is configurable +* Disinfection runs if pump speed is greater than 0 +* Heat pump operates if required and constraints are met + #### Overflow +The Overflow mode is similar to Stand-by, but the water actively overflows into the buffer tank instead of using the gravity line. This mode provides the best aesthetic look of the overflow pool. + +##### Pool status +* Pool is open (cover rolled up) +* Water overflows into the tank +* Filtration pump runs at an intermediate or high speed +* Disinfection runs at appropriate flow speeds +* Boost can be activated + #### Comfort +Comfort mode is designed for when people are swimming in the pool. The pump runs at an adequate speed, the heating is forced to maintain a comfortable temperature, and disinfection remains active to keep the water clean. Depending on your configuration, the pool can either overflow or use the gravity line. + +##### Pool status +* Pool is open +* Heating is forced to maintain temperature +* Higher filtration speed +* Disinfection is active ### Advanced modes #### Sweep +Sweep mode is intended for cleaning the pool, either manually or using a robot cleaner. The pump runs at high speed using the gravity line, and disinfection is temporarily halted to prioritize cleaning operations. + #### Backwash +Backwash mode is an automated maintenance mode to clean the filter. It reverses the water flow through the filter using water from the buffer tank at high speed, discharging the dirty water to the drain. This is immediately followed by a rinse phase to settle the sand before returning to standard operation. + #### Wintering +Wintering mode protects the pool and equipment from freezing during cold weather. The cover is fully opened to avoid damage from ice. When the air temperature drops below a safety threshold, the system automatically starts stirring the water periodically at a set speed to prevent freezing. + #### Halt +Halt mode completely stops the entire Poupool system. All pumps are turned off, valves are closed, and heating and disinfection are halted. This is used for maintenance or complete shutdown. ## Heating +Poupool manages the pool temperature using a connected heat pump. The system monitors the water temperature and compares it against a configured setpoint. Heating only activates when the filtration system is running, and the air temperature is above a minimum threshold (to ensure heat pump efficiency). The system uses hysteresis to avoid turning the heat pump on and off too rapidly and can be configured with a daily start timer. ## Disinfection +Disinfection in Poupool is completely automated using PWM-controlled dosing pumps for both pH reduction and liquid chlorine (based on ORP). +The system operates in a loop: it waits, adjusts the dosage by reading current sensor values and comparing them to the setpoints (using Proportional controllers), and then treats the water. + ### pH +The pH controller reads the current pH value from the sensor. If the pH is higher than the setpoint (defaulting to a setpoint like 7.0), it calculates a required dose of "pH minus" chemical and injects it using the pH dosing pump. + ### ORP +The Oxidation-Reduction Potential (ORP) controller measures the sanitizing capability of the water. If the ORP drops below the configured setpoint (e.g., 600 mV), it triggers the chlorine dosing pump to inject liquid chlorine and restore the required sanitation levels. ## Tank +The tank acts as the buffer for the overflow pool. Its level is continuously monitored by a sensor. +The tank has multiple states: Low, Normal, High, and Fill. Poupool uses different minimum and maximum level thresholds based on whether the pool is in Eco or Overflow mode. If the water level drops below the minimum threshold (minus a hysteresis margin), the system automatically opens the main water valve to refill the tank. ## Swimming pump +Poupool can control a counter-current swimming pump. The pump can run in a `timed` mode (turning off automatically after a set duration) or `continuous` mode. It only operates when the pool is open (e.g., in Stand-by, Overflow, or Comfort modes). It also features its own wintering mode, periodically starting the pump if the water drops below freezing thresholds to prevent the pipes from freezing. ## Light +Pool lights can be toggled via the user interface. The controller simply switches the lighting circuit between `on` and `halt` states. From c3849031e3bf387b0be4a0bf5c47b32240987189 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 22:06:28 +0000 Subject: [PATCH 2/3] docs: deeply expand user manual with diagrams and chemical concepts Expanded the user manual to address PR feedback. Added detailed sections explaining the fundamental concepts of pH, ORP, and Proportional controllers. Added Mermaid diagrams to map out the hardware architecture and mode state machines. Greatly expanded the depth of documentation on Heating, Disinfection, Tank management, and Wintering logic. Co-authored-by: lostcontrol <983305+lostcontrol@users.noreply.github.com> --- docs/README.md | 172 +++++++++++++++++++++++++++++++++++++------------ plan.md | 11 ++++ 2 files changed, 142 insertions(+), 41 deletions(-) create mode 100644 plan.md diff --git a/docs/README.md b/docs/README.md index 30aabc3..4a8b17b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,15 +1,59 @@ # Poupool User Manual + ## Introduction -Poupool is an overflow swimming pool control software. It takes care of everything: tank (the buffer of an overflow pool), filtration, disinfection (pH and ORP monitoring), heating (with a heat pump), cover, lights, temperature monitoring and counter current pump (with variable speed). +Poupool is an advanced, fully automated overflow swimming pool control software. It takes care of everything: the buffer tank, filtration, chemical disinfection (pH and ORP monitoring), 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. + +--- + +## Core Concepts Explained +To fully understand how Poupool manages your pool, it's helpful to grasp a few core chemical and control engineering concepts. + +### What is pH? +pH is a scale used to specify the acidity or basicity of an aqueous solution. It ranges from 0 to 14: +- A pH of 7 is neutral. +- A pH less than 7 is acidic. +- A pH greater than 7 is basic (alkaline). + +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. + +### What is ORP? +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. -All the hardware is COTS (commercial off-the-shelf) based on Raspberry Pi 3, Arduino, relay boards and electronic components easily available from the Internet. +### Proportional (P) Controllers +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. + +--- + +## Hardware Architecture Diagram +Poupool is distributed across a main computer (Raspberry Pi) and a microcontroller (Arduino). + +```mermaid +graph TD + PI[Raspberry Pi 3
Main Controller & UI] -->|I2C / Serial| ARD[Arduino
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] +``` + +--- ## Modes + 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. ### Main modes + #### Eco 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. @@ -28,67 +72,113 @@ This mode is internally subdivided into several states. The standard flow is fir * Stand-by * Overflow +```mermaid +stateDiagram-v2 + [*] --> eco_waiting + eco_waiting --> eco_normal : Start period + eco_normal --> eco_tank : Filter pool done + eco_tank --> eco_waiting : Filter tank done +``` + + #### Stand-by -The Stand-by mode is used when the pool is open but not actively being used or overflowing. In this mode, the water circulates through the gravity line rather than overflowing into the tank. Filtration and disinfection can run depending on your settings. It is possible to activate a boost for increased circulation. +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. -##### Pool status -* Pool is open (cover rolled up) -* Water circulates via the gravity line (no overflow) -* Filtration pump speed is configurable -* Disinfection runs if pump speed is greater than 0 -* Heat pump operates if required and constraints are met +- **Valves:** Gravity valve is OPEN, Tank valve is CLOSED. +- **Filtration:** Runs at your configured stand-by speed. +- **Disinfection:** Only enabled if the filtration speed is greater than 0. +- **Features:** You can manually trigger a "Boost" which increases the pump speed significantly for 5 minutes. Heating will operate if necessary. #### Overflow -The Overflow mode is similar to Stand-by, but the water actively overflows into the buffer tank instead of using the gravity line. This mode provides the best aesthetic look of the overflow 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. -##### Pool status -* Pool is open (cover rolled up) -* Water overflows into the tank -* Filtration pump runs at an intermediate or high speed -* Disinfection runs at appropriate flow speeds -* Boost can be activated +- **Valves:** Gravity valve is CLOSED, Tank valve is OPEN. +- **Filtration:** Runs at an intermediate or high speed to maintain the overflow edge. +- **Disinfection:** Automatically enabled as long as the pump is running at a moderate speed (high enough to flow, low enough for accurate sensor readings). +- **Features:** A "Boost" mode is also available here to quickly clear debris from the surface. #### Comfort -Comfort mode is designed for when people are swimming in the pool. The pump runs at an adequate speed, the heating is forced to maintain a comfortable temperature, and disinfection remains active to keep the water clean. Depending on your configuration, the pool can either overflow or use the gravity line. +Comfort mode is designed for when you are actively swimming. -##### Pool status -* Pool is open -* Heating is forced to maintain temperature -* Higher filtration speed -* Disinfection is active +- **Heating:** It overrides normal daily heating schedules and *forces* the heat pump ON to aggressively maintain your comfortable temperature setpoint. +- **Filtration:** Runs at an elevated speed (Speed 2) to handle bather load. +- **Disinfection:** Fully active. +- **Valves:** Depending on the `overflow_in_comfort` setting, the pool will either overflow to the tank or use the gravity line. + +--- ### Advanced modes + #### Sweep -Sweep mode is intended for cleaning the pool, either manually or using a robot cleaner. The pump runs at high speed using the gravity line, and disinfection is temporarily halted to prioritize cleaning operations. +Sweep mode is intended for intensive cleaning, typically when using a manual vacuum hose or a suction-side robot cleaner. +- **Configuration:** Gravity valve OPEN, Tank valve CLOSED. +- **Pumps:** Filtration pump is forced to Speed 3 (high suction). Disinfection is halted so concentrated chemicals aren't sucked up the vacuum. #### Backwash -Backwash mode is an automated maintenance mode to clean the filter. It reverses the water flow through the filter using water from the buffer tank at high speed, discharging the dirty water to the drain. This is immediately followed by a rinse phase to settle the sand before returning to standard operation. +Sand filters need to be periodically backwashed to flush trapped dirt out to the drain. Poupool automates this complex valve orchestration. +- **Phase 1 (Backwash):** The system draws water from the buffer tank, runs the pump at high speed, and switches the automated backwash and drain valves to flush the filter. +- **Phase 2 (Rinse):** The valves adjust to rinse the sand bed and settle it before returning to standard operation. +*Note: A backwash cycle consumes water from the tank, which will be automatically refilled by the Tank logic.* #### Wintering -Wintering mode protects the pool and equipment from freezing during cold weather. The cover is fully opened to avoid damage from ice. When the air temperature drops below a safety threshold, the system automatically starts stirring the water periodically at a set speed to prevent freezing. +Wintering protects the pool infrastructure from catastrophic freezing damage when temperatures drop. +- The pool cover is automatically commanded to OPEN completely (ice can crush the slats). +- The system continuously monitors the air temperature. +- If the temperature drops below the configured `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 -Halt mode completely stops the entire Poupool system. All pumps are turned off, valves are closed, and heating and disinfection are halted. This is used for maintenance or complete shutdown. +Halt mode is the emergency or maintenance stop. +- It aggressively shuts down all actors: Disinfection, Tank refilling, Arduino hardware interface, Heating, Lights, and the Swim pump. +- All valves are powered off and all pumps are deactivated. + +--- + +## Heating Detailed Logic +Poupool manages the pool temperature using a connected heat pump, orchestrated by a robust state machine. + +1. **Time Checks:** Heating is restricted to a daily cycle. It schedules its start time (e.g., waiting for the sun to come up). +2. **Temperature Constraints:** It will not run if the ambient air temperature is too low (e.g., below 15°C) because heat pumps become incredibly inefficient in the cold. +3. **Hysteresis:** Heating starts if `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. +4. **Filtration Lock:** The heat pump cannot run unless the main filtration pump is pushing water through it. If heating finishes, Poupool enforces a mandatory cool-down delay (keeping the main pump running) to dissipate residual heat from the compressor. + +--- + +## Disinfection Details +Disinfection is fully automated via proportional PWM controllers. + +```mermaid +stateDiagram-v2 + [*] --> waiting + waiting --> running_adjusting + running_adjusting --> running_treating : Calculate Dose + running_treating --> running_adjusting : Inject and Wait +``` + +- **pH Control:** The controller calculates the difference between your desired pH (e.g., 7.2) and the current sensor reading. Since Poupool assumes "pH minus" is used, the system calculates a proportional dose and activates the acid pump via PWM for a maximum cycle of `PH_PWM_PERIOD`. +- **ORP Control:** Similarly, if the ORP drops below the setpoint (e.g., 650 mV), the controller computes the necessary dose of liquid chlorine and activates the chlorine pump. +- **Safety:** Both pumps feature a hardcoded `SECURITY_DURATION` limit. If the pump runs continuously for hours without reaching the setpoint (e.g., an empty chemical barrel or a broken sensor), the system shuts down the pump to prevent accidental massive chemical dumping. -## Heating -Poupool manages the pool temperature using a connected heat pump. The system monitors the water temperature and compares it against a configured setpoint. Heating only activates when the filtration system is running, and the air temperature is above a minimum threshold (to ensure heat pump efficiency). The system uses hysteresis to avoid turning the heat pump on and off too rapidly and can be configured with a daily start timer. +--- -## Disinfection -Disinfection in Poupool is completely automated using PWM-controlled dosing pumps for both pH reduction and liquid chlorine (based on ORP). -The system operates in a loop: it waits, adjusts the dosage by reading current sensor values and comparing them to the setpoints (using Proportional controllers), and then treats the water. +## Tank Management +The buffer tank stores the water displaced by swimmers and provides the necessary volume for the overflow effect. -### pH -The pH controller reads the current pH value from the sensor. If the pH is higher than the setpoint (defaulting to a setpoint like 7.0), it calculates a required dose of "pH minus" chemical and injects it using the pH dosing pump. +- **Level Sensors:** A continuous level sensor measures the height of water in the tank. +- **States:** The tank state machine transitions between `Halt`, `Fill`, `Low`, `Normal`, and `High`. +- **Dynamic Thresholds:** The required water level changes dynamically. In `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. +- **Automatic Refill:** If the water drops below the `too_low` threshold, Poupool opens the main municipal water valve to refill the tank, implementing a hysteresis gap to prevent the valve from fluttering. +- **Empty Protection:** If the level stays critically low for too long, Poupool will emergency stop the entire filtration system to prevent the main pump from running dry. -### ORP -The Oxidation-Reduction Potential (ORP) controller measures the sanitizing capability of the water. If the ORP drops below the configured setpoint (e.g., 600 mV), it triggers the chlorine dosing pump to inject liquid chlorine and restore the required sanitation levels. +--- -## Tank -The tank acts as the buffer for the overflow pool. Its level is continuously monitored by a sensor. -The tank has multiple states: Low, Normal, High, and Fill. Poupool uses different minimum and maximum level thresholds based on whether the pool is in Eco or Overflow mode. If the water level drops below the minimum threshold (minus a hysteresis margin), the system automatically opens the main water valve to refill the tank. +## Swimming Pump +The swimming pump powers the counter-current swimming jets. +- **Modes:** It can be toggled to run `timed` (auto-shutoff after a specified duration) or `continuous`. +- **Interlocks:** It is strictly interlocked with the main filtration system. It will only activate if the pool is confirmed open (Stand-by, Overflow, or Comfort modes). +- **Variable Speed:** The jets can be adjusted by changing the speed parameter. +- **Winter Protection:** It has its own dedicated wintering logic, identical to the main filtration pump, to stir the counter-current pipes and prevent freezing. -## Swimming pump -Poupool can control a counter-current swimming pump. The pump can run in a `timed` mode (turning off automatically after a set duration) or `continuous` mode. It only operates when the pool is open (e.g., in Stand-by, Overflow, or Comfort modes). It also features its own wintering mode, periodically starting the pump if the water drops below freezing thresholds to prevent the pipes from freezing. +--- ## Light -Pool lights can be toggled via the user interface. The controller simply switches the lighting circuit between `on` and `halt` states. +Underwater pool lights are controlled via a simple toggle relay. The system switches between `on` and `halt` states to activate the illumination. diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..e0b7564 --- /dev/null +++ b/plan.md @@ -0,0 +1,11 @@ +1. **Expand `docs/README.md` significantly**: + - Add new chapters to explain fundamental pool chemistry concepts like pH, ORP (Oxidation-Reduction Potential), and how Proportional (PID-like) controllers work. + - Include detailed architectural diagrams using Mermaid.js syntax to visualize the hardware setup (Raspberry Pi, Arduino, Relays) and state machine logic (Eco mode loop, Disinfection loop). + - Deep dive into each component's behavior: what specific pumps/valves are activated in each mode, what speeds are used, etc. + - Clarify the hysteresis mechanisms in Heating and Tank control. + +2. **Run pre-commit steps**: `uv run pre-commit run -a` and run tests if anything else changes (though we only touch documentation). + +3. **Reply to PR comments**: using `reply_to_pr_comments`. + +4. **Submit**: using the original branch name `docs/user-manual-completion-16316513201850647926`. From 8d6d67233802535501a28e2d24090a8f85599f42 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 22:17:49 +0000 Subject: [PATCH 3/3] docs: refine user manual based on PR feedback - Expanded the Introduction to explicitly describe the difference between a standard skimmer pool and an overflow pool. - Moved the "Core Concepts Explained" (pH, ORP, PID) section to the bottom of the document under a new "Appendix: Knowledge Database" header. - Cleaned up the extraneous `plan.md` artifact from the repository. Co-authored-by: lostcontrol <983305+lostcontrol@users.noreply.github.com> --- docs/README.md | 49 ++++++++++++++++++++++++++----------------------- plan.md | 11 ----------- 2 files changed, 26 insertions(+), 34 deletions(-) delete mode 100644 plan.md diff --git a/docs/README.md b/docs/README.md index 4a8b17b..5bc4048 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,34 +1,13 @@ # Poupool User Manual ## Introduction -Poupool is an advanced, fully automated overflow swimming pool control software. It takes care of everything: the buffer tank, filtration, chemical disinfection (pH and ORP monitoring), heating (via a heat pump), the pool cover, underwater lights, multiple temperature sensors, and a variable-speed counter-current swimming pump. +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), 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. --- -## Core Concepts Explained -To fully understand how Poupool manages your pool, it's helpful to grasp a few core chemical and control engineering concepts. - -### What is pH? -pH is a scale used to specify the acidity or basicity of an aqueous solution. It ranges from 0 to 14: -- A pH of 7 is neutral. -- A pH less than 7 is acidic. -- A pH greater than 7 is basic (alkaline). - -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. - -### What is ORP? -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. - -### Proportional (P) Controllers -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. - ---- - ## Hardware Architecture Diagram Poupool is distributed across a main computer (Raspberry Pi) and a microcontroller (Arduino). @@ -182,3 +161,27 @@ The swimming pump powers the counter-current swimming jets. ## Light Underwater pool lights are controlled via a simple toggle relay. The system switches between `on` and `halt` states to activate the illumination. + +## Appendix: Knowledge Database + +## Core Concepts Explained +To fully understand how Poupool manages your pool, it's helpful to grasp a few core chemical and control engineering concepts. + +### What is pH? +pH is a scale used to specify the acidity or basicity of an aqueous solution. It ranges from 0 to 14: +- A pH of 7 is neutral. +- A pH less than 7 is acidic. +- A pH greater than 7 is basic (alkaline). + +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. + +### What is ORP? +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. + +### Proportional (P) Controllers +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. + +--- diff --git a/plan.md b/plan.md deleted file mode 100644 index e0b7564..0000000 --- a/plan.md +++ /dev/null @@ -1,11 +0,0 @@ -1. **Expand `docs/README.md` significantly**: - - Add new chapters to explain fundamental pool chemistry concepts like pH, ORP (Oxidation-Reduction Potential), and how Proportional (PID-like) controllers work. - - Include detailed architectural diagrams using Mermaid.js syntax to visualize the hardware setup (Raspberry Pi, Arduino, Relays) and state machine logic (Eco mode loop, Disinfection loop). - - Deep dive into each component's behavior: what specific pumps/valves are activated in each mode, what speeds are used, etc. - - Clarify the hysteresis mechanisms in Heating and Tank control. - -2. **Run pre-commit steps**: `uv run pre-commit run -a` and run tests if anything else changes (though we only touch documentation). - -3. **Reply to PR comments**: using `reply_to_pr_comments`. - -4. **Submit**: using the original branch name `docs/user-manual-completion-16316513201850647926`.