Last Update: March 21, 2015

Documentation

WiFi Radar 2.0 User Manual

by Sean Robinson

Introduction

This guide should help explain the features of WiFi Radar 2.0 and how to utilize them. This document does not try to be comprehensive, but instead may point to external documents that more fully explain a topic. If your question is not answered here, please email the WiFi Radar mailing list and ask the helpful people there.

Starting WiFi Radar

WiFi Radar runs ifconfig and iwconfig (and, optionally, a DHCP client and a WPA supplicant), which require root priviledges. So, one must run wifi-radar as root or use sudo wifi-radar.

Selecting a Network Card

From the main window, click the Preferences button. On the General tab, select ''Auto-detect wireless device'' to have WiFi Radar use the first wireless NIC it finds. Or un-select Auto-detect wireless device and choose a wireless card from the Wireless device pull-down.

Configuring a Profile

Select an access point (AP) or profile and click the Configure button. This opens the Profile Editor window. The network name and address should have been set when one entered the editor. Clicking on a right-pointing arrowhead will cause the related item to expand.

Roaming

Roaming describes how to interact with mulitple access point (AP) networks, a.k.a. Master-mode networks. Without Roaming, one can/must set a profile for each AP with which one wishes to associate in the network.

With Roaming, all APs in the network are collected under one network profile. The signal icon in a Roaming profile is the AP with the strongest signal in the latest scan-pass and this AP is used to associate with the network. Some sources claim the WiFi NIC driver will re-associate with a stronger signal AP if the existing associated signal strength falls below a threshold. This does not appear to be true for all drivers.

WiFi Options

The Mode and Channel settings may be overridden if the detected network advertises diffent values.

The Key is for WEP encryption and is sent as-is to the iwconfig command. If one has a hex string as the key, just enter it directly (e.g. passcode is ABCDEF-12345, use ABCDEF12345). If the key is a password, it should be prepended with "s:" (e.g. password is CoffeeShack2009, use s:CoffeeShack2009).

The Security setting does not currently do anything. Instead, the Key determines whether the connection is encrypted.

WPA Options

Expanding No WPA changes the section title to Use WPA and WiFi Radar will attempt to use WPA with the Driver one enters.

Network Configuration Options

Expanding Automatic network configuration (DHCP) changes the section title to Manual network configuration. In the collapsed mode, WiFi Radar will use the configured DHCP client to configure the network connection after associating with the AP. In the expanded mode (i.e. manual configuration), the setting one enters for each of option (IP, NetMask, etc) is used.

Commands

The Connection Commands are used to run a command before and after connecting to a network. The Disconnection Commands are used to run a command before and after disconnecting from a network. More information about the environment in which these commands execute can be read in the Environmental Variables in Connect and Disconnect Scripts HOWTO.

Networks with Multiple Access Points

See the Roaming section of Configuring a Profile.

Connecting to and Disconnecting from a Network

Because WiFi Radar only connects with one or fewer networks at a time, the Connect and Disconnect buttons share the same space on the main window, but only one is visible at a time.

Connecting to a network is as simple as selecting a profile in the list of APs and clicking on the Connect button. In fact, the Connect button will not be clickable until a profile has been selected.

If one is currently connected to a network, click the Disconnect button.

Main Window

This is the main user interface for WiFi Radar. The left side of the window shows a list of configured profiles and currently detected access points (AP). Under this list is a status message detailing connection information. The right side contains buttons with commands to manipulate profiles, including: New, Configure, Delete, Connect, and Disconnect. And the bottom of the window has buttons general to WiFi Radar operations, including: About, Preferences, and Close.

In the AP list, each row is a network. The first column has one or two icons for whether the network is a configured profile and whether encryption is used. The Access Point column shows the network name and address for a non-roaming (single AP) network or network name and "Multiple APs" for a roaming profile. The Signal column displays an icon with bars indicating signal stength. The Mode column shows the network access type. The 802.11 column displays the network type (i.e. a, b, g, or n), some NIC drivers do not report this information and this column will only show 'g'. The Channel column shows the channel on which the network is operating.

