led-ticker-pool 0.1.0__py3-none-any.whl

led_ticker_pool/__init__.py

@@ -0,0 +1,11 @@
+"""led-ticker-pool: a pool water-temperature monitor widget for led-ticker.
+
+Contributed via the ``led_ticker.plugins`` entry point. The entry-point name
+``pool`` is the plugin namespace, so the widget is ``type = "pool.monitor"``.
+"""
+
+from led_ticker_pool.monitor import PoolMonitor
+
+
+def register(api):
+    api.widget("monitor")(PoolMonitor)

led_ticker_pool/monitor.py

@@ -0,0 +1,609 @@
+"""Pool water-temperature widget backed by the pool_monitor InfluxDB v2 server."""
+
+import csv
+import difflib
+import io
+import logging
+import os
+import re
+from datetime import UTC, datetime
+from typing import Any, Self
+
+import aiohttp
+import attrs
+from led_ticker.plugin import (
+    Color,
+    ColorProviderBase,
+    Font,
+    SegmentMessage,
+    TwoRowMessage,
+    colors,
+    make_color,
+    resolve_font,
+    run_monitor_loop,
+    spawn_tracked,
+)
+
+# Deadband (in the display unit) below which a change reads as "steady" —
+# avoids flicker on sub-degree sensor noise.
+_TREND_DEADBAND: float = 0.5
+
+_SENSOR_ID_RE: re.Pattern[str] = re.compile(r"^[A-Za-z0-9_-]+$")
+
+# Supported layouts and the per-row font knobs that only apply to "two_row".
+_VALID_LAYOUTS: tuple[str, ...] = ("ticker", "two_row")
+_TWO_ROW_ONLY: tuple[str, ...] = (
+    "top_font",
+    "top_font_size",
+    "top_font_threshold",
+    "bottom_font",
+    "bottom_font_size",
+    "bottom_font_threshold",
+    "top_row_height",
+)
+
+# Color palette.
+#
+# DIM is reserved for the stale-temp signal (sensor data older than
+# `stale_after`) — kept distinctly washed-out so users can tell the
+# temperature isn't current.
+#
+# The prefix labels ("Pool 24h", "Pool 7D", etc.) and separators ("/")
+# use the widget's configurable `label_color` field — defaults to white
+# but can be tinted (e.g. an icy cyan for a pool widget).
+#
+# AVG_COLOR is the 7-day mean — pink, deliberately distinct from the
+# HI/LO orange/blue axis and from white labels. The 7D AVG is the only
+# value on its row that isn't an extreme, so it gets its own attention-
+# grabbing color.
+#
+# STEADY_COLOR is the trend-arrow "no change" case (used only when
+# `_trend_arrow` returns the steady glyph). Kept neutral gray so the
+# arrow reads as the absence of trend rather than a third alert color.
+DIM: Color = make_color(110, 110, 110)
+AVG_COLOR: Color = colors.PINK
+STEADY_COLOR: Color = make_color(210, 210, 210)
+HI_COLOR: Color = colors.ORANGE
+LO_COLOR: Color = colors.BLUE
+
+
+class _HiLoColorProvider(ColorProviderBase):
+    """Per-char color for combined HI/LO bottom rows like "84/72F".
+
+    Paints the HI portion in `hi_color`, the LO portion in `lo_color`,
+    and the separator + unit-letter suffix in `label_color`. Indices
+    are passed in at construction so the provider doesn't need to know
+    the underlying text — keeps it dumb.
+
+    `per_char = True` triggers TwoRowMessage's per-character render
+    path. `frame_invariant = True` because no animation.
+    """
+
+    per_char: bool = True
+    frame_invariant: bool = True
+
+    def __init__(
+        self,
+        *,
+        hi_end: int,
+        lo_start: int,
+        lo_end: int,
+        hi_color: Color,
+        lo_color: Color,
+        label_color: Color,
+    ) -> None:
+        self._hi_end = hi_end
+        self._lo_start = lo_start
+        self._lo_end = lo_end
+        self._hi_color = hi_color
+        self._lo_color = lo_color
+        self._label_color = label_color
+
+    def color_for(self, frame: int, char_index: int, total_chars: int) -> Color:
+        if char_index < self._hi_end:
+            return self._hi_color
+        if char_index < self._lo_start:
+            return self._label_color
+        if char_index < self._lo_end:
+            return self._lo_color
+        return self._label_color
+
+
+def _zone_color(temp_f: float) -> Color:
+    """Color for a water temp by dashboard zone (boundaries in °F)."""
+    if temp_f < 70.0:
+        return colors.BLUE
+    if temp_f < 80.0:
+        return colors.GREEN
+    if temp_f < 90.0:
+        return colors.ORANGE
+    return colors.RED
+
+
+def _c_to_display(temp_c: float, units: str) -> float:
+    """Convert stored Celsius to the display unit."""
+    if units == "imperial":
+        return temp_c * 9.0 / 5.0 + 32.0
+    return temp_c
+
+
+def _fmt_temp(temp_display: float, units: str) -> str:
+    """Whole-degree temp with unit suffix, e.g. '82F'.
+
+    No degree symbol — the hires Inter rasterized at small `font_size`
+    drops the U+00B0 glyph (renders as '?'), and the weather widget
+    already uses bare 'F'/'C' for the same reason. Stay consistent.
+    """
+    suffix = "F" if units == "imperial" else "C"
+    return f"{round(temp_display)}{suffix}"
+
+
+def _trend_arrow(
+    now_f: float, past_f: float | None, *, ascii_only: bool
+) -> tuple[str, Color]:
+    """Return (glyph, color) for the trend vs ~30 min ago.
+
+    `ascii_only` selects the lores-safe glyph set. Color: green up,
+    red down, gray steady.
+    """
+    up = ("^" if ascii_only else "▲", colors.GREEN)
+    down = ("v" if ascii_only else "▼", colors.RED)
+    steady = ("-" if ascii_only else "–", STEADY_COLOR)
+    if past_f is None:
+        return steady
+    delta = now_f - past_f
+    if delta > _TREND_DEADBAND:
+        return up
+    if delta < -_TREND_DEADBAND:
+        return down
+    return steady
+
+
+def _build_flux(
+    *, bucket: str, sensor_id: str | None, range_start: str, agg: str
+) -> str:
+    """Build a single-scalar Flux query.
+
+    `range_start` is a Flux duration ('-7d', '-1h') or an RFC3339
+    timestamp. `agg` is one of 'last', 'mean', 'min', 'max'.
+
+    A `group()` is inserted before the aggregation so that buckets
+    with multiple sensors (pool water + ambient air + heater coil etc.)
+    return a single global aggregate row, not one row per series.
+    Without `group()` the CSV parser would pick the first series's
+    aggregate — which depends on InfluxDB's tag-value sort order and
+    on which sensors happen to have data in the query range. That
+    inconsistency surfaced as "season HI 37°F but pool app shows 90°F"
+    on a multi-sensor bucket: for short ranges only the pool sensor
+    had data so its max returned first; for year-to-date the ambient
+    air sensor had data too and sorted earlier.
+
+    Set `sensor_id` in config to pin a specific sensor and skip the
+    cross-sensor aggregation.
+    """
+    sensor_clause = f' and r.id == "{sensor_id}"' if sensor_id else ""
+    return (
+        f'from(bucket: "{bucket}")\n'
+        f"  |> range(start: {range_start})\n"
+        f'  |> filter(fn: (r) => r._measurement == "mqtt_consumer"'
+        f' and r._field == "temperature_C"{sensor_clause})\n'
+        f"  |> group()\n"
+        f"  |> {agg}()"
+    )
+
+
+def _parse_scalar_csv(text: str) -> tuple[float | None, str | None]:
+    """Parse an InfluxDB v2 annotated-CSV response into (value, time).
+
+    Returns (None, None) when there is no data row. Reads the first
+    data row's `_value` (float) and `_time` columns.
+    """
+    reader = csv.reader(io.StringIO(text))
+    header: list[str] | None = None
+    for row in reader:
+        if not row or all(c == "" for c in row):
+            continue
+        if row[0].startswith("#"):
+            continue
+        if header is None:
+            header = row
+            continue
+        record = dict(zip(header, row, strict=False))
+        raw = record.get("_value", "")
+        if raw == "":
+            return None, None
+        return float(raw), record.get("_time") or None
+    return None, None
+
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_INTERVAL = 300
+
+
+@attrs.define
+class PoolMonitor:
+    """Pool water temperature, cycled as title/today/7-day/season screens."""
+
+    session: aiohttp.ClientSession
+    title: str = "POOL TEMPS"
+    sensor_id: str | None = None
+    units: str = "imperial"
+    # How far back to look for the latest reading. Decoupled from
+    # `stale_after`: this is the hard cutoff below which there's nothing
+    # to show (→ "--"); a found reading older than `stale_after` still
+    # displays, dimmed. Flux duration string (e.g. "-24h", "-90m").
+    current_window: str = "-24h"
+    # Seconds since the last reading before it's shown dim-gray as stale.
+    # 4 h default so a reading that rode out a multi-hour sensor gap shows
+    # (dimmed) rather than dimming almost immediately.
+    stale_after: float = 14400.0
+    influxdb_url: str = attrs.field(
+        factory=lambda: os.getenv("INFLUXDB_URL", "http://influxdb:8086")
+    )
+    influxdb_org: str = attrs.field(factory=lambda: os.getenv("INFLUXDB_ORG", "pool"))
+    influxdb_bucket: str = attrs.field(
+        factory=lambda: os.getenv("INFLUXDB_BUCKET", "pool_temps")
+    )
+    influxdb_token: str = attrs.field(factory=lambda: os.getenv("INFLUXDB_TOKEN", ""))
+    font: Font = attrs.field(factory=lambda: resolve_font("6x12"), kw_only=True)
+    layout: str = attrs.field(default="ticker", kw_only=True)
+    label_color: Color = attrs.field(factory=lambda: colors.RGB_WHITE, kw_only=True)
+    top_font: Font | None = attrs.field(default=None, kw_only=True)
+    bottom_font: Font | None = attrs.field(default=None, kw_only=True)
+    top_row_height: int | None = attrs.field(default=None, kw_only=True)
+    feed_title: SegmentMessage | TwoRowMessage | None = attrs.field(
+        init=False, default=None
+    )
+    feed_stories: list[SegmentMessage | TwoRowMessage] = attrs.field(
+        init=False, factory=list
+    )
+
+    @classmethod
+    def validate_config(cls, cfg):
+        msgs = []
+        cw = cfg.get("current_window")
+        if cw is not None and not re.match(r"^-(\d+(ns|us|ms|s|m|h|d|w))+$", str(cw)):
+            msgs.append(
+                "current_window must be a negative Flux duration "
+                f'(e.g. "-24h", "-90m"); got {cw!r}'
+            )
+        sid = cfg.get("sensor_id")
+        if sid is not None and not _SENSOR_ID_RE.match(str(sid)):
+            msgs.append(f"sensor_id must match [A-Za-z0-9_-]+; got {sid!r}")
+        layout = cfg.get("layout")
+        if layout is not None and layout not in _VALID_LAYOUTS:
+            hint = ""
+            close = difflib.get_close_matches(str(layout), _VALID_LAYOUTS, n=1)
+            if close:
+                hint = f" (did you mean {close[0]!r}?)"
+            msgs.append(f"layout must be one of {_VALID_LAYOUTS}; got {layout!r}{hint}")
+        if cfg.get("layout", "ticker") != "two_row":
+            present = [k for k in _TWO_ROW_ONLY if k in cfg]
+            if present:
+                msgs.append(
+                    f'{", ".join(present)} only valid with layout = "two_row" '
+                    f"(current layout: {cfg.get('layout', 'ticker')!r})"
+                )
+        return msgs
+
+    @classmethod
+    async def start(
+        cls,
+        session: aiohttp.ClientSession,
+        update_interval: int = _DEFAULT_INTERVAL,
+        **kwargs: Any,
+    ) -> Self:
+        widget = cls(session=session, **kwargs)
+        if not widget.influxdb_token:
+            raise ValueError("INFLUXDB_TOKEN not set. Add it to your .env file.")
+        if widget.sensor_id is not None and not _SENSOR_ID_RE.match(widget.sensor_id):
+            raise ValueError(
+                f"Invalid sensor_id {widget.sensor_id!r}: must match [A-Za-z0-9_-]+"
+            )
+        widget._set_placeholder()
+        try:
+            await widget.update()
+        except Exception:
+            logger.exception("Pool initial update failed; showing placeholder")
+        spawn_tracked(run_monitor_loop(widget, update_interval))
+        return widget
+
+    async def _query(
+        self, range_start: str, agg: str
+    ) -> tuple[float | None, str | None]:
+        flux = _build_flux(
+            bucket=self.influxdb_bucket,
+            sensor_id=self.sensor_id,
+            range_start=range_start,
+            agg=agg,
+        )
+        url = f"{self.influxdb_url}/api/v2/query?org={self.influxdb_org}"
+        headers = {
+            "Authorization": f"Token {self.influxdb_token}",
+            "Content-Type": "application/vnd.flux",
+            "Accept": "application/csv",
+        }
+        async with self.session.post(url, data=flux, headers=headers) as resp:
+            resp.raise_for_status()
+            text = await resp.text()
+        value, ts = _parse_scalar_csv(text)
+        # DEBUG-level so production logs stay quiet; flip --log-level DEBUG
+        # to verify each scalar query is returning a sensible value when
+        # the displayed numbers look wrong (e.g. season HI too low).
+        logger.debug(
+            "pool query: range=%s agg=%s → value=%s ts=%s",
+            range_start,
+            agg,
+            value,
+            ts,
+        )
+        return value, ts
+
+    async def update(self) -> None:
+        year_start = f"{datetime.now(UTC).year}-01-01T00:00:00Z"
+        current_c, current_time = await self._query(self.current_window, "last")
+        past_c, _ = await self._query("-45m", "mean")  # ~30 min lookback avg
+        today_min_c, _ = await self._query("today()", "min")
+        today_max_c, _ = await self._query("today()", "max")
+        d7_mean_c, _ = await self._query("-7d", "mean")
+        d7_min_c, _ = await self._query("-7d", "min")
+        d7_max_c, _ = await self._query("-7d", "max")
+        season_min_c, _ = await self._query(year_start, "min")
+        season_max_c, _ = await self._query(year_start, "max")
+
+        if current_c is None:
+            # The single most common "temps aren't showing" cause: the
+            # `-1h last` query came back with no data row. Surface it at
+            # WARNING (default log level) with enough context to tell
+            # apart an empty bucket, a wrong bucket/sensor, or an
+            # unreachable server — without ever logging the token.
+            sensor = self.sensor_id or "<all>"
+            logger.warning(
+                "pool: no current temperature from InfluxDB "
+                "(url=%s org=%s bucket=%s sensor=%s) → showing placeholder. "
+                "Check the bucket has recent temperature_C data and that "
+                "url/org/bucket/sensor_id match your InfluxDB.",
+                self.influxdb_url,
+                self.influxdb_org,
+                self.influxdb_bucket,
+                sensor,
+            )
+            self._set_placeholder()
+            return
+
+        age = self._age_seconds(current_time)
+        # One INFO line per successful update (Container contract): a
+        # silent log stream after startup means the background task died.
+        now_display = _c_to_display(current_c, self.units)
+        logger.info(
+            "pool updated: current=%s age=%.0fs stale=%s "
+            "today=%s/%s 7d=%s/%s season=%s/%s (layout=%s)",
+            _fmt_temp(now_display, self.units),
+            age,
+            age > self.stale_after,
+            self._disp(today_max_c),
+            self._disp(today_min_c),
+            self._disp(d7_max_c),
+            self._disp(d7_min_c),
+            self._disp(season_max_c),
+            self._disp(season_min_c),
+            self.layout,
+        )
+        if self.layout == "two_row":
+            self._build_two_row_screens(
+                current_c=current_c,
+                current_age_s=age,
+                past_c=past_c,
+                today_min_c=today_min_c,
+                today_max_c=today_max_c,
+                d7_mean_c=d7_mean_c,
+                d7_min_c=d7_min_c,
+                d7_max_c=d7_max_c,
+                season_min_c=season_min_c,
+                season_max_c=season_max_c,
+            )
+        else:
+            self._build_ticker_screens(
+                current_c=current_c,
+                current_age_s=age,
+                past_c=past_c,
+                today_min_c=today_min_c,
+                today_max_c=today_max_c,
+                d7_mean_c=d7_mean_c,
+                d7_min_c=d7_min_c,
+                d7_max_c=d7_max_c,
+                season_min_c=season_min_c,
+                season_max_c=season_max_c,
+            )
+
+    @staticmethod
+    def _age_seconds(ts: str | None) -> float:
+        if not ts:
+            return float("inf")
+        try:
+            t = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        except ValueError:
+            return float("inf")
+        return (datetime.now(UTC) - t).total_seconds()
+
+    def _disp(self, c: float | None) -> str:
+        if c is None:
+            return "--"
+        return str(round(_c_to_display(c, self.units)))
+
+    def _build_two_row_screens(
+        self,
+        *,
+        current_c: float,
+        current_age_s: float,
+        past_c: float | None,
+        today_min_c: float | None,
+        today_max_c: float | None,
+        d7_mean_c: float | None,
+        d7_min_c: float | None,
+        d7_max_c: float | None,
+        season_min_c: float | None,
+        season_max_c: float | None,
+    ) -> None:
+        """Build feed_title + feed_stories in two_row layout. See spec
+        docs/superpowers/specs/2026-05-28-pool-two-row-layout-design.md.
+        """
+        now_display = _c_to_display(current_c, self.units)
+        zone_f = _c_to_display(current_c, "imperial")
+        stale = current_age_s > self.stale_after
+
+        kw = {
+            "font": self.font,
+            "top_font": self.top_font,
+            "bottom_font": self.bottom_font,
+            "top_row_height": self.top_row_height,
+            "top_color": self.label_color,
+        }
+
+        self.feed_title = TwoRowMessage(
+            top_text="POOL",
+            bottom_text="TEMPS",
+            bottom_color=colors.RGB_WHITE,
+            **kw,
+        )
+
+        unit_letter = "F" if self.units == "imperial" else "C"
+        today_bottom_color = DIM if stale else _zone_color(zone_f)
+        today = TwoRowMessage(
+            top_text="POOL 24H",
+            bottom_text=_fmt_temp(now_display, self.units),
+            bottom_color=today_bottom_color,
+            **kw,
+        )
+
+        d7_hi = self._disp(d7_max_c)
+        d7_lo = self._disp(d7_min_c)
+        d7_text = f"{d7_hi}/{d7_lo}{unit_letter}"
+        d7 = TwoRowMessage(
+            top_text="POOL 7D",
+            bottom_text=d7_text,
+            bottom_color=_HiLoColorProvider(
+                hi_end=len(d7_hi),
+                lo_start=len(d7_hi) + 1,
+                lo_end=len(d7_hi) + 1 + len(d7_lo),
+                hi_color=HI_COLOR,
+                lo_color=LO_COLOR,
+                label_color=self.label_color,
+            ),
+            **kw,
+        )
+
+        season_hi = self._disp(season_max_c)
+        season_lo = self._disp(season_min_c)
+        season_text = f"{season_hi}/{season_lo}{unit_letter}"
+        season = TwoRowMessage(
+            top_text="POOL SEASON",
+            bottom_text=season_text,
+            bottom_color=_HiLoColorProvider(
+                hi_end=len(season_hi),
+                lo_start=len(season_hi) + 1,
+                lo_end=len(season_hi) + 1 + len(season_lo),
+                hi_color=HI_COLOR,
+                lo_color=LO_COLOR,
+                label_color=self.label_color,
+            ),
+            **kw,
+        )
+        self.feed_stories = [today, d7, season]
+
+    def _build_ticker_screens(
+        self,
+        *,
+        current_c: float,
+        current_age_s: float,
+        past_c: float | None,
+        today_min_c: float | None,
+        today_max_c: float | None,
+        d7_mean_c: float | None,
+        d7_min_c: float | None,
+        d7_max_c: float | None,
+        season_min_c: float | None,
+        season_max_c: float | None,
+    ) -> None:
+        now_display = _c_to_display(current_c, self.units)
+        past_display = _c_to_display(past_c, self.units) if past_c is not None else None
+        # Zone color always evaluated in °F so thresholds are consistent across units.
+        zone_f = _c_to_display(current_c, "imperial")
+        stale = current_age_s > self.stale_after
+
+        self.feed_title = SegmentMessage(
+            [(self.title, colors.RGB_WHITE)], center=True, font=self.font
+        )
+
+        temp_color = DIM if stale else _zone_color(zone_f)
+        arrow, arrow_color = _trend_arrow(now_display, past_display, ascii_only=True)
+        today = SegmentMessage(
+            [
+                ("Pool 24h ", self.label_color),
+                (_fmt_temp(now_display, self.units), temp_color),
+                (f" {arrow} ", arrow_color),
+                (self._disp(today_max_c), HI_COLOR),
+                ("/", self.label_color),
+                (self._disp(today_min_c), LO_COLOR),
+            ],
+            center=True,
+            font=self.font,
+        )
+        d7 = SegmentMessage(
+            [
+                ("Pool 7D AVG ", self.label_color),
+                (self._disp(d7_mean_c), AVG_COLOR),
+                ("  ", self.label_color),
+                (self._disp(d7_max_c), HI_COLOR),
+                ("/", self.label_color),
+                (self._disp(d7_min_c), LO_COLOR),
+            ],
+            center=True,
+            font=self.font,
+        )
+        season = SegmentMessage(
+            [
+                ("Pool Season HI ", self.label_color),
+                (self._disp(season_max_c), HI_COLOR),
+                ("  LO ", self.label_color),
+                (self._disp(season_min_c), LO_COLOR),
+            ],
+            center=True,
+            font=self.font,
+        )
+        self.feed_stories = [today, d7, season]
+
+    def _set_placeholder(self) -> None:
+        if self.layout == "two_row":
+            kw = {
+                "font": self.font,
+                "top_font": self.top_font,
+                "bottom_font": self.bottom_font,
+                "top_row_height": self.top_row_height,
+                "top_color": self.label_color,
+                "bottom_color": self.label_color,
+            }
+            self.feed_title = TwoRowMessage(
+                top_text="POOL",
+                bottom_text="TEMPS",
+                **kw,
+            )
+            self.feed_stories = [
+                TwoRowMessage(
+                    top_text=self.title,
+                    bottom_text="--",
+                    **kw,
+                )
+            ]
+            return
+        self.feed_title = SegmentMessage(
+            [(self.title, colors.RGB_WHITE)], center=True, font=self.font
+        )
+        self.feed_stories = [
+            SegmentMessage(
+                [(f"{self.title} ", self.label_color), ("--", self.label_color)],
+                center=True,
+                font=self.font,
+            )
+        ]

