ARCHITECTURE

StumblerPainter uses a Model-View-Controller approach. The code is separated into three packages, core, gui and graphing. The Model and Controller are found in the core package, while the View is spread across the gui and graphing packages.

Table of Contents

1.0 MODEL

The data to be analyzed is contained in NetStumbler NS1 files submitted by the user. NS1 files form a database of individual readings taken from a WiFi card. When paired to a GPS unit, these readings can be laid out spatially. Each reading records signal strength, noise, channel, GPS coordinates (if applicable) and many others.

Functionality from the PlaceLab library was used to open and extract the information stored within the NS1 files. In the goal of avoiding a dependency to external .jar files, the required source code was extracted and included in the project. This code is contained in the org.placelab.* package.

Once extracted, the result is an ns1 object which contains a Vector of AP objects. These AP objects contain all the readings, named Encounters, which were recorded for a specific access point. This Vector is the main Data Structure that is used by StumblerPainter. Both the AP and Encounter classes are defined within the org.placelab.util.ns1 package.

back to top

2.0 CONTROLLER

The main class, StumblerPainter, takes care of instantiating the GUI as well as defining the methods and procedures that control how the View interacts with the Data Structure. It first presents a Splash screen to the user and then creates an instance of itself.

StumblerPainter's constructor takes care of instantiating the GUI objects and registering all of the ActionListeners to the GUI objects. The ActionListeners are all defined within the constructor. Contained within the ActionListeners is the logic for all the main actions that can be performed within StumblerPainter such as opening NS1 files and opening images and changing the display mode of the graphing module.

These main actions are listed in the Actions.java class. This class contains a list of strings used to identify the actions defined within StumblerPainter.

back to top

3.0 VIEW

The view for StumblerPainter consists of the GUI itself as well as the graphing functions used to represent the recorded stumbler data.

3.1 GUI

As an exercise on learning GUI programming, the GUI was entirely coded manually following Java's Layout and Visual Alignment best practices from the Java Look and Feel Design Guidelines. The GUI consists of three main components: the MainWindow, the MapPane and the CoordinateWindow. Each window, as per Java Best Practices, is invoked statically through a static function named createAndDrawWindow().

The MainWindow, instantiated by StumblerPainter's constructor, is the primary interface that is presented when the program starts. From the MainWindow, the user can open NS1 files, images and can navigate between the three panes located within the MainWindow. Two of these panes present a simple table showing the data contained in the NS1 files, one showing each reading individually and the other showing the list of discovered access points. The third pane is the canvas used for plotting the collected data.

Each GUI item provides methods for registering Actions to its components. These methods are invoked during the static instantiation of the component with createAndDrawWindow. The keywords used to link program functionality to the GUI components are listed in the Actions class. Each Window is responsible for defining the behavior and registering the actions of its internal actions which do not affect the rest of the system.

back to top

3.2 Graphing

The Graphing module of StumblerPainter is found inside the stumblerpainter.graphing package. The Module contains all the logic used for the 2d painting used by StumblerPainter. The MapPane coordinates the plotting of the stumbler results and displays them.

Upon instantiation, it receives a reference to the Access-Point data structure containing all the readings. Depending on what APs the user wants to see it then simplifies the GPS location data by converting them to ratios (WeightedSeedRatio) and generates a new list locally, leaving the original data structure untouched.

The MapPane then supplies the static plotting functions with the necessary information to create a signal map. The notion of distance that the map will have is supplied by the user in meters-per-pixel. The user also supplies the background image onto which the signal map will be superimposed. If no background was selected, the MapPane automatically fits all the stumbler data into a blank window.

back to top

3.2.1 MapPane

The MapPane is the container for all data-generated images. It is responsible for coordinating the generation of the images to be displayed and for laying them onto itself. It is able to graph the stumbling results whether the user attached a background map or not. Another of its functionalities is to calculate the bounds of the area to be painted. If a background is selected, the bounds will depend on the distance covered by the submitted map. If no background is selected, the bounds will adjust to all the readings in the submitted NS1 file. This is to allow the user to see the readings directly.

back to top

3.2.2 Plotter

