Add PICLOCK_TROUBLE_DOTS to invert indicator dots into trouble lights

Author: lee

AGENTS.md

@@ -83,6 +83,9 @@ hardware-touching part is isolated:
   the loop polls it every tick). It feeds the **upper-left** indicator dot: lit while the
   link is up, dark when the link drops or the interface disappears (e.g. firmware crash).
   Any read error → down. `PICLOCK_WIFI_DOT` / `PICLOCK_WIFI_IFACE` configure it.
+  Both indicator dots share a polarity switch, `PICLOCK_TROUBLE_DOTS` (`Config.trouble_dots`,
+  default off): off = status lights (lit while nominal); on = trouble lights (lit only when
+  off-nominal, so a healthy clock shows just the time). Applied in `app.py` via `_dot_lit()`.
 - [piclock/config.py](piclock/config.py) — `Config` dataclass with `PICLOCK_*` env overrides
   (brightness, schedule on/off + times + wake/night brightness, 24h, blink, sync dot +
   freshness window, wifi dot + interface, I2C

README.md

@@ -130,6 +130,7 @@ Set via environment variables (typically in the systemd unit):
 | `PICLOCK_SYNC_FRESH` | `4500` | Seconds since the last successful sync before the sync dot goes dark (~2× timesyncd's max poll interval) |
 | `PICLOCK_WIFI_DOT` | `1` | Upper-left dot lit while the Wi-Fi link is up, dark when it drops; `0` disables the dot |
 | `PICLOCK_WIFI_IFACE` | `wlan0` | Interface the Wi-Fi dot watches |
+| `PICLOCK_TROUBLE_DOTS` | `0` | `1` inverts both dots into trouble lights: dark while nominal, lit only when NTP is stale/unsynced or the Wi-Fi link is down |
 | `PICLOCK_I2C_BUS` | `1` | I2C bus number |
 | `PICLOCK_I2C_ADDRESS` | `0x70` | HT16K33 address |
 | `PICLOCK_TICK` | `0.2` | Loop period, seconds |

SOFTWARE_RUNBOOK.md

@@ -148,7 +148,10 @@ The commands travel over a Unix socket (`/run/piclock/ctl.sock`, mode 0660) gate
 
 Config via `PICLOCK_*` env (in the unit): `PICLOCK_24H=1`, `PICLOCK_BRIGHTNESS=0..15`,
 `PICLOCK_BLINK=0/1`, `PICLOCK_SYNC_DOT=0/1` (lower-left dot lit while NTP-synced, dark when
-free-running; on by default), `PICLOCK_DISPLAY=null` (run without hardware), and
+free-running; on by default), `PICLOCK_WIFI_DOT=0/1` + `PICLOCK_WIFI_IFACE=wlan0`
+(upper-left dot lit while the Wi-Fi link is up, polled from sysfs every tick; on by
+default), `PICLOCK_TROUBLE_DOTS=0/1` (`1` inverts both dots into trouble lights — dark
+while nominal, lit only on stale/unsynced NTP or a down link; off by default), `PICLOCK_DISPLAY=null` (run without hardware), and
 `PICLOCK_WAKE_BRIGHTNESS` / `PICLOCK_NIGHT_BRIGHTNESS` (0-15 levels the optional day/night
 schedule applies at its wake and dim edges — see §5; the schedule's on/off switch and times
 live in its drop-in, also §5). The unit sets

piclock/app.py

@@ -33,6 +33,12 @@
 _BLANK_TEXT = "    "
 
 
+def _dot_lit(nominal: bool, trouble: bool) -> bool:
+    """Indicator polarity: status lights are lit while nominal, trouble lights
+    only while off-nominal (see Config.trouble_dots)."""
+    return (not nominal) if trouble else nominal
+
+
 def run(config: Config | None = None) -> None:
     logging.basicConfig(
         level=logging.INFO,
@@ -187,12 +193,14 @@ def _handle_signal(signum, _frame):
                     blink=config.blink_colon,
                 )
                 text, colon = state.text, state.colon
-                sync_dot = state.sync_dot and config.sync_dot and sync_fresh
+                sync_ok = state.sync_dot and sync_fresh
                 # Wi-Fi status is not a function of the time, so it joins here
                 # rather than passing through render(). Polled per tick: it is
                 # one sysfs read (~140 us), and per-second freshness is the
                 # point of the indicator.
-                wifi_dot = config.wifi_dot and wifi.is_wifi_up(config.wifi_iface)
+                wifi_ok = wifi.is_wifi_up(config.wifi_iface) if config.wifi_dot else True
+                sync_dot = config.sync_dot and _dot_lit(sync_ok, config.trouble_dots)
+                wifi_dot = config.wifi_dot and _dot_lit(wifi_ok, config.trouble_dots)
             else:
                 # display off
                 text, colon, sync_dot, wifi_dot = _BLANK_TEXT, False, False, False

piclock/config.py

@@ -97,6 +97,12 @@ class Config:
     # in-process file read, no subprocess.
     wifi_dot: bool = True
     wifi_iface: str = "wlan0"
+    # Indicator polarity. Default (False): the dots are *status* lights — lit
+    # while everything is nominal (synced / link up). True: the dots are
+    # *trouble* lights — dark while nominal and lit only when something is
+    # wrong (sync stale or never achieved / link down), so a healthy clock
+    # shows nothing but the time. Each dot's enable flag still applies.
+    trouble_dots: bool = False
     tick_seconds: float = 0.2  # loop granularity; colon blink derives from wall clock
     backend: str = "ht16k33"  # "ht16k33" for hardware, "null" for off-Pi dev/testing
 
@@ -170,6 +176,7 @@ def from_env(cls) -> "Config":
             ),
             wifi_dot=_env_bool("PICLOCK_WIFI_DOT", cls.wifi_dot),
             wifi_iface=os.environ.get("PICLOCK_WIFI_IFACE", cls.wifi_iface).strip(),
