Temperature Daemon — Installation (Raspberry Pi)

Install the temperature daemon on the Pi 3 controller. Design details: README.md.

Prerequisites

• Raspberry Pi OS with Python 3
• DS18B20 probes wired to 1-Wire (GPIO4 default), 4.7 kΩ pull-up to 3.3 V
• Two probe bundles: 1 hot-water input, 4 tub water (see README teach-in)
• Network not required for the daemon itself; Redis runs locally

1. Enable 1-Wire

Add to boot config (Pi OS often uses /boot/firmware/config.txt; older images use /boot/config.txt):

dtoverlay=w1-gpio

Reboot, then verify:

ls /sys/bus/w1/devices/28-*
python3 /path/to/hot-tub/src/read_temps.py

2. Install service

From the hot-tub repository on the Pi:

cd /path/to/hot-tub
sudo deploy/temp/install.sh

Optional: install from a fixed path:

sudo INSTALL_ROOT=/opt/hot-tub deploy/temp/install.sh

The script installs redis-server, python3-redis, user hot-tub, config under /etc/hot-tub/, systemd unit hot-tub-temps, and logrotate for /var/log/hot-tub/temp.log.

3. Guided probe teach-in

ROM ids are learned once and stored in /etc/hot-tub/temp-probes.json.

Recommended order

1. Disconnect both M12 bundles.
2. Connect hot-in bundle only (1 probe).

3. Run teach-in (either stop the service and run once, or set "setup_mode": true in /etc/hot-tub/temp.json and restart):

   sudo systemctl stop hot-tub-temps
   cd /path/to/hot-tub/src
   sudo PYTHONPATH=. python3 -m temp --config /etc/hot-tub/temp.json --setup --once \
     --devices-path /sys/bus/w1/devices

   Confirm log or Redis shows hot-in learned (setup_state moves toward need_water).

4. Connect water bundle only (4 probes), or connect both if hot-in id is already stored.

   sudo PYTHONPATH=. python3 -m temp --config /etc/hot-tub/temp.json --setup --once

5. Set "setup_mode": false in /etc/hot-tub/temp.json when setup_state is ready.

6. Start the service:

   sudo systemctl start hot-tub-temps

Failure: If all 5 probes are connected but the map file is empty, the daemon publishes need_reinstall. Clear the map and repeat teach-in one bundle at a time:

sudo rm /etc/hot-tub/temp-probes.json

4. Verify

systemctl status hot-tub-temps
tail -f /var/log/hot-tub/temp.log
redis-cli GET temps:latest
redis-cli GET temps:setup
redis-cli GET health:temps
redis-cli SUBSCRIBE temps.reading

Expect updates about every 5 seconds (config interval_s).

5. Development (off the Pi)

cd src
PYTHONPATH=. python3 -m temp --dry-run --setup --once --devices-path /path/to/fake/w1
python3 -m unittest temp.tests.test_identity temp.tests.test_reader -v

Dry-run writes to /tmp/hot-tub-temp.log when the configured log path is under /var.

File locations

Path	Purpose
/etc/hot-tub/temp.json	Daemon config
/etc/hot-tub/temp-probes.json	Learned probe ids
/var/log/hot-tub/temp.log	Application log
/etc/systemd/system/hot-tub-temps.service	systemd unit
/etc/logrotate.d/hot-tub-temp	Log rotation

Uninstall

sudo systemctl disable --now hot-tub-temps
sudo rm /etc/systemd/system/hot-tub-temps.service
sudo systemctl daemon-reload

Config and probe map under /etc/hot-tub/ are left in place unless you remove them manually.