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
Editable wiring diagrams: diagrams/hot-tub-electrical.drawio (v1) and diagrams/hot-tub-electrical-v2.drawio (v2, same facts, swimlane layout with legend) — open either in diagrams.net or the Draw.io desktop app.
Current understanding (2026-10-22): the Raspberry Pi reads five DS18B20 probes directly on its own 1-Wire bus (4 tub-water probes + 1 hot-water-input probe) — there is no separate microcontroller sensor hub in the shipped design (that approach is kept below only as a legacy alternative). A low-water float switch is a FUTURE addition: no hardware is installed yet, and the control daemon does not read one today. Water level is presumed adequate in software until that hardware exists.
The Raspberry Pi reads the five temperature probes, 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:
- Open the propane bottle.
- Set the heater's gas and water controls to known safe positions.
- 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.
Wi-Fi
|
+-------------+
| Raspberry Pi |
+-------------+
| |
1-Wire GPIO4| |GPIO22 / GPIO23
| |
+-----------+ +------------------+
| 5 DS18B20 | |
| probes: | +-----------+
| 4 tub + | | AC Switch |
| 1 hot-in | | Modules |
+-----------+ +-----+-----+
|
+--------------+--------------+
| |
+---------------+ +---------------+
| Heat Circ Pump| | Filter Pump |
+-------+-------+ +---------------+
|
v
+---------------+
| Propane Heater|
+-------+-------+
|
v
Back to Tub
[FUTURE, not installed] Low-water float switch -----> GPIO17Recommended 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 Probes — Direct Pi 1-Wire (shipped design)
Buy:
- 5 waterproof DS18B20 temperature probes with stainless tips and 6 ft to 10 ft cables — 4 for the tub, 1 for the hot-water input.
- 1 4.7 kOhm resistor for the DS18B20 pull-up (one resistor serves the whole bus).
- 5 waterproof 3-pin connectors, such as M8/M12 aviation connectors, or 3-pin waterproof pigtail connectors, wired as two pluggable bundles: a 4-probe "water" bundle and a 1-probe "hot-in" bundle.
All five probes connect directly to the Raspberry Pi's own 1-Wire bus — no separate microcontroller sensor hub is used. The shipped hot-tub-temps daemon (src/temp/) reads /sys/bus/w1/devices/28-* via the Pi's w1-gpio overlay, learns which ROM ids belong to which bundle during a guided install (see src/temp/README.md), and publishes readings to Redis. This replaces the Pico/hub concept described in the legacy alternative below.
Four tub probes — calculate the tub temperature from their average:
- Hot-return side probe: measures the side where heated water enters the tub.
- 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 also watches the spread between probes — if one probe reads far hotter than the others, the software can flag disagreement instead of trusting a bad reading.
One hot-water-input probe — measures the water entering from the propane heater (the hot_in_f reading), not tub water. It is mounted on the heater-side return line, close to where hot water re-enters the tub plumbing, so the control daemon can confirm the heater is actually producing hot water during startup (see "startup check" in src/control/README.md). It is not included in the tub average.
The DS18B20 probes use three wires, and all five probes share one bus:
DS18B20 wire Pi connection
------------------------------------------------
Red / VCC 3.3V
Black / GND Ground
Yellow / Data GPIO4 (BCM), with 4.7k pull-up to 3.3VMany DS18B20 probes use red, black, and yellow wires, but verify the datasheet for the exact probes you buy. Each probe has a unique digital address (ROM id) that the temperature daemon labels during a one-time teach-in: connect one bundle at a time so the daemon can learn which ids are "hot-in" vs "tub".
For reliability, run all five probe cables back to a small terminal block near the Pi instead of splicing them permanently. This makes it easier to replace a bad probe later.
Legacy alternative: separate microcontroller sensor hub (not used in the shipped build)
An earlier design considered offloading temperature reading to a small microcontroller (e.g. Raspberry Pi Pico) that would read the DS18B20 bus and send one compact package to the Pi over USB/UART. This is not what the shipped hot-tub-temps daemon does, and is kept here only for historical reference in case a future revision wants to move sensing off the main Pi.
Would have needed:
- 1 Raspberry Pi Pico, Pico W, Arduino Nano / Uno, Adafruit QT Py RP2040, or similar small microcontroller.
- 1 USB cable from the sensor hub to the Raspberry Pi, or a 3-wire UART connection if the hub will be mounted separately.
- 1 small screw-terminal breakout board or terminal strip for the sensor hub.
4 DS18B20 tub probes
|
v
+----------------------+
| Temperature Sensor |
| Hub, such as Pico |
+----------+-----------+
|
| USB serial, or UART
v
+----------------------+
| Raspberry Pi |
| main controller |
+----------------------+Illustrative hub-to-Pi message format (not the actual temps:latest schema the shipped daemon publishes — see src/temp/README.md for that):
{
"average_f": 102.4,
"sensors": [
{ "id": "probe_1", "temp_f": 102.8, "status": "ok" },
{ "id": "probe_2", "temp_f": 102.1, "status": "ok" },
{ "id": "probe_3", "temp_f": null, "status": "missing" },
{ "id": "probe_4", "temp_f": 102.3, "status": "ok" }
],
"failed_sensors": ["probe_3"]
}Water Level / Dry-Run Protection — FUTURE CONCERN, not installed
Current state: no float switch is installed, and the control daemon does not read one. Water level is presumed adequate in software (src/control/safety.py has a # TODO: GPIO17 low-water float when hardware is added marker, but nothing wires to it yet). This section describes the planned future addition, not a required part of the current build.
Would need, when added:
- 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 (once installed):
- 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:
+--------------------------------------------------+
| Waterproof Control Box |
| |
| +------------------+ +-----------------+ |
| | Raspberry Pi | 1-Wire| Probe terminal | |
| | on standoffs +------>| block (5x DS18B20| |
| | (GPIO4 + pull-up)| | 4 tub + 1 hot-in)| |
| +------------------+ +-----------------+ |
| |
| 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.
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 TankRecommended 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:
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 tankDuring 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 — FUTURE CONCERN, not installed
Not built yet; the mounting below is the plan for when this hardware is added. Today the controller does not check water level at all. Mount the float switch near the pump intake height, once installed. The controller should refuse to run the heat pump if this switch indicates low water.
Side view of tub wall
Normal water line -------------------------
[ temp probe ]
Minimum safe line -----[ float switch ]---- <-- FUTURE, not installed
[ 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:
Function Pi Pin / GPIO Status
----------------------------------------------------------------
1-Wire probe bus (x5) GPIO4 Shipped (hot-tub-temps)
Heat relay control GPIO22 Shipped (hot-tub-control)
Filter relay control GPIO23 Shipped (hot-tub-control)
Low-water float switch GPIO17 FUTURE — not installed
Optional flow switch GPIO27 Optional — not implemented
Ground Any Pi GND pin
3.3V sensor power Pi 3.3V pinSuggested DS18B20 bus wiring (direct to the Pi, no sensor hub):
Function Pi connection
------------------------------------------------
DS18B20 data bus (x5) GPIO4 (BCM)
DS18B20 pull-up 4.7 kOhm from data to 3.3V
DS18B20 power 3.3V
DS18B20 ground GroundFor switches such as the future float and optional 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:
House / outdoor outlet
|
v
GFCI protection
|
v
Outdoor-rated extension cord
|
v
Weather-protected relay outlets
|
+--> Heat circulation pump
|
+--> Filter pumpImportant 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
-
Build the plumbing loop without automation first. Confirm that the pump reliably moves water through the heater and back to the tub.
-
Mount the waterproof control box. Choose a stable location near the tub but away from splash zones and heater exhaust.
-
Install cable glands or bulkhead connectors. Put sensor connectors on one side or the bottom of the enclosure. Put AC/control cable entries separately.
-
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.
-
Connect the DS18B20 temperature probes directly to the Pi's 1-Wire bus. Wire VCC to 3.3V, ground to ground, and data to GPIO4 with a 4.7 kOhm pull-up resistor. Connect one bundle at a time (hot-in, then water, or vice versa) so
hot-tub-tempscan learn each probe's role — see src/temp/INSTALL.md. -
(Future — skip for now.) Connect the low-water float switch. Not part of the current build. When this hardware is added, wire it to a GPIO input and ground through a waterproof connector.
-
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.
-
Plug pumps into the relay-controlled outlets. Label one outlet "HEAT PUMP" and the other "FILTER PUMP".
-
Test each part manually. Confirm the Pi can read all five temperature probes (
redis-cli GET temps:latest), and can turn the heat pump and filter outlets on/off. -
Test with water before using heat. Run the heat circulation pump with propane closed first. Confirm water flow and no leaks.
-
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
- HOT WATER INPUT TEMP
- LOW WATER SWITCH, once installed (FUTURE — not currently part of the build)
- 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:
- (Future — not enforced today; no float switch installed.) Do not run heat if the low-water switch says water is too low.
- Do not run heat if too many temperature probes are missing or failing beyond the allowed limit.
- Do not run heat if the working 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 (also not installed today).
- 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:
- Five waterproof DS18B20 probes (4 tub + 1 hot-water-input), wired directly to the Pi's own 1-Wire bus on GPIO4 — no separate sensor hub.
- The
hot-tub-tempsdaemon (shipped insrc/temp/), which reads the probes, learns probe roles during install, and publishes average temperature, individual readings, and failed probes to Redis. - Web interface target temperature setting.
- Software hysteresis, such as heating until the 4-point tub 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 — FUTURE, not yet built
Add, when this hardware is built:
- Low-water float switch (not installed today;
src/control/safety.pyhas a TODO hook for it). - Optional flow switch (not installed today).
- Optional outside temperature sensor.
Result (once built): the system can refuse unsafe heating and support future freeze-protection behavior. Today, none of this phase exists — water level is presumed adequate in software.
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.
- 5 waterproof DS18B20 temperature probes — 4 for the tub, 1 for the hot-water input — wired directly to the Pi's 1-Wire bus (GPIO4). No sensor-hub microcontroller is needed.
- 1 4.7 kOhm resistor for the DS18B20 pull-up.
- 5 waterproof 3-pin connectors for the temperature probes, bundled as a 4-probe "water" connector and a 1-probe "hot-in" connector.
- 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.
Not required for the current build, future concern only:
- 1 waterproof float switch (low-water protection — planned for GPIO17, not installed, not read by the control daemon today).
- Optional inline flow switch.
- Optional outside temperature probe.
This gives the system enough hardware to measure a 4-point average tub temperature plus a hot-water-input temperature, control heating circulation, and control filtration. Low-water detection is not yet implemented — water level is presumed adequate in software until the float switch above is added.