Wi-viz: Wireless Network Visualization

By Nate True (www.natetrue.com, wiviz@natetrue.com)

Wi-viz is Open-Source, published under the GNU General Public License v2.0.

Quick links: Download source or Online Demo Page
        (also Wi-viz binaries)

About Wi-viz

No one can see radio signals. They're just there, like magic. Few people question how these mysterious signals connect their laptop computers to the Internet, how the complicated protocols work to move their data speedily from one wireless location to the next.

That is, until something goes wrong.

This is where Wi-viz comes in. Running on a Linksys WRT54G or compatible router powered by the excellent Linux firmware OpenWRT, Wi-viz places the wireless apparatus into a special monitor mode that doesn't interfere with the operation of the router. Here it sits, calmly examining all wireless packets coming into the interface, extracting valuable information about the surrounding wireless infrastructure.

With Wi-viz's handy intuitive web interface, Wi-viz exposes this information in a simple, easy-to-use, self-arranging format:

Wi-viz creates a self-organizing map of the wireless environment.

Using Wi-viz

First off, go buy yourself a Linux-running wireless router based on the Broadcom BCM47xx/53xx hardware (list). If you don't have one, or you just can't wait to see the elegance of Wi-viz, please feel free to try out the demo.

Mouse-over to see more info
Once you have your wireless router, install the OpenWRT custom linux firmware following the method described in OpenWRT's excellent Wiki documentation. Be sure to use the "experimental" version, as Wi-viz requires it. Don't worry, this "experimental" version is experimental by name only. It has undergone extensive testing and is quite reliable. The installlation process is a little complicated, but the payoff is well worth it for a fully functional 200mhz(ish) computer in a very inexpensive lightweight platform with low power consumption. Oh, and Wi-viz!

Wi-viz controls
Okay, now you've gotten OpenWRT running. All that remains is to download the Wi-viz binary tarball and extract it to /
You could also download the source and compile it yourself, but cross-compiling is a bloody spicy meatball. Not recommended for the faint of heart.

After installing, simply go to the Wi-viz page on the built-in webserver on your router (probably

Wi-viz will automatically start monitoring your wireless environment and creating the self-rearranging map. Use the controls on the right to start/stop the dynamic webpage, or enable channel hopping (which won't work if your router is in AP mode).

You can mouse-over any icon on the map to display additional information.

Inside Wi-viz

Alright, so you've read this far down and haven't been distracted by the pretty demo or the glamour of hacking your wireless router. So let's dive in and see how Wi-viz works, shall we?

Wi-viz pretty much consists of two parts, the back-end packet-gathering daemon and the front-end DHTML self-rearranging Javascript display. Both are vital to the creation of Wi-viz's signature diagnostic display.

An in-depth look at Wi-viz

The packet analyzer

The packet analyzer itself kind of has two parts. The smaller part is the channel-hopper. It pretty much gets started as a fork and does ioctls to change the channel of the wireless card, then sleeps until it's time to change channels again. I mentioned it first because it's so boring and predictable, and I like to get my technical descriptions off to a good start.

The primary portion of the packet analyzer daemon starts by placing a special, undocumented ioctl call to the Broadcom driver (greets to nbd for that) which causes the driver to go into a special monitor mode. Packets meant for the router are processed as normal, but whenever a packet would be rejected by the Broadcom wireless chipset's Media Access Control layer, a Prism monitor-mode header is added to it and it is sent in via the new monitor-mode interface, the network device prism0.

The packet analyzer uses libpcap to snarf these packets off of the device, then runs an analysis routine on them. The packets are scrubbed for source/destination MAC addresses as well as BSSID's. Beacon and probe-request frames are used to capture data about access points, and data frames indicate associations. To ensure speedy response, hosts are stored in a statically-allocated table and indexed via hashing with linear probing.

When the daemon receives a SIGUSR1, it dumps its current host table in a Javascript format to /tmp/wiviz-pipe for retrieval.

The DHTML self-arranging display

The front-end really isn't anything special. It uses setTimeout() to reload a hidden iframe every five seconds, which contains a function call to a callback in wiviz.js. The callback then steps through the list, updating any hosts already on the display, and positioning any new hosts based on a hash of the MAC address and the signal strength. Then the whole thing undergoes an iterative declumping step which uses something akin to physics simulation to make unrelated stations repel each other while APs and their clients attract. Lines of dots (known as 'pips') connect APs to connected clients to show their relation.

The self-organizing map was designed with intuitive use in mind. Hosts will always appear in the same area of the map, since their position is calculated using the MAC address. Also, stations are assigned a short pronouncible "mnemonic" name to let you tell them apart.

Configuration changes are implemented via form submittal to a CGI on the webserver. The CGI dumps its output to /tmp/wiviz-cfg and sends Wi-viz a SIGUSR2 to tell it to reload its configuration. Wi-viz does this happily and assimilates the new configuration.

And that's how Wi-viz works. I really just threw it together over a period of like three days, so don't get on me for it not being elegant. There are still plenty of things Wi-viz does not do, and here are some of them:

Things Wi-viz does not do (the incomplete list)

Of course, since Wi-viz is open-source, you could implement all the changes you want! If you can think of anything else that Wi-viz does not do, please don't hesitate not to e-mail me.


Okay, so you finished reading my page and now you're bored. Here are some links to check out:
This page and all content Copyright © 2005 by Nathan True, wiviz@natetrue.com