1Spectrum Tools
2--------------
3(c) 2007-10 Michael Kershaw/Dragorn <dragorn@kismetwireless.net>
4Licensed under GPL
5
6Wi-Spy and Metageek are (c)/(tm)/(foo) MetaGeek LLC
7
8Spectrum-Tools is a set of utilities for using the Wi-Spy USB spectrum
9analyzer tools from Metageek LLC (http://www.metageek.net). They include
10userspace drivers for the hardware (implemented via libusb), a graphing
11UI built on GTK/Cairo, network servers for remote devices, and simple
12utilities for developing additional tools.
13
14Extra thanks to Ryan Woodings and Metageek at large for providing hardware,
15device specs, and support for open source!
16
17* Spectool GTK
18
19 A GTK/Cairo based grapher for the Wi-Spy devices. Roughly analogous to
20 the Metageek windows application, the GTK UI provides Planar (standard
21 SA interface), Topographic (time-based 2d view) and Spectral (waterfall)
22 graphs, supports multiple simultaneous devices, and network devices.
23
24 Planar Graph:
25 A traditional view of the spectrum showing average, peak, and current
26 values. Markers may be placed on the graph to show detailed information
27 about specific frequencies.
28
29 Spectral Graph:
30 A traditional waterfall view of the spectrum over time, color intensity
31 indicates power levels at a given time.
32
33 Topographic Graph:
34 2d view of signal peaks over time. Graph points are calculated by
35 the frequency at which it was the peak power sample for that slice of
36 spectrum.
37
38 Requirements:
39 * A Wi-Spy analyzer
40 * LibUSB (0.1.12 or 1.0 with the compatibility layer)
41 * GTK 2.0 with Cairo support
42
43* Spectool Raw
44
45 Minimal interface to the device which prints supported ranges and
46 spectral data. Multiple device and network device support included.
47
48 Requirements:
49 * A Wi-Spy analyzer
50 * LibUSB (0.1.12 or 1.0 with the compatibility layer)
51
52* Spectool Net
53
54 Network server for the cross-platform cross-tool network protocol for
55 remote sensors. Supports broadcast announcement, device locking, remote
56 device configuration, etc.
57
58 Requirements:
59 * A Wi-Spy analyzer
60 * LibUSB
61
62COMPILING:
63 Prepare the source using './configure', the standard autoconf configuration
64 should detect the presence of GTK, libUSB, etc. Review the
65 configuration output if a component is not detected.
66
67 To build the tools, simply run 'make' (or 'gmake', depending on platform).
68
69 LibUSB 0.12 is required. LibUSB 1.0 may be used, but the compatibility
70 layer must be installed.
71
72INSTALLING UDEV RULES:
73 Udev is the dynamic device system for Linux. The file "99-wispy.rules" contains
74 the rules to make the wispy device accessible by users in the group "plugdev"
75 without requiring root access.
76
77 Typically udev rules go in /etc/udev/rules.d/ however it may depend on your
78 distribution. Those packaging wispy-tools for distros should modify this
79 location as necessary. Depending on your distro, it may be necessary to
80 restart udevd with "/etc/init.d/udevd restart"
81
82ODDS & ENDS:
83 * Can I use an 802.11 card instead of a Wi-Spy?
84
85 NO.
86
87 The Wi-Spy might look like a wireless card, but it's not. It's designed
88 to report signal levels, not decode traffic. An 802.11 card is a very
89 different beast, and if theres a way to get spectral data out, it's
90 not public (and would be completely dependent on the device type).
91
92 * Can I make this suid root?
93
94 I suppose you could, but I wouldn't recommend it. While it doesn't handle
95 any foreign data (all data comes from the USB device, which reports signal
96 levels, not packet data), there could be unknown overflows in the local
97 app or in one of the libraries it uses, like GTK. It'd be a better idea
98 to not create an exposure unnecessarily.
99
100 A much better method would be to add the udev rules.
101
102 * Will this work on *BSD?
103
104 Maybe - I've made efforts to make it cross-platform, however not all
105 *BSD variants have support for detaching HID devices and don't know
106 to ignore the Wi-Spy hardware.
107
108 * When will you add feature $foo?
109
110 When I get to it, when someone asks for it, or when someone sends me a
111 patch.
112
113 * What about Kismet?
114
115 Some form of integration with Kismet will come in the NewCore branch of
116 Kismet at some point in the not-too-distant future.
117
118 * You don't know what you're doing, $bar isn't written right
119
120 Probably. I'm not a big graphics coder. Send me patches.
121
122 * What happened to curses and log?
123
124 Curses was more hassle than I thought it was worth to port to the new
125 framework. If people complain about it going missing, I'll rewrite it
126 to use the new stuff.
127
128 Logging has evolved into a binary file. Support will be added in a
129 future release, as standalone and as part of the GUI.
130
131TROUBLESHOOTING:
132
133 * Unable to claim device
134
135 The Spectrum tools have to be able to claim the device. If another
136 tool has already grabbed it (like another copy of one of the tools, or
137 more often, the kernel HID) then it won't be able to run.
138
139 If you are running on a platform for which LibUSB has detach support,
140 the tools will try to disconnect the device from whatever is claiming it
141 currently.
142
143 If you are running on older versions of Linux and LibUSB, the tools
144 contain a terrible hack which guess at libusb and kernel internals and
145 attempt to disconnect.
146
147 * Strange GTK errors and compile fails
148
149 You probably have an older GTK which doesn't have Cairo integration.
150 Upgrade.
151
152 * Unable to attach - are you root?
153
154 The spectrum tools use a userspace driver implemented in LibUSB. It has to
155 be able to directly open and write to the USB device, which means it has
156 to be running as root, or as an account with equivalent hardware access
157 rights. The enclosed udev rules should allow you to set the ownsership
158 of the devices automatically.
159
160 * Something crashed
161
162 Let me know what happened, send me a core dump or a gdb backtrace.
163
164