POS-Automation/docs/superpowers/specs/2026-06-07-ha-google-home-trigger-design.md

# POS Briefing — Home Assistant / Google Home Trigger (Design)

Date: 2026-06-07
Status: Proposed — awaiting Seth's review

## Goal

Replace the (never-installed) cron schedule with an **on-demand** trigger: tap a
**button in Google Home** → the daily briefing prints on the Epson TM-m30. No cron.

## Background / findings (this session)

- "Not firing" had two causes, both now moot under this design: (1) no cron entry
  was ever installed on steel141 — the "schedule 4:58am/3pm" commit only edited
  SESSION.md; (2) `yfinance` was missing from steel141's system python3 →
  **installed** (`pip --user --break-system-packages`, matching lgtv's PEP-668 approach).
- The pipeline itself **works end-to-end on steel141** (verified via non-printing
  dry run, `scripts/dryrun.py`): FreshRSS 100 items, weather (the uncommitted
  hourly rewrite), finance (yfinance), and summarization all produce a ~2.4 KB
  ESC/POS receipt. `zfs`/`reddit`/`grafana` return `None` on steel141 (non-fatal;
  out of scope here — see Out of Scope).
- Printer **changes IP on every restart** (router DHCP, no reservation). Currently
  `192.168.0.184:9100`, MAC `50:57:9c:eb:0f:07` (Epson). Always on.

## Architecture

Mirrors the proven `lgtv` chain (steel141 systemd MQTT bridge + HA MQTT discovery +
free manual `google_assistant` integration).

```
[Google Home tap]
  → google_assistant integration (already wired; acct slingshooter08; exposes LG TV switch today)
  → HA script "Print Daily Briefing"  (exposed to Google as a Scene → momentary button)
  → MQTT publish to broker CT 301 (192.168.0.154:1883)
  → pos-briefing-mqtt.service on steel141 (systemd, User=claude)
  → pos_briefing.py  → printer discovery (by MAC) → ESC/POS over TCP :9100
  → status/availability published back to MQTT (HA shows success/fail)
```

## Components

### 1. MQTT bridge — `pos_briefing_mqtt.py` + `pos-briefing-mqtt.service` (new, steel141)
- systemd `Type=simple`, `User=claude`, `EnvironmentFile=/etc/pos-briefing/pos-briefing.env`
  (holds `MQTT_PASSWORD`, root-owned 0600, never committed). `Restart=on-failure`.
- Connects to broker `192.168.0.154:1883`, user `posbriefing` (or reuse an existing
  broker user — TBD at install; lgtv uses a per-device user).
- On connect: publishes **MQTT discovery** for an HA **button** entity
  (`homeassistant/button/pos_briefing/config`) + availability `online`; LWT → `offline`.
- Subscribes command topic `posbriefing/button/press` (payload `PRESS`).
- On press: runs the briefing **as a subprocess**
  (`/usr/bin/python3 /home/claude/bin/POS-Automation/pos_briefing.py`) so a slow/long
  print never blocks the MQTT loop and a script crash can't kill the bridge.
  Publishes `posbriefing/status` = `printing` → `ok` / `error:<msg>`.
- Debounce: ignore a new press while one is already in flight (prevents double prints).

Topics:
| Topic | Dir | Payload |
|-------|-----|---------|
| `homeassistant/button/pos_briefing/config` | pub (retain) | discovery JSON |
| `posbriefing/availability` | pub (retain) | `online` / `offline` (LWT) |
| `posbriefing/button/press` | sub | `PRESS` |
| `posbriefing/status` | pub (retain) | `idle` / `printing` / `ok` / `error:<msg>` |

### 2. Printer discovery (new, in `pos_briefing.py`) — kills the DHCP-IP problem
- Resolve current printer IP by **MAC `50:57:9c:eb:0f:07`** instead of trusting a
  hardcoded `printer_ip`.
- Algorithm (lgtv "cached IP, sweep on miss"):
  1. Read cached IP from `~/.cache/pos-briefing/last_ip` (seed = config `printer_ip`).
  2. `ping -c1` it, check `ip neigh` lladdr == target MAC, and `:9100` open → use it.
  3. On miss: ARP-prime sweep the /24 (`ping -c1 -W1` fan-out), then scan `ip neigh`
     for the MAC → its IP. Re-cache.
  4. Still not found → raise a clear error (bridge reports `error:printer-not-found`).
- Config gains `printer_mac`; `printer_ip` becomes a seed/fallback only.
- **Belt-and-suspenders (Seth's action, router-side):** add a DHCP reservation for
  the printer MAC so the IP stops moving. Discovery makes this optional for correctness.

### 3. HA script + Google Home exposure (Seth's HA side; I provide exact YAML/steps)
- MQTT discovery auto-creates `button.pos_briefing` (no hand YAML for the entity).
- Google's `google_assistant` integration doesn't support HA `button` entities → wrap:
  an HA `script.print_daily_briefing` that presses the button. Scripts map to Google's
  **Scene** trait → appear as a tappable **button** in the Google Home app (momentary).
- Add the script to the same `google_assistant` expose list that already exposes the
  TV switch; re-sync. (Per lgtv DECISIONS 2026-06-06: manual integration, scopes must
  include email+name, "HTTP basic auth header" OFF, Test activated by slingshooter08.)

### 4. gemma4 summarizer swap (in `pos_briefing.py`)
- Point summarization at a **gemma4 model on steel141 Ollama** (candidate
  `gemma4:26b` or `gemma4:31b-it-q4_K_M`) via the existing direct Ollama HTTP call —
  change `ollama_model` in config + the prompt string.
- **Prompt convergence:** done by Claude *now*, interactively, via the `ask_gemma4`
  MCP tool against real FreshRSS article samples, iterating until summaries are tight
  (30–50 words, factual, no preamble). The finalized prompt string is then baked into
  `pos_briefing.py` (which calls Ollama directly — it cannot call the MCP at runtime).

### 5. Deps / install
- `yfinance` — installed (done). `paho-mqtt` — present for `claude`. Confirm both
  pinned/persisted. `install.sh` mirrors lgtv: copies bridge to `/usr/local/bin`,
  unit to `/etc/systemd/system`, env to `/etc/pos-briefing/`, `daemon-reload`, enable.

## Error handling
- Printer not found / unreachable → `error:printer-not-found`; no partial print.
- Briefing subprocess nonzero exit or timeout (cap ~180s) → `error:<rc>`; bridge stays up.
- MQTT disconnect → paho auto-reconnect; LWT marks `offline` so HA/Google show it down.
- Data-source failures inside the briefing remain non-fatal (dashboard prints what it has).

## Testing
- `scripts/dryrun.py` — full pipeline, print suppressed (already used to verify).
- Bridge unit: publish `PRESS` to the command topic by hand (`mosquitto_pub`) → observe
  `status` transitions and a real receipt; confirm `button.pos_briefing` appears in HA.
- Discovery: unit-test MAC→IP resolution with cache hit, cache miss+sweep, and not-found.
- End-to-end: tap the button in Google Home → receipt prints.

## Out of scope (noted, not fixed here)
- `zfs` (steel141 isn't the tank host — `cannot open 'tank'`), `reddit`, `grafana`
  returning `None` on steel141. Track separately.
- Committing the in-tree weather rewrite is folded into this work (it's verified).

## Open items for Seth
- Broker MQTT user for the bridge: new `posbriefing` user vs reuse existing? (install-time)
- gemma4 model choice: `26b` vs `31b-it-q4_K_M` (I'll recommend after convergence).