A live map of your home network: which devices are connected, to which access point (main router, mesh extender, secondary AP), with what signal, since when, and how they move from one AP to another. Every device can have a type (with an icon) and a room. It runs as a single Python process with a local SQLite history, and the web page is available in English and Italian, with dark and light themes.
It was built for one specific setup, but it is adaptable. Netmap never talks to the TP-Link router directly: it reads it through Home Assistant, and it reads the optional secondary AP over SSH.
flowchart LR
internet((Internet)) --- ax55["TP-Link Archer AX55<br/>main router"]
ax55 -. "Wi-Fi / LAN" .- clients1["Phones, PCs, TV…"]
ax55 -. mesh .- re["Mesh extender<br/>(optional)"]
ax55 == "5 GHz Wi-Fi uplink" ==> opal["GL.iNet Opal · OpenWrt<br/>secondary AP (optional)"]
opal -. "2.4 GHz Wi-Fi" .- iot["IoT devices"]
opal -. "LAN port" .- cam["Camera"]
ha["Home Assistant<br/>device_tracker entities"] -- "router integration" --> ax55
subgraph host ["Netmap host (LXC / Docker)"]
netmap["Netmap<br/>Flask + worker"] --- db[("SQLite<br/>network.db")]
netmap --- files["names.json<br/>meta.json"]
end
netmap -- "HTTP API · token" --> ha
netmap -- "SSH · iwinfo, ubus, ip neigh, bridge" --> opal
browser["Browser"] -- "http://host:8080" --> netmap
kuma["Uptime Kuma"] -- "/api/health" --> netmap
The labels in the interface say "AX55" and "Opal" because that is the author's setup. The secondary access point is optional: without
OPAL_HOSTNetmap works with the main router only.
A single background thread polls both sources in parallel, merges them by MAC address and publishes a new snapshot that the page picks up.
sequenceDiagram
autonumber
participant W as Worker (every POLL_SECONDS)
participant HA as Home Assistant
participant O as Opal (SSH)
participant B as build()
participant DB as SQLite
participant UI as Browser
par in parallel
W->>HA: GET device_tracker states (template)
HA-->>W: MAC, IP, AP, band, RSSI, rates
and
W->>O: one SSH session, batched commands
O-->>W: assoclist, hostapd clients, uplink, ARP, bridge FDB
end
Note over W: source failed? reuse last valid reading (≤ 10 min), mark it stale
W->>B: router + Opal + names.json + meta.json + previous state
B-->>W: devices, groups, aliases, alerts
W->>W: detect events (AP/band change, connect, disconnect)
W->>DB: seen, samples, events (hourly prune)
W-->>UI: new STATE snapshot
UI->>W: GET /api/data?since=ts
For a device behind the secondary AP both sources may report something, sometimes under the wrong MAC:
flowchart TD
mac["Device MAC"] --> q1{"Associated to the Opal<br/>(iwinfo / hostapd)?"}
q1 -- yes --> opalwifi["Behind the Opal · Wi-Fi<br/>RSSI from the Opal"]
q1 -- no --> q2{"In the Opal bridge FDB<br/>on OPAL_LAN_IF / OPAL_WIRED_MACS?"}
q2 -- yes --> opalwired["Behind the Opal · wired"]
q2 -- no --> q3{"Reported by the AX55<br/>under its own MAC?"}
q3 -- yes --> ax["On the AX55 / extender<br/>as Home Assistant reports it"]
q3 -- no --> q4{"Seen by the AX55 with the<br/>Opal's MAC (alias)?"}
q4 -- yes --> alias["Online behind the Opal<br/>(Wi-Fi vs wired unknown)"]
q4 -- no --> off["Offline"]
Recently vanished Opal clients stay connected for OPAL_MISSING_GRACE_SECONDS (only while the Opal answers), because the radio views drop clients for a moment from time to time. See docs/presence-detection.md.
- Map grouped by connection, room or type, with colour-coded signal (RSSI) and one icon per category.
- Table with filtering, sorting, renaming and editing of type and room.
- Signal history (1 h / 6 h / 24 h / 7 d) for every device and for the secondary AP's uplink.
- Roaming: records moves between APs or bands, connections and disconnections, with a ranking of the most unstable devices. Events also show up as vertical lines in the signal chart.
- Alerts: IP conflict, weak signal (grouped by room), weak uplink or uplink attached to the wrong AP, new device, cameras/network gear offline.
- Source priority: for what sits behind the secondary AP, the AP itself wins (associated and wired clients), then what the main router reports. Devices that the router sees under the AP's MAC ("aliases") are handled too.
- Diagnostics: a panel with the state, duration and detail of each source, readable logs and
/api/healthfor monitors. - Failure tolerant: if a source stops answering it shows the last valid reading (up to 10 minutes) and does not invent events.
- Two languages and two themes: Italian and English, dark and light, with selectors in the header. Both choices are remembered; the first time the language follows the browser.
- Quick copy of IP and MAC from cards and table rows.
- Python 3.11+ (or Docker).
- Home Assistant with the router's
device_trackerentities (statehome= connected). Netmap reads these attributes:mac/mac_address,ip/ip_address,friendly_name/host_name/hostname,connection,band,ap_name,signal,tx_rate,rx_rate(kbps),ssid,source_type. The author uses them with a TP-Link Archer AX55: with another integration you may need to adaptfetch_home_assistantandHA_TEMPLATEinapp.py. - (Optional) an OpenWrt/GL.iNet access point with SSH. It uses
iwinfo,ubus call hostapd.<if> get_clients,ip neighand, for wired devices,bridge(theip-bridgepackage) orbrctl. Developed on a GL.iNet Opal (GL-SFT1200). - paramiko < 5: version 5 dropped the SHA-1
ssh-rsahost key that older Dropbear servers still use (requirements.txtalready pins it).
git clone https://github.com/<user>/netmap && cd netmap
python3 -m venv venv && . venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env # fill in HA_URL, HA_TOKEN and, if needed, OPAL_*
cp names.example.json names.json && cp meta.example.json meta.json # optional
python app.py # http://localhost:8080
pytest # testsOr with Docker:
cp .env.example .env # fill it in; mount the SSH key as in docker-compose.yml
docker compose up -d --build # data in ./dataFor everyday use see docs/DEPLOY.md (Proxmox LXC, Docker, reverse proxy, monitoring).
Everything is set through environment variables or the .env file (see .env.example).
| Variable | Default | Description |
|---|---|---|
HA_URL, HA_TOKEN |
– | Home Assistant and its long-lived access token. HA_VERIFY_SSL=false for self-signed certificates |
OPAL_HOST |
empty | Secondary AP over SSH; empty = disabled |
OPAL_PORT, OPAL_USER |
22, root |
|
OPAL_PASSWORD / OPAL_KEY |
– | Password (OPAL_PASS also accepted) or private key (recommended) |
OPAL_KNOWN_HOSTS |
– | If set the host key is verified, otherwise it is accepted on first contact |
OPAL_AP_IF, OPAL_STA_IF |
wlan0, wlan-sta0 |
Access point interface and the client interface used for the uplink |
OPAL_LAN_IF, OPAL_BRIDGE |
– , br-lan |
Physical LAN port (e.g. eth0.1): MACs seen there are "wired". List the ports with ls /sys/class/net/br-lan/brif |
OPAL_WIRED_MACS |
– | Wired MACs listed by hand (alternative to OPAL_LAN_IF) |
UPLINK_EXPECTED_AP |
– | Part of the name of the AP the secondary AP must be attached to; alert if different |
EXTENDER_NAMES |
– | Mesh extenders (partial name) to tell them apart in roaming |
AX55_MAC, RE700X_MAC |
– | Used only if the router does not say which AP the secondary AP is attached to |
OPAL_MISSING_GRACE_SECONDS |
120 |
How long an Opal client missing from the radio views stays connected; 0 disables it |
POLL_SECONDS |
30 |
Cycle period, including the collection time (minimum 10) |
RETENTION_DAYS |
14 |
How long samples and events are kept |
RSSI_GOOD, RSSI_WARN, UPLINK_WARN |
-60, -75, -70 |
Thresholds in dBm |
NEW_DEVICE_HOURS |
48 |
How long a never-seen MAC counts as "new" |
OFFLINE_ALERT_TYPES, OFFLINE_ALERT_MINUTES |
camera,rete, 10 |
Types to alert on when they stay offline (empty = never). Type keys: pc, server, smartphone, tv, camera, luce_presa, iot, rete, altro |
DB_PATH, NAMES_FILE, META_FILE |
next to app.py |
In production use a dedicated data folder |
DASH_USER, DASH_PASSWORD |
– | Optional HTTP Basic auth |
NETMAP_LANG |
en |
Language of the logs: en or it. The page language is chosen in the browser |
LOG_LEVEL, LOG_FILE |
INFO, – |
DEBUG adds tracebacks and the time of every SSH command |
HOST, PORT |
0.0.0.0, 8080 |
Bind address of python app.py (with Waitress use --listen) |
DASH_NO_WORKER |
– | Set to disable the polling worker (tests, debugging) |
Each device can have a name (names.json), a type and a room (meta.json), editable from the page (pencil in the table, or the "Edit" button under the chart).
Types: PC/laptop, Server/VM/LXC, Smartphone/tablet, TV/audio/media, Camera/doorbell, IoT lights/plugs/relays, IoT other, Network, Other. Change them in TYPES in app.py (the icons live in ICON in templates/index.html).
For unclassified devices Netmap suggests a type from the name or the MAC (dimmed icon and (?)); the "Apply suggestions" button confirms them in bulk without overwriting choices you already made. The suggestions are keywords in KIND_HINTS: add your own.
| What | Where | Notes |
|---|---|---|
| Names (labels) | names.json |
Source of truth. If a name is missing, the one the router reports is used |
| Type and room | meta.json |
Source of truth |
| Signal samples, roaming events, "last seen" | network.db (SQLite) |
Measurements only, tied to the MAC, never to the name |
So there is no migration: the JSON files are not "loaded" into the database. Names, types and rooms are read from the files on every cycle and applied to the incoming data.
- Rename from the page: the server rewrites the file atomically and starts a cycle right away; the page updates instantly. History and events follow the MAC, so they show the new name immediately, past events included.
- Edit the file by hand: it applies from the next cycle, no restart needed. MACs may use upper case, colons or dashes. JSON has no comments, and after the first save from the page the keys are sorted.
- Invalid JSON (e.g. a trailing comma): Netmap keeps using the last valid version, shows the error in the page and in the log, and refuses to rewrite the file until you fix it, so nothing gets lost.
- Clear name, type and room: the entry disappears and the device goes back to the router's name.
- Backup:
names.json,meta.jsonandnetwork.db(the database only holds history: losing it does not remove your labels).
| Alert | When |
|---|---|
| IP conflict | Two connected devices share the same IP |
| Weak signal | RSSI ≤ RSSI_WARN; with two or more in the same room and AP, a single alert "Weak signal in Kitchen…" |
| Uplink | Signal ≤ UPLINK_WARN, or the secondary AP attached to an AP other than UPLINK_EXPECTED_AP |
| New device | A never-seen MAC, within NEW_DEVICE_HOURS, with no name in names.json; yellow if the type is unknown. On first start everything already present counts as known |
| Offline | Cameras and network gear (configurable) offline for more than OFFLINE_ALERT_MINUTES. Not raised while a source is failing |
Alerts that refer to a device are clickable and open its history.
Start · every 30 s · HA http://… · Opal root@…:22 (AP wlan0, uplink wlan-sta0, LAN ports eth0.1) · DB … (14 d) · auth off · log INFO
Cycle 12 · HA ok 0.04 s (77 trackers received, 74 valid · template · 26 KB) · Opal ok 1.2 s (6 Wi-Fi clients, 1 wired · SSH reused · 5890 B) · 32/73 connected · +19 samples · 1.3 s total
AP change: Phone from «AX55 · 5 GHz» to «Opal · 2.4 GHz»
AX55↔Opal alias: Purifier (192.0.2.220) is seen by the AX55 with the Opal's MAC 94:… → treated as ONLINE behind the Opal
Offline: Kitchen camera · Kitchen for 12 min (Camera / doorbell)
Home Assistant · AX55: ERROR · ConnectionError… (attempt #1)
If an SSH command takes longer than 1 s, slow: … appears in the cycle line. For details use LOG_LEVEL=DEBUG. Set NETMAP_LANG=it for Italian logs.
Requests that change data need the header X-Requested-With: dashboard (CSRF protection). Texts meant for display (alerts[].text, types, source detail) are {"it": …, "en": …} objects and the page picks one; group labels use neutral tokens (wired, guest, undetermined).
| Method and path | Description |
|---|---|
GET /api/data[?since=ts] |
Full state (answers {"unchanged":true} if nothing changed) |
POST /api/refresh |
Forces a cycle and answers with the new data |
GET /api/health |
200 if everything is fine, 503 otherwise: {"status": "ok"|"degraded"|"starting", "failing": […], "last_cycle_age_s": n, "cycles": n} (for Uptime Kuma & co.) |
GET /api/history?mac=…&hours=24 |
Signal series (mac=opal:uplink for the uplink) |
GET /api/events?hours=24[&mac=…] |
AP/band changes, connections, disconnections |
PATCH /api/names/<mac> |
{"name": "…"} (empty removes it) |
PATCH /api/meta/<mac> |
{"type": "camera", "room": "Kitchen"} |
POST /api/meta/apply-suggestions |
Confirms the suggested types |
- Netmap does not do TLS: use it on your LAN or behind a reverse proxy with HTTPS. With
DASH_USER/DASH_PASSWORDset, Basic auth travels in clear text without HTTPS. - Use a dedicated SSH key for the secondary AP and
OPAL_KNOWN_HOSTSto verify the host. The Home Assistant token can belong to a dedicated user. - The
.envfile holds secrets: permissions640or stricter, never in the repository.
- The labels "AX55", "Opal" and the group names are hard-coded.
- Event precision is that of the refresh cycle plus the time the routers take to report a client as gone.
- "Behind the Opal" does not distinguish Wi-Fi from wired for devices seen only as aliases.
- A single process: do not start several workers (they would duplicate the polling).
.gitignore excludes .env, names.json, meta.json, databases, logs and keys: they hold the MACs, IPs and names of your home. Before the first push:
git status --short # no personal file among those to be added
git grep -nIiE "([0-9a-f]{2}:){5}[0-9a-f]{2}" -- . ':!tests' ':!*.example.json' ':!.env.example'
git grep -nIi "token\|password" -- . ':!*.md' ':!.env.example' ':!app.py' ':!config.py' ':!sources.py' ':!deploy'If a token ends up in the history, revoke it in Home Assistant: rewriting the history is not enough.
- docs/DEPLOY.md — production setup (LXC, Docker, reverse proxy, monitoring)
- docs/device-mapping.md — how devices, APs and RSSI are identified
- docs/presence-detection.md —
iwinfovshostapdon the Opal - assets/brand/ — logo, icons and palette
MIT © 2026 Tkd-Alex


