Pi Scanner

Discover, catalog, and monitor Raspberry Pi devices on a home LAN by MAC address (OUI matching), with a persistent CSV catalog, a web dashboard, and a merge tool for combining catalogs scanned from multiple machines.

Files

• pi_discover.py — CLI scanner. Discovers hosts on the local subnet (via arp-scan, falling back to nmap/ping-sweep + the kernel's ARP cache), flags Raspberry Pi hardware by matching MAC OUI prefixes, and maintains a persistent catalog CSV keyed by MAC address.
• webapp.py — Flask dashboard on top of the same catalog: live online/offline status, a Pi-only/all-hosts toggle, a Rescan button, CSV and JSON export, and hand-editable per-device hardware fields (type / RAM / disk).
• merge_catalogs.sh — merges two catalog CSVs (e.g. from two different scanning machines) into one, matched by MAC, preferring hand-edited hardware fields over blank ones and the more recently-seen data for everything else.

Prerequisites

• Python 3 (both scripts are stdlib-only except Flask — no pip install needed for pi_discover.py or merge_catalogs.sh)
• pip install flask --break-system-packages — only required for webapp.py
• arp-scan (recommended) — gives the fastest, most complete scans and real MAC addresses without needing root, once granted the raw-socket capability once:

  sudo dnf install arp-scan        # Fedora etc.
  sudo apt install arp-scan        # Debian/Ubuntu/Raspberry Pi OS
  sudo setcap cap_net_raw+eip $(which arp-scan)
  

  Without arp-scan, both tools fall back to nmap (if installed) or a pure-Python ping sweep, reading MAC addresses from the kernel's own ARP cache — slower, and won't get MAC addresses at all on OSes that block reading /proc/net/arp unprivileged (e.g. unrooted Android).
• Linux only. Both scripts shell out to ip, ping, and optionally avahi-resolve for hostname lookups.

Usage

# One-off scan, prints the catalog (Pi-only by default)
./pi_discover.py

# Force a specific interface/subnet, show every host, save a JSON snapshot
./pi_discover.py -i eth0 -s 192.168.1.0/24 --all --json scan.json

# Web dashboard (needs Flask; webapp.py must sit next to pi_discover.py)
python3 webapp.py                       # http://<host>:5000
sudo python3 webapp.py                  # if arp-scan needs root instead of setcap

# Merge catalogs from two machines
./merge_catalogs.sh fedora_catalog.csv pi5_catalog.csv merged_catalog.csv

The catalog lives at ~/.local/share/pi_discover/catalog.csv by default (override with --db / webapp.py --db). It's a plain CSV, keyed by MAC address, safe to inspect, edit by hand, back up, or merge.

Notes

• Detection is MAC-OUI based, so a Pi reachable only through a non-Pi network interface (a USB Ethernet dongle, a carrier board's added NIC chip, etc.) won't be auto-detected — use the hardware-info fields in the web dashboard to annotate it manually if needed.
• Rescans never overwrite hand-edited hardware fields; only the merge script and the web UI's Edit mode touch them.