Added initial code for daemons

+.venv-web/

+/var/log/hot-tub/web.log {

+ weekly

+ rotate 8

+ compress

+ delaycompress

+ missingok

+ notifempty

+ copytruncate

+}

+[Unit]

+Description=Hot Tub Web Service

+After=network-online.target redis-server.service

+Wants=network-online.target

+Documentation=file://src/web/INSTALL.md

+

+[Service]

+Type=simple

+User=hot-tub

+Group=hot-tub

+Environment=PYTHONPATH=__INSTALL_ROOT__/src

+ExecStart=/usr/bin/python3 -m web --config /etc/hot-tub/web.json

+Restart=on-failure

+RestartSec=5

+

+[Install]

+WantedBy=multi-user.target

+#!/usr/bin/env bash

+# Install hot-tub web service on Raspberry Pi OS (run with sudo).

+set -euo pipefail

+

+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"

+INSTALL_ROOT="${INSTALL_ROOT:-${REPO_ROOT}}"

+

+if [[ "$(id -u)" -ne 0 ]]; then

+ echo "Run as root: sudo $0" >&2

+ exit 1

+fi

+

+DIST="${INSTALL_ROOT}/src/web/frontend/dist/index.html"

+if [[ ! -f "${DIST}" ]]; then

+ echo "Missing built frontend: ${DIST}" >&2

+ echo "Build on a dev machine: cd src/web/frontend && npm install && npm run build" >&2

+ exit 1

+fi

+

+echo "==> Installing packages (python3-redis, python3-flask)..."

+export DEBIAN_FRONTEND=noninteractive

+apt-get update -qq

+apt-get install -y -qq python3-redis python3-flask

+

+if ! systemctl is-active --quiet redis-server 2>/dev/null && ! systemctl is-active --quiet redis 2>/dev/null; then

+ echo "==> Redis not running; installing redis-server..."

+ apt-get install -y -qq redis-server

+fi

+

+echo "==> Ensuring hot-tub system user..."

+if ! id hot-tub &>/dev/null; then

+ useradd --system --home /var/lib/hot-tub --shell /usr/sbin/nologin hot-tub

+fi

+

+echo "==> Preparing log and config paths..."

+mkdir -p /var/log/hot-tub /etc/hot-tub /var/lib/hot-tub

+chown hot-tub:hot-tub /var/log/hot-tub /var/lib/hot-tub

+

+if [[ ! -f /etc/hot-tub/web.json ]]; then

+ install -m 0644 "${INSTALL_ROOT}/src/web/config.example.json" /etc/hot-tub/web.json

+ sed -i "s|\"static_dir\": \"frontend/dist\"|\"static_dir\": \"${INSTALL_ROOT}/src/web/frontend/dist\"|" /etc/hot-tub/web.json

+ echo " Created /etc/hot-tub/web.json from example"

+else

+ echo " Keeping existing /etc/hot-tub/web.json"

+fi

+

+echo "==> Installing systemd unit..."

+sed "s|__INSTALL_ROOT__|${INSTALL_ROOT}|g" "${SCRIPT_DIR}/hot-tub-web.service" \

+ > /etc/systemd/system/hot-tub-web.service

+

+echo "==> Installing logrotate..."

+install -m 0644 "${SCRIPT_DIR}/hot-tub-web.logrotate" /etc/logrotate.d/hot-tub-web

+

+echo "==> Enabling services..."

+systemctl enable redis-server 2>/dev/null || systemctl enable redis 2>/dev/null || true

+systemctl start redis-server 2>/dev/null || systemctl start redis 2>/dev/null || true

+systemctl daemon-reload

+systemctl enable hot-tub-web.service

+systemctl restart hot-tub-web.service || systemctl start hot-tub-web.service

+

+echo ""

+echo "Installation complete."

+echo " Repo / code root: ${INSTALL_ROOT}"

+echo " Config: /etc/hot-tub/web.json"

+echo " Log: /var/log/hot-tub/web.log"

+echo " UI: http://<pi-ip>:8080/"

+echo ""

+echo "Status: systemctl status hot-tub-web"

+echo "Logs: tail -f /var/log/hot-tub/web.log"

+echo "SSE: curl -N http://localhost:8080/api/events"

+<mxfile host="app.diagrams.net" modified="2026-10-22T17:18:00.000Z" agent="Claude Sonnet via Cursor" version="22.1.0" type="device">

+ <diagram id="hot-tub-electrical-v2" name="Hot tub electrical (v2)">

+ <mxGraphModel dx="1400" dy="900" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1400" pageHeight="970" math="0" shadow="0">

+ <root>

+ <mxCell id="0" />

+ <mxCell id="1" parent="0" />

+

+ <mxCell id="v2title" value="Hot tub — electrical wiring (v2)" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontSize=20;fontStyle=1" vertex="1" parent="1">

+ <mxGeometry x="200" y="18" width="1000" height="38" as="geometry" />

+ </mxCell>

+ <mxCell id="v2subtitle" value="Rendered by Claude Sonnet · same facts as v1: GPIO22 heat relay, GPIO23 filter relay, GPIO4 1-Wire bus with all 5 DS18B20 probes. Low-water float is a FUTURE addition — not installed, no GPIO wired today." style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontSize=11;fontColor=#666666;" vertex="1" parent="1">

+ <mxGeometry x="120" y="56" width="1160" height="26" as="geometry" />

+ </mxCell>

+

+ <!-- Legend -->

+ <mxCell id="lg1sw" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">

+ <mxGeometry x="40" y="92" width="16" height="16" as="geometry" />

+ </mxCell>

+ <mxCell id="lg1tx" value="Controller (Pi)" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;" vertex="1" parent="1">

+ <mxGeometry x="62" y="88" width="150" height="24" as="geometry" />

+ </mxCell>

+

+ <mxCell id="lg2sw" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">

+ <mxGeometry x="260" y="92" width="16" height="16" as="geometry" />

+ </mxCell>

+ <mxCell id="lg2tx" value="Sensor / 1-Wire" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;" vertex="1" parent="1">

+ <mxGeometry x="282" y="88" width="150" height="24" as="geometry" />

+ </mxCell>

+

+ <mxCell id="lg3sw" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;dashed=1;" vertex="1" parent="1">

+ <mxGeometry x="480" y="92" width="16" height="16" as="geometry" />

+ </mxCell>

+ <mxCell id="lg3tx" value="Optional / planned" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;" vertex="1" parent="1">

+ <mxGeometry x="502" y="88" width="160" height="24" as="geometry" />

+ </mxCell>

+

+ <mxCell id="lg4sw" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">

+ <mxGeometry x="700" y="92" width="16" height="16" as="geometry" />

+ </mxCell>

+ <mxCell id="lg4tx" value="GPIO control signal" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;" vertex="1" parent="1">

+ <mxGeometry x="722" y="88" width="170" height="24" as="geometry" />

+ </mxCell>

+

+ <mxCell id="lg5sw" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">

+ <mxGeometry x="920" y="92" width="16" height="16" as="geometry" />

+ </mxCell>

+ <mxCell id="lg5tx" value="120 VAC power" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;" vertex="1" parent="1">

+ <mxGeometry x="942" y="88" width="150" height="24" as="geometry" />

+ </mxCell>

+

+ <mxCell id="lg6sw" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;dashed=1;" vertex="1" parent="1">

+ <mxGeometry x="1140" y="92" width="16" height="16" as="geometry" />

+ </mxCell>

+ <mxCell id="lg6tx" value="Plumbing / mechanical" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;" vertex="1" parent="1">

+ <mxGeometry x="1162" y="88" width="180" height="24" as="geometry" />

+ </mxCell>

+

+ <!-- Lane: low-voltage control -->

+ <mxCell id="laneControl" value="Low-voltage control &amp; sensors" style="swimlane;html=1;startSize=34;fillColor=#f5f5f5;strokeColor=#666666;fontStyle=1;fontSize=13;rounded=0;" vertex="1" parent="1">