The Plotter.java class is located inside the stumblerpainter.graphing package and contains all the methods used for plotting various 2d data onto the signal map. All the methods inside the Plotter class are designed to be called statically (no instance of the Plotter object ever needs to be created) so as to keep the plotting functions as independent and interchangeable as possible from the rest of the program.

All of the methods except drawLegend() are used to draw the data acquired from the site survey. Each method takes in the width and height of the image to be produced in pixels, the meters-per-pixel value defining the distance between each pixel and the Weighted-Seed Ratio containing the relative location data of each reading.

The end result is a finished 2D image that maps the positional data within a rectangular viewport. All untouched pixels are left black. All remaining black pixels are then made transparent using the makeColorTransparent function from the stumblerpainter.gui package. The resulting image can then easily be superimposed to a background image.

back to top

3.2.2.1 Weighted-Seed Ratio

The Weighted-Seed Ratio exists to remove complexity from the Plotting algorithms. Instead of having the plotting algorithms execute complex GPS conversion operations, the GPS coordinates of each reading are converted to simple ratios with respect to the range of degrees spanned by the points to be plotted. Once each GPS coordinate is converted to a ratio between 0 and 1, with position information still stored in the ratio, it is easy to scale the ratio map to the desired plot resolution. When multiplying the plot's desired height and width in pixels to the ratio, the result is the exact location in pixels on the plot.

back to top

3.2.2.2 createMWVSSPlot and plotConeSS

One ideal algorithm for plotting wireless signals is the Voronoi diagram and more specifically the Multiplicatively-Weighted Voronoi diagram. The Voronoi diagram is based on the principle that every seed on the plot is given a region of the plot depending on the location of the other seeds. Each line delimiting a seed's region would travel at exactly the half way point between each surrounding seed.

Since stronger signals will travel more easily than others, each seed is given a weight depending on its signal strength. The result is that seeds with a larger weight will have larger regions than those with a lesser weight. This is analogous to dropping different size pebbles into a puddle of water.

The method used to create this MWV plot traverses all of the readings sequentially for each predetermined signal strength range. Strong signals will be composed of most of the components of the predetermined ranges while weaker signals will only be represented by the lower end ranges of the spectrum.

When considering that wireless signals fade logarithmically over distances, it can be deduced that the resulting plot is a layering of different colored concentric and overlapping circles. The strongest signals will show the largest number of concentric circles each getting smaller as they reach the higher categories of signal strength.

This type of plot essentially treats each reading as an emitter and tries to interpolate the distance that a signal travels as well as the strength it would have in proximity to the original reading.

Since the end result is essentially a collection of concentric circles (or cones) of varying sizes and colors, it is more efficient to avoid calculating the distance of each seed with respect to its neighboring seeds and to simply draw a series of circles representing each signal strength range that the reading belongs to with the correct circle size depending on signal propagation laws. This is essentially what PlotConeSS does.

back to top

3.2.2.3 PlotSeed

The previously explored plotting algorithms were all dropped in favor of a simpler method. The plotSeed method draws a simple 4-pixel wide circle for each reading colored by its signal value. This method is ideal for allowing the user to simply see where the readings are located with their respective signal strengths without any interpolation. The more readings there are the higher quality the plot.

back to top

3.2.3 PlotterHelper

The PlotterHelper class provides a set of static functions which are used to prepare or obtain data for the Plotter.

Primarily, PlotterHelper will create the Weighted-Seed Ratio Vectors used by the Plotter functions. To accomplish this, the createWSR function uses the AP data structure and the GPS bounds calculated by the MapPane. Knowing the data's bounds, the function is able to calculate the distance of each reading with respect to the origin located at the Southwest corner of the submitted data and represent this as a ratio.

PlotterHelper also provides a few GPS conversion functions for converting back and forth between GPS coordinates and distance in meters. The conversions included allow calculating the distance between two GPS coordinates and also converting from meters to GPS degrees. It is important to note that latitudinal location is important when calculating longitudinal distance since longitudinal degrees cover a larger distance at the equator than they do at the poles.

Finally, PlotterHelper provides some utility functions. These functions either clean the data structure by removing invalid entries, generate new AP lists with only the selected APs or return the proper color for graphing a particular signal strength or noise value.

back to top