wifi-observer 0.1.0__py3-none-any.whl

wifi_observer-0.1.0.dist-info/METADATA

@@ -0,0 +1,391 @@
+Metadata-Version: 2.4
+Name: wifi-observer
+Version: 0.1.0
+Summary: Terminal tool that monitors internet reachability and WiFi signal strength once per second, with a live UI, JSON logging, and matplotlib graphs.
+Author: biswanathamz
+License: MIT
+Project-URL: Homepage, https://github.com/biswanathamz/wifi-observer
+Project-URL: Repository, https://github.com/biswanathamz/wifi-observer
+Project-URL: Issues, https://github.com/biswanathamz/wifi-observer/issues
+Keywords: wifi,network,monitor,ping,latency,signal,terminal,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: graph
+Requires-Dist: matplotlib; extra == "graph"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# 📶 WiFi Observer
+
+**A terminal tool that tells you — every second — whether your problem is the _internet_ or your _WiFi_.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
+[![Platform: Linux](https://img.shields.io/badge/platform-Linux-lightgrey.svg)](#requirements)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
+[![Made with: Python & Bash](https://img.shields.io/badge/made%20with-Python%20%26%20Bash-1f425f.svg)](#how-it-works)
+
+</div>
+
+WiFi Observer continuously monitors two **independent** things — internet
+reachability (via ping) and WiFi signal strength (in dBm) — so you can tell *why*
+your connection is bad, not just *that* it is. It runs entirely in your terminal,
+keeps a live history in memory, logs every sample to JSON, and draws a graph of
+the session. Built with the Python standard library + Bash; the only optional
+dependency is matplotlib (for graphs), installed automatically on first run.
+
+---
+
+## 📑 Table of contents
+
+- [Why](#why)
+- [Demo](#demo)
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [How it works](#how-it-works)
+- [Output & file formats](#output--file-formats)
+- [Reading the numbers](#reading-the-numbers)
+- [Project structure](#project-structure)
+- [Requirements](#requirements)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why
+
+A plain ping test lumps two different failures together. WiFi Observer separates
+them:
+
+| WiFi signal | Internet | Likely culprit |
+|-------------|----------|----------------|
+| Strong & stable | Down / lossy | **ISP / router** — not your WiFi |
+| Weak / unstable | Down / lossy | **Your WiFi** — distance, walls, interference |
+| Strong & stable | Fine | All good ✅ |
+
+So instead of "the internet is slow," you get an answer you can act on.
+
+---
+
+## Demo
+
+```
+┌─ WiFi Observer ───────────────────────────────────────────┐
+ SSID: HomeNet-5G   iface: wlan0
+ elapsed: 00:04:12   remaining: 00:05:48
+ log → logs/2026-06-28/wifi-215205.jsonl
+
+ INTERNET   ● UP     target 8.8.8.8
+   latency : last 23.4 ms   avg 26.1   min 18.0   max 142.0 ms
+   quality : packet loss  0.8%  (2/250)   jitter 5.2 ms
+   outages : 2   downtime 00:04   longest 00:03
+
+ WIFI SIGNAL   -47 dBm (Excellent)
+   stability : STABLE  (±1.8 dBm)   min -52   max -44   avg -47.3 dBm
+
+ latency  ▁▂▃█▂▂▃▃▂·▂▃▂▂   (· = a probe with no reply / outage)
+ signal   ▅▅▆▆▅▅▄▅▅▆▆▅▄▅
+└────────────────────────────────────────────────────────────┘
+ [g] save graph    [q] quit    (Ctrl+C also quits)
+```
+
+The exported graph stacks **internet latency** (outages marked in red) over
+**WiFi signal strength** (with quality reference lines), sharing a time axis.
+
+> 💡 Tip: drop a real screenshot/GIF here (e.g. `docs/demo.png`) before publishing.
+
+---
+
+## Features
+
+- 📡 **Two metrics at once** — internet reachability *and* WiFi signal, sampled every second.
+- 🖥️ **Live terminal UI** — single self-refreshing screen with two labelled sections and sparklines.
+- ⏱️ **Pick a duration on start** — 1 min / 10 min / 1 hr / until you close it, with a live countdown.
+- ⌨️ **Interactive keys** — `g` saves a graph instantly, `q` quits.
+- 📝 **JSON logging** — every sample appended (JSON-lines), crash-safe.
+- 📊 **Graphs ("maps")** — matplotlib charts generated from inside the app and on exit.
+- 🗂️ **Date-organised output** — logs, summary, and graph grouped under `logs/YYYY-MM-DD/`.
+- 🔧 **Near-zero setup** — monitor is stdlib-only; matplotlib is auto-installed into a local `.venv`.
+- 🛟 **Degrades gracefully** — no colours? no matplotlib? not a TTY? It still runs and tells you.
+
+---
+
+## Installation
+
+```bash
+# 1. Clone
+git clone https://github.com/biswanathamz/wifi-observer.git
+cd wifi-observer
+
+# 2. Run — that's it.
+./run.sh
+```
+
+There is **no build step**. The monitor uses only the Python 3 standard library
+and the system `ping`. The first run bootstraps a local `.venv` and installs
+`matplotlib` so graphs work (skip with `./run.sh --no-graph-setup`).
+
+> Prefer to manage deps yourself? `pip install matplotlib` and run
+> `python3 wifi_observer.py` directly.
+
+### Install as a command (optional)
+
+Install it as a proper CLI so `wifi-observer` is on your `PATH`:
+
+```bash
+pip install .                 # core only (stdlib monitor)
+pip install '.[graph]'        # + matplotlib, for the `g` graph feature
+wifi-observer --help
+```
+
+Without the `graph` extra the monitor still runs fully; graphs are simply
+skipped until matplotlib is present.
+
+---
+
+## Usage
+
+```bash
+./run.sh                      # ping 8.8.8.8 every 1s
+./run.sh -H 1.1.1.1 -i 2      # ping Cloudflare, every 2 seconds
+./run.sh -H 192.168.1.1       # ping your router (tests the LAN link only)
+./run.sh --no-color           # plain text
+./run.sh --help               # full option list
+```
+
+**On start**, choose how long to run:
+
+```
+WiFi Observer — how long should it run?
+   [1] 1 minute
+   [2] 10 minutes
+   [3] 1 hour
+   [4] Until I close it
+Select 1-4 (default 4):
+```
+
+**While running**, the UI is interactive:
+
+| Key | Action |
+|-----|--------|
+| `g` | Generate & save a graph (PNG) right now |
+| `q` | Quit and print the session summary |
+| `Ctrl+C` | Also quits cleanly |
+
+A graph is **also saved automatically on exit**, and everything lands under
+`logs/<today>/`.
+
+---
+
+## Configuration
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-H, --host` | `8.8.8.8` | Host/IP to ping (an IP avoids DNS; a hostname is resolved by `ping`). |
+| `-i, --interval` | `1.0` | Seconds between samples. |
+| `-t, --timeout` | `1.0` | Per-ping timeout (s) → a slow/no reply counts as DOWN. |
+| `-n, --history` | `3600` | Samples kept in memory for the live UI / sparklines. |
+| `--log PATH` | auto | Custom JSON-lines log path (default `logs/<date>/wifi-<time>.jsonl`). |
+| `--no-log` | off | Disable JSON logging. |
+| `--no-color` | off | Plain text, no ANSI colours. |
+| `--no-graph-setup` | off | *(run.sh)* Skip the matplotlib `.venv` bootstrap. |
+
+---
+
+## How it works
+
+### Architecture
+
+| File | Language | Role |
+|------|----------|------|
+| [run.sh](run.sh) | Bash | Checks deps, bootstraps matplotlib into `.venv`, launches the app. |
+| [wifi_observer.py](wifi_observer.py) | Python | Monitor loop, measurements, statistics, interactive UI, JSON logging. |
+| [wifi_observer_plot.py](wifi_observer_plot.py) | Python | Builds the matplotlib figure; used by the app and standalone. |
+
+### The per-second cycle
+
+1. **Ping** the host once → reachable? + latency.
+2. **Read WiFi signal** from `/proc/net/wireless` → dBm + link quality.
+3. Build a sample record and append it to the **in-memory history** and the **JSON log**.
+4. Update **running statistics** incrementally (counts, sums, sums-of-squares).
+5. **Redraw** the UI.
+6. Wait out the interval while **polling the keyboard** for `g`/`q`.
+
+### How the ping works
+
+No hand-rolled ICMP — it runs the system `ping`:
+
+```
+ping -c 1 -W <timeout> <host>
+```
+
+`-c 1` sends one echo request; `-W` is the reply timeout. UP/DOWN is decided from
+ping's **exit code** (0 = reply); latency is parsed from the output (`time=23.4 ms`)
+with a regex. Because the OS `ping` already holds the ICMP privilege, **no `sudo`
+is needed**. The call is wrapped so a hang or failure can never crash the loop — it
+just records a DOWN sample.
+
+### How the WiFi signal is read
+
+The kernel exposes live wireless stats as text in `/proc/net/wireless`. The program
+parses the active interface's row for **link quality** (≈ out of 70 → a 0–100 %
+figure) and **signal level in dBm**. No external command, no privileges.
+
+### Statistics
+
+Aggregates are maintained incrementally so each tick is O(1) no matter how long
+you run: uptime %, packet loss %, latency avg/min/max, **jitter** (latency
+std-dev), outage count/total/longest, and signal avg/min/max with **std-dev**
+(which drives the stability verdict).
+
+History is a bounded `deque` (default last **3600** samples ≈ 1 h), so memory stays
+capped — while the **JSON log keeps the full session** on disk, and graphs are
+built from that log.
+
+---
+
+## Output & file formats
+
+Each run writes into a **date folder**, all artifacts sharing one basename:
+
+```
+logs/
+└── 2026-06-28/
+    ├── wifi-215205.jsonl         # one JSON object per sample
+    ├── wifi-215205.summary.json  # session aggregates
+    └── wifi-215205.png           # the graph ("map")
+```
+
+**Per-sample log line** (`.jsonl`):
+
+```json
+{"ts": 1782662252.80, "time": "2026-06-28T21:27:32.802", "internet_up": true,
+ "latency_ms": 47.8, "signal_dbm": -63.0, "signal_quality": 67.1, "ssid": "HomeNet-5G"}
+```
+
+**Summary** (`.summary.json`) — start/end/duration, config, plus `internet` and
+`wifi_signal` blocks (uptime %, packet loss, latency stats, outages, signal
+avg/min/max/stddev/stability).
+
+Re-plot any old log standalone:
+
+```bash
+python3 wifi_observer_plot.py                              # newest log → <log>.png
+python3 wifi_observer_plot.py logs/2026-06-28/wifi-215205.jsonl -o report.png --show
+```
+
+---
+
+## Reading the numbers
+
+**WiFi signal (dBm)** — higher (closer to 0) is better:
+
+| dBm | Label | Meaning |
+|-----|-------|---------|
+| ≥ -50 | Excellent | Right next to the router |
+| -50 to -60 | Good | Solid, reliable |
+| -60 to -67 | Fair | Usable; HD video fine |
+| -67 to -75 | Weak | Drops/slowdowns likely |
+| < -75 | Very weak | Often unusable |
+
+**Stability** (from signal std-dev): `STABLE` < 3 dBm, `FLUCTUATING` < 6 dBm,
+`UNSTABLE` ≥ 6 dBm. **Latency / jitter / packet loss** — lower is better; high
+jitter hurts calls/gaming even when average latency looks fine.
+
+---
+
+## Project structure
+
+```
+wifi-observer/
+├── doc/
+│   └── SPEC.md              # full specification
+├── run.sh                   # Bash launcher (+ matplotlib venv bootstrap)
+├── wifi_observer.py         # Python monitor, UI, logging
+├── wifi_observer_plot.py    # matplotlib figure builder (UI + standalone)
+├── LICENSE                  # MIT
+├── README.md
+├── .venv/                   # auto-created on first run        [git-ignored]
+└── logs/                    # date folders of output           [git-ignored]
+```
+
+---
+
+## Requirements
+
+- **Linux** with `python3` (3.8+) and `ping` on `PATH`. The monitor itself is
+  **standard-library only**.
+- **WiFi signal** needs `/proc/net/wireless` (standard on Linux WiFi). SSID/
+  interface detection uses `iwgetid`/`nmcli` when present; otherwise it shows `?`.
+- **matplotlib** — only for graphs; `run.sh` installs it into a local `.venv` on
+  first run (needs `python3-venv` + network once). Skip with `--no-graph-setup`.
+
+> **Platform note:** Linux-focused. The `ping` flags and signal reading target
+> Linux; macOS/Windows support would need contributions (see the roadmap).
+
+---
+
+## Roadmap
+
+Ideas and good first contributions:
+
+- [ ] macOS / Windows support (`ping` flags + signal reading)
+- [ ] Optional gateway probe to pinpoint LAN-vs-WAN faults
+- [ ] DNS-resolution check (distinguish "internet down" from "DNS down")
+- [ ] Desktop notification on outage start / recovery
+- [ ] CSV export and a `--summary-only` headless mode
+- [ ] Configurable thresholds (signal labels, stability bands)
+
+Found a bug or want a feature? Please [open an issue](../../issues).
+
+---
+
+## Contributing
+
+Contributions are welcome! 🎉
+
+1. **Fork** the repo and create a branch: `git checkout -b feature/my-change`.
+2. **Make your change.** Keep the monitor **standard-library only** (matplotlib is
+   fine to import *lazily* inside `wifi_observer_plot.py`). Match the existing style.
+3. **Test it** — run `./run.sh` and verify the live UI, logging, and a generated
+   graph. For unreachable-host behaviour, try `./run.sh -H 192.0.2.1` (TEST-NET).
+4. **Commit** with a clear message and **open a Pull Request** describing what and
+   why.
+
+Please keep changes focused, document new flags in the README, and be kind in
+code review. By contributing, you agree your work is licensed under the project's
+MIT license.
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE) — free to use, modify, and distribute
+with attribution. © 2026 biswanathamz.
+
+<div align="center">
+
+⭐ If this saved you a frustrating "is it me or the internet?" moment, consider starring the repo.
+
+</div>

wifi_observer-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+wifi_observer.py,sha256=XcVupLAItwIuXwiGwmXBMd3npNzrMrnltEKT-RpsKMs,25097
+wifi_observer_plot.py,sha256=Bc6cKVQk7vAvQJWXEl-QVFQfVCTlGxuXJ9PmEQ8piWI,5086
+wifi_observer-0.1.0.dist-info/licenses/LICENSE,sha256=pCxO2maGZZtmtxS4sOnpvBnEvwopdbLnPFPSnwTkNm0,1069
+wifi_observer-0.1.0.dist-info/METADATA,sha256=ocDlTbTPz7ZL_t9a6e9nhIqhMLyKNkC-H_7QbHn85do,14253
+wifi_observer-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+wifi_observer-0.1.0.dist-info/entry_points.txt,sha256=PrtzvZU3kWJMhdNMpoH35HF2SFC_vHuP9fKbMcIS5Zc,53
+wifi_observer-0.1.0.dist-info/top_level.txt,sha256=I9MMq84fqBOrwGjgTjN7Gn9HzlswjkNrYEYYnIHlqeg,33
+wifi_observer-0.1.0.dist-info/RECORD,,

wifi_observer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wifi_observer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wifi-observer = wifi_observer:main

wifi_observer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 biswanathamz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wifi_observer-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+wifi_observer
+wifi_observer_plot

wifi_observer.py

@@ -0,0 +1,652 @@
+#!/usr/bin/env python3
+"""WiFi Observer — terminal-based connectivity & signal monitor.
+
+Each interval it measures two independent things:
+
+  1. INTERNET  — pings a reliable host (default 8.8.8.8, Google DNS) to tell
+     whether the internet is reachable, and how fast (latency, packet loss).
+  2. WIFI SIGNAL — reads the radio signal strength in dBm from the adapter
+     (/proc/net/wireless) to tell whether the WiFi link is strong and stable.
+
+Every sample is appended to a JSON-lines log, and a summary JSON is written on
+exit. Use plot.py to render graphs from the log with matplotlib.
+
+Core uses the Python 3 stdlib + system `ping` only. See doc/SPEC.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import datetime as dt
+import json
+import math
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import asdict, dataclass
+
+
+# --------------------------------------------------------------------------- #
+# Data model
+# --------------------------------------------------------------------------- #
+@dataclass
+class Probe:
+    ts: float                       # epoch seconds
+    time: str                       # ISO-8601 local timestamp (for the log)
+    internet_up: bool               # internet host reachable?
+    latency_ms: float | None        # round-trip ms (None when down)
+    signal_dbm: float | None        # WiFi signal level in dBm (None if unknown)
+    signal_quality: float | None    # link quality 0-100% (None if unknown)
+    ssid: str                       # network name at sample time
+
+
+def _stddev(n: int, s: float, ss: float) -> float:
+    """Population standard deviation from count, sum, sum-of-squares."""
+    if n < 2:
+        return 0.0
+    var = (ss - s * s / n) / n
+    return math.sqrt(var) if var > 0 else 0.0
+
+
+class Stats:
+    """Incrementally-maintained session aggregates for both metrics."""
+
+    def __init__(self) -> None:
+        # --- internet ---
+        self.total = 0
+        self.up_count = 0
+        self.down_count = 0
+        self.outages = 0
+        self.downtime_s = 0.0
+        self.longest_outage_s = 0.0
+        self.lat_last: float | None = None
+        self.lat_min: float | None = None
+        self.lat_max: float | None = None
+        self._lat_n = 0
+        self._lat_s = 0.0
+        self._lat_ss = 0.0
+        # streak / outage bookkeeping
+        self.current_up: bool | None = None
+        self.streak_start = time.time()
+        self._cur_outage_start: float | None = None
+
+        # --- wifi signal (dBm) ---
+        self.sig_last: float | None = None
+        self.sig_min: float | None = None
+        self.sig_max: float | None = None
+        self._sig_n = 0
+        self._sig_s = 0.0
+        self._sig_ss = 0.0
+
+    # ---- internet derived ----
+    @property
+    def lat_avg(self) -> float | None:
+        return self._lat_s / self._lat_n if self._lat_n else None
+
+    @property
+    def lat_jitter(self) -> float:
+        return _stddev(self._lat_n, self._lat_s, self._lat_ss)
+
+    @property
+    def uptime_pct(self) -> float:
+        return 100.0 * self.up_count / self.total if self.total else 0.0
+
+    @property
+    def loss_pct(self) -> float:
+        return 100.0 * self.down_count / self.total if self.total else 0.0
+
+    # ---- signal derived ----
+    @property
+    def sig_avg(self) -> float | None:
+        return self._sig_s / self._sig_n if self._sig_n else None
+
+    @property
+    def sig_std(self) -> float:
+        return _stddev(self._sig_n, self._sig_s, self._sig_ss)
+
+    def add(self, p: Probe) -> None:
+        self.total += 1
+
+        # --- internet ---
+        if p.internet_up:
+            self.up_count += 1
+            self.lat_last = p.latency_ms
+            if p.latency_ms is not None:
+                self._lat_n += 1
+                self._lat_s += p.latency_ms
+                self._lat_ss += p.latency_ms * p.latency_ms
+                self.lat_min = p.latency_ms if self.lat_min is None else min(self.lat_min, p.latency_ms)
+                self.lat_max = p.latency_ms if self.lat_max is None else max(self.lat_max, p.latency_ms)
+        else:
+            self.down_count += 1
+            self.lat_last = None
+
+        if self.current_up is None:
+            self.current_up = p.internet_up
+            self.streak_start = p.ts
+            if not p.internet_up:
+                self.outages += 1
+                self._cur_outage_start = p.ts
+        elif p.internet_up != self.current_up:
+            self.current_up = p.internet_up
+            self.streak_start = p.ts
+            if not p.internet_up:
+                self.outages += 1
+                self._cur_outage_start = p.ts
+            else:
+                self._cur_outage_start = None
+
+        if not p.internet_up and self._cur_outage_start is not None:
+            self.longest_outage_s = max(self.longest_outage_s, p.ts - self._cur_outage_start)
+
+        # --- signal ---
+        if p.signal_dbm is not None:
+            self.sig_last = p.signal_dbm
+            self._sig_n += 1
+            self._sig_s += p.signal_dbm
+            self._sig_ss += p.signal_dbm * p.signal_dbm
+            self.sig_min = p.signal_dbm if self.sig_min is None else min(self.sig_min, p.signal_dbm)
+            self.sig_max = p.signal_dbm if self.sig_max is None else max(self.sig_max, p.signal_dbm)
+
+
+# --------------------------------------------------------------------------- #
+# Measurements
+# --------------------------------------------------------------------------- #
+_LAT_RE = re.compile(r"time[=<]\s*([\d.]+)\s*ms")
+
+
+def ping_once(host: str, timeout: float) -> tuple[bool, float | None]:
+    """Single ping. Returns (reachable, latency_ms)."""
+    timeout_s = max(1, int(round(timeout)))
+    cmd = ["ping", "-c", "1", "-W", str(timeout_s), host]
+    try:
+        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                              timeout=timeout + 2.0, text=True)
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return False, None
+    if proc.returncode != 0:
+        return False, None
+    m = _LAT_RE.search(proc.stdout)
+    return True, (float(m.group(1)) if m else None)
+
+
+def read_wifi_signal(iface: str) -> tuple[float | None, float | None]:
+    """Read (signal_dbm, quality_pct) from /proc/net/wireless. No root needed."""
+    try:
+        with open("/proc/net/wireless", encoding="utf-8") as f:
+            lines = f.readlines()
+    except OSError:
+        return None, None
+    for line in lines[2:]:                      # skip the two header rows
+        if ":" not in line:
+            continue
+        name, rest = line.split(":", 1)
+        name = name.strip()
+        if iface not in ("?", "") and name != iface:
+            continue
+        parts = rest.split()
+        if len(parts) < 3:
+            continue
+        try:
+            quality = float(parts[1].rstrip("."))   # link quality (often /70)
+            level = float(parts[2].rstrip("."))      # signal level in dBm
+        except ValueError:
+            continue
+        quality_pct = max(0.0, min(100.0, quality / 70.0 * 100.0))
+        return level, quality_pct
+    return None, None
+
+
+def signal_label(dbm: float | None) -> str:
+    if dbm is None:
+        return "n/a"
+    if dbm >= -50: return "Excellent"
+    if dbm >= -60: return "Good"
+    if dbm >= -67: return "Fair"
+    if dbm >= -75: return "Weak"
+    return "Very weak"
+
+
+def stability_label(std: float, samples: int) -> str:
+    if samples < 3:
+        return "…"
+    if std < 3.0:  return "STABLE"
+    if std < 6.0:  return "FLUCTUATING"
+    return "UNSTABLE"
+
+
+# --------------------------------------------------------------------------- #
+# Environment discovery (best-effort, non-fatal)
+# --------------------------------------------------------------------------- #
+def detect_ssid() -> str:
+    for cmd in (["iwgetid", "-r"], ["nmcli", "-t", "-f", "active,ssid", "dev", "wifi"]):
+        try:
+            out = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                                 text=True, timeout=2.0).stdout.strip()
+        except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+            continue
+        if not out:
+            continue
+        if cmd[0] == "nmcli":
+            for line in out.splitlines():
+                if line.startswith("yes:"):
+                    return line.split(":", 1)[1] or "?"
+            continue
+        return out
+    return "?"
+
+
+def detect_iface() -> str:
+    try:
+        out = subprocess.run(["iwgetid"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                             text=True, timeout=2.0).stdout
+        if out:
+            return out.split()[0]
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired, IndexError):
+        pass
+    # Fall back to the first wireless interface present.
+    try:
+        with open("/proc/net/wireless", encoding="utf-8") as f:
+            for line in f.readlines()[2:]:
+                if ":" in line:
+                    return line.split(":", 1)[0].strip()
+    except OSError:
+        pass
+    return "?"
+
+
+# --------------------------------------------------------------------------- #
+# UI helpers
+# --------------------------------------------------------------------------- #
+class Colors:
+    def __init__(self, enabled: bool) -> None:
+        self.enabled = enabled
+
+    def _w(self, code: str, s: str) -> str:
+        return f"\033[{code}m{s}\033[0m" if self.enabled else s
+
+    def green(self, s):  return self._w("32", s)
+    def red(self, s):    return self._w("31", s)
+    def yellow(self, s): return self._w("33", s)
+    def cyan(self, s):   return self._w("36", s)
+    def dim(self, s):    return self._w("2", s)
+    def bold(self, s):   return self._w("1", s)
+
+
+_SPARKS = "▁▂▃▄▅▆▇█"
+
+
+def spark_series(values: list, width: int, miss: str = "·") -> str:
+    """Render numeric series as blocks; None entries become `miss`."""
+    items = values[-width:]
+    nums = [v for v in items if v is not None]
+    if not nums:
+        return miss * len(items)
+    lo, hi = min(nums), max(nums)
+    span = (hi - lo) or 1.0
+    out = []
+    for v in items:
+        if v is None:
+            out.append(miss)
+        else:
+            idx = int((v - lo) / span * (len(_SPARKS) - 1))
+            out.append(_SPARKS[min(max(idx, 0), len(_SPARKS) - 1)])
+    return "".join(out)
+
+
+def fmt_duration(seconds: float) -> str:
+    seconds = int(seconds)
+    h, rem = divmod(seconds, 3600)
+    m, s = divmod(rem, 60)
+    return f"{h:02d}:{m:02d}:{s:02d}" if h else f"{m:02d}:{s:02d}"
+
+
+def fmt_ms(v: float | None) -> str:
+    return f"{v:.1f}" if v is not None else "--"
+
+
+def fmt_dbm(v: float | None) -> str:
+    return f"{v:.0f}" if v is not None else "--"
+
+
+HIDE_CURSOR, SHOW_CURSOR, CLEAR_HOME = "\033[?25l", "\033[?25h", "\033[H\033[J"
+
+
+# --------------------------------------------------------------------------- #
+# Interactive input
+# --------------------------------------------------------------------------- #
+DURATION_CHOICES = [
+    ("1", "1 minute", 60),
+    ("2", "10 minutes", 600),
+    ("3", "1 hour", 3600),
+    ("4", "Until I close it", None),
+]
+
+
+def choose_duration(c: "Colors"):
+    """Prompt the user for how long to run. Returns seconds, or None for forever."""
+    if not sys.stdin.isatty():
+        return None                          # non-interactive: run until stopped
+    print(c.bold("WiFi Observer") + " — how long should it run?")
+    for key, label, _ in DURATION_CHOICES:
+        print(f"   [{key}] {label}")
+    while True:
+        try:
+            choice = input(c.cyan("Select 1-4 ") + "(default 4): ").strip() or "4"
+        except EOFError:
+            return None
+        for key, _, dur in DURATION_CHOICES:
+            if choice == key:
+                return dur
+        print("   Please enter 1, 2, 3, or 4.")
+
+
+class KeyReader:
+    """Context manager for non-blocking single-key reads from the terminal."""
+
+    def __init__(self) -> None:
+        self.enabled = sys.stdin.isatty()
+        self._fd = None
+        self._old = None
+
+    def __enter__(self) -> "KeyReader":
+        if self.enabled:
+            import termios
+            import tty
+            try:
+                self._fd = sys.stdin.fileno()
+                self._old = termios.tcgetattr(self._fd)
+                tty.setcbreak(self._fd)
+            except (termios.error, OSError):
+                self.enabled = False
+        return self
+
+    def __exit__(self, *exc) -> None:
+        if self._old is not None:
+            import termios
+            try:
+                termios.tcsetattr(self._fd, termios.TCSADRAIN, self._old)
+            except (termios.error, OSError):
+                pass
+
+    def poll(self, timeout: float):
+        """Wait up to `timeout`s for a keypress; return the char or None."""
+        if not self.enabled:
+            if timeout > 0:
+                time.sleep(timeout)
+            return None
+        import select
+        try:
+            ready, _, _ = select.select([sys.stdin], [], [], max(0.0, timeout))
+        except (OSError, ValueError):
+            return None
+        return sys.stdin.read(1) if ready else None
+
+
+def generate_graph(history, log_path, graph_path):
+    """Render a graph from the full log (or in-memory history). Returns (ok, msg)."""
+    import wifi_observer_plot as plot
+    if log_path and os.path.isfile(log_path):
+        rows = plot.load(log_path)           # full session, even beyond memory cap
+    else:
+        rows = [asdict(p) for p in history]
+    if not rows:
+        return False, "no data to plot yet"
+    os.makedirs(os.path.dirname(graph_path) or ".", exist_ok=True)
+    try:
+        plot.build_figure(rows, graph_path)
+    except ImportError:
+        return False, "matplotlib not installed — run: pip install matplotlib"
+    except Exception as exc:                  # never let plotting crash the monitor
+        return False, f"graph error: {exc}"
+    return True, f"graph saved → {graph_path}"
+
+
+def render(cfg, stats: Stats, history, ssid, iface, started, log_path,
+           duration_s, status, c: Colors) -> str:
+    now = time.time()
+    cols = shutil.get_terminal_size((80, 24)).columns
+    inner = max(48, min(cols, 76))
+    spark_w = max(20, inner - 14)
+
+    if duration_s is None:
+        time_left = c.dim("mode: until closed")
+    else:
+        time_left = "remaining: " + fmt_duration(max(0.0, duration_s - (now - started)))
+
+    # Internet status
+    if stats.current_up is None:
+        net = c.dim("… starting")
+    elif stats.current_up:
+        net = c.green("● UP  ")
+    else:
+        net = c.red("● DOWN")
+    lat = stats.lat_last
+    lat_str = c.red("--") if lat is None else (c.yellow(fmt_ms(lat)) if lat > 150 else fmt_ms(lat))
+
+    # Signal status
+    dbm = stats.sig_last
+    lab = signal_label(dbm)
+    if dbm is None:
+        sig_str = c.dim("-- dBm (n/a)")
+    elif dbm >= -60:
+        sig_str = c.green(f"{fmt_dbm(dbm)} dBm ({lab})")
+    elif dbm >= -75:
+        sig_str = c.yellow(f"{fmt_dbm(dbm)} dBm ({lab})")
+    else:
+        sig_str = c.red(f"{fmt_dbm(dbm)} dBm ({lab})")
+
+    stab = stability_label(stats.sig_std, stats._sig_n)
+    stab_str = {"STABLE": c.green, "FLUCTUATING": c.yellow, "UNSTABLE": c.red}.get(
+        stab, c.dim)(stab)
+
+    lat_spark = spark_series([p.latency_ms if p.internet_up else None for p in history], spark_w)
+    sig_spark = spark_series([p.signal_dbm for p in history], spark_w)
+    if c.enabled:
+        lat_spark = "".join(c.red("·") if ch == "·" else ch for ch in lat_spark)
+
+    bar = "─" * (inner - 2)
+    lines = [
+        c.cyan("┌─ WiFi Observer " + bar[15:] + "┐"),
+        f" SSID: {c.bold(ssid)}   iface: {iface}",
+        f" elapsed: {fmt_duration(now - started)}   {time_left}",
+        c.dim(f" log → {log_path}"),
+        "",
+        c.bold(" INTERNET") + f"   {net}   target {cfg.host}",
+        f"   latency : last {lat_str} ms   avg {fmt_ms(stats.lat_avg)}"
+        f"   min {fmt_ms(stats.lat_min)}   max {fmt_ms(stats.lat_max)} ms",
+        f"   quality : packet loss {stats.loss_pct:4.1f}%  ({stats.down_count}/{stats.total})"
+        f"   jitter {stats.lat_jitter:.1f} ms",
+        f"   outages : {stats.outages}   downtime {fmt_duration(stats.downtime_s)}"
+        f"   longest {fmt_duration(stats.longest_outage_s)}",
+        "",
+        c.bold(" WIFI SIGNAL") + f"   {sig_str}",
+        f"   stability : {stab_str}  (±{stats.sig_std:.1f} dBm)"
+        f"   min {fmt_dbm(stats.sig_min)}   max {fmt_dbm(stats.sig_max)}   avg {fmt_dbm(stats.sig_avg)} dBm",
+        "",
+        f" latency  {lat_spark}",
+        f" signal   {sig_spark}",
+        c.cyan("└" + "─" * (inner - 2) + "┘"),
+        " " + c.bold("[g]") + c.dim(" save graph    ") + c.bold("[q]") + c.dim(" quit    ")
+        + c.dim("(Ctrl+C also quits)"),
+        (" " + c.yellow(status)) if status else "",
+    ]
+    return CLEAR_HOME + "\n".join(lines) + "\n"
+
+
+def print_summary(stats: Stats, started, log_path, summary_path, graph_msg, c: Colors) -> None:
+    now = time.time()
+    if c.enabled:
+        sys.stdout.write(SHOW_CURSOR)
+    print()
+    print(c.bold("── Session summary ─────────────────────────────"))
+    print(f" duration     : {fmt_duration(now - started)}")
+    print(" INTERNET")
+    print(f"   uptime     : {stats.uptime_pct:.1f}%   packet loss {stats.loss_pct:.1f}%   ({stats.up_count}/{stats.total})")
+    print(f"   latency    : avg {fmt_ms(stats.lat_avg)}  min {fmt_ms(stats.lat_min)}  max {fmt_ms(stats.lat_max)}  jitter {stats.lat_jitter:.1f} ms")
+    print(f"   outages    : {stats.outages}   downtime {fmt_duration(stats.downtime_s)}   longest {fmt_duration(stats.longest_outage_s)}")
+    print(" WIFI SIGNAL")
+    print(f"   signal     : avg {fmt_dbm(stats.sig_avg)}  min {fmt_dbm(stats.sig_min)}  max {fmt_dbm(stats.sig_max)} dBm  ({signal_label(stats.sig_avg)})")
+    print(f"   stability  : {stability_label(stats.sig_std, stats._sig_n)}  (±{stats.sig_std:.1f} dBm)")
+    print("─────────────────────────────────────────────────")
+    print(c.dim(f" log     : {log_path}"))
+    print(c.dim(f" summary : {summary_path}"))
+    print(c.dim(f" graph   : {graph_msg}"))
+
+
+def write_summary_json(path, stats: Stats, started, cfg, ssid, iface) -> None:
+    now = time.time()
+    data = {
+        "started": dt.datetime.fromtimestamp(started).isoformat(timespec="seconds"),
+        "ended": dt.datetime.fromtimestamp(now).isoformat(timespec="seconds"),
+        "duration_s": round(now - started, 1),
+        "host": cfg.host, "interval_s": cfg.interval, "ssid": ssid, "iface": iface,
+        "internet": {
+            "samples": stats.total, "up": stats.up_count, "down": stats.down_count,
+            "uptime_pct": round(stats.uptime_pct, 2), "packet_loss_pct": round(stats.loss_pct, 2),
+            "latency_avg_ms": round(stats.lat_avg, 2) if stats.lat_avg is not None else None,
+            "latency_min_ms": stats.lat_min, "latency_max_ms": stats.lat_max,
+            "latency_jitter_ms": round(stats.lat_jitter, 2),
+            "outages": stats.outages, "downtime_s": round(stats.downtime_s, 1),
+            "longest_outage_s": round(stats.longest_outage_s, 1),
+        },
+        "wifi_signal": {
+            "samples": stats._sig_n,
+            "avg_dbm": round(stats.sig_avg, 1) if stats.sig_avg is not None else None,
+            "min_dbm": stats.sig_min, "max_dbm": stats.sig_max,
+            "stddev_dbm": round(stats.sig_std, 2),
+            "stability": stability_label(stats.sig_std, stats._sig_n),
+        },
+    }
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+
+# --------------------------------------------------------------------------- #
+# Main
+# --------------------------------------------------------------------------- #
+def parse_args(argv=None):
+    p = argparse.ArgumentParser(prog="wifi_observer",
+                                description="Observe internet reachability and WiFi signal stability.")
+    p.add_argument("-H", "--host", default="8.8.8.8",
+                   help="Internet host to ping (default: 8.8.8.8, Google DNS)")
+    p.add_argument("-i", "--interval", type=float, default=1.0, help="Seconds between samples (default: 1.0)")
+    p.add_argument("-t", "--timeout", type=float, default=1.0, help="Per-ping timeout seconds (default: 1.0)")
+    p.add_argument("-n", "--history", type=int, default=3600, help="Samples kept in memory for the UI (default: 3600)")
+    p.add_argument("--log", metavar="PATH", default=None,
+                   help="JSON-lines log path (default: logs/wifi-<timestamp>.jsonl)")
+    p.add_argument("--no-log", action="store_true", help="Disable JSON logging")
+    p.add_argument("--no-color", action="store_true", help="Disable ANSI colors")
+    return p.parse_args(argv)
+
+
+def main(argv=None) -> int:
+    cfg = parse_args(argv)
+    color = (not cfg.no_color) and sys.stdout.isatty() and os.environ.get("TERM") != "dumb"
+    c = Colors(color)
+
+    if shutil.which("ping") is None:
+        print("error: 'ping' not found in PATH", file=sys.stderr)
+        return 1
+
+    # 1) Interactive startup prompt: how long to run.
+    duration_s = choose_duration(c)
+
+    ssid = detect_ssid()
+    iface = detect_iface()
+    started = time.time()
+    started_dt = dt.datetime.fromtimestamp(started)
+    stamp = started_dt.strftime("%H%M%S")
+    out_dir = os.path.join("logs", started_dt.strftime("%Y-%m-%d"))   # logs/<date>/
+
+    # Logging + graph output paths, grouped under logs/<date>/.
+    log_fh = None
+    log_path = summary_path = "(disabled)"
+    if not cfg.no_log:
+        if cfg.log:
+            log_path = cfg.log
+            os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
+        else:
+            os.makedirs(out_dir, exist_ok=True)
+            log_path = os.path.join(out_dir, f"wifi-{stamp}.jsonl")
+        summary_path = os.path.splitext(log_path)[0] + ".summary.json"
+        log_fh = open(log_path, "a", buffering=1, encoding="utf-8")
+    graph_path = (os.path.splitext(log_path)[0] + ".png") if log_fh is not None \
+        else os.path.join(out_dir, f"wifi-{stamp}.png")
+
+    history = collections.deque(maxlen=cfg.history)
+    stats = Stats()
+
+    stop = {"flag": False}
+    signal.signal(signal.SIGINT, lambda *_: stop.__setitem__("flag", True))
+
+    def draw(status=""):
+        sys.stdout.write(render(cfg, stats, history, ssid, iface, started,
+                                log_path, duration_s, status, c))
+        sys.stdout.flush()
+
+    def time_up():
+        return duration_s is not None and (time.time() - started) >= duration_s
+
+    # 2) Interactive monitor loop with live keys ([g] graph, [q] quit).
+    with KeyReader() as keys:
+        if color:
+            sys.stdout.write(HIDE_CURSOR)
+        prev_tick = started
+        try:
+            while not stop["flag"] and not time_up():
+                tick = time.time()
+                up, latency = ping_once(cfg.host, cfg.timeout)
+                sdbm, squal = read_wifi_signal(iface)
+                ts = time.time()
+                p = Probe(ts=ts, time=dt.datetime.fromtimestamp(ts).isoformat(timespec="milliseconds"),
+                          internet_up=up, latency_ms=latency, signal_dbm=sdbm,
+                          signal_quality=squal, ssid=ssid)
+
+                if stats.current_up is False:      # accumulate downtime per tick while down
+                    stats.downtime_s += ts - prev_tick
+                prev_tick = ts
+
+                history.append(p)
+                stats.add(p)
+                if log_fh is not None:
+                    log_fh.write(json.dumps(asdict(p)) + "\n")
+
+                draw()
+
+                # Wait out the interval, staying responsive to keypresses.
+                deadline = tick + cfg.interval
+                while not stop["flag"] and not time_up():
+                    wait = deadline - time.time()
+                    if wait <= 0:
+                        break
+                    key = keys.poll(min(0.2, wait))
+                    if not key:
+                        continue
+                    if key in ("q", "Q"):
+                        stop["flag"] = True
+                    elif key in ("g", "G"):
+                        draw(status="generating graph…")
+                        _, msg = generate_graph(history, log_path, graph_path)
+                        draw(status=msg)
+        finally:
+            if color:
+                sys.stdout.write(SHOW_CURSOR)
+                sys.stdout.flush()
+            if log_fh is not None:
+                log_fh.close()
+                write_summary_json(summary_path, stats, started, cfg, ssid, iface)
+
+    # 3) Always leave the user with a graph (no need to run plot.py by hand).
+    _, graph_msg = generate_graph(history, log_path, graph_path)
+    print_summary(stats, started, log_path, summary_path, graph_msg, c)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wifi_observer_plot.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""wifi_observer_plot.py — render graphs from WiFi Observer data using matplotlib.
+
+The live program (wifi_observer.py) imports `build_figure` from here when you
+press [g], so you normally never run this script by hand. It also works
+standalone:
+
+    python3 wifi_observer_plot.py [LOGFILE] [-o OUTPUT.png] [--show]
+
+If LOGFILE is omitted, the newest logs/wifi-*.jsonl is used. Produces two
+stacked charts sharing a time axis:
+    1. Internet latency over time (outages marked in red).
+    2. WiFi signal strength (dBm) over time, with quality reference lines.
+
+Requires matplotlib:  pip install matplotlib
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import glob
+import json
+import os
+import sys
+
+
+def load(path: str) -> list[dict]:
+    """Read a JSON-lines log into a list of dicts."""
+    rows = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    rows.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return rows
+
+
+def newest_log() -> str | None:
+    # Search both logs/wifi-*.jsonl and logs/<date>/wifi-*.jsonl.
+    found = set(glob.glob(os.path.join("logs", "wifi-*.jsonl")))
+    found |= set(glob.glob(os.path.join("logs", "**", "wifi-*.jsonl"), recursive=True))
+    files = sorted(found, key=os.path.getmtime)
+    return files[-1] if files else None
+
+
+def build_figure(rows: list[dict], out_path: str, show: bool = False) -> str:
+    """Render `rows` to an image at `out_path`. Returns the path.
+
+    Raises ImportError if matplotlib is unavailable (handled by callers).
+    """
+    import matplotlib
+    if not show:
+        matplotlib.use("Agg")               # headless: save without a display
+    import matplotlib.pyplot as plt
+    import matplotlib.dates as mdates
+
+    times = [dt.datetime.fromtimestamp(r["ts"]) for r in rows]
+    lat = [r.get("latency_ms") if r.get("internet_up") else None for r in rows]
+    lat_y = [v if v is not None else float("nan") for v in lat]
+    out_t = [t for t, r in zip(times, rows) if not r.get("internet_up")]
+    sig = [r.get("signal_dbm") for r in rows]
+    sig_t = [t for t, v in zip(times, sig) if v is not None]
+    sig_y = [v for v in sig if v is not None]
+    ssid = next((r.get("ssid") for r in rows if r.get("ssid")), "?")
+
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(11, 7), sharex=True)
+    fig.suptitle(f"WiFi Observer — {ssid}   ({len(rows)} samples)", fontweight="bold")
+
+    # --- Internet latency ---
+    ax1.plot(times, lat_y, color="#1f77b4", linewidth=1.2, label="latency (ms)")
+    if out_t:
+        ymax = max((v for v in lat if v is not None), default=1.0)
+        ax1.scatter(out_t, [ymax] * len(out_t), color="red", marker="v", s=28,
+                    zorder=5, label=f"outage ({len(out_t)})")
+    ax1.set_ylabel("Internet latency (ms)")
+    ax1.grid(True, alpha=0.3)
+    ax1.legend(loc="upper right", fontsize=8)
+
+    # --- WiFi signal ---
+    if sig_y:
+        ax2.plot(sig_t, sig_y, color="#2ca02c", linewidth=1.2, label="signal (dBm)")
+        for lvl, col in [(-50, "#2ca02c"), (-67, "#ff7f0e"), (-75, "#d62728")]:
+            ax2.axhline(lvl, color=col, linestyle="--", linewidth=0.7, alpha=0.5)
+        ax2.legend(loc="upper right", fontsize=8)
+    else:
+        ax2.text(0.5, 0.5, "no WiFi signal data\n(/proc/net/wireless unavailable)",
+                 ha="center", va="center", transform=ax2.transAxes, color="gray")
+    ax2.set_ylabel("WiFi signal (dBm)")
+    ax2.set_xlabel("Time")
+    ax2.grid(True, alpha=0.3)
+    ax2.xaxis.set_major_formatter(mdates.DateFormatter("%H:%M:%S"))
+    fig.autofmt_xdate()
+    fig.tight_layout(rect=(0, 0, 1, 0.97))
+
+    fig.savefig(out_path, dpi=120)
+    if show:
+        plt.show()
+    plt.close(fig)
+    return out_path
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Plot a WiFi Observer log with matplotlib.")
+    ap.add_argument("logfile", nargs="?", help="JSON-lines log (default: newest in logs/)")
+    ap.add_argument("-o", "--output", help="Output image path (default: <logfile>.png)")
+    ap.add_argument("--show", action="store_true", help="Open an interactive window too")
+    args = ap.parse_args(argv)
+
+    path = args.logfile or newest_log()
+    if not path:
+        print("error: no log file given and none found in logs/", file=sys.stderr)
+        return 1
+    if not os.path.isfile(path):
+        print(f"error: log file not found: {path}", file=sys.stderr)
+        return 1
+
+    rows = load(path)
+    if not rows:
+        print(f"error: no samples found in {path}", file=sys.stderr)
+        return 1
+
+    out = args.output or (os.path.splitext(path)[0] + ".png")
+    try:
+        build_figure(rows, out, show=args.show)
+    except ImportError:
+        print("error: matplotlib is required.  Install it with:\n    pip install matplotlib",
+              file=sys.stderr)
+        return 2
+    print(f"saved graph → {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())