Add temperature daemon, Pi deploy assets, and temp_sim diagnostic tool. Implements Redis-backed DS18B20 polling with probe teach-in, systemd install, and a manual simulator for testing Control without hardware. Co-authored-by: Cursor <cursoragent@cursor.com>

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

+ weekly

+ rotate 8

+ compress

+ delaycompress

+ missingok

+ notifempty

+ copytruncate

+}

+d /var/log/hot-tub 0755 hot-tub hot-tub -

+d /etc/hot-tub 0755 root root -

+d /var/lib/hot-tub 0755 hot-tub hot-tub -

+[Unit]

+Description=Hot Tub Temperature Daemon

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

+Wants=network-online.target

+Documentation=file://INSTALL.md

+

+[Service]

+Type=simple

+User=hot-tub

+Group=hot-tub

+Environment=PYTHONPATH=__INSTALL_ROOT__/src

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

+Restart=on-failure

+RestartSec=5

+

+[Install]

+WantedBy=multi-user.target

+#!/usr/bin/env bash

+# Install hot-tub temperature daemon 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

+

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

+export DEBIAN_FRONTEND=noninteractive

+apt-get update -qq

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

+

+echo "==> Creating 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 "==> Installing tmpfiles, log directory, config paths..."

+install -m 0644 "${SCRIPT_DIR}/hot-tub-temp.tmpfiles.conf" /etc/tmpfiles.d/hot-tub-temp.conf

+systemd-tmpfiles --create /etc/tmpfiles.d/hot-tub-temp.conf

+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/temp.json ]]; then

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

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

+else

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

+fi

+

+chown -R hot-tub:hot-tub "${INSTALL_ROOT}/src/temp" 2>/dev/null || true

+

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

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

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

+

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

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

+

+echo "==> Enabling redis and hot-tub-temps..."

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

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

+

+echo ""

+echo "Installation complete."

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

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

+echo " Probe map: /etc/hot-tub/temp-probes.json (created during teach-in)"

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

+echo ""

+echo "1-Wire: ensure boot config contains: dtoverlay=w1-gpio"

+echo " (Raspberry Pi OS: /boot/firmware/config.txt or /boot/config.txt)"

+echo " Reboot after enabling, then verify: ls /sys/bus/w1/devices/28-*"

+echo ""

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

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

+echo "Redis: redis-cli GET temps:latest"

+# Temperature Daemon — Installation (Raspberry Pi)

+

