Created projects folder, moved hot tub stuff into it

-# Hardware Setup Plan

-

-This document describes a practical DIY hardware implementation for automating the stock-tank hot tub. It assumes the existing propane camping water heater remains manually set for gas and burner behavior, while the automation controls water circulation, filtration, temperature sensing, and optional safety sensors.

-

-The design goal is to keep the system beginner-friendly: use plug-in AC switching, screw terminals, waterproof connectors, and replaceable sensors instead of soldered permanent wiring.

-

-> Safety note: this project combines water, outdoor electricity, propane, and hot water. Use GFCI protection for all AC power. Do not place non-outdoor-rated AC gear where it can get wet. Do not automate propane gas valves unless you are using certified gas-control hardware and know the applicable code. When in doubt, have an electrician review the AC side.

-

-## System Overview

-

-The Raspberry Pi reads temperature and safety sensors, then turns two AC loads on and off:

-

-- Heat circulation pump: moves tub water through the propane heater.

-- Filter pump: runs the 1000 gph filtration pump on demand or on a schedule.

-

-The propane heater is still manually prepared before use:

-

-1. Open the propane bottle.

-2. Set the heater's gas and water controls to known safe positions.

-3. Let the automation switch the circulation pump to start or stop heating.

-

-When the heat pump runs, water flow causes the propane heater to ignite using its normal built-in flow switch.

-

-```text

- Wi-Fi

- |

- +-------------+

- | Raspberry Pi |

- +-------------+

- | | |

- temp probe| | |GPIO / USB control

- | | |

- +-----+ | +------------------+

- | | |

- +-----------+ +-----------+ +-----------+

- | Tub Temp | | Low Water | | AC Switch |

- | Sensor | | Sensor | | Modules |

- +-----------+ +-----------+ +-----+-----+

- |

- +-----------------+-----------------+

- | |

- +---------------+ +---------------+

- | Heat Circ Pump| | Filter Pump |

- +-------+-------+ +---------------+

- |

- v

- +---------------+

- | Propane Heater|

- +-------+-------+

- |

- v

- Back to Tub

-```

-

-## Recommended Shopping List

-

-### Core Control Hardware

-

-Buy:

-

-- 1 Raspberry Pi Zero 2 W, Raspberry Pi 3, or Raspberry Pi 4.

-- 1 official Raspberry Pi power supply.

-- 1 high-endurance microSD card, 32 GB or larger.

-- 1 waterproof plastic enclosure, NEMA 4X / IP65 or better, roughly 12 in x 10 in x 6 in or larger.

-- 1 small DIN rail or mounting plate for the inside of the enclosure.

-- 1 set of cable glands or waterproof bulkhead connectors for every cable entering the box.

-- 1 Raspberry Pi screw-terminal breakout or screw-terminal HAT.

-- 1 pack of Wago lever nuts or small screw terminal blocks.

-- 1 pack of adhesive cable tie mounts and UV-resistant zip ties.

-- 1 outdoor-rated extension cord sized for the total pump load.

-- 1 outdoor GFCI outlet, portable inline GFCI adapter, or GFCI-protected circuit.

-

-The Raspberry Pi should live inside the waterproof enclosure. Mount it on standoffs or a DIN-rail adapter so it is not loose inside the box.

-

-### AC Pump Switching

-

-For a beginner-friendly build, avoid bare relay boards that expose mains voltage. Use enclosed AC switching modules.

-

-Buy one of these approaches:

-

-#### Preferred: Enclosed IoT Relay Modules

-

-- 2 enclosed AC relay outlet modules, such as Digital Loggers IoT Relay or an equivalent enclosed relay module with a low-voltage control input.

-- 2 short outdoor-rated extension cords, if needed, to route pump plugs cleanly.

-

-Use one relay module for the heat circulation pump and one for the filter pump. The Pi only sends a low-voltage control signal; the relay module handles AC switching inside an enclosed product.

-

-#### Acceptable Alternative: Outdoor Smart Plugs

-

