Spectrum Tools 
--------------
(c) 2007-10 Michael Kershaw/Dragorn <dragorn@kismetwireless.net>
Licensed under GPL

Wi-Spy and Metageek are (c)/(tm)/(foo) MetaGeek LLC

Spectrum-Tools is a set of utilities for using the Wi-Spy USB spectrum
analyzer tools from Metageek LLC (http://www.metageek.net).  They include
userspace drivers for the hardware (implemented via libusb), a graphing 
UI built on GTK/Cairo, network servers for remote devices, and simple 
utilities for developing additional tools.

Extra thanks to Ryan Woodings and Metageek at large for providing hardware,
device specs, and support for open source!

* Spectool GTK

  A GTK/Cairo based grapher for the Wi-Spy devices.  Roughly analogous to
  the Metageek windows application, the GTK UI provides Planar (standard
  SA interface), Topographic (time-based 2d view) and Spectral (waterfall)
  graphs, supports multiple simultaneous devices, and network devices.

  Planar Graph:
    A traditional view of the spectrum showing average, peak, and current
    values.  Markers may be placed on the graph to show detailed information
    about specific frequencies.

  Spectral Graph:
    A traditional waterfall view of the spectrum over time, color intensity
    indicates power levels at a given time.

  Topographic Graph:
    2d view of signal peaks over time.  Graph points are calculated by
    the frequency at which it was the peak power sample for that slice of
    spectrum.

  Requirements:
    * A Wi-Spy analyzer
    * LibUSB (0.1.12 or 1.0 with the compatibility layer)
    * GTK 2.0 with Cairo support

* Spectool Raw

  Minimal interface to the device which prints supported ranges and 
  spectral data.  Multiple device and network device support included.

  Requirements:
    * A Wi-Spy analyzer
    * LibUSB (0.1.12 or 1.0 with the compatibility layer)
 
* Spectool Net

  Network server for the cross-platform cross-tool network protocol for
  remote sensors.  Supports broadcast announcement, device locking, remote
  device configuration, etc.

  Requirements:
    * A Wi-Spy analyzer
    * LibUSB

COMPILING:
  Prepare the source using './configure', the standard autoconf configuration
  should detect the presence of GTK, libUSB, etc.  Review the
  configuration output if a component is not detected.

  To build the tools, simply run 'make' (or 'gmake', depending on platform).

  LibUSB 0.12 is required.  LibUSB 1.0 may be used, but the compatibility
  layer must be installed.

INSTALLING UDEV RULES:
  Udev is the dynamic device system for Linux.  The file "99-wispy.rules" contains
  the rules to make the wispy device accessible by users in the group "plugdev"
  without requiring root access.

  Typically udev rules go in /etc/udev/rules.d/ however it may depend on your
  distribution.  Those packaging wispy-tools for distros should modify this
  location as necessary.  Depending on your distro, it may be necessary to 
  restart udevd with "/etc/init.d/udevd restart"

ODDS & ENDS:
  * Can I use an 802.11 card instead of a Wi-Spy?

    NO.

    The Wi-Spy might look like a wireless card, but it's not.  It's designed
    to report signal levels, not decode traffic.  An 802.11 card is a very
    different beast, and if theres a way to get spectral data out, it's 
    not public (and would be completely dependent on the device type).

  * Can I make this suid root?

    I suppose you could, but I wouldn't recommend it.  While it doesn't handle
    any foreign data (all data comes from the USB device, which reports signal
    levels, not packet data), there could be unknown overflows in the local
    app or in one of the libraries it uses, like GTK.  It'd be a better idea 
    to not create an exposure unnecessarily.

    A much better method would be to add the udev rules.

  * Will this work on *BSD?

    Maybe - I've made efforts to make it cross-platform, however not all
    *BSD variants have support for detaching HID devices and don't know
    to ignore the Wi-Spy hardware.

  * When will you add feature $foo?

    When I get to it, when someone asks for it, or when someone sends me a
    patch.

  * What about Kismet?

    Some form of integration with Kismet will come in the NewCore branch of
    Kismet at some point in the not-too-distant future.

  * You don't know what you're doing, $bar isn't written right

    Probably.  I'm not a big graphics coder.  Send me patches.

  * What happened to curses and log?

    Curses was more hassle than I thought it was worth to port to the new
    framework.  If people complain about it going missing, I'll rewrite it
    to use the new stuff.

    Logging has evolved into a binary file.  Support will be added in a 
    future release, as standalone and as part of the GUI.

TROUBLESHOOTING:

  * Unable to claim device
  
    The Spectrum tools have to be able to claim the device.  If another 
    tool has already grabbed it (like another copy of one of the tools, or 
    more often, the kernel HID) then it won't be able to run.

    If you are running on a platform for which LibUSB has detach support,
    the tools will try to disconnect the device from whatever is claiming it
    currently.

    If you are running on older versions of Linux and LibUSB, the tools
    contain a terrible hack which guess at libusb and kernel internals and
    attempt to disconnect.

  * Strange GTK errors and compile fails

    You probably have an older GTK which doesn't have Cairo integration.
    Upgrade.

  * Unable to attach - are you root?

    The spectrum tools use a userspace driver implemented in LibUSB.  It has to
    be able to directly open and write to the USB device, which means it has 
    to be running as root, or as an account with equivalent hardware access
    rights.  The enclosed udev rules should allow you to set the ownsership
    of the devices automatically.

  * Something crashed

    Let me know what happened, send me a core dump or a gdb backtrace.