+ <mxGeometry x="40" y="130" width="620" height="580" as="geometry" />

+ </mxCell>

+

+ <mxCell id="pi" value="&lt;b&gt;Raspberry Pi 3&lt;/b&gt;&lt;br&gt;(controller)&lt;br&gt;&lt;br&gt;• hot-tub-control&lt;br&gt;• hot-tub-temps&lt;br&gt;• hot-tub-web&lt;br&gt;• Redis (localhost)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=left;spacingLeft=10;verticalAlign=top;spacingTop=8;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="44" width="220" height="130" as="geometry" />

+ </mxCell>

+

+ <mxCell id="busbar" value="1-Wire bus — GPIO4 (BCM), 4.7 kΩ pull-up to 3.3V, shared GND" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontStyle=1;fontSize=11;verticalAlign=middle;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="190" width="560" height="30" as="geometry" />

+ </mxCell>

+

+ <mxCell id="lbl_water" value="Water bundle — 4 probes (tub_avg_f)" style="text;html=1;strokeColor=none;fillColor=none;align=left;fontSize=10;fontStyle=1;fontColor=#8a6d1a;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="224" width="330" height="14" as="geometry" />

+ </mxCell>

+ <mxCell id="lbl_hotin" value="Hot-in bundle (hot_in_f)" style="text;html=1;strokeColor=none;fillColor=none;align=left;fontSize=10;fontStyle=1;fontColor=#8a6d1a;" vertex="1" parent="laneControl">

+ <mxGeometry x="460" y="224" width="130" height="14" as="geometry" />

+ </mxCell>

+

+ <mxCell id="tub1" value="Tub 1&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="242" width="84" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="tub2" value="Tub 2&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="laneControl">

+ <mxGeometry x="112" y="242" width="84" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="tub3" value="Tub 3&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="laneControl">

+ <mxGeometry x="204" y="242" width="84" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="tub4" value="Tub 4&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="laneControl">

+ <mxGeometry x="296" y="242" width="84" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="hotin" value="Hot-in&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6b3;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="laneControl">

+ <mxGeometry x="460" y="242" width="100" height="56" as="geometry" />

+ </mxCell>

+

+ <mxCell id="note_probes" value="5 physical DS18B20 probes share one 1-Wire bus (two pluggable M8/M12 bundles). Identity learned at install time — src/temp/README.md." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#999999;dashed=1;align=left;spacingLeft=10;verticalAlign=top;spacingTop=6;fontSize=10;fontColor=#555555;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="308" width="560" height="46" as="geometry" />

+ </mxCell>

+

+ <mxCell id="future_label" value="FUTURE CONCERN — not yet installed" style="text;html=1;strokeColor=none;fillColor=none;align=left;fontSize=11;fontStyle=1;fontColor=#9a5b00;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="364" width="400" height="16" as="geometry" />

+ </mxCell>

+

+ <mxCell id="float" value="&lt;b&gt;Low-water float switch&lt;/b&gt;&lt;br&gt;Planned: GPIO17 → switch, other side → GND&lt;br&gt;&lt;i&gt;No hardware installed. Water level is presumed adequate in software (src/control/safety.py TODO).&lt;/i&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;dashed=1;dashPattern=4 4;align=left;spacingLeft=10;verticalAlign=top;spacingTop=8;fontSize=10;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="384" width="270" height="110" as="geometry" />

+ </mxCell>

+

+ <mxCell id="flow" value="&lt;b&gt;Flow switch&lt;/b&gt; (optional)&lt;br&gt;Planned: GPIO27 → GND&lt;br&gt;&lt;i&gt;No hardware installed; not implemented.&lt;/i&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;dashed=1;dashPattern=4 4;align=left;spacingLeft=10;verticalAlign=top;spacingTop=8;fontSize=10;" vertex="1" parent="laneControl">

+ <mxGeometry x="310" y="384" width="270" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="gpio_out" value="&lt;b&gt;GPIO outputs&lt;/b&gt; — BCM22 → heat relay IN+ · BCM23 → filter relay IN+ · common GND to relay modules · active_high: true (config)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;align=left;spacingLeft=10;verticalAlign=middle;" vertex="1" parent="laneControl">

+ <mxGeometry x="20" y="504" width="560" height="50" as="geometry" />

+ </mxCell>

+

+ <!-- Lane: AC power -->

+ <mxCell id="laneAC" value="AC power &amp; pumps" style="swimlane;html=1;startSize=34;fillColor=#fff7f0;strokeColor=#d79b00;fontStyle=1;fontSize=13;rounded=0;" vertex="1" parent="1">

+ <mxGeometry x="700" y="130" width="620" height="580" as="geometry" />

+ </mxCell>

+

+ <mxCell id="gfci" value="&lt;b&gt;Outdoor outlet&lt;/b&gt;&lt;br&gt;+ GFCI protection" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="20" y="44" width="160" height="60" as="geometry" />

+ </mxCell>

+

+ <mxCell id="cord" value="Outdoor-rated&lt;br&gt;extension cord" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="210" y="44" width="150" height="60" as="geometry" />

+ </mxCell>

+

+ <mxCell id="relay1" value="&lt;b&gt;Enclosed AC relay #1&lt;/b&gt;&lt;br&gt;HEAT PUMP outlet&lt;br&gt;Low-voltage IN ← GPIO22" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;align=left;spacingLeft=8;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="20" y="124" width="260" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="relay2" value="&lt;b&gt;Enclosed AC relay #2&lt;/b&gt;&lt;br&gt;FILTER PUMP outlet&lt;br&gt;Low-voltage IN ← GPIO23" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;align=left;spacingLeft=8;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="310" y="124" width="260" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="pump_heat" value="&lt;b&gt;Heat circulation pump&lt;/b&gt;&lt;br&gt;120 VAC plug → relay #1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#b85450;align=left;spacingLeft=8;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="20" y="224" width="260" height="90" as="geometry" />

+ </mxCell>

+

+ <mxCell id="pump_filt" value="&lt;b&gt;Filter pump&lt;/b&gt;&lt;br&gt;120 VAC plug → relay #2" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#b85450;align=left;spacingLeft=8;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="310" y="224" width="260" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="heater" value="&lt;b&gt;Propane camp heater&lt;/b&gt;&lt;br&gt;Gas &amp; controls: manual&lt;br&gt;Ignites on water flow" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=8;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="20" y="334" width="260" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="tub" value="&lt;b&gt;Stock-tank tub&lt;/b&gt;&lt;br&gt;(water reservoir)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=8;verticalAlign=middle;" vertex="1" parent="laneAC">

+ <mxGeometry x="310" y="334" width="260" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="note_plumb" value="&lt;i&gt;Plumbing is a closed loop:&lt;/i&gt; tub → pump intake → pump → (heater for the heat loop) → return to tub. AC relays switch pump power only — they never touch propane gas." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#999999;dashed=1;align=left;spacingLeft=10;verticalAlign=top;spacingTop=6;fontSize=11;fontColor=#555555;" vertex="1" parent="laneAC">

+ <mxGeometry x="20" y="424" width="550" height="90" as="geometry" />

+ </mxCell>

+

+ <!-- Edges: control/sensor side -->

+ <mxCell id="e_pi_busbar" value="3.3V / GND" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;endArrow=classic;endFill=1;fontSize=10;" edge="1" parent="1" source="pi" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub1_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub1" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub2_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub2" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub3_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub3" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub4_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub4" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_hotin_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="hotin" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_float_pi" value="GPIO17 (future)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#9673a6;dashed=1;dashPattern=4 4;endArrow=classic;fontSize=10;" edge="1" parent="1" source="float" target="pi">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_flow_pi" value="GPIO27 (optional)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#9673a6;dashed=1;dashPattern=4 4;endArrow=classic;fontSize=10;" edge="1" parent="1" source="flow" target="pi">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_pi_gpioout" value="GPIO22 / GPIO23" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#82b366;endArrow=classic;strokeWidth=2;fontSize=10;" edge="1" parent="1" source="pi" target="gpio_out">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- Edges: GPIO crossing to AC lane -->