-- 2 outdoor-rated smart plugs with local API support.

-

-This is easier electrically, but depends more on Wi-Fi and vendor behavior. Prefer smart plugs that can be controlled locally on your LAN instead of only through a cloud service.

-

-Avoid:

-

-- Loose relay boards switching 120 VAC inside a plastic box.

-- Indoor smart plugs sitting outdoors.

-- Non-GFCI AC power.

-- Running pump current through breadboards, jumper wires, or small PCB traces.

-

-### Temperature Sensors

-

-Buy:

-

-- 4 waterproof DS18B20 temperature probes with stainless tips and 6 ft to 10 ft cables.

-- 1 4.7 kOhm resistor, if your Pi screw-terminal board does not include a DS18B20 pull-up resistor.

-- 4 waterproof 3-pin connectors, such as M8/M12 aviation connectors, or 3-pin waterproof pigtail connectors.

-

-Use four tub temperature probes and calculate the tub temperature from their average:

-

-- Hot-return side probe: measures the side where heated water enters.

-- Opposite-side probe: measures the side farthest from the hot return.

-- Near-end probe: measures one end of the tank.

-- Far-end probe: measures the other end of the tank.

-

-A 4-point average is a better fit for this tub than a single probe because the heater return can create temporary hot spots. The controller can also watch the spread between probes. For example, if one probe reads 10 degrees hotter than the others, the software can ignore that probe temporarily or keep circulating water until the readings converge.

-

-The DS18B20 probes use three wires:

-

-```text

-DS18B20 wire Raspberry Pi connection

-------------------------------------------------

-Red / VCC 3.3V

-Black / GND Ground

-Yellow / Data GPIO4, with 4.7k pull-up to 3.3V

-```

-

-Many DS18B20 probes use red, black, and yellow wires, but verify the datasheet for the exact probes you buy. DS18B20 probes can share the same 3-wire bus, so all four probes can connect to the same 3.3V, ground, and GPIO4 data terminals. Each probe has a unique digital address that the software can label during setup.

-

-For reliability, run the four probe cables back to a small terminal block in the control box instead of splicing them permanently. This makes it easier to replace a bad probe later.

-

-### Water Level / Dry-Run Protection

-

-Buy:

-

-- 1 vertical float switch or horizontal side-mount float switch rated for water exposure.

-- 1 waterproof 2-pin connector.

-- 1 short piece of PVC pipe or plastic guard to protect the float from swimmers and sloshing water.

-

-The water-level sensor should tell the Pi whether the tub has enough water to safely run the heating pump. A float switch is more beginner-friendly than ultrasonic sensing because steam, splashing, and outdoor light can confuse distance sensors.

-

-Recommended mounting:

-

-- Place the float switch near the side wall of the tank.

-- Set it slightly above the minimum safe intake level for the heat circulation pump.

-- Protect it with a small slotted PVC guard so it cannot be bumped easily.

-

-### Optional Flow Sensor

-

-Buy:

-

-- 1 inline water flow switch or flow meter sized for the heater loop tubing.

-- Matching hose adapters, clamps, and thread seal tape.

-

-A flow sensor is optional but useful. It lets the controller confirm that water is actually moving when the heat pump is on. This can catch a clogged line, failed pump, blocked intake, or closed valve.

-

-For a beginner build, a simple flow switch is easier than a pulse-counting flow meter. Wire it like a basic open/closed sensor.

-

-### Optional Outside Temperature Sensor

-

-Buy:

-

-- 1 waterproof DS18B20 probe for outside air temperature, or 1 weatherproof outdoor temperature module.

-

-This can support future anti-freeze logic. Mount it under the control box or under a small shield so it reads outdoor air, not direct sun or heat radiating from the tub.

-

-### Plumbing Hardware

-

-Buy as needed to match the pump and heater hose sizes:

-

-- Reinforced hose rated for hot water.

-- Stainless hose clamps.

-- Barbed hose adapters.

-- Thread seal tape.

-- Ball valves for isolating the pump and heater.

