# LuxStats

Hardware/software status LEDs for your desk: a Pimoroni **Tiny 2040** drives a
NeoPixel strip while a **PyQt5 configurator applet** owns the configuration,
maps LED zones to live statuses, and pushes every change to the board
instantly. The board is treated as read-only: config lives on the host and is
re-pushed on connect.

```
luxstats/
├── firmware/
│   ├── boot.py     # enables the second USB CDC (data) serial channel
│   └── code.py     # LuxStats firmware v2 (CircuitPython, RAM-only config)
├── host/
│   ├── luxstats_configurator.py   # PyQt5 applet
│   ├── system_monitor.py          # status probes + notification watcher
│   └── requirements.txt
└── README.md
```

## Hardware setup

Wire NeoPixel data-in to **GP0** (configurable), power from 5V/USB, share
ground. Default pixel order `GRBW` (SK6812 RGBW); use `GRB` for WS2812B.

1. Install CircuitPython 8/9 on the Tiny 2040.
2. Copy Adafruit `neopixel.mpy` into `CIRCUITPY/lib/`.
3. Copy `firmware/boot.py` and `firmware/code.py` to the `CIRCUITPY` root.
4. Power-cycle once; the board then exposes two serial ports (REPL + the
   LuxStats data channel).

## Host setup

```bash
cd host
pip install -r requirements.txt        # PyQt5, pyserial, psutil
python3 luxstats_configurator.py
```

Linux extras: `dialout` group for serial, `fuser` (psmisc) for camera
detection, `dbus-monitor` for the notification watcher, `nvidia-smi` for
NVIDIA GPUs (AMD uses sysfs/hwmon automatically), and the `drivetemp`/`nvme`
kernel sensors for drive temperatures.

## Running in the background (Arch Linux)

`./luxstats.sh` auto-detects the newest installed Python 3, runs directly on
the system interpreter when `python-pyqt5 python-pyserial python-psutil` are
installed via pacman (no venv), and otherwise creates a managed venv under
`~/.local/share/luxstats/venv`. It launches the app detached
(`start`/`stop`/`status`), logging to `~/.local/state/luxstats/luxstats.log`.
An optional systemd user unit is in `packaging/luxstats.service`.

The app auto-connects at startup (and on every link drop) to the device named
`Tiny 2040 (8MB) - CircuitPython CDC2 control` on any `/dev/ttyACM#` port -
the name is stored in the config and editable on the Connection tab.

## Zone model

Everything on the strip is an **ordered list of zones**. A zone is either a
status source or an ambient effect region:

* **Status zones** — known sources are locked to their correct type:
  `cpu`/`gpu`/`ram`/`disk*` are percent (gradient, optional bar-graph fill);
  `*_temp` sources report **raw Celsius** and map onto a gradient between a
  per-zone min/max °C; `eth` and `wifi` are **positional** — one color per
  position (down/10M/100M/1G/2.5G/10G and down/2.4/5/6 GHz, no blending) —
  and `eth` reads 0 unless the link carrier is actually up; `vpn`/`cam` are
  on/off colors; `custom` takes pushed RGBW values.
* **Ambient zones** — off/solid/breathe/rainbow/sparkle with color and speed,
  assigned to an explicit range. Pixels not claimed by any zone stay off.

Zones **may not overlap**: the app flags conflicts (and ranges past the end
of the strip) and blocks pushes until fixed. Reorder zones with Move
up/down. Each row has a **Test** start/stop toggle that blinks that exact LED
range on the strip while you dial in positions; the camera glow zone
(start/count) has its own start/stop test button.

The **camera glow** overlay uses assigned LEDs with range syntax
(`1-5,9-13`) and the same animation presets as ambient zones
(solid/breathe/rainbow/sparkle). Overlays render on top of zones, in order:
camera glow → notification blinker → range-test blink. Any start/stop test
(zone range, camera glow, raw fill) pauses automated polling and resumes it
when the test stops; fake-status buttons pause polling for 10 s.

## Automation

The Automation tab discovers every source — including **all mounted physical
drives** (usage per drive, temperature where a `nvme`/`drivetemp` sensor
exists, plus `disk`/`disk_temp` aggregates) and **separate CPU/GPU
utilisation and temperature** — and pushes the enabled ones at your chosen
interval (adjustable in 100 ms steps; slow probes are cached internally so
10 Hz polling stays cheap). Camera use toggles the glow automatically —
detection ignores PipeWire/WirePlumber/PulseAudio holding `/dev/video*`
open, and both on AND off transitions are pushed. Desktop notifications
(Linux/DBus) fire the blinker. The watcher toggle, camera-automation toggle,
blinker period/count, and poll interval all persist in the host config.

## Configuration & persistence

Every edit auto-pushes to the device after a short debounce — there is no
Apply button. Config is saved on the host at
`~/.config/luxstats/config.json` (Linux/macOS) or `%APPDATA%\luxstats`
(Windows), reloaded at startup, and pushed on every connect. Profiles can be
exported/imported as JSON.

## Connection reliability

The firmware uses non-blocking serial writes (it can never stall waiting on
the host to read a reply) and only acks `status` updates when asked. The app
drains stale input before every request so request/response can't desync,
serialises writes across threads, pings the device after ~10 s of idle, and
auto-reconnects every few seconds if the link drops without a manual
disconnect.

## Serial protocol (JSON lines, host → device)

| Command | Purpose |
|---|---|
| `{"cmd":"ping"}` | health check, returns `{"pong":1,"fw":2}` |
| `{"cmd":"config","config":{...}}` | apply full configuration (RAM only) |
| `{"cmd":"get_config"}` | read back the active config |
| `{"cmd":"status","values":{"cpu":0.4,"gpu_temp":0.6,"disk_sda":0.8,...}}` | push live values (silent; add `"ack":1` for a reply) |
| `{"cmd":"notify","color":[r,g,b,w],"period":0.4,"count":6}` | blinker (`count:-1` = until cleared) |
| `{"cmd":"notify_clear"}` | stop the blinker |
| `{"cmd":"camera","active":true}` | camera glow on/off |
| `{"cmd":"test","start":2,"count":3,"active":true}` | blink a range while configuring (auto-expires after 3 min) |
| `{"cmd":"raw","pixels":[[r,g,b,w],...]}` / `{"cmd":"raw_off"}` | direct test mode |

Custom sources: add a zone with any name (type `custom` or `bool`) and push
matching keys via `status` — CI state, mic mute, meeting status, etc.