+ <mxCell id="e_gpio_relay1" value="heat control" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#82b366;endArrow=classic;strokeWidth=2;fontSize=10;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=0;entryY=0.3;entryDx=0;entryDy=0;" edge="1" parent="1" source="gpio_out" target="relay1">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_gpio_relay2" value="filter control" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#82b366;endArrow=classic;strokeWidth=2;fontSize=10;exitX=1;exitY=0.7;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="gpio_out" target="relay2">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- Edges: AC power chain -->

+ <mxCell id="e_gfci_cord" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="gfci" target="cord">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_cord_relay1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="cord" target="relay1">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_cord_relay2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="cord" target="relay2">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_relay1_pump" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="relay1" target="pump_heat">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_relay2_pump" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="relay2" target="pump_filt">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- Edges: plumbing loop -->

+ <mxCell id="e_pumpheat_heater" value="hot water" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#666666;dashed=1;endArrow=classic;fontSize=10;" edge="1" parent="1" source="pump_heat" target="heater">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_heater_tub" value="return" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#666666;dashed=1;endArrow=classic;fontSize=10;" edge="1" parent="1" source="heater" target="tub">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub_pumpheat" value="intake" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#666666;dashed=1;endArrow=classic;fontSize=10;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="tub" target="pump_heat">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub_pumpfilt" value="intake" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#666666;dashed=1;endArrow=classic;fontSize=10;" edge="1" parent="1" source="tub" target="pump_filt">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_pumpfilt_tub" value="filtered return" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#666666;dashed=1;endArrow=classic;fontSize=10;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=1;entryY=0.3;entryDx=0;entryDy=0;" edge="1" parent="1" source="pump_filt" target="tub">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- GPIO summary table -->

+ <mxCell id="table" value="&lt;b&gt;GPIO summary (BCM numbering)&lt;/b&gt;&lt;br&gt;&lt;table cellpadding=&quot;4&quot; style=&quot;font-size:11px&quot;&gt;&lt;tr&gt;&lt;td&gt;&lt;b&gt;Function&lt;/b&gt;&lt;/td&gt;&lt;td&gt;&lt;b&gt;GPIO&lt;/b&gt;&lt;/td&gt;&lt;td&gt;&lt;b&gt;Notes&lt;/b&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Heat relay&lt;/td&gt;&lt;td&gt;22&lt;/td&gt;&lt;td&gt;control daemon (config.json: gpio.heat_pump)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Filter relay&lt;/td&gt;&lt;td&gt;23&lt;/td&gt;&lt;td&gt;control daemon (config.json: gpio.filter_pump)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;1-Wire data (×5 probes)&lt;/td&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;w1-gpio overlay; 4.7kΩ pull-up to 3.3V; 4 tub + 1 hot-in&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Low-water float&lt;/td&gt;&lt;td&gt;17&lt;/td&gt;&lt;td&gt;&lt;b&gt;FUTURE — no hardware installed&lt;/b&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Flow switch&lt;/td&gt;&lt;td&gt;27&lt;/td&gt;&lt;td&gt;optional, not implemented&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;br&gt;&lt;b&gt;Note:&lt;/b&gt; the shipped &lt;code&gt;hot-tub-temps&lt;/code&gt; daemon reads the Pi's own 1-Wire sysfs directly — no separate USB/UART sensor hub is used." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#999999;align=left;spacingLeft=10;verticalAlign=top;spacingTop=8;" vertex="1" parent="1">

+ <mxGeometry x="40" y="730" width="1280" height="150" as="geometry" />

+ </mxCell>

+

+ <mxCell id="warn" value="⚠ Pi does not power pumps. Use GFCI protection. Drip loops on every plug. Never exceed the amp rating of the relay module, cord, or outlet. Do not automate the propane gas valve. Water level is currently software-presumed adequate — add the float switch before leaving the tub unattended." style="text;html=1;strokeColor=none;fillColor=#fff2cc;align=center;verticalAlign=middle;fontSize=11;fontStyle=1" vertex="1" parent="1">

+ <mxGeometry x="40" y="900" width="1280" height="30" as="geometry" />

+ </mxCell>

+

+ </root>

+ </mxGraphModel>

+ </diagram>

+</mxfile>

+<mxfile host="app.diagrams.net" modified="2026-10-22T17:48:00.000Z" agent="cursor-agent" version="24.0.0" type="device">

+ <diagram id="hotTubElectricalV3" name="Hot Tub Electrical v3">

+ <mxGraphModel dx="2200" dy="1400" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1800" pageHeight="1350" math="0" shadow="0">

+ <root>

+ <mxCell id="0" />

+ <mxCell id="1" parent="0" />

+

+ <!-- ===== Title ===== -->

+ <mxCell id="title1" value="Hot Tub Electrical Circuit Diagram — v3 (fresh design)" style="text;html=1;align=center;verticalAlign=middle;fontSize=22;fontStyle=1;fillColor=none;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="40" y="10" width="1710" height="40" as="geometry" />

+ </mxCell>

+

+ <!-- ===== Section A: AC Power Path ===== -->

+ <mxCell id="secA_bg" value="AC Power Path — 120V AC, GFCI Protected" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;align=left;fontSize=14;fontStyle=1;fillColor=#FFE6CC;strokeColor=#D79B00;spacingLeft=14;spacingTop=10;" vertex="1" parent="1">

+ <mxGeometry x="40" y="60" width="1710" height="260" as="geometry" />

+ </mxCell>

+

+ <mxCell id="houseOutlet" value="House / Outdoor&#10;Outlet&#10;(120V AC)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#D79B00;" vertex="1" parent="1">

+ <mxGeometry x="80" y="160" width="160" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="gfci" value="GFCI Protection&#10;(outlet, breaker, or&#10;inline GFCI adapter)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#D79B00;" vertex="1" parent="1">

+ <mxGeometry x="300" y="160" width="160" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="extCord" value="Outdoor-Rated&#10;Extension Cord" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#D79B00;" vertex="1" parent="1">

+ <mxGeometry x="520" y="160" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="relay1" value="Enclosed Relay Module 1&#10;(low-voltage control input)&#10;&quot;HEAT PUMP OUTLET&quot;" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#D79B00;" vertex="1" parent="1">

+ <mxGeometry x="760" y="110" width="200" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="relay2" value="Enclosed Relay Module 2&#10;(low-voltage control input)&#10;&quot;FILTER PUMP OUTLET&quot;" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#D79B00;" vertex="1" parent="1">

+ <mxGeometry x="760" y="220" width="200" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="heatPump" value="Heat Circulation Pump&#10;(2.64 gpm)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#D79B00;" vertex="1" parent="1">

+ <mxGeometry x="1020" y="110" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="filterPump" value="Filter Pump&#10;(1000 gph)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#D79B00;" vertex="1" parent="1">

+ <mxGeometry x="1020" y="220" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="propaneHeater" value="Propane Heater&#10;(manual gas &amp; water&#10;controls)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#F5F5F5;strokeColor=#666666;" vertex="1" parent="1">

+ <mxGeometry x="1260" y="110" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="tub" value="Stock Tank&#10;(6' x 2' x 2')" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#F5F5F5;strokeColor=#666666;" vertex="1" parent="1">

+ <mxGeometry x="1500" y="165" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <!-- AC path edges -->