-- Unions or quick-disconnect hose fittings for service.

-- Intake strainer for the heat circulation pump.

-- Optional check valve to discourage reverse flow.

-

-The exact fittings depend on the current pump, heater, and tank connections. Bring one existing hose/fitting to the hardware store if you are unsure of sizes.

-

-## Physical Layout

-

-Mount the control box close enough for sensor cables and pump cords, but not where bathers will splash it.

-

-Good locations:

-

-- On a post next to the tub.

-- On a nearby wall.

-- On a small stand beside the tub.

-

-Avoid:

-

-- Attaching the control box where it can be submerged.

-- Mounting it directly above heater exhaust.

-- Placing it where people step over cords.

-- Letting cable glands point upward where rain can sit on them.

-

-Recommended enclosure layout:

-

-```text

-+--------------------------------------------------+

-| Waterproof Control Box |

-| |

-| +------------------+ +-----------------+ |

-| | Raspberry Pi | | Terminal Blocks | |

-| | on standoffs | | Sensors / GPIO | |

-| +------------------+ +-----------------+ |

-| |

-| Low-voltage side AC relay side |

-| +----------------+ +-----------+ |

-| | Sensor glands | | Relay 1 | |

-| | M8/M12 plugs | | Relay 2 | |

-| +----------------+ +-----------+ |

-| |

-| Bottom cable entries: sensors, control wires, AC |

-+--------------------------------------------------+

-```

-

-Keep low-voltage sensor wiring separated from AC pump cords inside the enclosure. If the relay modules are too large or not rated to sit inside the enclosure, mount them in their own weather-protected location and run only their low-voltage control wires back to the Pi box.

-

-## Plumbing Layout

-

-The heat loop should pull water from the tub, push it through the pump, then through the propane heater, and return hot water to the tub.

-

-```text

-Stock Tank

- |

- | intake with strainer

- v

-+------------------+

-| Heat Circ Pump | controlled by Pi relay

-+--------+---------+

- |

- v

-+------------------+

-| Propane Heater | gas remains manually opened/set

-+--------+---------+

- |

- | hot return line

- v

-Stock Tank

-```

-

-Recommended details:

-

-- Put a strainer before the heat pump intake.

-- Add a ball valve on each side of the pump/heater loop so you can service parts without draining the tub.

-- Use unions or quick disconnects near the pump and heater.

-- Keep hoses short and smooth to reduce flow restriction.

-- Keep heater exhaust fully outdoors and unobstructed.

-

-## Sensor Attachment

-

-### Tub Temperature Probes

-

-The temperature probes should read circulating tub water, not air, tank wall temperature, or only the hot heater return stream.

-

-Recommended placement:

-

-- Put four probes around the tank so the controller can average the readings.

-- Keep all probe tips at roughly the same depth, about halfway down the water column.

-- Put one probe near the heater return side, but not directly in the blast of hot return water.

-- Put one probe on the opposite side of the tank.

-- Put one probe near each long end of the tank.

-- Use adhesive cable clips, stainless clips, or a small bracket to keep the probe tips submerged.

-- Route the probe cables up and out of the tub so bathers cannot snag them.

-

-Do not let the probe tip rest directly against the aluminum tank wall. It should be surrounded by water.

-

-Top-down placement for a 6 ft x 2 ft stock tank:

-

-```text

-Top view

-

- +--------------------------------------------------+

- | Probe 3 Probe 4 |

- | |

- | |

- | hot return ---> circulating water |

- | |

- | Probe 1 Probe 2 |

- +--------------------------------------------------+

-

-Probe 1: near heater return side, offset from direct hot flow

-Probe 2: opposite side from heater return

-Probe 3: one long end of the tank

-Probe 4: other long end of the tank

-```

-

-During heating, display both the average temperature and the temperature spread. The average is useful for control. The spread tells the user whether the tank is evenly mixed yet.

-

-### Low-Water Float Switch

-

-Mount the float switch near the pump intake height. The controller should refuse to run the heat pump if this switch indicates low water.