+            trouble_dots=_env_bool("PICLOCK_TROUBLE_DOTS", cls.trouble_dots),
             tick_seconds=_env_float("PICLOCK_TICK", cls.tick_seconds),
             backend=os.environ.get("PICLOCK_DISPLAY", cls.backend).strip().lower(),
             ctl_socket=os.environ.get("PICLOCK_CTL_SOCKET", cls.ctl_socket),

systemd/piclock.service

@@ -30,11 +30,15 @@ Environment=PICLOCK_CTL_SOCKET=/run/piclock/ctl.sock
 # Keep each value on its own line and put comments on their own `#` lines.
 # PICLOCK_BRIGHTNESS: 0-15; 0 = dimmest, for a dark bedroom.
 Environment=PICLOCK_BRIGHTNESS=0
-# PICLOCK_24H: 1 = 24-hour time (the default), 0 = 12-hour (leading-zero hour
-# blanked, no PM indicator). Uncomment for 12-hour.
-# Environment=PICLOCK_24H=0
+# PICLOCK_24H: 1 = 24-hour time, 0 = 12-hour (leading-zero hour blanked, no PM
+# indicator). Flip to 1 (or comment out) to go back to 24-hour.
+Environment=PICLOCK_24H=0
 # PICLOCK_BLINK=1 makes the colon blink at 1 Hz (default: steady).
 # Environment=PICLOCK_BLINK=1
+# PICLOCK_TROUBLE_DOTS=1 inverts the two indicator dots into trouble lights:
+# dark while Wi-Fi is up and NTP is fresh, lit only when something is wrong.
+# Default 0 = status lights (lit while nominal).
+# Environment=PICLOCK_TROUBLE_DOTS=1
 # PICLOCK_WAKE_BRIGHTNESS / PICLOCK_NIGHT_BRIGHTNESS: 0-15 levels the optional
 # day/night schedule applies at its wake and dim edges (defaults: 15 = full,
 # 0 = dimmest lit level).

tests/test_app.py

@@ -0,0 +1,16 @@
+import pytest
+
+from piclock.app import _dot_lit
+
+
+@pytest.mark.parametrize(
+    "nominal, trouble, lit",
+    [
+        (True, False, True),  # status light: lit while nominal
+        (False, False, False),
+        (True, True, False),  # trouble light: dark while nominal
+        (False, True, True),
+    ],
+)
+def test_dot_polarity(nominal, trouble, lit):
+    assert _dot_lit(nominal, trouble) is lit

tests/test_config.py

@@ -118,16 +118,19 @@ def test_indicator_dot_defaults():
     assert cfg.sync_fresh_seconds == 4500.0
     assert cfg.wifi_dot is True
     assert cfg.wifi_iface == "wlan0"
+    assert cfg.trouble_dots is False
 
 
 def test_from_env_reads_indicator_dot_settings(monkeypatch):
     monkeypatch.setenv("PICLOCK_SYNC_FRESH", "600")
     monkeypatch.setenv("PICLOCK_WIFI_DOT", "off")
     monkeypatch.setenv("PICLOCK_WIFI_IFACE", "wlan1")
+    monkeypatch.setenv("PICLOCK_TROUBLE_DOTS", "1")
     cfg = Config.from_env()
     assert cfg.sync_fresh_seconds == 600.0
     assert cfg.wifi_dot is False
     assert cfg.wifi_iface == "wlan1"
+    assert cfg.trouble_dots is True
 
 
 @pytest.mark.parametrize("window", [0, -1.0])