whm also known as wifi-heat-mapper
is a Python library for benchmarking Wi-Fi networks and gather useful metrics that can be converted into meaningful easy-to-understand heatmaps. The tool aims to assist network engineers, admins and homelabbers in figuring out the performance of their Access Points and Routers.
This tool is heavily inspired by python-wifi-survey-heatmap by Jason Antman.
- Operating System
- Linux x86_64 (64 bit)
- Python version: 3.7 - 3.9 (with Tkinter)
- iperf3 >= 0.1.11
- matplotlib >= 3.4.0
- tqdm >= 4.55.0
- Pillow >= 8.2.0
- scipy >= 1.6.0
- numpy >= 1.20.0
- PySimpleGUI >= 4.34.0
- Ookla Speedtest CLI >= 1.0.0.2 (Recommended)
- Sivel Speedtest CLI >= 2.1.3 (Jitter is not available, Not Recommended)
- Librespeed CLI >= 1.0.9 (Strongly Recommended)
By default Tkinter is not installed with Python. Users are requested to install Tkinter using their respective package managers.
$ pacman -S tk
$ dnf install python3-tkinter
$ apt install python3-tk
$ zypper install python3-tk
The easiest way to install whm is via pip.
$ pip install whm
Alternatively, you can clone the repository and compile it.
$ git clone https://github.com/Nischay-Pro/wifi-heat-mapper.git
$ cd wifi-heat-mapper
$ python3 setup.py install
whm requires connecting to an iperf3
instance running in server mode. On a machine which is available in your LAN run iperf3 -s
to start iperf3 in server mode in foreground. I strongly recommend running the iperf3 instance on a wired computer or virtual machine instance.
By default, iperf3 will use TCP and UDP ports 5201.
Initially, you need to bootstrap your configuration specifying the graphs you would like to view, the number of times you want to repeat benchmarking, the wireless interface you will be using to profile, and the SSID configured. In case you are using librespeed-cli
you will be asked if you prefer it over speedtest
and optionally provide a path to your custom libre server list.
whm supports multiple graphs allowing users to select one, more, or all graphs. The tool will automatically gather the appropriate metrics to generate the graphs.
$ whm bootstrap
NOTE: To profile metrics from Ookla speedtest, the user needs to ensure that they have installed the binary provided by Ookla and is accessible from
$PATH
environment variable.
After completing the process, a file called config.json
will be available in the directory you have executed the command from.
To specify a save path and file name use the --config
option, including the path and the filename for storing the configuration details.
For example:
$ whm bootstrap --config /home/example/whm/test.json
Once you have generated the configuration file you can start benchmarking.
$ whm benchmark -m examples/sample_floor_map.jpg -s 192.168.1.100 -c config.json
Command-line options used:
-m
or--map
is the path to the floop map.-s
or--server
is the IP address(:port) of the iperf3 server. You can specify a port usingIPADDRESS:PORT
, like192.168.1.100:5123
. If no port is specified the default port5201
is used.-c
or--config
is the path to the configuration file you bootstrapped earlier.
After specifying the appropriate options a GUI window will open up.
You will be presented with a canvas with your floor map loaded.
- Exit: To quit benchmarking
- Save Results: Save the results you have captured till now. Results are stored in the same configuration file you have used earlier.
- Plot: To plot the results you have captured.
- Clean All: Wipes the canvas clean, removing all captured metrics.
- Start by Left-clicking on the canvas roughly at a position where you are capturing the metrics from. A gray circle with a blue outline should appear now.
- Now right-click on the circle. You will be presented with a drop-down menu having 3 options.
- Benchmark: whm will start capturing metrics at this position.
- Delete: whm will delete the point and metrics (if any) at this point.
- Mark / Un-Mark as Station: whm will mark this point as a Base station. Useful if you want to have a heatmap displaying the position of one or more base stations. You would still need to benchmark at this point. The border color will change from black to red, indicating a base station point.
- Select
Benchmark
and wait for a few seconds (or minutes) depending on the graphs you have requested and the number of times benchmarks are repeated. Once benchmarking is done, the circle's fill color changes from gray to light blue.- Benchmark results are automatically saved when they complete successfully.
- Alternatively, if you would like to rerun benchmarking, simply select any point using the cursor; the black border becomes blue. You can now right-click and select
Benchmark
to recapture metrics.
-
Now move to a new position you want to benchmark from and select the rough position in the canvas.
-
whm requires at least 4 points to generate plots. I strongly recommend profiling as many points as possible to increase the accuracy of the heatmap.
-
Once completed click on
Save Results
to save the metrics to file. You can then plot your metrics by pressingPlot
.
To resume from a previous benchmarking state, simply repeat the command you used to run the benchmarking initially. All results are stored in the configuration file the user has specified originally.
whm also offers the user additional command-line arguments when plotting.
To generate plots with custom flags, you can specify them using the whm plot
command.
$ whm plot -m ./examples/sample_floor_map.jpg -c config.json -l 100 -d 300 -f png
Command-line options used:
-m
or--map
is the path to the floop map.-c
or--config
is the path to the configuration file you bootstrapped earlier.-l
or--levels
(optional) is the number and positions of the contour lines / regions. Default (100)-d
or--dpi
(optional) is the resolution of the figure in dots-per-inch. Default (300)-f
or--format
(optional) is used to specify the export file format for generated plots. Default (png). Supported options include (png, pdf, ps, eps, svg)
The directory from which the user has run the command will contain the graphs that the user requested during bootstrap.
A sample configuration, including benchmark results and plots generated is provided in the examples folder.
Pull requests are welcome. For significant changes, please open an issue first to discuss what you would like to change.
Please make sure to run tests as appropriate.