WLAN Network Monitor

Overview

Project Overview

WLAN Network Monitor is a purpose-built Python daemon that continuously polls two heterogeneous network appliances — a Zyxel router and a TP-Link extender — normalises their divergent API responses into a unified device model, and surfaces that data through a bidirectional Telegram bot interface. The system runs unattended on a low-power home server and is designed to survive hardware glitches, API timeouts, and transient credential expiry without requiring manual intervention.

Capabilities

Key Features

Unified Device Aggregation
Polls Zyxel and TP-Link APIs on configurable intervals, normalises vendor-specific schemas into a consistent DeviceRecord model, and deduplicates MAC addresses seen across both access points.
Autonomous Safe-Fail Recovery
A watchdog loop catches all runtime exceptions, logs structured diagnostics, attempts a graceful credential refresh, and resumes polling — all without restarting the process or losing accumulated state.
Bidirectional Telegram Bot Interface
Exposes a command set over the Telegram Bot API that lets you query live device lists, trigger network scans, and receive anomaly alerts from any device with Telegram installed.
Encrypted Credential Store
Router passwords and session tokens are stored encrypted at rest using Fernet symmetric encryption. Keys are derived from a per-installation secret, ensuring credentials are never exposed in plaintext on disk.

Origin

The Idea

It started with a simple frustration: I had no reliable way to tell whether an unknown device on my home network was a guest, an IoT sensor, or something that shouldn't be there at all. The existing router admin pages were clunky, required being on the same network, and showed completely different information depending on which device you were logged into.

The Vendor Fragmentation Problem

The Zyxel router and the TP-Link range extender each exposed device lists through entirely different HTTP APIs — different authentication flows, different JSON schemas, and different definitions of what constitutes an 'active' connection. Building a single coherent view meant writing two completely independent scrapers and reconciling their outputs into one model.

The Always-On Requirement

A monitor that crashes at 2 a.m. and stays down until someone notices is worse than no monitor at all. The watchdog loop was not an afterthought — it was the first module I designed. Every other component was built with the assumption that it would eventually throw an exception, and the system needed to recover from that without losing context.

Implementation

Building the Telegram Interface

Choosing Telegram as the remote interface was deliberate. The Bot API is stable, well-documented, handles long-polling reliably, and works over any internet connection — including mobile data when I'm away from home. More importantly, it meant I could get live network data with a simple slash command from anywhere in the world without opening any inbound ports.

Command Design

The bot exposes four primary commands: /devices lists all currently active connections with hostname, IP, MAC, and which access point they're connected to. /scan forces an immediate poll cycle outside the normal interval. /history shows the last N connect/disconnect events. /alert toggles push notifications for new device appearances. Each command is handled in its own coroutine so a slow scan doesn't block an incoming /devices query.

Threading Model

The polling scheduler and the Telegram long-poll listener run in separate daemon threads sharing a thread-safe queue. When the scheduler detects a change — a new device, a disconnect, or a credential expiry — it pushes an event onto the queue. The bot thread drains the queue and formats the appropriate notification. This keeps both subsystems completely independent and prevents a Telegram API hiccup from affecting the core monitoring loop.

Security

Security Considerations

Storing router credentials in plaintext in a YAML file felt wrong from day one, even for a personal project. The cryptographic layer uses Fernet symmetric encryption from the Python cryptography library, with the key derived from a per-installation secret stored outside the project directory. This is not enterprise-grade HSM security, but it establishes the correct habit: secrets are never committed, never logged, and never visible in plaintext on disk.

Results

Impact & Outcomes

99.8%Uptime (30-day)
2Vendors Unified
<3.1 sAvg. Latency
100%Alerts Delivered

Takeaways

Lessons Learned

Vendor APIs at the consumer hardware tier are effectively undocumented; building a robust adapter requires treating every response as untrusted and validating schema at ingestion time.
Threading in Python is sufficient for I/O-bound polling daemons — async would add complexity without meaningful throughput gains at this scale.
Encrypting secrets at rest, even in a home environment, establishes the discipline that transfers directly to production systems.
A well-defined recovery contract (log → refresh → retry → escalate) dramatically reduces 3 a.m. debugging sessions compared to a bare try/except that silently swallows errors.