+ <mxCell id="e_house_gfci" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#D79B00;strokeWidth=2;rounded=0;" edge="1" parent="1" source="houseOutlet" target="gfci">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_gfci_cord" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#D79B00;strokeWidth=2;rounded=0;" edge="1" parent="1" source="gfci" target="extCord">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_cord_relay1" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#D79B00;strokeWidth=2;rounded=0;exitX=1;exitY=0.25;entryX=0;entryY=0.5;" edge="1" parent="1" source="extCord" target="relay1">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_cord_relay2" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#D79B00;strokeWidth=2;rounded=0;exitX=1;exitY=0.75;entryX=0;entryY=0.5;" edge="1" parent="1" source="extCord" target="relay2">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_relay1_heatpump" value="switched 120V" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#D79B00;strokeWidth=2;rounded=0;fontSize=10;" edge="1" parent="1" source="relay1" target="heatPump">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_relay2_filterpump" value="switched 120V" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#D79B00;strokeWidth=2;rounded=0;fontSize=10;" edge="1" parent="1" source="relay2" target="filterPump">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- Plumbing context edges (non-electrical, for reference only) -->

+ <mxCell id="e_heatpump_heater" value="water flow" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#999999;dashed=1;dashPattern=1 3;endArrow=open;fontSize=9;fontColor=#666666;" edge="1" parent="1" source="heatPump" target="propaneHeater">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_heater_tub" value="hot return" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#999999;dashed=1;dashPattern=1 3;endArrow=open;fontSize=9;fontColor=#666666;exitX=1;exitY=0.5;entryX=0.5;entryY=0;" edge="1" parent="1" source="propaneHeater" target="tub">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_filterpump_tub" value="filter loop (intake &amp; return)" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#999999;dashed=1;dashPattern=1 3;startArrow=open;endArrow=open;fontSize=9;fontColor=#666666;exitX=1;exitY=0.5;entryX=0.5;entryY=1;" edge="1" parent="1" source="filterPump" target="tub">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- ===== Section B: Low-Voltage Control (Raspberry Pi) ===== -->

+ <mxCell id="secB_bg" value="Low-Voltage Control — Raspberry Pi GPIO" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;align=left;fontSize=14;fontStyle=1;fillColor=#DAE8FC;strokeColor=#6C8EBF;spacingLeft=14;spacingTop=10;" vertex="1" parent="1">

+ <mxGeometry x="40" y="340" width="1710" height="220" as="geometry" />

+ </mxCell>

+

+ <mxCell id="piPower" value="5V USB Power Supply&#10;(separate wall outlet,&#10;not through relay)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;fillColor=#FFFFFF;strokeColor=#1F77B4;" vertex="1" parent="1">

+ <mxGeometry x="80" y="420" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="pi" value="Raspberry Pi&#10;&#10;GPIO4 = 1-Wire data bus&#10;GPIO22 = Heat relay control&#10;GPIO23 = Filter relay control&#10;GPIO17 = Float switch (future)&#10;GPIO27 = Flow switch (optional)&#10;3.3V / GND = sensor power" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;align=left;spacingLeft=8;fillColor=#FFFFFF;strokeColor=#1F77B4;strokeWidth=2;" vertex="1" parent="1">

+ <mxGeometry x="360" y="390" width="260" height="140" as="geometry" />

+ </mxCell>

+

+ <mxCell id="noteB" value="Blue lines above connect GPIO22 / GPIO23 to the relay modules' low-voltage control inputs in the AC Power Path section. The Pi never switches 120V AC directly — it only triggers the enclosed relay modules." style="text;html=1;align=left;verticalAlign=middle;fontSize=11;fontStyle=2;fillColor=none;strokeColor=none;whiteSpace=wrap;" vertex="1" parent="1">

+ <mxGeometry x="680" y="420" width="1000" height="60" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_pipower_pi" value="5V" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#1F77B4;strokeWidth=2;rounded=0;fontSize=10;" edge="1" parent="1" source="piPower" target="pi">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_pi_relay1_ctrl" value="GPIO22 control&#10;(low-voltage)" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#1F77B4;strokeWidth=2;rounded=0;fontSize=10;exitX=0.65;exitY=0;entryX=0.15;entryY=1;" edge="1" parent="1" source="pi" target="relay1">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_pi_relay2_ctrl" value="GPIO23 control&#10;(low-voltage)" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#1F77B4;strokeWidth=2;rounded=0;fontSize=10;exitX=0.85;exitY=0;entryX=0.15;entryY=1;" edge="1" parent="1" source="pi" target="relay2">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- ===== Section C: 1-Wire Temperature Sensor Bus ===== -->

+ <mxCell id="secC_bg" value="1-Wire Temperature Sensor Bus — GPIO4" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;align=left;fontSize=14;fontStyle=1;fillColor=#D5E8D4;strokeColor=#82B366;spacingLeft=14;spacingTop=10;" vertex="1" parent="1">

+ <mxGeometry x="40" y="580" width="1710" height="380" as="geometry" />

+ </mxCell>

+

+ <mxCell id="resistor" value="4.7kΩ Pull-up&#10;Resistor" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;fillColor=#FFFFFF;strokeColor=#2CA02C;" vertex="1" parent="1">

+ <mxGeometry x="660" y="630" width="160" height="50" as="geometry" />

+ </mxCell>

+

+ <mxCell id="junction" value="" style="ellipse;whiteSpace=wrap;html=1;fillColor=#000000;strokeColor=#000000;resizable=0;" vertex="1" parent="1">

+ <mxGeometry x="732" y="700" width="16" height="16" as="geometry" />

+ </mxCell>

+

+ <mxCell id="bus" value="Shared 1-Wire Bus (GPIO4 Data + 3.3V + GND)" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;fillColor=#FFFFFF;strokeColor=#2CA02C;strokeWidth=2;" vertex="1" parent="1">

+ <mxGeometry x="700" y="750" width="960" height="40" as="geometry" />

+ </mxCell>

+

+ <mxCell id="labelHotInNote" value="Not included in tub average" style="text;html=1;align=center;verticalAlign=middle;fontSize=10;fontStyle=2;fillColor=none;strokeColor=none;whiteSpace=wrap;" vertex="1" parent="1">

+ <mxGeometry x="700" y="805" width="170" height="20" as="geometry" />

+ </mxCell>

+

+ <mxCell id="labelTubAvg" value="4 Tub Probes — averaged for tub temperature (software flags disagreement between probes)" style="text;html=1;align=center;verticalAlign=middle;fontSize=10;fontStyle=2;fillColor=none;strokeColor=none;whiteSpace=wrap;" vertex="1" parent="1">

+ <mxGeometry x="900" y="805" width="760" height="20" as="geometry" />

+ </mxCell>

+

+ <mxCell id="probeHotIn" value="DS18B20&#10;Hot-Water-Input Probe&#10;(hot_in_f)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#FFFFFF;strokeColor=#2CA02C;" vertex="1" parent="1">

+ <mxGeometry x="700" y="830" width="170" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="probeTub1" value="DS18B20&#10;Tub Probe 1&#10;(hot-return side)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#FFFFFF;strokeColor=#2CA02C;" vertex="1" parent="1">

+ <mxGeometry x="900" y="830" width="170" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="probeTub2" value="DS18B20&#10;Tub Probe 2&#10;(opposite side)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#FFFFFF;strokeColor=#2CA02C;" vertex="1" parent="1">

+ <mxGeometry x="1100" y="830" width="170" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="probeTub3" value="DS18B20&#10;Tub Probe 3&#10;(near end)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#FFFFFF;strokeColor=#2CA02C;" vertex="1" parent="1">

+ <mxGeometry x="1300" y="830" width="170" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="probeTub4" value="DS18B20&#10;Tub Probe 4&#10;(far end)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#FFFFFF;strokeColor=#2CA02C;" vertex="1" parent="1">

+ <mxGeometry x="1500" y="830" width="170" height="80" as="geometry" />

+ </mxCell>

+

+ <!-- Sensor bus edges -->

