FamReynaBrain/projects/network_usage/README.md

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

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.