-

-```text

-Side view of tub wall

-

- Normal water line -------------------------

-

- [ temp probe ]

-

- Minimum safe line -----[ float switch ]----

-

- [ pump intake / strainer ]

-```

-

-## Electrical Connections

-

-### Low-Voltage Sensor Wiring

-

-Bring each sensor into the enclosure through a waterproof connector or cable gland. Inside the box, land the wires on screw terminals.

-

-Suggested Pi GPIO assignments:

-

-```text

-Function Pi Pin / GPIO

-------------------------------------------------

-DS18B20 data bus GPIO4

-Low-water float switch GPIO17

-Optional flow switch GPIO27

-Heat relay control GPIO22

-Filter relay control GPIO23

-Ground Any Pi GND pin

-3.3V sensor power Pi 3.3V pin

-```

-

-The DS18B20 data line needs a 4.7 kOhm pull-up resistor between data and 3.3V. Some breakout boards include this resistor.

-

-For switches such as float and flow sensors, wire one side to GPIO and the other to ground, then configure the Pi input with an internal pull-up resistor in software.

-

-### AC Power Path

-

-The AC power path should be simple and GFCI-protected:

-

-```text

-House / outdoor outlet

- |

- v

-GFCI protection

- |

- v

-Outdoor-rated extension cord

- |

- v

-Weather-protected relay outlets

- |

- +--> Heat circulation pump

- |

- +--> Filter pump

-```

-

-Important rules:

-

-- The Raspberry Pi does not power the pumps.

-- Pump AC power only passes through enclosed relay outlets or outdoor smart plugs.

-- All pump plugs should have drip loops.

-- Keep every plug connection off the ground.

-- Do not exceed the amp rating of the relay module, smart plug, extension cord, or outlet.

-

-## Assembly Steps

-

-1. Build the plumbing loop without automation first.

- Confirm that the pump reliably moves water through the heater and back to the tub.

-

-2. Mount the waterproof control box.

- Choose a stable location near the tub but away from splash zones and heater exhaust.

-

-3. Install cable glands or bulkhead connectors.

- Put sensor connectors on one side or the bottom of the enclosure. Put AC/control cable entries separately.

-

-4. Mount the Raspberry Pi and terminal blocks.

- Use standoffs, DIN rail adapters, or a mounting plate. Do not let electronics float loose in the box.

-

-5. Connect the DS18B20 temperature probes.

- Wire VCC to 3.3V, ground to ground, and data to GPIO4 with a 4.7 kOhm pull-up resistor.

-

-6. Connect the low-water float switch.

- Wire it to a GPIO input and ground through a waterproof connector.

-

-7. Connect relay control inputs.

- Wire the Pi GPIO relay outputs to the low-voltage control inputs of the enclosed relay modules. Follow the relay module's manual for polarity and trigger voltage.

-

-8. Plug pumps into the relay-controlled outlets.

- Label one outlet "HEAT PUMP" and the other "FILTER PUMP".

-

-9. Test each part manually.

- Confirm the software can read all four temperature probes, see the float switch change state, turn the heat pump outlet on/off, and turn the filter outlet on/off.

-

-10. Test with water before using heat.

- Run the heat circulation pump with propane closed first. Confirm water flow and no leaks.

-

-11. Test heating under supervision.

- Open propane, start heating, and watch the first full heat-up cycle in person. Confirm the controller stops heating near the target temperature.

-

-## Recommended Labels

-

-Label everything before closing the box:

-

-- HEAT PUMP OUTLET

-- FILTER PUMP OUTLET

-- TUB TEMP 1

-- TUB TEMP 2

-- TUB TEMP 3

-- TUB TEMP 4

-- LOW WATER SWITCH

-- OUTSIDE TEMP, if installed

-- PI POWER

-- GFCI REQUIRED

-

-Labels matter because this system will be used outdoors, serviced later, and possibly unplugged between uses.

-

-## Minimum Safety Behavior the Hardware Should Support