+ <mxCell id="e_pi_junction" value="GPIO4 (1-Wire Data)" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=2;rounded=0;fontSize=10;exitX=0.3;exitY=1;entryX=0.5;entryY=0;" edge="1" parent="1" source="pi" target="junction">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_junction_resistor" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=2;rounded=0;exitX=0.5;exitY=0;entryX=0.3;entryY=1;" edge="1" parent="1" source="junction" target="resistor">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_resistor_pi3v3" value="3.3V" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=2;rounded=0;fontSize=10;exitX=0.3;exitY=0;entryX=0.45;entryY=1;" edge="1" parent="1" source="resistor" target="pi">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_junction_bus" value="data" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=2;rounded=0;fontSize=10;exitX=1;exitY=0.5;entryX=0.05;entryY=0;" edge="1" parent="1" source="junction" target="bus">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_pi_gnd_bus" value="GND" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=2;rounded=0;fontSize=10;exitX=0.55;exitY=1;entryX=0.95;entryY=0;" edge="1" parent="1" source="pi" target="bus">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_bus_probeHotIn" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=1;rounded=0;endArrow=none;startArrow=none;" edge="1" parent="1" source="bus" target="probeHotIn">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_bus_probeTub1" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=1;rounded=0;endArrow=none;startArrow=none;" edge="1" parent="1" source="bus" target="probeTub1">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_bus_probeTub2" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=1;rounded=0;endArrow=none;startArrow=none;" edge="1" parent="1" source="bus" target="probeTub2">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_bus_probeTub3" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=1;rounded=0;endArrow=none;startArrow=none;" edge="1" parent="1" source="bus" target="probeTub3">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_bus_probeTub4" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#2CA02C;strokeWidth=1;rounded=0;endArrow=none;startArrow=none;" edge="1" parent="1" source="bus" target="probeTub4">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- ===== Section D: Future / Optional additions ===== -->

+ <mxCell id="secD_bg" value="Future / Optional — Not Currently Installed" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;align=left;fontSize=14;fontStyle=1;fillColor=#F5F5F5;strokeColor=#666666;dashed=1;spacingLeft=14;spacingTop=10;" vertex="1" parent="1">

+ <mxGeometry x="40" y="980" width="1710" height="160" as="geometry" />

+ </mxCell>

+

+ <mxCell id="floatSwitch" value="Low-Water Float Switch&#10;GPIO17 — FUTURE&#10;(not installed; water level&#10;presumed adequate today)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#F5F5F5;strokeColor=#666666;dashed=1;" vertex="1" parent="1">

+ <mxGeometry x="300" y="1030" width="240" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="flowSwitch" value="Inline Flow Switch&#10;GPIO27 — OPTIONAL&#10;(not installed)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#F5F5F5;strokeColor=#666666;dashed=1;" vertex="1" parent="1">

+ <mxGeometry x="620" y="1030" width="240" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="outsideTemp" value="Outside Air DS18B20 Probe&#10;OPTIONAL — would share&#10;the 1-Wire bus above&#10;(not installed; for future&#10;anti-freeze logic)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=11;fillColor=#F5F5F5;strokeColor=#666666;dashed=1;" vertex="1" parent="1">

+ <mxGeometry x="940" y="1030" width="260" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_bus_outsideTemp" value="optional bus tap" style="edgeStyle=orthogonalEdgeStyle;html=1;strokeColor=#666666;dashed=1;dashPattern=2 2;rounded=0;fontSize=9;exitX=0.9;exitY=1;entryX=0.5;entryY=0;" edge="1" parent="1" source="bus" target="outsideTemp">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <!-- ===== Legend ===== -->

+ <mxCell id="legend_bg" value="Legend" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;align=left;fontSize=14;fontStyle=1;fillColor=#FFFFFF;strokeColor=#000000;spacingLeft=14;spacingTop=10;" vertex="1" parent="1">

+ <mxGeometry x="40" y="1160" width="620" height="170" as="geometry" />

+ </mxCell>

+

+ <mxCell id="legendSwatch1" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#D79B00;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="60" y="1198" width="40" height="10" as="geometry" />

+ </mxCell>

+ <mxCell id="legendText1" value="120V AC mains (GFCI protected)" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;fillColor=none;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="115" y="1190" width="500" height="26" as="geometry" />

+ </mxCell>

+

+ <mxCell id="legendSwatch2" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#1F77B4;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="60" y="1228" width="40" height="10" as="geometry" />

+ </mxCell>

+ <mxCell id="legendText2" value="Low-voltage DC — Pi power &amp; relay control signals" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;fillColor=none;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="115" y="1220" width="500" height="26" as="geometry" />

+ </mxCell>

+

+ <mxCell id="legendSwatch3" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#2CA02C;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="60" y="1258" width="40" height="10" as="geometry" />

+ </mxCell>

+ <mxCell id="legendText3" value="1-Wire sensor bus (3.3V / GND / GPIO4 data)" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;fillColor=none;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="115" y="1250" width="500" height="26" as="geometry" />

+ </mxCell>

+

+ <mxCell id="legendSwatch4" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#999999;dashed=1;" vertex="1" parent="1">

+ <mxGeometry x="60" y="1288" width="40" height="10" as="geometry" />

+ </mxCell>

+ <mxCell id="legendText4" value="Plumbing / water flow (non-electrical, shown for context)" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;fillColor=none;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="115" y="1280" width="500" height="26" as="geometry" />

+ </mxCell>

+

+ <mxCell id="legendSwatch5" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#F5F5F5;strokeColor=#666666;dashed=1;" vertex="1" parent="1">

+ <mxGeometry x="60" y="1313" width="40" height="10" as="geometry" />

+ </mxCell>

+ <mxCell id="legendText5" value="Future / optional — not currently installed" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;fillColor=none;strokeColor=none;" vertex="1" parent="1">

+ <mxGeometry x="115" y="1305" width="500" height="26" as="geometry" />

+ </mxCell>

+

+ </root>

+ </mxGraphModel>

+ </diagram>

+</mxfile>

+<mxfile host="app.diagrams.net" modified="2026-10-22T18:00:00.000Z" agent="Cursor" version="22.1.0" type="device">

+ <diagram id="hot-tub-electrical" name="Hot tub electrical">

+ <mxGraphModel dx="1200" dy="900" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1200" pageHeight="940" math="0" shadow="0">

+ <root>

+ <mxCell id="0" />

+ <mxCell id="1" parent="0" />

+

+ <mxCell id="title" value="Hot tub — electrical wiring (control side)" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontSize=18;fontStyle=1" vertex="1" parent="1">

+ <mxGeometry x="250" y="20" width="700" height="40" as="geometry" />

+ </mxCell>

+ <mxCell id="subtitle" value="Matches hardware-setup.md and control.json (GPIO22 heat, GPIO23 filter, GPIO4 1-Wire). All 5 DS18B20 probes read directly on the Pi's own 1-Wire bus. Low-water float is a FUTURE addition — not installed, no GPIO wired today." style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontSize=11;fontColor=#666666;" vertex="1" parent="1">

+ <mxGeometry x="100" y="56" width="1000" height="34" as="geometry" />

+ </mxCell>

+

+ <mxCell id="enc" value="Waterproof enclosure — keep low-voltage wiring separate from AC pump cords" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;dashed=1;dashPattern=8 8;verticalAlign=top;fontStyle=1;spacingTop=8;" vertex="1" parent="1">

+ <mxGeometry x="40" y="100" width="580" height="600" as="geometry" />

+ </mxCell>

+

+ <mxCell id="pi" value="&lt;b&gt;Raspberry Pi 3&lt;/b&gt;&lt;br&gt;(controller)&lt;br&gt;&lt;br&gt;• hot-tub-control&lt;br&gt;• hot-tub-temps&lt;br&gt;• hot-tub-web&lt;br&gt;• Redis (localhost)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=left;spacingLeft=10;verticalAlign=top;spacingTop=8;" vertex="1" parent="1">

+ <mxGeometry x="70" y="150" width="200" height="130" as="geometry" />