led_ticker_pool-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: led-ticker-pool
+Version: 0.1.0
+Summary: Pool water-temperature monitor widget for led-ticker (InfluxDB v2 backed).
+Project-URL: Homepage, https://docs.ledticker.dev
+Project-URL: Repository, https://github.com/JamesAwesome/led-ticker-plugins
+Project-URL: Issues, https://github.com/JamesAwesome/led-ticker-plugins/issues
+Author-email: James Awesome <james@morelli.nyc>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.14
+Requires-Dist: aiohttp
+Requires-Dist: led-ticker-core>=2.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# led-ticker-pool
+
+A pool water-temperature monitor **widget** for [led-ticker](https://github.com/JamesAwesome/led-ticker), backed by an InfluxDB v2 server (e.g. [pool_monitor](https://github.com/JamesAwesome/pool_monitor)). It's a led-ticker **plugin** — installing this package contributes a `pool.monitor` widget you reference in your led-ticker config.
+
+It cycles four screens — a title card, today's current temperature with a trend arrow (`^`/`v`/`-`) and hi/lo, a 7-day mean with hi/lo, and a season (current-year) hi/lo. Temperature is zone-colored — blue below 70°F, green 70–79°F, orange 80–89°F, red 90°F+ — so the comfort level is readable at a glance. Data is fetched in the background via async polling, so the display keeps running even if the server is briefly unreachable.
+
+## Screenshots
+
+**`layout = "ticker"`** (default — single-row segmented screens, smallsign-friendly):
+
+![Pool widget in ticker layout — single-row segmented screens with trend arrow and hi/lo](docs/widget-pool.gif)
+
+**`layout = "two_row"`** (stacked label-on-top / big-number-on-bottom, bigsign / longboi):
+
+![Pool widget in two_row layout — stacked label-on-top, big-number-on-bottom](docs/widget-pool-two-row.gif)
+
+## Prerequisites
+
+- **A running led-ticker** (the sign + its config). This widget plugs into it.
+- **A running InfluxDB v2 server** holding pool temperature data. The reference stack is [pool_monitor](https://github.com/JamesAwesome/pool_monitor), which provides the bucket and sensor schema this widget expects.
+- **An InfluxDB auth token** — set `INFLUXDB_TOKEN` in your led-ticker `.env` (or as a per-widget config key). The widget raises `ValueError` at startup if it's missing. See [InfluxDB setup](#influxdb-setup) for all four connection variables.
+
+## Install
+
+The widget auto-registers via the `led_ticker.plugins` entry point — once the package is installed, no `[plugins]` config change is needed.
+
+**Into a containerized led-ticker (recommended):** add this package to `config/requirements-plugins.txt` (copy it from `config/requirements-plugins.example.txt`, which already lists it), then rebuild:
+
+```bash
+# in your led-ticker checkout
+cp config/requirements-plugins.example.txt config/requirements-plugins.txt
+docker compose up -d --build
+```
+
+**Standalone (bare-metal / a venv that already has led-ticker):**
+
+```bash
+pip install "git+https://github.com/JamesAwesome/led-ticker-pool.git@main"
+```
+
+(led-ticker isn't on PyPI, so `pip` can't fetch it — this path works only where led-ticker is already installed, e.g. inside the led-ticker Docker image or a venv set up as in [Development](#development) below. See the led-ticker [Plugins docs](https://docs.ledticker.dev/plugins/) for the constraint-based install the image uses.)
+
+## Configuration
+
+Reference the widget in a playlist section by `type = "pool.monitor"`:
+
+```toml
+[[playlist.section.widget]]
+type = "pool.monitor"
+title = "POOL TEMPS"
+units = "imperial"
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | string | `"POOL TEMPS"` | Label shown on the title screen. |
+| `sensor_id` | string | none | Sensor ID to filter on. Omit to use the only/first sensor in the bucket. Must match `[A-Za-z0-9_-]+`. |
+| `units` | string | `"imperial"` | `"imperial"` (°F) or `"metric"` (°C). |
+| `update_interval` | int | `300` | Seconds between InfluxDB fetches (5 min default). |
+| `current_window` | string | `"-24h"` | How far back to search for the latest reading, as a negative Flux duration (`"-24h"`, `"-90m"`). Older than this → `--` placeholder. Widen it if your sensor reports infrequently. |
+| `stale_after` | float | `14400` | Seconds since the last reading before the temperature dims to gray (stale signal). 4 h default. |
+| `influxdb_url` | string | `$INFLUXDB_URL` / `"http://influxdb:8086"` | InfluxDB v2 base URL. Config overrides the env var. |
+| `influxdb_org` | string | `$INFLUXDB_ORG` / `"pool"` | InfluxDB organization. |
+| `influxdb_bucket` | string | `$INFLUXDB_BUCKET` / `"pool_temps"` | InfluxDB bucket. |
+| `influxdb_token` | string | `$INFLUXDB_TOKEN` | InfluxDB v2 token. **Required** — the widget raises `ValueError` at startup if it's missing. |
+| `layout` | `"ticker"` \| `"two_row"` | `"ticker"` | Render mode (see below). |
+| `label_color` | `[r,g,b]` | white | Color for prefix labels / separators. |
+| `font` / `font_size` / `font_threshold` | font name / int / int | `"6x12"` | Main text font. A BDF alias (`6x12`, `5x8`) or a hires font name (`Inter-Regular`) with `font_size` in real pixels. In `two_row`, the per-row knobs below override this. |
+| `top_font` / `top_font_size` / `top_font_threshold` | font / int / int | inherit `font` | **two_row only:** top (label) row font knobs. |
+| `bottom_font` / `bottom_font_size` / `bottom_font_threshold` | font / int / int | inherit | **two_row only:** bottom (value) row font knobs. |
+| `top_row_height` | int (logical rows) | `None` | **two_row only:** top band height. `None` = symmetric 8/8 split. |
+
+The per-row knobs apply ONLY when `layout = "two_row"`; setting them under `ticker` fails config validation.
+
+### Layouts
+
+- **`ticker`** (default) — single-row segmented screens; the today screen shows current temp + trend arrow and hi/lo, the 7-day screen the mean + hi/lo, the season screen HI/LO together. Best for small panels (smallsign 160×16).
+- **`two_row`** — stacked label-on-top / big-number-on-bottom. Cycles four screens with top-row labels `POOL` (title), `POOL 24H` (current temp, zone-colored), `POOL 7D` (7-day HI/LO), and `POOL SEASON` (season HI/LO) — HI in orange, LO in blue, shown together on one screen (e.g. `84/72F`). The trend arrow is dropped (bottom is the value only). Best for bigsign / longboi (256×64 / 512×64).
+
+A `two_row` example:
+
+```toml
+[[playlist.section.widget]]
+type = "pool.monitor"
+title = "POOL TEMPS"
+layout = "two_row"
+units = "imperial"
+font = "Inter-Regular"
+font_size = 32
+label_color = [130, 220, 255]
+```
+
+## InfluxDB setup
+
+The widget reads connection details from your led-ticker `.env` (or per-widget overrides). `INFLUXDB_TOKEN` is required; the rest default to the standard pool_monitor Docker Compose stack.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `INFLUXDB_TOKEN` | **yes** | — | InfluxDB v2 auth token. |
+| `INFLUXDB_URL` | no | `http://influxdb:8086` | Base URL. |
+| `INFLUXDB_ORG` | no | `pool` | Organization. |
+| `INFLUXDB_BUCKET` | no | `pool_temps` | Bucket. |
+
+The widget queries water-temperature readings with Flux over HTTP and computes today / 7-day / season aggregates. Stale data (older than `stale_after`) renders dim gray; the trend arrow compares the latest reading to a ~45-minute trailing average (sub-0.5°F shows `-`).
+
+## Development
+
+led-ticker isn't on PyPI, so install it editable from a sibling checkout. This repo's `pyproject.toml` pins `led-ticker` to `../led-ticker` via `[tool.uv.sources]`:
+
+```bash
+git clone https://github.com/JamesAwesome/led-ticker ../led-ticker   # sibling checkout
+git clone https://github.com/JamesAwesome/led-ticker-pool && cd led-ticker-pool
+uv venv
+uv pip install -e ../led-ticker -e ".[dev]"
+uv run pytest -q
+```
+
+> **Note:** led-ticker's `graphics` surface works headless via its bundled stub, but the full `RGBMatrix`/canvas test stub lives in led-ticker's `tests/stubs/` and isn't shipped. This repo's tests put it on the path via `pyproject.toml`'s `[tool.pytest.ini_options] pythonpath = ["../led-ticker/tests/stubs"]`.
+
+## Links
+
+- led-ticker project: <https://github.com/JamesAwesome/led-ticker>
+- led-ticker plugin system: <https://docs.ledticker.dev/plugins/>

led_ticker_pool-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+led_ticker_pool/__init__.py,sha256=DfvdIFE6ET8PL80lWnVj8b54yHF5uJ0_MfEi-Mep_QQ,345
+led_ticker_pool/monitor.py,sha256=CN0bpuRYvt-7zfO2dDUA-0g_G0VkRrHJKG_0EOhQ68M,21934
+led_ticker_pool-0.1.0.dist-info/METADATA,sha256=6kYINf_BkvaDYJK7cCTEmr-RqsNRPW2-cIg5StRwD5Q,8814
+led_ticker_pool-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+led_ticker_pool-0.1.0.dist-info/entry_points.txt,sha256=_X9VYKBc6VWSlR9BvRa4cK0Umzvqb_BbgMPgEaz8xrU,53
+led_ticker_pool-0.1.0.dist-info/licenses/LICENSE,sha256=kFECdLBfsSUUTLoH4nlAu-gQPyXoHbWMZDg8p2DGAP4,1070
+led_ticker_pool-0.1.0.dist-info/RECORD,,

led_ticker_pool-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

led_ticker_pool-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[led_ticker.plugins]
+pool = led_ticker_pool:register

led_ticker_pool-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Awesome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.