A Python application for Linux machines to perform WiFi site surveys and present the results as a heatmap overlayed on a floorplan.
This is rather rough "beta" code. The heatmap generation code is roughly based on Beau Gunderson's MIT-licensed wifi-heatmap code.
Many thanks to DL6ER who contributed a massive amount of improvements to this project.
Check out the Running In Docker steps below to get single-line commands that run without the need to install anything on your computer (thanks to using docker). Creating a heatmap using the software consists of the following three essential steps: 1. Start an iperf3 server on any machine in your local network. This server is used for bandwidth measurements to be independent of your Internet connection. When omitting the --server option, this may be skipped, however, be aware that the performance heatmaps tpyically are the icing on the cake of your measurement and are very useful in determining the real performance of your WiFi. 2. Use the wifi-survey tool to record a measurement. You can load a floorplan and click on your current location ot record signal strength and determine the achievable bandwidth. 3. Once done with all the measurements, use the wifi-heatmap tool to compute a high-resolution heatmap from your recorded data. In case your data turns out to be too coarse, you can always go back to step 2 and delete or move old and also add new measurements at any time.
NOTE: These can all be ignored when using Docker. DOCKER IS THE RECOMMENDED INSTALLATION METHOD. See below.
Recommended installation is via
python setup.py develop in a virtualenv setup with
--system-site-packages (for the above dependencies).
Tested with Python 3.7.
At each survey location, data collection should take 45-60 seconds. The data collected is currently:
Hints: - The duration of the bandwidth measurement can be changed using the --duration argument of wifi-survey. This has great influence on the actual length of the individual data collections. - Scanning for other network takes rather long. As this isn't required in most cases, it is not enabled by default
On the system you're using as the
iperf3 server, run
iperf3 -s to start iperf3 in server mode in the foreground.
By default it will use TCP and UDP ports 5201 for communication, and these must be open in your firewall (at least from the client machine).
Ideally, you should be running the same exact iperf3 version on both machines.
The survey tool (
wifi-survey) must be run as root or via
sudo in order to use iwconfig/iwlist (or via Docker; see below).
First connect to the network that you want to survey. Then, run
sudo wifi-survey where:
Command-line options include:
--interface INTERFACEis the name of your Wireless interface (e.g.
--picture PICTUREis the path to a floorplan PNG file to use as the background for the map; see examples/example_floorplan.png for an example. In order to compare multiple surveys it may be helpful to pre-mark your measurement points on the floorplan, like `examples/example_with_marks.png <examples/example_with_marks.png`_. The UI currently loads the PNG at exact size, so it may help to scale your PNG file to your display.
--title TITLEis the title for the survey (such as the network name or AP location), which will also be used to name the data file and output files.
--server IPERF3_SERVERto enable
iperf3scans. The generated speed heatmaps are very useful (much more useful than signal strength) in visualizing the real performance of your network as they are live measurements with real data (instead of only theoretical values).
--scanto enable wireless scaning at the end of each measurement. This may take a lot of time, however, generates data used later for generating channel utilization graphs. If you're using a modern wireless product that allows running RF scans, it makes sense to use that data instead of these scans.
--bssid BSSIDallows you to specify a single desired BSSID for your survey. This will be checked several times during of every measurement, and the measurement will be discarded if you're connected to the wrong BSSID. This can be useful as a safeguard to make sure you don't accidentally roam to a different AP.
--duration 123allows you to change the duration of each individual iperf3 test run (default is 10 seconds as mentioned above)
--ding FILENAMEwill play the audio file at FILENAME when each measurement point is complete. See Playing A Sound When Measurement Finishes below for details.
TITLE.json already exists, the data from it will be pre-loaded into the application; this can be used to resume a survey.
When the UI loads, you should see your PNG file displayed. The UI is really simple:
Title.jsonand it's ready for the next measurement. If
iperf3encounters an error, you'll be prompted whether you want to retry or not; if you don't, whatever results iperf was able to obtain will be saved for that point.
At the end of the process, you should end up with a JSON file in your current directory named after the title you provided to
Title.json) that's owned by root. Fix the permissions if you want.
Note: The actual survey methodology is largely up to you. In order to get accurate results, you likely want to manually handle AP associations yourself. Ideally, you lock your client to a single AP and single frequency/band for the survey.
It's possible to have
wifi-survey play a sound when each measurement is complete. This can be handy if you're reading or watching something in another window while waiting for the measurements.
To enable this, call
wifi-survey with the
--ding argument, passing it the path to an audio file to play. A short sound effect is included in this repository at
wifi_survey_heatmap/complete.oga and can be used via
--ding wifi_survey_heatmap/complete.oga. by default, this will call
/usr/bin/paplay (the PulseAudio player) passing it the ding file path as the only argument. The command used can be overridden with
--ding-command /path/to/command but it must be one that accepts the path to an audio file as its only argument.
Inside Docker, however, this becomes quite a bit more difficult. Currently PulseAudio systems are supported, and this can be set up and enabled with the following steps:
1. Find your host computer's IP address on the
ip addr show dev docker0 - mine (and most Linux machines) is
1. Find the CIDR block of your
docker0 network. I do this using
ip route show dev docker0, which gives me a CIDR of
1. Have PulseAudio listen on a TCP socket, allowing connections from your Docker network:
pactl load-module module-native-protocol-tcp port=34567 auth-ip-acl=172.17.0.0/16
1. If you have iptables restricting traffic, insert a rule allowing traffic on port 34567 from Docker before your
DROP rule. For example, to insert a rule at position 5 in the
iptables -I INPUT 5 -s 172.17.0.0/16 -p tcp -m multiport --dports 34567 -m comment --comment "accept PulseAudio port 34567 tcp from Docker" -j ACCEPT
1. When running the Docker container, add
-e "PULSE_SERVER=tcp:172.17.0.1:34567" to the
docker run command.
1. When running
wifi-survey, add the
--ding argument as specified above. Note that the path to the file must be inside the container; you can put an audio file in your current directory and use it via
--ding /pwd/audioFile or you can use the default file built-in to the container via
Once you've performed a survey with a given title and the results are saved in
wifi-heatmap TITLE to generate heatmap files in the current directory. This process does not require (and shouldn't have) root/sudo and operates only on the JSON data file. For this, it will look better if you use a PNG without the measurement location marks.
You can optionally pass the path to a JSON file mapping the access point MAC addresses (BSSIDs) to friendly names via the
--ap-names argument. If specified, this will annotate each measurement dot on the heatmap with the name (mapping value) and frequency band of the AP that was connected when the measurement was taken. This can be useful in multi-AP roaming environments.
The end result of this process for a given survey (Title) should be some
.png images in your current directory:
If you'd like to synchronize the colors/thresholds across multiple heatmaps, such as when comparing different AP placements, you can run
wifi-heatmap-thresholds passing it each of the titles / output JSON filenames. This will generate a
thresholds.json file in the current directory, suitable for passing to the
Add --show-points to see the measurement points in the generated maps. Typically, they aren't important when you have a sufficiently dense grid of points so they are hidden by default.
docker run \ --net="host" \ --privileged \ --name survey \ -it \ --rm \ -v $(pwd):/pwd \ -w /pwd \ -e DISPLAY=$DISPLAY \ -v "$HOME/.Xauthority:/root/.Xauthority:ro" \ jantman/python-wifi-survey-heatmap \ wifi-survey -b <BSSID> -i <INTERFACE> -s <IPERF SERVER> -p <FLOORPLAN PNG> -t <TITLE>
Note that running with
--privileged is required in order to manipulate the host's wireless interface.
docker run -it --rm -v $(pwd):/pwd -w /pwd jantman/python-wifi-survey-heatmap:23429a4 wifi-heatmap <TITLE>
docker run -it --rm -p 5201:5201/tcp -p 5201:5201/udp jantman/python-wifi-survey-heatmap iperf3 -s