+ </mxCell>

+

+ <mxCell id="busbar" value="1-Wire bus — GPIO4 (BCM), 4.7 kΩ pull-up to 3.3V, shared GND" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontStyle=1;fontSize=11;" vertex="1" parent="1">

+ <mxGeometry x="70" y="300" width="510" height="34" as="geometry" />

+ </mxCell>

+

+ <mxCell id="lbl_water" value="Water bundle — 4 probes (tub_avg_f)" style="text;html=1;strokeColor=none;fillColor=none;align=left;fontSize=10;fontStyle=1;fontColor=#8a6d1a;" vertex="1" parent="1">

+ <mxGeometry x="70" y="348" width="320" height="16" as="geometry" />

+ </mxCell>

+ <mxCell id="lbl_hotin" value="Hot-in bundle — 1 probe (hot_in_f)" style="text;html=1;strokeColor=none;fillColor=none;align=left;fontSize=10;fontStyle=1;fontColor=#8a6d1a;" vertex="1" parent="1">

+ <mxGeometry x="400" y="348" width="180" height="16" as="geometry" />

+ </mxCell>

+

+ <mxCell id="tub1" value="Tub probe 1&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="1">

+ <mxGeometry x="70" y="368" width="90" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="tub2" value="Tub probe 2&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="1">

+ <mxGeometry x="170" y="368" width="90" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="tub3" value="Tub probe 3&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="1">

+ <mxGeometry x="270" y="368" width="90" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="tub4" value="Tub probe 4&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="1">

+ <mxGeometry x="370" y="368" width="90" height="56" as="geometry" />

+ </mxCell>

+ <mxCell id="hotin" value="Hot-in probe&lt;br&gt;DS18B20" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6b3;strokeColor=#d6b656;fontSize=10;" vertex="1" parent="1">

+ <mxGeometry x="490" y="368" width="90" height="56" as="geometry" />

+ </mxCell>

+

+ <mxCell id="note_probes" value="5 physical DS18B20 probes share one 1-Wire bus, wired as two pluggable bundles (M8/M12 drops). Identity (which ROM id is which role) is learned at install time — see src/temp/README.md." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#999999;dashed=1;align=left;spacingLeft=10;verticalAlign=top;spacingTop=6;fontSize=10;fontColor=#555555;" vertex="1" parent="1">

+ <mxGeometry x="70" y="434" width="510" height="56" as="geometry" />

+ </mxCell>

+

+ <mxCell id="future_box" value="FUTURE CONCERN — not yet installed" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fdf0e6;strokeColor=#d79b00;dashed=1;dashPattern=6 6;verticalAlign=top;fontStyle=1;fontSize=12;fontColor=#9a5b00;spacingTop=6;align=center;" vertex="1" parent="1">

+ <mxGeometry x="70" y="500" width="510" height="130" as="geometry" />

+ </mxCell>

+

+ <mxCell id="float" value="&lt;b&gt;Low-water float switch&lt;/b&gt;&lt;br&gt;Planned: GPIO17 → switch, other side → GND&lt;br&gt;&lt;i&gt;No hardware installed. Water level is presumed adequate in software (src/control/safety.py TODO). Not wired into the control daemon.&lt;/i&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;dashed=1;dashPattern=4 4;align=left;spacingLeft=10;verticalAlign=top;spacingTop=6;fontSize=10;" vertex="1" parent="1">

+ <mxGeometry x="90" y="530" width="240" height="90" as="geometry" />

+ </mxCell>

+

+ <mxCell id="flow" value="&lt;b&gt;Flow switch&lt;/b&gt; (optional)&lt;br&gt;Planned: GPIO27 → GND&lt;br&gt;&lt;i&gt;No hardware installed; not implemented.&lt;/i&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;dashed=1;dashPattern=4 4;align=left;spacingLeft=10;verticalAlign=top;spacingTop=6;fontSize=10;" vertex="1" parent="1">

+ <mxGeometry x="350" y="530" width="210" height="90" as="geometry" />

+ </mxCell>

+

+ <mxCell id="gpio_out" value="&lt;b&gt;GPIO outputs&lt;/b&gt; — BCM22 → heat relay IN+ · BCM23 → filter relay IN+ · common GND to relay modules · active_high: true (config)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;align=left;spacingLeft=10;verticalAlign=middle;" vertex="1" parent="1">

+ <mxGeometry x="70" y="650" width="510" height="34" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_pi_bus" value="3.3V + GND" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;endArrow=classic;endFill=1;fontSize=10;" edge="1" parent="1" source="pi" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub1_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub1" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub2_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub2" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub3_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub3" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_tub4_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="tub4" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_hotin_bus" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#d6b656;startArrow=none;endArrow=none;" edge="1" parent="1" source="hotin" target="busbar">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_float_pi" value="GPIO17 (future)" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#9673a6;dashed=1;dashPattern=4 4;endArrow=classic;fontSize=9;" edge="1" parent="1" source="float" target="pi">

+ <mxGeometry relative="1" as="geometry">

+ <Array as="points">

+ <mxPoint x="30" y="575" />

+ <mxPoint x="30" y="215" />

+ </Array>

+ </mxGeometry>

+ </mxCell>

+

+ <mxCell id="ac_box" value="AC side (enclosed relay modules or outdoor-rated location)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;dashed=1;dashPattern=8 8;verticalAlign=top;fontStyle=1;spacingTop=8;" vertex="1" parent="1">

+ <mxGeometry x="650" y="100" width="460" height="420" as="geometry" />

+ </mxCell>

+

+ <mxCell id="gfci" value="&lt;b&gt;Outdoor outlet&lt;/b&gt;&lt;br&gt;+ GFCI protection" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">

+ <mxGeometry x="690" y="140" width="160" height="60" as="geometry" />

+ </mxCell>

+

+ <mxCell id="cord" value="Outdoor-rated&lt;br&gt;extension cord" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">

+ <mxGeometry x="890" y="140" width="120" height="60" as="geometry" />

+ </mxCell>

+

+ <mxCell id="relay1" value="&lt;b&gt;Enclosed AC relay #1&lt;/b&gt;&lt;br&gt;HEAT PUMP outlet&lt;br&gt;Low-voltage IN ← GPIO22" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;align=left;spacingLeft=8;" vertex="1" parent="1">

+ <mxGeometry x="690" y="240" width="200" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="relay2" value="&lt;b&gt;Enclosed AC relay #2&lt;/b&gt;&lt;br&gt;FILTER PUMP outlet&lt;br&gt;Low-voltage IN ← GPIO23" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;align=left;spacingLeft=8;" vertex="1" parent="1">

+ <mxGeometry x="690" y="350" width="200" height="80" as="geometry" />

+ </mxCell>

+

+ <mxCell id="pump_heat" value="&lt;b&gt;Heat circulation pump&lt;/b&gt;&lt;br&gt;120 VAC plug → relay #1&lt;br&gt;Tub → pump → propane heater → tub" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#b85450;align=left;spacingLeft=8;" vertex="1" parent="1">

+ <mxGeometry x="910" y="230" width="180" height="90" as="geometry" />

+ </mxCell>

+

+ <mxCell id="pump_filt" value="&lt;b&gt;Filter pump&lt;/b&gt;&lt;br&gt;120 VAC plug → relay #2" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#b85450;align=left;spacingLeft=8;" vertex="1" parent="1">

+ <mxGeometry x="910" y="345" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="heater" value="&lt;b&gt;Propane camp heater&lt;/b&gt;&lt;br&gt;Gas &amp; controls: &lt;b&gt;manual&lt;/b&gt;&lt;br&gt;Ignites on water flow" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=8;" vertex="1" parent="1">