The buttons on the upper part of the right-hand side of the window are for creating a new profile, configuring a profile, or deleting a profile. The lower portion of the right-hand side displays either the Connect or Disconnect button, depending on the connection state.

The bottom of the main window has three buttons: About, Preferences, and Close. The About button shows copyright and license information along with a list of contributors. The Preferences button opens the Preferences window, allowing one to set various options for WiFi Radar. The Close button quits the program, but does not change the state of the wireless connection.

Icons

The icons used in WiFi Radar are, hopefully, easily interpreted. But, if one is wondering about the meaning of each of these visual elements, this should clear up any confusion.

These icons indicate either a known or unknown network. Specifically, is there a profile configured for the network, or not.

This icon, if shown, is a variation of a lock (depending on your GNOME icon theme) and indicates whether the network is encrypted.

These icons are a somewhat arbitary indicator of signal level, where more bars filled means a stronger signal.

Profile Editor

The Profile Editor is where one configures an access point (or network) profile.

The network name is sometimes also called the network ESSID. The network address is also known as the BSSID and is only used if one is connecting to a single access point (AP) and Roaming is off. With Roaming on, this profile connects to whichever AP in the network provides the strongest signal.

Under WiFi Options, Mode and Channel will generally be automatically set by WiFi Radar at the time a network connection is requested. The Key is the WEP encryption key to use with this network. This key is sent as-is to the card, so should either be a hexadecimal string or a passphrase beginning with "s:" Security mode is not currently used explicitly, setting the Key sets the encryption mode.

The WPA Driver should be one of the drivers available in your WPA Supplicant.

If one opens the Use DHCP expander, one can set manual IP network settings.

One can set commands to run before and after the connection phase and before and after the disconnection phase. More information is available about the environment in which these commands run.

Preferences

General

The General tab in the preferences window allows one to set the wireless device to use, control whether to vocalize status messages, and decide how to control the wireless card. If one would prefer to have status messages in WiFi Radar spoken, enable Use speak-up and set the external command to use for such messages.

Some wireless cards work best if each set of commands is ended with a note to immediately make the changes requested. If one's wireless card does not seem to be associating with access points, try enabling Commit required.

Some wireless cards will not scan for available access points until told to activate as a network interface. If one has set the wireless device above and scanning still does not show nearby access pointsx, try enabling ifup required.

Advanced

The Advanced tab in the preferences window allows one to set the various external commands used to configure the wireless card and scan for access points. One can also choose where the log file will be saved and how much detail will be saved in it.

The default value for each of these options is probably sane. The distribution package one installed should have set these to be locally correct.

The Log level can be changed to save more detailed information about WiFi Radar. The default value of '50' saves the least amount of information. A log level of '1' saves the most information, probably more information than one needs unless debugging a problem. In WiFi Radar v.2.0.x, one must restart the program before the new logging threshold or log file are used.

DHCP

The DHCP tab in the preferences window allows one to choose the DHCP client and its parameters. These parameters can be set for requesting DHCP service and killing (stopping) DHCP. The other options in this tab determine how long the DHCP client should try acquiring an IP address (and other settings) and where the client stores its running state information (PID file).

Again, most of this should have been set-up by the distribution-specific package.

Interpolated strings are allowed in the option values. A HOWTO describing the use of interpolated strings is available and the list of usable strings is in the configuration file.

WPA

The WPA tab in the preferences window allows one to choose the WPA Supplicant and its parameters.

Again, most of this should have been set-up by the distribution-specific package.

Interpolated strings are allowed in the option values. A HOWTO describing the use of interpolated strings is available and the list of usable strings is in the configuration file.

Licenses

WiFi Radar is copyright 2004 - 2009 by Ahmad Baitalmal, Brian Elliott Finley, Sean Robinson, and various other contributors and is licensed under the GNU GPL (General Public License). This User Manual is copyright 2009 by Sean Robinson and is licensed under the Creative Commons Attribution License.

Appendices

Appendix: Configuration File