-

-The hardware should make it possible for the software to enforce these rules:

-

-- Do not run heat if the low-water switch says water is too low.

-- Do not run heat if the four temperature probes disagree by an extreme amount.

-- Do not run heat above a hard maximum temperature.

-- Do not run heat indefinitely if temperature is not rising.

-- Optionally stop heat if the flow switch says water is not moving.

-- Keep filter control independent from heat control.

-

-Hardware alone will not enforce all of this, but the sensors and relay layout make those software checks possible.

-

-## Suggested Build Phases

-

-### Phase 1: Basic Remote Control

-

-Install:

-

-- Raspberry Pi.

-- Two enclosed AC relay outlets or two outdoor smart plugs.

-- Heat pump control.

-- Filter pump control.

-

-Result: remote on/off for heating circulation and filtration.

-

-### Phase 2: Temperature Automation

-

-Add:

-

-- Four waterproof DS18B20 tub temperature probes.

-- Web interface target temperature setting.

-- Software hysteresis, such as heating until the 4-point average reaches target temperature and restarting when the average drops 3 degrees.

-

-Result: the system can maintain a target temperature range.

-

-### Phase 3: Safety Sensors

-

-Add:

-

-- Low-water float switch.

-- Optional flow switch.

-- Optional outside temperature sensor.

-

-Result: the system can refuse unsafe heating and support future freeze-protection behavior.

-

-## Final Recommended Parts Summary

-

-For the first complete version, buy:

-

-- Raspberry Pi Zero 2 W, Pi 3, or Pi 4.

-- Official Pi power supply.

-- 32 GB or larger high-endurance microSD card.

-- IP65 / NEMA 4X waterproof enclosure.

-- Pi screw-terminal breakout or HAT.

-- Waterproof cable glands or M8/M12 connectors.

-- 2 enclosed AC relay outlet modules, or 2 outdoor smart plugs with local control.

-- 4 waterproof DS18B20 tub temperature probes.

-- 1 waterproof float switch.

-- Optional inline flow switch.

-- Optional outside temperature probe.

-- Wago connectors or screw terminal blocks.

-- Outdoor-rated extension cord and GFCI protection.

-- Hot-water-rated hose, hose clamps, valves, unions, and strainers as needed.

-

-This gives the system enough hardware to measure a 4-point average water temperature, control heating circulation, control filtration, and detect the most important unsafe condition: low water.

-# Hot Tub Automation

-

-Given a "Cowboy Hot Tub", the idea is to replace the heavily manual control system with a highly automated one that can be managed remotely.

-

-## Current Setup

-

-- 6' x 2' x 2' Aluminum Stock Tank

-- Propane powered camping water heater (manual controls for gas and water flow)

-- 2.64 gpm pump - to cycle water from the stock tank through the water heater

-- Floating thermometers that transmit temparature wirelessly to a receiver in the house

-- Remote on/off switch for pump electric plug

-- 1000 gph water filter / pump - Must be plugged / unplugged manually to operate

-

-Given the above setup, when the tub is to be used, the user must:

-- ensure the propane gas bottle is open

-- turn on the pump

-- watch the temperature rise

-- once the tub is at the desired temperature, turn off the pump

-

-## Target Setup

-

-- temp sensors in the tub report temp to computer of some kind

-- filter and heat pump connected to computer somehow

-- computer connected to web via Wifi

-- computer exposes web interface and API allowing user or app to:

- - see temperature

- - turn on / off heat

- - turn on / off filter

- - set target temp, allow computer to maintain temp within 3 degree range

- - possibly even report on water level (requires additional sensors)

- - possibly anti-freeze pumping depending on external temp?

-

-## Implementation Notes

-

-### Hardware Setup

-

-- Computer likely raspberry pi

-- pi lives in a waterproof computer box which may be attachable to the tub

-- system powered by plugging in an extension cord to exposed electrical connector

-- all sensors and accessories controlled by the computer should be pluggable / unpluggable (not soldered or fixed attachment)