WISPY Utilties
--------------
(c) 2005 Michael Kershaw/Dragorn <dragorn@kismetwireless.net>
Licensed under GPL

WiSPY and Metageek are (c)/(tm)/(foo) MetaGeek LLC

These are a set of utilities for accessing the WiSPY USB 2.4GHz spectrum
analyzer by Metageek LLC (http://www.metageek.net).  Simple graphing examples
are provided, as well as a basic USB interface utility for basing future
graphing projects against.

An extra thanks to Ryan Woodings of MetaGeek for providing operational 
details and supporting open source!

* WiSPY Curses

  A simple Curses-based grapher for data from the WiSPY device.  Data is fetched
  purely in userspace via libusb.
  
  WISPY_CURSES REQUIREMENTS:
    * A WiSPY analyzer
    * LibUSB
    * Libcurses or libncurses
    * A platform supported by LibUSB (tested on Linux, OSX)

* WiSPY GTK

  A GTK grapher for data from the WiSPY device.  Data is fetched purely in
  userspace via libusb.  The WiSPY GTK interface is modeled off the Metageek
  windows application interface, although there are some differences.
  
  WISPY_GTK REQUIREMENTS:
    * A WiSPY analyzer
    * LibUSB
    * GTK 1.2 or GTK 2.0
    * A platform supported by LibUSB

COMPILING:
  Prepare the source using './configure', the standard autoconf configuration
  tool.  Configure should detect libusb, curses, and gtk-1.2 and gtk-2.0 
  installs.

  To build the tools, simply run 'make'.

WISPY CURSES:
  wispy_curses must be run as root, or as a user with r/w access to the 
  USB system.

  On the graph display, ':' denotes the peak value seen for that frequency,
  and '*' denotes the current value.

  Pressing 'c' clears the previous peak signal levels.  'q' quits.

WISPY GTK:
  wispy_gtk must be run as root, or as a user with r/w access to the
  USB system.

  There are 2 graphing modes:  Graph, and Spectromap

  GRAPH MODE:
  On the graph display, the black denotes the peak value seen and the yellow
  denotes the current signal.  The green denotes the average value since the
  graphs were last cleared.

  While in graph mode, a marker can be set by clicking or clicking and dragging
  inside the graph area.  It will indicate the power level the marker is set to.
  The marker can be removed by click and dragging it out of the graph area.

  Channels can be hilighted by clicking on the channel number.  Click in the
  channel area, not on a number, to unselect channel hilighting.

  SPECTROMAP MODE:
  Spectromap mode is a historical representation of the signal data seen.  
  Each row represents the peak data for that sample period, indicated by color
  intensity.  Blue indicates the weakest signals, while red indicates the
  strongest.

  The 'clear' button resets the peak, average, and spectromap history values.

ODDS & ENDS:
  * Can I make this suid root?

    I suppose you could, but I wouldn't reccomend 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 or Curses.  It'd be a 
    better idea to not create an exposure unnecessarily.

  * 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.

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

    If you are running under Linux, the tools contain a terrible hack to try
    to detatch the driver from the kernel HID drivers.  This hack depends on
    guessing internals of LibUSB and might not work on versions of the 
    library other than what I've used.  LibUSB will be incorporating kernel 
    detatch functionality soon, and proper detection & usage of that will
    be added to the WiSPY tools.

  * Unable to attach - are you root?

    The WiSPY tools use a userspace driver implemented in LinUSB.  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.

  * Something crashed

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