+ <mxGeometry x="910" y="430" width="180" height="70" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_gfci_cord" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="gfci" target="cord">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_cord_r1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="cord" target="relay1">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_cord_r2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="cord" target="relay2">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_r1_p" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="relay1" target="pump_heat">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_r2_p" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#b85450;endArrow=classic;" edge="1" parent="1" source="relay2" target="pump_filt">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+ <mxCell id="e_pump_h" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#666666;dashed=1;endArrow=classic;" edge="1" parent="1" source="pump_heat" target="heater">

+ <mxGeometry relative="1" as="geometry" />

+ </mxCell>

+

+ <mxCell id="e_gpio_r1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#82b366;endArrow=classic;strokeWidth=2;" edge="1" parent="1" source="gpio_out" target="relay1">

+ <mxGeometry relative="1" as="geometry">

+ <Array as="points">

+ <mxPoint x="630" y="667" />

+ <mxPoint x="630" y="280" />

+ </Array>

+ </mxGeometry>

+ </mxCell>

+ <mxCell id="e_gpio_r2" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#82b366;endArrow=classic;strokeWidth=2;" edge="1" parent="1" source="gpio_out" target="relay2">

+ <mxGeometry relative="1" as="geometry">

+ <Array as="points">

+ <mxPoint x="615" y="667" />

+ <mxPoint x="615" y="390" />

+ </Array>

+ </mxGeometry>

+ </mxCell>

+ <mxCell id="e_gpio_l" value="Low-voltage control wires only (follow relay module manual)" style="text;html=1;strokeColor=none;fillColor=none;align=center;fontSize=10;fontColor=#006600;" vertex="1" parent="1">

+ <mxGeometry x="595" y="560" width="105" height="90" as="geometry" />

+ </mxCell>

+

+ <mxCell id="table" value="&lt;b&gt;GPIO summary (BCM)&lt;/b&gt;&lt;br&gt;&lt;table cellpadding=&quot;4&quot; style=&quot;font-size:11px&quot;&gt;&lt;tr&gt;&lt;td&gt;&lt;b&gt;Function&lt;/b&gt;&lt;/td&gt;&lt;td&gt;&lt;b&gt;GPIO&lt;/b&gt;&lt;/td&gt;&lt;td&gt;&lt;b&gt;Notes&lt;/b&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Heat relay&lt;/td&gt;&lt;td&gt;22&lt;/td&gt;&lt;td&gt;control daemon&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Filter relay&lt;/td&gt;&lt;td&gt;23&lt;/td&gt;&lt;td&gt;control daemon&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;1-Wire data (×5 probes)&lt;/td&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;w1-gpio overlay; 4.7k pull-up; 4 tub + 1 hot-in&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Low-water float&lt;/td&gt;&lt;td&gt;17&lt;/td&gt;&lt;td&gt;&lt;b&gt;FUTURE — no hardware installed&lt;/b&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Flow switch&lt;/td&gt;&lt;td&gt;27&lt;/td&gt;&lt;td&gt;optional, not implemented&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;br&gt;&lt;b&gt;Note:&lt;/b&gt; the shipped &lt;code&gt;hot-tub-temps&lt;/code&gt; daemon reads the Pi's own 1-Wire sysfs directly — no separate USB/UART sensor hub is used." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#999999;align=left;spacingLeft=10;verticalAlign=top;spacingTop=8;" vertex="1" parent="1">

+ <mxGeometry x="40" y="730" width="1120" height="160" as="geometry" />

+ </mxCell>

+

+ <mxCell id="warn" value="⚠ Pi does not power pumps. Use GFCI. Drip loops on all plugs. Do not exceed relay/cord/outlet amp ratings. Water level is currently software-presumed adequate — add the float switch before leaving the tub unattended." style="text;html=1;strokeColor=none;fillColor=#fff2cc;align=center;verticalAlign=middle;fontSize=11;fontStyle=1" vertex="1" parent="1">

+ <mxGeometry x="40" y="900" width="1120" height="30" as="geometry" />

+ </mxCell>

+

+ </root>

+ </mxGraphModel>

+ </diagram>

+</mxfile>

