Introduction

One of the problems of relying on search engines is that the more obscure the subject you are interested in, the greater the chance that what you'll get will be either unlocatable or outdated. These are my notes on setting up the ubertooth on an ubuntu system in September of 2018, which turned out to be a slightly different experience from what I went through earlier in this year so I thought I should try and make a record of it somewhere.

The Current Release

The current release for the Ubertooth firmware and code is 2018-08-R1. Download the ubertooth-2018-08-R1.tar.xz file from that page and untar it. You will also want the matching libbtb code.

Building and Installing the Code

For some reason the instructions on the home page assume you already have the code built and installed, but there's actually some previous steps you need to do.

Install the Dependencies

sudo apt install cmake libusb-1.0-0-dev make gcc g++ libbluetooth-dev \
pkg-config libpcap-dev python-numpy python-pyside python-qt4

The python-<packages> can be downloaded from pip, and you really don't need the pyside and qt4 libraries unless you want to run the spectral scanner, which is kind of their hello-world, which is nice, but the pyside code is actually depracated because qt5 is the current version and it won't work with python 3.6 (the current ubuntu default) so I personally would skip it. numpy is always a good idea no matter what you end up doing.

Build libbtbb

libbtb is the Bluetooth Baseband Library which you need for ubertooth to decode bluetooth packets. Change into the folder you downloaded earlier and build and install it.

mkdir build
cd build
cmake ..
make
sudo make install

[ 88%] Built target btbb
[ 88%] Built target btaptap
[100%] Built target pcapdump
Install the project...
-- Install configuration: ""
-- Installing: /usr/local/lib/pkgconfig/libbtbb.pc
-- Installing: /usr/local/lib/libbtbb.so.1.0
-- Installing: /usr/local/lib/libbtbb.so.1
-- Installing: /usr/local/lib/libbtbb.so
-- Installing: /usr/local/include/btbb.h
running build
running build_py
running install
running install_lib
creating //usr/local/lib/python2.7/site-packages/pcapdump
copying /home/dogen/Downloads/libbtbb-2018-08-R1/build/python/pcaptools/build/lib.linux-x86_64-2.7/pcapdump/pcapdump.py -> //usr/local/lib/python2.7/site-packages/pcapdump
copying /home/dogen/Downloads/libbtbb-2018-08-R1/build/python/pcaptools/build/lib.linux-x86_64-2.7/pcapdump/__init__.py -> //usr/local/lib/python2.7/site-packages/pcapdump
byte-compiling //usr/local/lib/python2.7/site-packages/pcapdump/pcapdump.py to pcapdump.pyc
byte-compiling //usr/local/lib/python2.7/site-packages/pcapdump/__init__.py to __init__.pyc
running install_egg_info
Writing //usr/local/lib/python2.7/site-packages/pcapdump-0.0.0-py2.7.egg-info
-- Installing: /usr/local/bin/btaptap

Now run ldconfig.

sudo ldconfig

Ubertooth Tools

Do the same thing to build the tools. First untar the file you downloaded, change into the host folder (ubertooth-2018-08-R1/host) and build and install the code.

mkdir build
cd build/
cmake ..
make
sudo make install
sudo ldconfig

You should now have some command-line tools that start with ubertooth- (e.g. ubertooth-rx).

Privileges

You can use setcap to make it so that you don't need to run things as root. This is how to make it so you can run ubertooth-scan.

sudo setcap 'CAP_NET_RAW+eip CAP_NET_ADMIN+eip' (which ubertooth-scan)

Update the Firmware

One of the commands installed in the previous step was ubertooth-dfu which is the Do Firmware Update command that we need to update the firmware. First insert the ubertooth USB dongle, then change into the ubertooth-2018-08-R1/ubertooth-one-firmware-bin folder and run the update command.

Warning: According to the documentation you need to make sure to have an antenna on the ubertooth before inserting it. Also, it too a couple of attempts inserting, removing, and re-inserting the ubertooth before it worked for some reason (you can tell it's ready when there are two green LEDs and one red LED lit up).

ubertooth-dfu -d bluetooth_rxtx.dfu -r

As I mentioned before, the GUI for the spectral analysis is out of date and didn't install in my setup, but you can check that the ubertooth is working by just running the spectral analysis without a GUI.

ubertooth-specan

This should send a timestamp, frequency, RSSI CSV to stdout as the ubertooth sweeps the channels and shows the amount of electromagnetic radiation it sees on each.

Spectools

Since we can't run the python spectrum analyzer, we should turn to a better alternative, spectools. This was a project to mostly re-create the metageek wi-spy GUI but it supports the ubertooth. It actually looks like a dead project (the last News item on their site was from 2012), but it works for now. Luckily ubuntu has this in the repositories so you should be able to just install it with apt.

sudo apt install spectools

Once you install it you can either run spectool_curses which will run at the command line but only has one view, or spectool_gtk which will run in an X-windows environment and show three views of the 2.4 GHz spectrum.

Kismet

Now we come to the interesting installation. At this point you probably have all the command-line utilities you need, but kismet provides a convenient interface to start capturing packets. Unfortunately it is going through a major upgrade which makes it incompatible with the ubertooth plugin for it (maybe, there's two plugins and one of them might work, but they don't seem to document it (or much else, for that matter)).