WifiMapLinux

Residential Wi-Fi mapping tool for Linux.
Measure real-world coverage across a multi-floor house, generate heatmaps, simulate AP placement, and export coverage reports.

---

Features

• Field audit — Wi-Fi scan (iw/nmcli) + position marking on the floor plan → 2D per-floor heatmap
• AP simulation — virtual access point placement + Log-Distance Path Loss 3D model (ITU-R P.1238)
• Multi-floor navigation — per-floor tabs, visual inter-floor alignment, interpolated vertical cross-section
• Overlay comparison — measured heatmap vs. simulated heatmap side by side
• Export — annotated PNG (plan + heatmap) and multi-page PDF coverage report
• Bilingual — French and English UI (Settings → Language, restart to apply)
• Integrated help — Help menu (F1) with guided topics for every workflow

Target audience

Residential use — homeowner or tenant wanting to optimise their home Wi-Fi network, without the budget or training required for professional tools (Ekahau, NetSpot).

Status

V2 complete — fully functional application, simulation and export available.
See docs/Roadmap.md for the version history and next steps.

Stack

Layer	Technology
UI	Python 3.11+, PySide6 (Qt6)
Floor plan canvas + heatmap	QGraphicsView, QPainter
Vertical cross-section view	QWidget + QPainter
Radio propagation	Log-Distance Path Loss 3D (NumPy)
IDW interpolation	NumPy
Storage	SQLite local (SQLModel)
Wi-Fi scan	iw, nmcli (Linux)
Export	Pillow

Architecture decisions: docs/Architecture-Decisions.md

Installation

Arch Linux — AUR

# with yay
yay -S wifimaplinux

# with paru
paru -S wifimaplinux

After install, launch with:

wifimaplinux

Manual (any Linux distro)

git clone https://github.com/thongor77/WifiMapLinux.git
cd WifiMapLinux
python -m venv .venv --system-site-packages
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py

System requirements:

• Linux (Arch, Debian, Ubuntu)
• Python 3.11+
• PySide6 available (system or venv)
• iw or nmcli for Wi-Fi scanning

Quick start

1. Create a house — left panel → "New building" then "New floor"
2. Import a plan — "Import PNG floor plan" → calibrate the scale (2 clicks + real-world distance)
3. Measure — "Measure Wi-Fi" → click your position on the floor plan
4. Visualise — enable "Heatmap" in the bottom bar
5. Simulate — "Place virtual AP" → enable "Simulation"
6. Export — Export menu → PNG or PDF

Press F1 or open Help → Help… at any time for step-by-step guidance on each workflow.

Source structure

app/
├── models/          — SQLModel: Building, Floor, FloorPlan, MeasurementPoint, AccessPoint
├── services/        — IDW, LDPL propagation, Wi-Fi scanner, Pillow export, i18n, settings
└── ui/
    ├── main_window.py
    ├── floor_plan_widget.py   — QGraphicsView: floor plan + heatmaps + markers
    ├── section_view.py        — interpolated vertical cross-section
    ├── heatmap_controls.py    — control bar (heatmap, simulation, opacity, section)
    ├── building_panel.py      — house/floor tree + action buttons
    ├── floor_tab_bar.py       — per-floor tab navigation
    └── dialogs/               — FloorDialog, ScanDialog, AlignmentDialog, APDialog,
                                  AboutDialog, HelpDialog

Support the project

If this project is useful to you, you can support its development:

• PayPal — Donate via PayPal
• Bitcoin — bc1qspe0tky7552qas72wgn8w9dswr0dxlv24w39t6ztjqk3nz6kc5tqv753a4

Differences from WifiMapper

WifiMapper (sibling project) targets small businesses with a 2D single-floor web tool.
WifiMapLinux targets residential use, adds multi-floor support, 3D simulation, and coverage reports.
Both projects are independent and share no code.

License

MIT — see LICENSE