Documentation

diff --git a/pool.yaml b/pool.yaml
index 1557a38078d4d9eef550eb6c423b786d4465db8b..0d2ed722063d3b35318e8124d91d7b3b2af22b22 100644 (file)
--- a/pool.yaml
+++ b/pool.yaml
@@ -9,6 +9,60 @@
 # GPIO16 (yellow): mains relay for pool pump
 # GPIO32 (blue): mains relay for shed fan
 
+#
+# PHYSICAL SETUP
+#
+# There is a mains relay which controls the pool filter pump. It should pump
+# for around 8 hours a day for filtration. But the return from the pump to
+# the pool is routed via a solar mat on the roof of the shed. A bypass valve
+# exists to allow the water to flow directly back to the pool instead, and
+# another relay controls the 12v feed to open/close it.
+#
+# So when the sun shines, the bypass valve closes and the water is forced to
+# flow over the roof to get back to the pool. When it doesn't, the bypass
+# opens and flow through the roof (mostly) stops.
+#
+# There is a "solar in" temperature sensor in the inlet manifold (where the
+# water flows on its way either through the bypass, or to the roof). The
+# "solar out" temperature sensor is in the top corner of the solar mat, on
+# the roof.
+#
+# The 1-wire temperature sensors are a little bit unreliable. Sometimes they
+# stop working, and power cycling them seems to help. So there's a relay on
+# the 5v power feed to those. A counter for each sensors is unconditionally
+# incremented every minute, and zeroed when a successful reading is taken.
+# If either counter reaches 5 (minutes since a successful reading), the 1w
+# power is bounced.
+#
+# The failure count is also used when comparing input against output
+# temperatures in order to determine whether to open the bypass valve, to
+# ensure that the temperatures being compared are not stale.
+#
+# To avoid unnecessary cycles of the valve motor and reduce hysteresis, the
+# temperature-based open/close of the bypass valve is rate-limited to one
+# activation each five minutes, even though the actual temperature readings
+# occur every minute. It is also tweaked to open the bypass valve early
+# (stop pumping our precious pool heat into the sky as soon as possible),
+# and open later (it's OK for the sun to keep warming the water that's
+# sitting in the solar mat; that heat isn't lost as it'll be pumped into the
+# pool when we *do* close the bypass valve).
+#
+# The pool pump runs unconditionally for the core part of the day (10h-17h)
+# for filtration purposes, and *may* also run between 7h and 19h for
+# heating, according to the temperature readings. The pump will turn *off*
+# any time after 17h if the bypass valve opens for more than 10 minutes.
+# It's harder to know when to turn *on* in the morning, since as no water is
+# flowing the sensors are reading their respective ambient temperatures. So
+# we just use a hard-coded threshold of 20°C on the 'solar out' temperature
+# on the roof, and turn the pump on if that threshold is reached after 7am.
+#
+# If the pump is turned on by the timer at 10h on a cold day, it's likely
+# that the 'solar out' temperature is still higher than the ambient reading
+# from the 'solar in'. So before turning the pump on, ensure the bypass
+# valve is open, to allow water to flow directly back to the pool. By the
+# time the control value is permitted to change state again in five minutes,
+# both sensors should be reporting the true water temperature.
+
 esphome:
   name: pool
   on_boot: