# Pi-hole device usage reports

This directory contains a read-only daily DNS usage collector enriched with the live TP-Link Deco client map.

## Run manually

```bash
python3 /Users/adolforeyna/brain/projects/network_usage/pihole_daily_report.py --date today
python3 /Users/adolforeyna/brain/projects/network_usage/pihole_daily_report.py --date yesterday
```

Each run writes:

- `reports/YYYY-MM-DD.json` — machine-readable data
- `reports/YYYY-MM-DD.md` — human-readable report
- `network_usage.sqlite3` — the same report JSON/Markdown plus Deco identity history

The report uses `America/New_York` calendar boundaries. Pi-hole is queried over the existing owner-only SSH path in SQLite read-only mode. The live Deco client list is retrieved with the existing `reyna-cli deco clients --json` integration.

The separate storage database is `/Users/adolforeyna/brain/projects/network_usage/network_usage.sqlite3`. It contains:

- `deco_snapshots` — timestamped client-list captures
- `deco_clients` — the IP/MAC/hostname/location rows for each capture
- `daily_reports` — the completed report JSON and Markdown

## Automation

`/Users/adolforeyna/.hermes/scripts/network_usage_daily_report.py` is the deterministic wrapper used by the Hermes scheduled job. It processes the previous local calendar day, stores the completed report in SQLite, writes one JSON/Markdown pair per day, and then removes raw Deco snapshots older than the current day. Reports remain available in the `daily_reports` table. It does not change Pi-hole, DNS, Deco, blocklists, or router settings.

`/Users/adolforeyna/.hermes/scripts/deco_snapshot_10m.py` runs every ten minutes and appends the live Deco client list to SQLite. This preserves enough same-day IP-to-MAC history to map Pi-hole clients that are offline when the daily report runs.

## Grouping plan

The report grouping layer should treat all `espressif` clients as one ESP32 group and both `Google-Home-Mini` clients as one household group. iPhone and Mac ownership remains unassigned until the LAN names are confirmed; MAC addresses remain the identity key underneath those friendly names.

“Top visited” excludes Pi-hole blocked statuses. “Top blocked” counts FTL blocked statuses, including gravity, regex, denylist, external blocking, and CNAME blocking. A device may appear in Pi-hole but not in the live Deco list if it is currently offline, has changed its IP, or is not in the current client snapshot; those entries are labeled accordingly rather than guessed.

## Roku/Casita assessment

The current live map identifies `50CasitaTv` at `192.168.68.114`, connected through the `Casita` Deco. The current report shows Roku log traffic already being blocked, especially `liberty.logs.roku.com` and `scribe.logs.roku.com`. A seven-day Pi-hole query inspection also found these Roku-adjacent domains allowed from the Roku devices:

- `display.ravm.tv` — promotional/display service candidate
- `identity.ads.roku.com` — advertising identity candidate
- `api.roku.com`, `themes-service.sr.roku.com`, and other Roku service domains — do not block as ad domains without testing

`ads.roku.com` is already present in one installed blocklist according to `pihole -q`; it was not queried by the Casita TV during the inspection window. On September 4, 2026, the two locally managed exact deny entries `display.ravm.tv` and `identity.ads.roku.com` were added with the comment `Roku ads`. The change was verified with `pihole -q` and live DNS lookups returning `0.0.0.0` for both domains.

DNS blocking can reduce home-screen/promotional ad retrieval but cannot guarantee that all inappropriate content disappears, and it may leave empty tiles or affect Roku UI behavior. No other Roku service domains were changed.

A safe next experiment is a dedicated Pi-hole client group containing only `50CasitaTv`, with a reviewed Roku candidate list and rollback available. That should be staged and tested only after explicit approval.