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
• Demo
• Features
• Installation
• Usage
• Configuration
• How it works
• Output & file formats
• Reading the numbers
• Project structure
• Requirements
• Roadmap
• Contributing
• License

Why

A plain ping test lumps two different failures together. WiFi Observer separates them:

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

# 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:

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

./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:

A graph is also saved automatically on exit, and everything lands under logs/<today>/.

Configuration

How it works

Architecture

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):

{"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:

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:

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.

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 — free to use, modify, and distribute with attribution. © 2026 biswanathamz.