There are three major components of Project Ubertooth:
- hardware: The hardware design of Ubertooth One is quite stable. You canbuild one or buy one.
- firmware: This is software that executes on the ARM processor on theUbertooth One itself. This page assumes that you have the USB bootloaderplus bluetooth_rxtx firmware installed on your board (which is typicallywhat is installed at the time of assembly). The bluetooth_rxtx firmware ismoderately stable but is likely to be enhanced as time goes on.
- host code: This is software running on a general purpose computerconnected to the Ubertooth One via USB. The sample host code for ProjectUbertooth is in active development and will likely change a great deal inthe coming months. If you have not yet built the host code, please followthe build guide.
Ubertooth One is a development platform. The true power of the device isbest realized when you start writing your own software and adapting it to yourneeds. If you are just getting to know the board, however, it can be helpful totry out open source code that others have made available. This guide will helpyou get started with your Ubertooth One by introducing you to some useful hostcode from the Ubertooth software repository.
Spectrum Analysis
The first thing you should try with a new Ubertooth One is real-timespectrum analysis. Take a look at Jared's demonstrationvideo for a preview.
Connect an antenna to your Ubertooth One and plug it into your computer.(Never operate your Ubertooth One without an antenna connected.) You should seethe RST and 1V8 LEDs illuminate. This indicates that the LPC175xmicrocontroller is running (RST) and that power is being supplied to the CC2400wireless transceiver IC (1V8). The USB LED may also light up if your computer'soperating system has enumerated and configured the device (typical on Linux).Now you need some host code to tell the Ubertooth One what to do.
Download the latestProject Ubertooth file release or check out current development code from thesvn repositoryand navigate to the host/specan_ui directory. Take a look at the README fileand make sure that you have installed the prerequisite software. Then executeubertooth-specan-ui as described in the README and watch the 2.4 GHz activitydetected by the Ubertooth One.
One possible thing that could go wrong at this point is that your operatingsystem does not grant you permission to communicate with the USB device.Depending on your distribution and preference, this can be fixed on Linuxeither by adding your user account to the "usb" group or by creatinga new udev rule such as:
$ echo 'ACTION=="add" BUS=="usb" SYSFS{idVendor}=="ffff"SYSFS{idProduct}=="0004" GROUP:="plugdev" MODE:="0660"' >/etc/udev/rules.d/99-ubertooth.rules
A udev rules file is available in host/bluetooth_rxtx directory in both svnand the release packages. Copy it to /etc/udev/rules.d and run thefollowing as root:
udevadm control --reload-rules
Make sure you are a member of the "plugdev" group or change therule to refer to the group of your choice. After adding the udev rule, unplugthe Ubertooth One, reboot or restart udevd, and plug in the Ubertooth Oneagain.
During operation of ubertooth-specan-ui the RX LED should illuminate, andthe USR LED should be dimly lit. After you finish trying outubertooth-specan-ui reset your Ubertooth One by unplugging it and plugging itback in.
LAP Sniffing
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 48bit MAC address, just like the MAC address of an Ethernet device. The LAPconsists of the lower 24 bits of the BD_ADDR and is the only part of theaddress that is transmitted with every packet.
The most important passive Bluetooth monitoring function is simply capturingthe LAP from each packet transmitted on a channel. LAP sniffing allows you toidentify Bluetooth devices operating in your vicinity.
In order to sniff LAPs, you'll have to compile the tools inhost/bluetooth_rxtx. These are command line programs intended to work with thebluetooth_rxtx firmware installed on your Ubertooth One. Follow theinstructions in the README file in that directory to install the theprerequisite libbtbb, a libraryfor Bluetooth baseband functions. You can install libbtbb from a file release ratherthan git if you prefer.
Once libbtbb is installed, just type "make" in thehost/bluetooth_rxtx directory to compile the tools there. Then make sure yourUbertooth One is plugged in and execute:
$ ubertooth-rx
You should see various random LAPs detected. Due to uncertainties inidentifying Bluetooth packets without prior knowledge of an address, it isnormal for this process to identify false positives. error correction shouldmitigate this problem, but a small number of false positives may still be seen.When you see the same LAP detected more than once, that is very likely an actualBluetooth transmission.
Generate some Bluetooth traffic and enjoy the show. I like to use a mobilephone or other Bluetooth device to perform an inquiry (usually called"find new Bluetooth devices" or something similar) to make sure thateverything is working properly. An inquiry should produce lots of packets withthe LAP 0x9e8b33.
Once you have seen a LAP multiple times, you can be confident that it is agenuine Bluetooth piconet. To find the next byte of the address, the UAP, wecan use:
$ ubertooth-rx -l [LAP]
In this mode ubertooth-rx only detects packets from the given piconet anduses them to determine the next byte of the address and some of the internalclock value.
For more information on this process, and the challenges involved in monitoring Bluetooth connections, please read this blog post
Kismet
More advanced Bluetooth sniffing has been implemented in the form of aplugin for Kismet, the venerable802.11 monitoring tool. In order to compile the Kismet-Ubertooth plugin, youwill need a Kismet source tree matching the installed version. The easiest wayto make this work is to uninstall any binary Kismet installation you may haveinstalled and then download the Kismet source and follow the instructions tocompile and install from the fresh source code. Once Kismet is installed,follow the instructions in host/kismet/plugin-ubertooth/README to install anduse the plugin.
Notice that Kismet-Ubertooth identifies not only the LAP but also the 8 bitUpper Address Part (UAP) of detected devices as it is able. This is done byanalyzing the timing and other characteristics of multiple packets over time.Another advantage of Kismet is that it dumps complete decoded packets to apcapbtbb file that can be read with a Wireshark plugin that is distributed withlibbtbb. Full packet decoding isonly possible when the packet's UAP has been determined.
Where to Go from Here
I hope you have found this guide helpful in getting to know your UbertoothOne. The host code for Project Ubertooth is in active development and newfeatures are being worked on all the time. If you are interested incontributing to the project, or if you need help or would just like to chatabout Project Ubertooth, join the ubertooth-generalmailing list. Happy hacking!