+Install the temperature daemon on the Pi 3 controller. Design details: [README.md](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`):

+

+```text

+dtoverlay=w1-gpio

+```

+

+Reboot, then verify:

+

+```bash

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

+

+```bash

+cd /path/to/hot-tub

+sudo deploy/temp/install.sh

+```

+

+Optional: install from a fixed path:

+

+```bash

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

+

+ ```bash

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

+

+ ```bash

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

+

+ ```bash

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

+

+```bash

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

+```

+

+## 4. Verify

+

+```bash

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

+

+```bash

+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

+

+```bash

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

+**Pi installation:** [INSTALL.md](INSTALL.md)

+

+**Diagnostic simulator (no hardware):** [../temp_sim/README.md](../temp_sim/README.md) — manual `python -m temp_sim`; stop `hot-tub-temps` first.

+

+"""Hot tub temperature daemon — DS18B20 polling, probe identity, Redis publish."""

+

+__version__ = "0.1.0"

+"""CLI entry: python -m temp"""

+

+from __future__ import annotations

+

+import argparse

+import json

+import sys

+from pathlib import Path

+

+from .config import load_config

+from .daemon import run_loop, run_once

+from .logging_setup import setup_logging

+

+

+def _path_writable(dir_path: Path) -> bool:

+ try:

+ dir_path.mkdir(parents=True, exist_ok=True)

+ test = dir_path / ".write_test"

+ test.write_text("")

+ test.unlink()

+ return True

+ except OSError:

+ return False

+

+

+def main() -> None:

+ parser = argparse.ArgumentParser(description="Hot tub temperature daemon")

+ parser.add_argument(

+ "--config",

+ type=Path,

+ default=Path("/etc/hot-tub/temp.json"),

+ help="Path to JSON config (default: /etc/hot-tub/temp.json)",

+ )

+ parser.add_argument(

+ "--once",

+ action="store_true",

+ help="Read once, publish/log once, exit",

+ )

+ parser.add_argument(

+ "--dry-run",

+ action="store_true",

+ help="No Redis; log/print only",

+ )

+ parser.add_argument(

+ "--setup",

+ action="store_true",

+ help="Enable setup_mode for this run (probe teach-in)",

+ )

+ parser.add_argument(

+ "--devices-path",

+ type=Path,

+ default=None,

+ help="Override 1-Wire devices path from config",

+ )

+ parser.add_argument(

+ "-v",

+ "--verbose",

+ action="store_true",

+ help="Debug logging",

+ )

+ args = parser.parse_args()

+

+ cfg_path = args.config if args.config.exists() else None

+ if cfg_path is None and not args.config.exists():

+ # Fall back to example next to package for dev

+ dev_example = Path(__file__).resolve().parent / "config.example.json"

+ cfg_path = dev_example if dev_example.exists() else None

+

+ cfg = load_config(cfg_path)

+ if args.setup:

+ cfg.setup_mode = True

+ if args.devices_path is not None:

+ cfg.devices_path = args.devices_path

+

+ if args.dry_run or not _path_writable(cfg.log_path.parent):

+ cfg.log_path = Path("/tmp/hot-tub-temp.log")

+ if args.dry_run or not _path_writable(cfg.probe_map_path.parent):

+ cfg.probe_map_path = Path("/tmp/hot-tub-temp-probes.json")

+

+ setup_logging(cfg.log_path, verbose=args.verbose)

+

+ if args.once:

+ reading = run_once(cfg, dry_run=args.dry_run)

+ print(json.dumps(reading, indent=2))

+ return

+

+ run_loop(cfg, dry_run=args.dry_run)

+

+

+if __name__ == "__main__":

+ try:

+ main()

+ except KeyboardInterrupt:

+ sys.exit(0)

+{

+ "interval_s": 5,

+ "devices_path": "/sys/bus/w1/devices",

+ "redis_url": "redis://127.0.0.1:6379/0",

+ "log_path": "/var/log/hot-tub/temp.log",

+ "probe_map_path": "/etc/hot-tub/temp-probes.json",

+ "setup_mode": false

+}

+"""Load temperature daemon configuration."""

+

+from __future__ import annotations

+

+import json

+from dataclasses import dataclass

+from pathlib import Path

+

+from .reader import DEFAULT_DEVICES_PATH

+

+

+@dataclass

+class TempConfig:

+ interval_s: float = 5.0

+ devices_path: Path = DEFAULT_DEVICES_PATH

+ redis_url: str = "redis://127.0.0.1:6379/0"

+ log_path: Path = Path("/var/log/hot-tub/temp.log")

+ probe_map_path: Path = Path("/etc/hot-tub/temp-probes.json")

+ setup_mode: bool = False

+

+

+def load_config(path: Path | None) -> TempConfig:

+ cfg = TempConfig()

+ if path is None or not path.exists():

+ return cfg

+ data = json.loads(path.read_text())

+ if "interval_s" in data:

+ cfg.interval_s = float(data["interval_s"])

+ if "devices_path" in data:

+ cfg.devices_path = Path(data["devices_path"])

+ if "redis_url" in data:

+ cfg.redis_url = str(data["redis_url"])

+ if "log_path" in data:

+ cfg.log_path = Path(data["log_path"])

+ if "probe_map_path" in data:

+ cfg.probe_map_path = Path(data["probe_map_path"])

+ if "setup_mode" in data:

+ cfg.setup_mode = bool(data["setup_mode"])

+ return cfg

+"""Temperature daemon main loop."""

+

+from __future__ import annotations

+

+import logging

+import os

+import signal

+import time

+from datetime import datetime, timezone

+from typing import Any

+

+from .config import TempConfig

+from .identity import (

+ TUB_COUNT,

+ classify_readings,

+ evaluate_identity,

+ load_probe_map,

+ save_probe_map,

+)

+from .reader import read_all_f

+from .redis_out import RedisPublisher

+

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

+

+_stop = False

+

+

+def _handle_signal(signum: int, _frame: object) -> None:

+ global _stop

+ logger.info("Received signal %s, shutting down", signum)

+ _stop = True

+

+

+def _utc_now() -> str:

+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

+

+

+def _health_status(setup_state: str, ok_count: int, visible_count: int) -> str:

+ if setup_state == "need_reinstall":

+ return "error"

+ if setup_state in ("need_hot_in", "need_water"):

+ return "degraded"

+ if visible_count == 0:

+ return "error"

+ if ok_count < TUB_COUNT:

+ return "degraded"

+ return "ok"

+

+

+def build_sample(

+ cfg: TempConfig,

+) -> tuple[dict[str, Any], Any, dict[str, Any], dict[str, Any]]:

+ from pathlib import Path

+

+ path = cfg.probe_map_path

+ setup_mode = cfg.setup_mode

+ probes_f = read_all_f(cfg.devices_path)

+ visible = list(probes_f.keys())

+ pmap = load_probe_map(path)

+ identity = evaluate_identity(visible, pmap, setup_mode=setup_mode)

+ if identity.map_changed:

+ save_probe_map(path, identity.probe_map)

+ logger.info("Probe map updated: %s", identity.detail)

+

+ labeled, tub_avg, hot_in_f, ok_count, fail_count, spread = classify_readings(

+ probes_f, identity.probe_map

+ )

+

+ reading: dict[str, Any] = {

+ "ts": _utc_now(),

+ "setup_state": identity.setup_state,

+ "probes": labeled,

+ "tub_avg_f": tub_avg,

+ "hot_in_f": hot_in_f,

+ "outdoor_f": None,

+ "ok_count": ok_count,

+ "fail_count": fail_count,

+ "spread_f": spread,

+ }

+

+ setup_payload = {

+ "ts": reading["ts"],

+ "state": identity.setup_state,

+ "detail": identity.detail,

+ "visible_ids": identity.visible_ids,

+ }

+

+ health_payload = {

+ "service": "temps",

+ "ts": reading["ts"],

+ "status": _health_status(identity.setup_state, ok_count, len(visible)),

+ "detail": identity.detail,

+ "pid": os.getpid(),

+ }

+

+ return reading, identity, setup_payload, health_payload

+

+

+def run_once(

+ cfg: TempConfig,

+ *,

+ dry_run: bool = False,

+ redis_pub: RedisPublisher | None = None,

+) -> dict[str, Any]:

+ reading, identity, setup_payload, health_payload = build_sample(cfg)

+ logger.info(

+ "sample setup=%s tub_avg=%s hot_in=%s ok=%s/%s visible=%s",

+ identity.setup_state,

+ reading["tub_avg_f"],

+ reading["hot_in_f"],

+ reading["ok_count"],

+ TUB_COUNT,

+ len(identity.visible_ids),

+ )

+ if dry_run:

+ return reading

+ pub = redis_pub or RedisPublisher(cfg.redis_url)

+ try:

+ pub.publish_reading(reading)

+ pub.publish_setup(setup_payload)

+ pub.publish_health(health_payload)

+ finally:

+ if redis_pub is None:

+ pub.close()

+ return reading

+

+

+def run_loop(cfg: TempConfig, *, dry_run: bool = False) -> None:

+ global _stop

+ _stop = False

+ signal.signal(signal.SIGTERM, _handle_signal)

+ signal.signal(signal.SIGINT, _handle_signal)

+

+ logger.info(

+ "Temperature daemon starting (dry_run=%s interval=%ss setup_mode=%s)",

+ dry_run,

+ cfg.interval_s,

+ cfg.setup_mode,

+ )

+

+ redis_pub: RedisPublisher | None = None

+ if not dry_run:

+ redis_pub = RedisPublisher(cfg.redis_url)

+

+ try:

+ while not _stop:

+ loop_start = time.monotonic()

+ try:

+ run_once(cfg, dry_run=dry_run, redis_pub=redis_pub)

+ except Exception:

+ logger.exception("Error in poll cycle")

+ elapsed = time.monotonic() - loop_start

+ sleep_s = max(0.0, cfg.interval_s - elapsed)

+ if sleep_s > 0 and not _stop:

+ time.sleep(sleep_s)

+ finally:

+ if redis_pub is not None:

+ redis_pub.close()

+ logger.info("Temperature daemon stopped")

+"""Probe identity: learn hot-in vs tub ROM ids, setup state machine."""

+

+from __future__ import annotations

+

+import json

+from dataclasses import dataclass, field

+from pathlib import Path

+from typing import Literal

+

+SetupState = Literal["need_hot_in", "need_water", "ready", "need_reinstall"]

+

+TUB_COUNT = 4

+

+

+@dataclass

+class ProbeMap:

+ hot_in: str | None = None

+ tub: list[str] = field(default_factory=list)

+

+ def is_complete(self) -> bool:

+ return self.hot_in is not None and len(self.tub) == TUB_COUNT

+

+ def known_ids(self) -> set[str]:

+ ids: set[str] = set()

+ if self.hot_in:

+ ids.add(self.hot_in)

+ ids.update(self.tub)

+ return ids

+

+

+def load_probe_map(path: Path) -> ProbeMap:

+ if not path.exists():

+ return ProbeMap()

+ try:

+ data = json.loads(path.read_text())

+ except (OSError, json.JSONDecodeError):

+ return ProbeMap()

+ hot_in = data.get("hot_in")

+ tub = data.get("tub") or []

+ if not isinstance(hot_in, str) and hot_in is not None:

+ hot_in = None

+ if not isinstance(tub, list):

+ tub = []

+ tub = [x for x in tub if isinstance(x, str)]

+ return ProbeMap(hot_in=hot_in, tub=tub)

+

+

+def save_probe_map(path: Path, probe_map: ProbeMap) -> None:

+ path.parent.mkdir(parents=True, exist_ok=True)

+ payload = {"hot_in": probe_map.hot_in, "tub": sorted(probe_map.tub)}

+ tmp = path.with_suffix(path.suffix + ".tmp")

+ tmp.write_text(json.dumps(payload, indent=2) + "\n")

+ tmp.replace(path)

+

+

+@dataclass

+class IdentityResult:

+ setup_state: SetupState

+ probe_map: ProbeMap

+ map_changed: bool

+ detail: str

+ visible_ids: list[str]

+

+

+def _try_learn(

+ visible: list[str],

+ pmap: ProbeMap,

+ *,

+ setup_mode: bool,

+) -> tuple[ProbeMap, bool, str]:

+ """Return updated map, whether it changed, and a detail string."""

+ n = len(visible)

+ vis = set(visible)

+ changed = False

+ detail = ""

+

+ if pmap.is_complete():

+ return pmap, False, detail

+

+ learning = setup_mode or not pmap.is_complete()

+ if not learning:

+ return pmap, False, detail

+

+ hot_known = pmap.hot_in is not None

+ tub_complete = len(pmap.tub) == TUB_COUNT

+

+ if not hot_known and n == 1:

+ pmap = ProbeMap(hot_in=visible[0], tub=list(pmap.tub))

+ return pmap, True, f"Learned hot_in={visible[0]}"

+

+ if not tub_complete and not hot_known and n == TUB_COUNT and setup_mode:

+ pmap = ProbeMap(hot_in=pmap.hot_in, tub=sorted(visible))

+ return pmap, True, f"Learned {TUB_COUNT} tub probes"

+

+ if hot_known and not tub_complete and n == TUB_COUNT + 1:

+ tub_ids = sorted(vis - {pmap.hot_in})

+ if len(tub_ids) == TUB_COUNT:

+ pmap = ProbeMap(hot_in=pmap.hot_in, tub=tub_ids)

+ return pmap, True, "Derived tub ids (hot_in already known)"

+

+ if tub_complete and not hot_known and n == TUB_COUNT + 1:

+ unknown = vis - set(pmap.tub)

+ if len(unknown) == 1:

+ hid = next(iter(unknown))

+ pmap = ProbeMap(hot_in=hid, tub=list(pmap.tub))

+ return pmap, True, f"Derived hot_in={hid}"

+

+ if hot_known and not tub_complete and n == TUB_COUNT and pmap.hot_in not in vis:

+ pmap = ProbeMap(hot_in=pmap.hot_in, tub=sorted(visible))

+ return pmap, True, "Learned 4 tub probes (water bundle alone)"

+

+ return pmap, changed, detail

+

+

+def _compute_setup_state(visible: list[str], pmap: ProbeMap) -> SetupState:

+ n = len(visible)

+ if n == TUB_COUNT + 1 and not pmap.hot_in and len(pmap.tub) == 0:

+ return "need_reinstall"

+ if pmap.is_complete():

+ return "ready"

+ if pmap.hot_in and len(pmap.tub) < TUB_COUNT:

+ return "need_water"

+ if len(pmap.tub) == TUB_COUNT and not pmap.hot_in:

+ return "need_hot_in"

+ if not pmap.hot_in and not pmap.tub:

+ if n >= TUB_COUNT + 1:

+ return "need_reinstall"

+ if n == TUB_COUNT:

+ return "need_hot_in"

+ if n == 1:

+ return "need_hot_in"

+ return "need_hot_in"

+ return "need_water"

+

+

+def evaluate_identity(

+ visible_ids: list[str],

+ probe_map: ProbeMap,

+ *,

+ setup_mode: bool,

+) -> IdentityResult:

+ visible = sorted(set(visible_ids))

+ pmap, changed, detail = _try_learn(visible, probe_map, setup_mode=setup_mode)

+ state = _compute_setup_state(visible, pmap)

+ if state == "need_reinstall" and not detail:

+ detail = "All 5 probes visible but no stored ids; connect bundles one at a time"

+ if not detail:

+ detail = state

+ return IdentityResult(

+ setup_state=state,

+ probe_map=pmap,

+ map_changed=changed,

+ detail=detail,

+ visible_ids=visible,

+ )

+

+

+def classify_readings(

+ probes_f: dict[str, float | None],

+ probe_map: ProbeMap,

+) -> tuple[dict[str, float | None], float | None, float | None, int, int, float | None]:

+ """Return labeled probes, tub_avg, hot_in_f, ok/fail counts, spread."""

+ labeled: dict[str, float | None] = dict(probes_f)

+ tub_temps: list[float] = []

+ hot_in_f: float | None = None

+

+ tub_set = set(probe_map.tub)

+ for device_id, temp_f in probes_f.items():

+ if device_id == probe_map.hot_in and temp_f is not None:

+ hot_in_f = temp_f

+ elif device_id in tub_set and temp_f is not None:

+ tub_temps.append(temp_f)

+

+ ok_count = len(tub_temps)

+ fail_count = max(0, len(probe_map.tub) - ok_count) if probe_map.tub else 0

+ tub_avg: float | None = sum(tub_temps) / len(tub_temps) if tub_temps else None

+ spread: float | None = None

+ if len(tub_temps) >= 2:

+ spread = max(tub_temps) - min(tub_temps)

+

+ return labeled, tub_avg, hot_in_f, ok_count, fail_count, spread

+"""File logging for the temperature daemon."""

+

+from __future__ import annotations

+

+import logging

+from pathlib import Path

+

+

+def setup_logging(log_path: Path, *, verbose: bool = False) -> logging.Logger:

+ log_path.parent.mkdir(parents=True, exist_ok=True)

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

+ logger.setLevel(logging.DEBUG if verbose else logging.INFO)

+ logger.handlers.clear()

+

+ handler = logging.FileHandler(log_path, encoding="utf-8")

+ handler.setFormatter(

+ logging.Formatter("%(asctime)s %(levelname)s %(message)s", datefmt="%Y-%m-%d %H:%M:%S")

+ )

+ logger.addHandler(handler)

+ return logger

+"""Read DS18B20 devices from Linux 1-Wire sysfs."""

+

+from __future__ import annotations

+

+from pathlib import Path

+

+DEFAULT_DEVICES_PATH = Path("/sys/bus/w1/devices")

+

+

+def c_to_f(temp_c: float) -> float:

+ return temp_c * 9.0 / 5.0 + 32.0

+

+

+def find_devices(devices_path: Path) -> list[str]:

+ if not devices_path.exists():

+ return []

+ return sorted(p.name for p in devices_path.iterdir() if p.name.startswith("28-"))

+

+

+def read_temp_c(devices_path: Path, device_id: str) -> float | None:

+ """Return temperature in Celsius, or None if the read/parse fails."""

+ slave_file = devices_path / device_id / "w1_slave"

+ try:

+ text = slave_file.read_text()

+ except OSError:

+ return None

+

+ lines = text.strip().splitlines()

+ if len(lines) < 2 or "YES" not in lines[0]:

+ return None

+

+ marker = "t="

+ if marker not in lines[1]:

+ return None

+

+ try:

+ milli_c = int(lines[1].split(marker, 1)[1])

+ except ValueError:

+ return None

+

+ if milli_c == 85000:

+ return None

+

+ return milli_c / 1000.0

+

+

+def read_all_f(devices_path: Path) -> dict[str, float | None]:

+ """Return device_id -> °F (or None on failure)."""

+ out: dict[str, float | None] = {}

+ for device_id in find_devices(devices_path):

+ temp_c = read_temp_c(devices_path, device_id)

+ out[device_id] = None if temp_c is None else c_to_f(temp_c)

+ return out

+"""Publish temperature readings, setup, and health to Redis."""

+

+from __future__ import annotations

+

+import json

+import logging

+import time

+from typing import Any

+

+try:

+ import redis

+except ImportError:

+ redis = None # type: ignore[assignment]

+

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

+

+KEY_LATEST = "temps:latest"

+CHAN_READING = "temps.reading"

+KEY_SETUP = "temps:setup"

+CHAN_SETUP = "temps.setup"

+KEY_HEALTH = "health:temps"

+CHAN_HEALTH = "health.temps"

+

+

+class RedisPublisher:

+ def __init__(self, redis_url: str) -> None:

+ if redis is None:

+ raise RuntimeError("redis package not installed (apt: python3-redis)")

+ self._url = redis_url

+ self._client: redis.Redis | None = None

+ self._last_setup_json: str | None = None

+ self._backoff_s = 1.0

+

+ def _connect(self) -> redis.Redis:

+ if self._client is None:

+ self._client = redis.from_url(self._url, decode_responses=True)

+ return self._client

+

+ def _ensure(self) -> redis.Redis | None:

+ try:

+ client = self._connect()

+ client.ping()

+ self._backoff_s = 1.0

+ return client

+ except Exception as exc:

+ logger.warning("Redis unavailable: %s (retry in %.0fs)", exc, self._backoff_s)

+ self._client = None

+ time.sleep(min(self._backoff_s, 30.0))

+ self._backoff_s = min(self._backoff_s * 2, 30.0)

+ return None

+

+ def publish_reading(self, payload: dict[str, Any]) -> bool:

+ client = self._ensure()

+ if client is None:

+ return False

+ body = json.dumps(payload)

+ client.set(KEY_LATEST, body)

+ client.publish(CHAN_READING, body)

+ return True

+

+ def publish_setup(self, payload: dict[str, Any]) -> bool:

+ client = self._ensure()

+ if client is None:

+ return False

+ body = json.dumps(payload)

+ if body == self._last_setup_json:

+ return True

+ self._last_setup_json = body

+ client.set(KEY_SETUP, body)

+ client.publish(CHAN_SETUP, body)

+ return True

+

+ def publish_health(self, payload: dict[str, Any]) -> bool:

+ client = self._ensure()

+ if client is None:

+ return False

+ body = json.dumps(payload)

+ client.set(KEY_HEALTH, body)

+ client.publish(CHAN_HEALTH, body)

+ return True

+

+ def close(self) -> None:

+ if self._client is not None:

+ try:

+ self._client.close()

+ except Exception:

+ pass

+ self._client = None

+"""Unit tests for probe identity teach-in."""

+

+from __future__ import annotations

+

+import tempfile

+import unittest

+from pathlib import Path

+

+from temp.identity import (

+ ProbeMap,

+ evaluate_identity,

+ load_probe_map,

+ save_probe_map,

+)

+

+

+class TestProbeMapPersistence(unittest.TestCase):

+ def test_save_load_roundtrip(self) -> None:

+ with tempfile.TemporaryDirectory() as tmp:

+ path = Path(tmp) / "probes.json"

+ pm = ProbeMap(hot_in="28-h", tub=["28-a", "28-b", "28-c", "28-d"])

+ save_probe_map(path, pm)

+ loaded = load_probe_map(path)

+ self.assertEqual(loaded.hot_in, "28-h")

+ self.assertEqual(sorted(loaded.tub), sorted(pm.tub))

+

+

+class TestEvaluateIdentity(unittest.TestCase):

+ def test_one_probe_learns_hot_in(self) -> None:

+ r = evaluate_identity(["28-hot"], ProbeMap(), setup_mode=True)

+ self.assertTrue(r.map_changed)

+ self.assertEqual(r.probe_map.hot_in, "28-hot")

+ self.assertEqual(r.setup_state, "need_water")

+

+ def test_four_alone_learns_tub_with_setup_mode(self) -> None:

+ ids = [f"28-t{i}" for i in range(4)]

+ r = evaluate_identity(ids, ProbeMap(), setup_mode=True)

+ self.assertTrue(r.map_changed)

+ self.assertEqual(sorted(r.probe_map.tub), sorted(ids))

+ self.assertEqual(r.setup_state, "need_hot_in")

+

+ def test_five_empty_map_need_reinstall(self) -> None:

+ ids = [f"28-x{i}" for i in range(5)]

+ r = evaluate_identity(ids, ProbeMap(), setup_mode=True)

+ self.assertFalse(r.map_changed)

+ self.assertEqual(r.setup_state, "need_reinstall")

+

+ def test_five_derive_tub_when_hot_known(self) -> None:

+ hot = "28-hot"

+ tubs = [f"28-t{i}" for i in range(4)]

+ pm = ProbeMap(hot_in=hot, tub=[])

+ r = evaluate_identity([hot, *tubs], pm, setup_mode=False)

+ self.assertTrue(r.map_changed)

+ self.assertEqual(sorted(r.probe_map.tub), sorted(tubs))

+ self.assertEqual(r.setup_state, "ready")

+

+ def test_five_derive_hot_when_tub_known(self) -> None:

+ hot = "28-hot"

+ tubs = [f"28-t{i}" for i in range(4)]

+ pm = ProbeMap(hot_in=None, tub=tubs)

+ r = evaluate_identity([hot, *tubs], pm, setup_mode=False)

+ self.assertTrue(r.map_changed)

+ self.assertEqual(r.probe_map.hot_in, hot)

+ self.assertEqual(r.setup_state, "ready")

+

+ def test_four_mixed_does_not_mislearn_when_hot_on_bus(self) -> None:

+ hot = "28-hot"

+ pm = ProbeMap(hot_in=hot, tub=[])

+ # hot + 3 tub = 4 devices — must not assign all 4 as tub

+ r = evaluate_identity([hot, "28-t1", "28-t2", "28-t3"], pm, setup_mode=True)

+ self.assertFalse(r.map_changed)

+ self.assertEqual(r.probe_map.tub, [])

+

+ def test_complete_map_no_overwrite_on_single_probe(self) -> None:

+ pm = ProbeMap(hot_in="28-h", tub=[f"28-t{i}" for i in range(4)])

+ r = evaluate_identity(["28-h"], pm, setup_mode=False)

+ self.assertFalse(r.map_changed)

+ self.assertEqual(r.setup_state, "ready")

+

+

+if __name__ == "__main__":

+ unittest.main()

+"""Unit tests for sysfs reader."""

+

+from __future__ import annotations

+

+import tempfile

+import unittest

+from pathlib import Path

+

+from temp.reader import c_to_f, find_devices, read_all_f, read_temp_c

+

+

+GOOD_SLAVE = "a1 01 4b 46 7f ff 0c 10 fe : crc=fe YES\nt=25000\n"

+BAD_SLAVE = "a1 01 4b 46 7f ff 0c 10 fe : crc=fe NO\nt=25000\n"

+

+

+class TestReader(unittest.TestCase):

+ def test_c_to_f(self) -> None:

+ self.assertAlmostEqual(c_to_f(0.0), 32.0)

+ self.assertAlmostEqual(c_to_f(100.0), 212.0)

+

+ def test_read_fake_sysfs(self) -> None:

+ with tempfile.TemporaryDirectory() as tmp:

+ base = Path(tmp)

+ dev = base / "28-000000000001"

+ dev.mkdir()

+ (dev / "w1_slave").write_text(GOOD_SLAVE)

+ self.assertEqual(find_devices(base), ["28-000000000001"])

+ self.assertAlmostEqual(read_temp_c(base, "28-000000000001"), 25.0)

+ all_f = read_all_f(base)

+ self.assertAlmostEqual(all_f["28-000000000001"], 77.0)

+

+ def test_crc_fail(self) -> None:

+ with tempfile.TemporaryDirectory() as tmp:

+ base = Path(tmp)

+ dev = base / "28-000000000002"

+ dev.mkdir()

+ (dev / "w1_slave").write_text(BAD_SLAVE)

+ self.assertIsNone(read_temp_c(base, "28-000000000002"))

+

+

+if __name__ == "__main__":

+ unittest.main()

+# Diagnostic Temperature Simulator (`temp_sim`)

+

+Manual troubleshooting tool that **pretends to be the Temperature Daemon** without reading 1-Wire or GPIO. It publishes the same Redis keys/channels as the real daemon ([`temp/redis_out.py`](../temp/redis_out.py)) so Control, Health, and Web can be tested on a desk or Pi without probes.

+

+## What it is / is not

+

+| Yes | No |

+|---|---|

+| Reads `control:latest` from Redis | Reads DS18B20 / sysfs |

+| Publishes `temps:latest`, `temps.reading`, `temps:setup`, `health:temps`, etc. | Drives relays or GPIO |

+| Prints every tick to stdout | systemd service (run manually only) |

+| Simulates tub + hot-in dynamics from Control heat state | Replaces Control daemon |

+

+**Important:** Stop the real temperature service before running the simulator, or both will fight over `temps:latest`:

+

+```bash

+sudo systemctl stop hot-tub-temps

+```

+

+## Prerequisites

+

+- Redis running locally (`redis-server`)

+- `python3-redis` (Debian: `sudo apt install python3-redis`)

+- For realistic behavior: Control daemon publishing `control:latest`, **or** inject fake control state yourself (below)

+

+## Run

+

+From the repo `src` directory:

+

+```bash

+cd /path/to/hot-tub/src

+PYTHONPATH=. python3 -m temp_sim

+```

+

+Options:

+

+```bash

+PYTHONPATH=. python3 -m temp_sim --interval 2

+PYTHONPATH=. python3 -m temp_sim --redis-url redis://127.0.0.1:6379/0

+```

+

+Each line on stdout shows mode (`HEAT` / `COOL`), Control `heat_phase` / `heat_pump`, simulated `tub` and `hot_in` °F, and Redis publish status. Ctrl+C to exit.

+

+When finished testing, restart the real daemon if needed:

+

+```bash

+sudo systemctl start hot-tub-temps

+```

+

+## Simulated physics

+

+Starting values: **tub average 70 °F**, **hot-in 70 °F**. Step size: **5 °F** per interval (default interval **5 s**).

+

+| Condition | Hot-in | Tub average (each tick) |

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

+| **Heat-up** — `heat_phase` is `startup_1`, `startup_2`, `startup_3`, or `heating`, **and** `heat_pump` is not `off` | Fixed **130 °F** | **+5 °F** (capped at 140 °F) |

+| **Cool-down** — `heat_phase` is `idle`, `error_startup`, or anything else; **or** `heat_pump` is `off`; **or** no `control:latest` | **Matches current tub** | **−5 °F** until floor **70 °F** |

+

+Four fake tub probes in Redis all equal `tub_avg_f`; hot probe equals `hot_in_f`. Setup is always `ready` with stable fake ROM ids (`28-sim-tub1` … `28-sim-hot`).

+

+## Inject Control state (no Control daemon)

+

+Minimal heating example:

+

+```bash

+redis-cli SET control:latest '{"heat_phase":"heating","heat_pump":"on","heat_mode":"maintain","target_f":102}'

+```

+

+Cool / idle example:

+

+```bash

+redis-cli SET control:latest '{"heat_phase":"idle","heat_pump":"off","heat_mode":"sleep","target_f":102}'

+```

+

+Startup attempt (Control checks hot-in rise after ~20 s):

+

+```bash

+redis-cli SET control:latest '{"heat_phase":"startup_1","heat_pump":"on","heat_mode":"maintain","target_f":102}'

+```

+

+Failed startup:

+

+```bash

+redis-cli SET control:latest '{"heat_phase":"error_startup","heat_pump":"off","heat_mode":"maintain","target_f":102}'

+```

+

+Run `temp_sim` in one terminal; change `control:latest` in another and watch stdout / `temps:latest`.

+

+## Verify Redis output

+

+```bash

+redis-cli GET temps:latest

+redis-cli GET health:temps

+redis-cli SUBSCRIBE temps.reading

+```

+

+Health payload includes `"detail": "temp_sim (diagnostic simulator)"` so you can tell it apart from the real daemon.

+

+## Related docs

+

+- Real daemon: [../temp/README.md](../temp/README.md), [../temp/INSTALL.md](../temp/INSTALL.md)

+- Control state fields: [../control/README.md](../control/README.md)

+"""Diagnostic temperature simulator — Redis-only, no hardware."""

+

+__version__ = "0.1.0"

+"""CLI: python -m temp_sim"""

+

+from __future__ import annotations

+

+import argparse

+import sys

+

+from .simulator import run_loop

+

+

+def main() -> None:

+ parser = argparse.ArgumentParser(

+ description="Diagnostic temperature simulator (Redis only, no hardware)"

+ )

+ parser.add_argument(

+ "--interval",

+ type=float,

+ default=5.0,

+ help="Seconds between simulated readings (default: 5)",

+ )

+ parser.add_argument(

+ "--redis-url",

+ default="redis://127.0.0.1:6379/0",

+ help="Redis URL (default: redis://127.0.0.1:6379/0)",

+ )

+ args = parser.parse_args()

+

+ if args.interval <= 0:

+ print("--interval must be > 0", file=sys.stderr)

+ sys.exit(2)

+

+ run_loop(redis_url=args.redis_url, interval_s=args.interval)

+

+

+if __name__ == "__main__":

+ try:

+ main()

+ except KeyboardInterrupt:

+ sys.exit(0)

+"""Simulate tub/hot-in temps from Control state; publish like the real temp daemon."""

+

+from __future__ import annotations

+

+import json

+import os

+import signal

+import time

+from dataclasses import dataclass

+from datetime import datetime, timezone

+from typing import Any

+

+try:

+ import redis

+except ImportError:

+ redis = None # type: ignore[assignment]

+

+from temp.redis_out import RedisPublisher

+

+KEY_CONTROL_LATEST = "control:latest"

+

+DEFAULT_TUB_F = 70.0

+DEFAULT_HOT_F = 70.0

+HOT_ACTIVE_F = 130.0

+STEP_F = 5.0

+TUB_MAX_F = 140.0

+

+TUB_PROBE_IDS = (

+ "28-sim-tub1",

+ "28-sim-tub2",

+ "28-sim-tub3",

+ "28-sim-tub4",

+)

+HOT_PROBE_ID = "28-sim-hot"

+

+HEATING_PHASES = frozenset({"startup_1", "startup_2", "startup_3", "heating"})

+

+_stop = False

+

+

+def _utc_now() -> str:

+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

+

+

+def _handle_signal(signum: int, _frame: object) -> None:

+ global _stop

+ print(f"\nSignal {signum}, stopping.")

+ _stop = True

+

+

+@dataclass

+class SimState:

+ tub_avg_f: float = DEFAULT_TUB_F

+ hot_in_f: float = DEFAULT_HOT_F

+

+

+def fetch_control_state(redis_url: str) -> dict[str, Any] | None:

+ if redis is None:

+ raise RuntimeError("redis package not installed (apt: python3-redis)")

+ client = redis.from_url(redis_url, decode_responses=True)

+ try:

+ raw = client.get(KEY_CONTROL_LATEST)

+ finally:

+ client.close()

+ if not raw:

+ return None

+ try:

+ data = json.loads(raw)

+ except json.JSONDecodeError:

+ return None

+ return data if isinstance(data, dict) else None

+

+

+def should_heat_up(control: dict[str, Any] | None) -> tuple[bool, str, str]:

+ """Return (heat_up, heat_phase, heat_pump) for display."""

+ if control is None:

+ return False, "—", "—"

+ phase = str(control.get("heat_phase") or "idle")

+ pump = str(control.get("heat_pump") or "off")

+ if phase in HEATING_PHASES and pump != "off":

+ return True, phase, pump

+ return False, phase, pump

+

+

+def tick_sim(state: SimState, heat_up: bool) -> None:

+ if heat_up:

+ state.hot_in_f = HOT_ACTIVE_F

+ state.tub_avg_f = min(state.tub_avg_f + STEP_F, TUB_MAX_F)

+ else:

+ state.tub_avg_f = max(DEFAULT_TUB_F, state.tub_avg_f - STEP_F)

+ state.hot_in_f = state.tub_avg_f

+

+

+def build_payloads(state: SimState) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:

+ ts = _utc_now()

+ probes = {pid: state.tub_avg_f for pid in TUB_PROBE_IDS}

+ probes[HOT_PROBE_ID] = state.hot_in_f

+

+ reading = {

+ "ts": ts,

+ "setup_state": "ready",

+ "probes": probes,

+ "tub_avg_f": state.tub_avg_f,

+ "hot_in_f": state.hot_in_f,

+ "outdoor_f": None,

+ "ok_count": 4,

+ "fail_count": 0,

+ "spread_f": 0.0,

+ }

+ setup_payload = {

+ "ts": ts,

+ "state": "ready",

+ "detail": "temp_sim diagnostic simulator",

+ "visible_ids": list(TUB_PROBE_IDS) + [HOT_PROBE_ID],

+ }

+ health_payload = {

+ "service": "temps",

+ "ts": ts,

+ "status": "ok",

+ "detail": "temp_sim (diagnostic simulator)",

+ "pid": os.getpid(),

+ }

+ return reading, setup_payload, health_payload

+

+

+def run_loop(*, redis_url: str, interval_s: float) -> None:

+ global _stop

+ _stop = False

+ signal.signal(signal.SIGTERM, _handle_signal)

+ signal.signal(signal.SIGINT, _handle_signal)

+

+ state = SimState()

+ pub = RedisPublisher(redis_url)

+

+ print(

+ f"temp_sim starting: interval={interval_s}s redis={redis_url} "

+ f"defaults tub={DEFAULT_TUB_F}F hot={DEFAULT_HOT_F}F"

+ )

+ print("Stop with Ctrl+C. Do not run while hot-tub-temps.service is active.\n")

+

+ try:

+ while not _stop:

+ loop_start = time.monotonic()

+ control = fetch_control_state(redis_url)

+ heat_up, phase, pump = should_heat_up(control)

+ mode = "HEAT" if heat_up else "COOL"

+ tick_sim(state, heat_up)

+

+ reading, setup_payload, health_payload = build_payloads(state)

+ ok_read = pub.publish_reading(reading)

+ ok_setup = pub.publish_setup(setup_payload)

+ ok_health = pub.publish_health(health_payload)

+ redis_ok = ok_read and ok_setup and ok_health

+

+ print(

+ f"{reading['ts']} {mode:4} phase={phase:12} pump={pump:3} "

+ f"tub={state.tub_avg_f:5.1f}F hot_in={state.hot_in_f:5.1f}F "

+ f"redis={'OK' if redis_ok else 'FAIL'}"

+ )

+

+ elapsed = time.monotonic() - loop_start

+ sleep_s = max(0.0, interval_s - elapsed)

+ if sleep_s > 0 and not _stop:

+ time.sleep(sleep_s)

+ finally:

+ pub.close()

+ print("temp_sim stopped.")