added getting started page

4 files changed, 144 insertions, 0 deletions

diff --git a/web/content/images/kismet.png b/web/content/images/kismet.png
new file mode 100644
index 0000000..d4c7f81
--- /dev/null
+++ b/web/content/images/kismet.png
diff --git a/web/content/images/specan_ui.png b/web/content/images/specan_ui.png
new file mode 100644
index 0000000..b2c2c90
--- /dev/null
+++ b/web/content/images/specan_ui.png
diff --git a/web/content/images/ubertooth-lap.png b/web/content/images/ubertooth-lap.png
new file mode 100644
index 0000000..026452a
--- /dev/null
+++ b/web/content/images/ubertooth-lap.png
diff --git a/web/content/usage/start.html b/web/content/usage/start.html
new file mode 100644
index 0000000..f2da52a
--- /dev/null
+++ b/web/content/usage/start.html
@@ -0,0 +1,144 @@
+--- 
+title: Getting Started
+---
+
+<h1>Getting Started</h1>
+
+<p>There are three major components of Project Ubertooth:</p>
+
+<ul>
+	<li>hardware: The hardware design of Ubertooth One is quite stable. You can
+	<a href="../../hardware/build">build</a> one or <a
+	href="http://greatscottgadgets.com/">buy</a> one.</li>
+	<li>firmware: This is software that executes on the ARM processor on the
+	Ubertooth One itself.  This page assumes that you have the USB bootloader
+	plus bluetooth_rxtx firmware installed on your board (which is typically
+	what is installed at the time of assembly). The bluetooth_rxtx firmware is
+	moderately stable but is likely to be enhanced as time goes on.</li>
+	<li>host code: This is software running on a general purpose computer
+	connected to the Ubertooth One via USB. The sample host code for Project
+	Ubertooth is in active development and will likely change a great deal in
+	the coming months.</li>
+</ul>
+
+<p>Ubertooth One is a development platform. The true power of the device is
+best realized when you start writing your own software and adapting it to your
+needs. If you are just getting to know the board, however, it can be helpful to
+try out open source code that others have made available. This guide will help
+you get started with your Ubertooth One by introducing you to some useful host
+code from the Ubertooth software repository.</p>
+
+<h2>Spectrum Analysis</h2>
+
+<img src="../../images/specan_ui.png" alt="spectrum analyzer screenshot" />
+
+<p>The first thing you should try with a new Ubertooth One is real-time
+spectrum analysis. Take a look at Jared's <a
+href="http://www.sharebrained.com/2011/05/24/ubertooth-spectrum-analysis-fun/">demonstration
+video</a> for a preview.</p>
+
+<p>Connect an antenna to your Ubertooth One and plug it into your computer.
+(Never operate your Ubertooth One without an antenna connected.) You should see
+the RST and 1V8 LEDs illuminate. This indicates that the LPC175x
+microcontroller is running (RST) and that power is being supplied to the CC2400
+wireless transceiver IC (1V8). The USB LED may also light up if your computer's
+operating system has enumerated and configured the device (typical on Linux).
+Now you need some host code to tell the Ubertooth One what to do.</p>
+
+<p><a href="http://sourceforge.net/projects/ubertooth/">Download</a> the latest
+Project Ubertooth file release or check out current development code from the
+<a href="http://sourceforge.net/projects/ubertooth/develop">svn repository</a>
+and navigate to the host/specan_ui directory. Take a look at the README file
+and make sure that you have installed the prerequisite software. Then execute
+specan_ui.py as described in the README and watch the 2.4 GHz activity detected
+by the Ubertooth One.</p>
+
+<p>One possible thing that could go wrong at this point is that your operating
+system does not grant you permission to communicate with the USB device.
+Depending on your distribution and preference, this can be fixed on Linux by
+either adding your user account to the &quot;usb&quot; group or by creating a new udev
+rule:</p>
+
+<code>$ echo 'ACTION==&quot;add&quot; BUS==&quot;usb&quot; SYSFS{idVendor}==&quot;ffff&quot;
+SYSFS{idProduct}==&quot;0004&quot; GROUP:=&quot;ubertooth&quot; MODE:=&quot;0660&quot; &gt;
+/etc/udev/rules.d/40-ubertooth.rules</code>
+
+<p>You can either create an &quot;ubertooth&quot; group to match this rule or change the
+rule to refer to the group of your choice.</p>
+
+<p>During operation of specan_ui.py, the RX LED should illuminate, and the USR
+LED should be dimly lit. After you finish trying out specan_ui.py, reset your
+Ubertooth One by unplugging it and plugging it back in.</p>
+
+<h2>LAP Sniffing</h2>
+
+<img src="../../images/ubertooth-lap.png" alt="ubertooth-lap screenshot" />
+
+<p>Bluetooth packets start with a code that is based on the Lower Address Part
+(LAP) of a particular Bluetooth Device Address (BD_ADDR). The BD_ADDR is a 48
+bit MAC address, just like the MAC address of an Ethernet device. The LAP
+consists of the lower 24 bits of the BD_ADDR and is the only part of the
+address that is transmitted with every packet.</p>
+
+<p>The most important passive Bluetooth monitoring function is simply capturing
+the LAP from each packet transmitted on a channel. LAP sniffing allows you to
+identify Bluetooth devices operating in your vicinity.</p>
+
+<p>In order to sniff LAPs, you'll have to compile the tools in
+host/bluetooth_rxtx. These are command line programs intended to work with the
+bluetooth_rxtx firmware installed on your Ubertooth One. Follow the
+instructions in the README file in that directory to install the the
+prerequisite <a href="http://libbtbb.sourceforge.net/">libbtbb</a>, a library
+for Bluetooth baseband functions. You can install libbtbb from a <a
+href="http://sourceforge.net/projects/libbtbb/files/">file release</a> rather
+than git if you prefer.</p>
+
+<p>Once libbtbb is installed, just type &quot;make&quot; in the
+host/bluetooth_rxtx directory to compile the tools there. Then make sure your
+Ubertooth One is plugged in and execute:</p>
+
+<code>$ ./ubertooth-lap</code>
+
+<p>You should see various random LAPs detected. Due to uncertainties in
+identifying Bluetooth packets without prior knowledge of an address, it is
+normal for this process to identify false positives at a rate of roughly 20 per
+minute. When you see the same LAP detected more than once, that is very likely
+an actual Bluetooth transmission.</p>
+
+<p>Generate some Bluetooth traffic and enjoy the show. I like to use a mobile
+phone or other Bluetooth device to perform an inquiry (usually called
+&quot;find new Bluetooth devices&quot; or something similar) to make sure that
+everything is working properly. An inquiry should produce lots of packets with
+the LAP 0x9e8b33.</p>
+
+<h2>Kismet</h2>
+
+<img src="../../images/kismet.png" alt="Kismet-Ubertooth screenshot" />
+
+<p>More advanced Bluetooth sniffing has been implemented in the form of a
+plugin for <a href="http://www.kismetwireless.net/">Kismet</a>, the venerable
+802.11 monitoring tool. In order to compile the Kismet-Ubertooth plugin, you
+will need a Kismet source tree matching the installed version. The easiest way
+to make this work is to uninstall any binary Kismet installation you may have
+installed and then download the Kismet source and follow the instructions to
+compile and install from the fresh source code. Once Kismet is installed,
+follow the instructions in host/kismet/plugin-ubertooth/README to install and
+use the plugin.</p>
+
+<p>Notice that Kismet-Ubertooth identifies not only the LAP but also the 8 bit
+Upper Address Part (UAP) of detected devices as it is able. This is done by
+analyzing the timing and other characteristics of multiple packets over time.
+Another advantage of Kismet is that it dumps complete decoded packets to a
+pcapbtbb file that can be read with a Wireshark plugin that is distributed with
+<a href="http://libbtbb.sourceforge.net/">libbtbb</a>. Full packet decoding is
+only possible when the packet's UAP has been determined.</p>
+
+<h2>Where to Go from Here</h2>
+
+<p>I hope you have found this guide helpful in getting to know your Ubertooth
+One. The host code for Project Ubertooth is in active development and new
+features are being worked on all the time. If you are interested in
+contributing to the project, or if you need help or would just like to chat
+about Project Ubertooth, join the <a
+href="https://lists.sourceforge.net/lists/listinfo/ubertooth-general">ubertooth-general</a>
+mailing list. Happy hacking!</p>