+**Editable wiring diagrams:** [diagrams/hot-tub-electrical.drawio](diagrams/hot-tub-electrical.drawio) (v1) and [diagrams/hot-tub-electrical-v2.drawio](diagrams/hot-tub-electrical-v2.drawio) (v2, same facts, swimlane layout with legend) — open either in [diagrams.net](https://app.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:

+ | |

+ 1-Wire GPIO4| |GPIO22 / GPIO23

+ | |

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

+ | 5 DS18B20 | |

+ | probes: | +-----------+

+ | 4 tub + | | AC Switch |

+ | 1 hot-in | | Modules |

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

+ |

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

+ | |

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

+ | Heat Circ Pump| | Filter Pump |

+

+ [FUTURE, not installed] Low-water float switch -----> GPIO17

+### Temperature Probes — Direct Pi 1-Wire (shipped design)

+- **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](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](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:

+

+```text

+DS18B20 wire Pi connection

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

+Red / VCC 3.3V

+Black / GND Ground

+Yellow / Data GPIO4 (BCM), 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. 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:

+

+Illustrative hub-to-Pi message format (not the actual `temps:latest` schema the shipped daemon publishes — see [src/temp/README.md](src/temp/README.md) for that):

+### 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:

+Recommended mounting (once installed):

+| | Raspberry Pi | 1-Wire| Probe terminal | |

+| | on standoffs +------>| block (5x DS18B20| |

+| | (GPIO4 + pull-up)| | 4 tub + 1 hot-in)| |

+### 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.

+ Minimum safe line -----[ float switch ]---- <-- FUTURE, not installed

+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

+Suggested DS18B20 bus wiring (direct to the Pi, no sensor hub):

+Function Pi connection

+DS18B20 data bus (x5) GPIO4 (BCM)

+For 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.

+4. Mount the Raspberry Pi and terminal blocks.

+5. 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-temps` can learn each probe's role — see [src/temp/INSTALL.md](src/temp/INSTALL.md).

+6. *(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.

+7. Connect relay control inputs.

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

+9. 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.

+10. Test with water before using heat.

+11. Test heating under supervision.

+- HOT WATER INPUT TEMP

+- LOW WATER SWITCH, once installed (FUTURE — not currently part of the build)

+- *(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.

+- Optionally stop heat if the flow switch says water is not moving (also not installed today).

+- 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-temps` daemon (shipped in `src/temp/`), which reads the probes, learns probe roles during install, and publishes average temperature, individual readings, and failed probes to Redis.

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

+### Phase 3: Safety Sensors — FUTURE, not yet built

+Add, when this hardware is built:

+- Low-water float switch (not installed today; `src/control/safety.py` has a TODO hook for it).

+- Optional flow switch (not installed today).

+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.

+- **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.

+**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.

+2. **Sensors are read-only.** The Temperature Daemon owns the Pi's own 1-Wire interface (direct GPIO4, no separate sensor-hub microcontroller — see [hardware-setup.md](hardware-setup.md)). Nothing else bit-bangs the DS18B20 bus.

+| Float / flow inputs (FUTURE, | | |

+| not installed) | | |

+- Five DS18B20 probes directly on the Pi's own 1-Wire bus (`w1-gpio` overlay, GPIO4) — 4 tub probes + 1 hot-water-input probe. No separate microcontroller sensor hub is used in the shipped design.

+| GPIO inputs | **FUTURE, not installed today:** low-water float (GPIO17), optional flow switch (GPIO27) — see [hardware-setup.md](hardware-setup.md#water-level--dry-run-protection--future-concern-not-installed). `src/control/safety.py` has a TODO hook only; water level is presumed adequate for now. |

+- *(Future — not implemented; no float hardware installed.)* No heat if low-water float indicates dry/low. Water level is presumed adequate today.

+- *(Future — not implemented.)* Optional: no heat if flow switch says no flow while heat pump should be running.

+- *(Future — not installed today.)* Float/flow inputs, once added, would use internal pull-ups; treat open/closed polarity in config.

+| DS18B20 bus (5 probes, direct Pi 1-Wire, GPIO4) | Temperature Daemon | Exclusive; no sensor hub in shipped design |

+| Float / flow GPIO | Control Daemon | **FUTURE** — not installed; would be read in safety path once added |

+### Low water while heating — FUTURE, not implemented today

+

+No float switch hardware is installed, and `src/control/safety.py` only has a TODO hook for it — this scenario describes the planned behavior once that hardware exists, not current behavior. Today, water level is presumed adequate in software.

+PYTHONPATH=. python3 -m control --no-gpio # Redis live, GPIO faked (stack test with temp_sim + web)

+ "--no-gpio",

+ action="store_true",

+ help="Do not drive relays; still connect to Redis (for stack testing)",

+ )

+ parser.add_argument(

+ gpio_dry_run = args.no_gpio

+ snapshot = run_once(cfg, dry_run=args.dry_run, gpio_dry_run=gpio_dry_run)

+ run_loop(cfg, dry_run=args.dry_run, gpio_dry_run=gpio_dry_run)

+ def __init__(

+ self,

+ cfg: ControlConfig,

+ *,

+ dry_run: bool = False,

+ gpio_dry_run: bool = False,

+ ) -> None:

+ self.relays = RelayOutputs(cfg.gpio, dry_run=dry_run or gpio_dry_run)

+ gpio_dry_run: bool = False,

+ eng = engine or ControlEngine(cfg, dry_run=dry_run, gpio_dry_run=gpio_dry_run)

+def run_loop(

+ cfg: ControlConfig,

+ *,

+ dry_run: bool = False,

+ gpio_dry_run: bool = False,

+) -> None:

+ logger.info("Control daemon starting (dry_run=%s gpio_dry_run=%s)", dry_run, gpio_dry_run)

+ engine = ControlEngine(cfg, dry_run=dry_run, gpio_dry_run=gpio_dry_run)

+ ignore_target=True,

+ state.heat_pump = "off"

+ logger.info("backflush aborted by safety; heat_mode -> sleep")

+ state.heat_mode = "sleep"

+ ignore_target: bool = False,

+ if not ignore_target and state.tub_avg_f >= state.target_f:

+ def test_backflush_completes_when_at_or_above_target(self) -> None:

+ state = ControlState(heat_mode="backflush", target_f=102.0)

+ ctx = FsmContext()

+ reading = _reading(105.0)

+ tick_heat(state, ctx, self.cfg, reading)

+ self.assertEqual(state.heat_phase, "backflush")

+ self.assertEqual(state.heat_pump, "on")

+ tick_heat(state, ctx, self.cfg, reading)

+ self.assertEqual(state.heat_mode, "sleep")

+ self.assertEqual(state.heat_pump, "off")

+

+ def test_backflush_safety_trip_reverts_to_sleep(self) -> None:

+ state = ControlState(heat_mode="backflush", target_f=102.0)

+ ctx = FsmContext()

+ tick_heat(state, ctx, self.cfg, _reading(90.0))

+ self.assertEqual(state.heat_phase, "backflush")

+ self.assertEqual(state.heat_pump, "on")

+ tick_heat(state, ctx, self.cfg, None)

+ self.assertEqual(state.heat_mode, "sleep")

+ self.assertEqual(state.heat_pump, "off")

+ self.assertEqual(state.heat_phase, "error_safety")

+ tick_heat(state, ctx, self.cfg, None)

+ self.assertEqual(state.heat_pump, "off")

+ self.assertNotEqual(state.heat_mode, "backflush")

+

+# Health Daemon Overview

+

+## Overview

+

+The purpose of this daemon is to monitor the health of all of the other services and translate them into signals via 3 physical LED lights. There are 3 lights this will control:

+

+- Temp:

+ - Off - No power, completely disconnected

+ - Red - Daemon reporting an error

+ - Orange, Solid - Daemon reporting a warning

+ - Orange, slow blinking - No temp sensors connected

+ - Orange, rapid blinking - Some temp sensors connected

+ - Green - Temp daemon reporting temps across all sensors

+- Control:

+ - Off - No power, completely disconnected

+ - Red - Daemon reporting an error

+ - Orange - Daemon reporting a warning

+ - Green - Control daemon working properly

+- Web:

+ - Off - No power, completely disconnected

+ - Red - Daemon reporting an error

+ - Warning - Daemon reporting a warning

+ - Green - Web interface up and working properly

+

+Health for each service should be monitored in the following ways:

+

+- Temp - Read Redis health state and subscribe to temp events

+ - if there are no temp events within the last 10 seconds, set LED to red

+ - if there is an error reported, set LED to red

+ - if there is a warning reported, set LED to orange

+ - use the sensor-connected logic above in the case that any sensors are not listed

+ - otherwise, set LED to green

+- Control - Read control health status from redis. Health should indicate:

+ - Healthy - Green LED

+ - Warning reported - Orange LED

+ - Error reported - Red LED

+ - Any health status timestamp older than 10 seconds - Orange LED

+ - Any health status timestamp older than 1 minute - Red LED

+- Web

+ - Http request to API health endpoint every 5 seconds

+ - Healthy - Green LED

+ - Warning reported - Orange LED

+ - Error reported - Red LED

+ - Http request to index every 5 seconds

+ - On 2xx status - Green LED

+ - On error status - Red LED

+ - on response lasting longer than 1 second - Orange LED

+**Preferred (with web UI):** Open **Diagnostic → Sensor Setup** on the hot tub web interface (`hot-tub-web` service). The wizard calls `temps.command` at runtime; you do not need to edit `setup_mode` or restart the daemon.

+

+**Manual / headless:**

+

+ "roles": { "hot_in": 112.0, "tub1": 101.2, "tub2": 101.0, "tub3": null, "tub4": 100.9 },

+"""Handle temps.command payloads (runtime sensor setup)."""

+

+from __future__ import annotations

+

+import logging

+from typing import Any

+

+from .config import TempConfig

+from .runtime import TempRuntime

+from .identity import backup_probe_map, clear_probe_map, restore_probe_map

+

+logger = logging.getLogger("hot_tub.temp")

+

+

+class TempCommandError(ValueError):

+ pass

+

+

+def apply_temp_command(

+ cfg: TempConfig,

+ runtime: TempRuntime,

+ envelope: dict[str, Any],

+) -> None:

+ op = envelope.get("op")

+ if not op or not isinstance(op, str):

+ raise TempCommandError("missing or invalid op")

+

+ path = cfg.probe_map_path

+

+ if op == "setup_start":

+ backup_probe_map(path)

+ clear_probe_map(path)

+ runtime.setup_mode_override = True

+ runtime.setup_active = True

+ logger.info("sensor setup started (probe map cleared, backup saved)")

+ return

+

+ if op == "setup_finish":

+ if runtime.last_setup_state != "ready":

+ raise TempCommandError(

+ f"setup_finish requires setup_state ready (got {runtime.last_setup_state!r})"

+ )

+ runtime.setup_mode_override = False

+ runtime.setup_active = False

+ logger.info("sensor setup finished")

+ return

+

+ if op == "setup_cancel":

+ restore_probe_map(path)

+ runtime.setup_mode_override = False

+ runtime.setup_active = False

+ logger.info("sensor setup cancelled (probe map restored)")

+ return

+

+ raise TempCommandError(f"unknown op: {op!r}")

+

+

+def parse_command_message(raw: str) -> dict[str, Any]:

+ import json

+

+ try:

+ data = json.loads(raw)

+ except json.JSONDecodeError as exc:

+ raise TempCommandError("invalid JSON") from exc

+ if not isinstance(data, dict):

+ raise TempCommandError("command must be a JSON object")

+ return data

+from .commands import TempCommandError, apply_temp_command, parse_command_message

+ role_readings,

+from .redis_out import CHAN_COMMAND, RedisPublisher

+from .runtime import TempRuntime