This build guide is out of date


Up to date instructions for the latest release are available on our GitHub wiki

Build Guide

The Ubertooth has been used with the following platforms:

The firmware image on the Ubertooth is normally tied to the release version of the host code that it operates with, instructions for obtaining firmware images and flashing them to the Ubertooth can be found here.

Ubuntu 12.04+

(Debian/BackTrack 5 - untested)

Prerequisites

There are some prerequisites that can be installed from the apt repositories on Debian/Ubuntu systems:

  sudo apt-get install libusb-1.0-0-dev make gcc pyside-tools python-numpy

PyUSB is not yet available from the apt repositories, so it must be downloaded and built from sourece as follows:

  wget http://sourceforge.net/projects/pyusb/files/PyUSB%201.0/1.0.0-alpha-3/pyusb-1.0.0a3.tar.gz/download -O pyusb-1.0.0a3.tar.gz
  tar xvf pyusb-1.0.0a3.tar.gz
  cd pyusb-1.0.0a3
  sudo python setup.py install

Next the Bluetooth baseband library (libbtbb) needs to be built for the Ubertooth tools to decode Bluetooth packets:

  wget http://sourceforge.net/projects/libbtbb/files/libbtbb-2012-10-R3.tar.xz/download -O libbtbb-2012-10-R3.tar.xz
  tar xf libbtbb-2012-10-R3.tar.xz
  cd libbtbb-2012-10-R3
  make
  sudo make install

Ubertooth tools

There are three sets of tools that use the Ubertooth - spectrum analyzer, Bluetooth sniffing tools and firmware update. All three are built and installed by default using the following method:

  wget http://sourceforge.net/projects/ubertooth/files/ubertooth-2012-10-R1.tar.xz/download -O ubertooth-2012-10-R1.tar.xz
  tar xf ubertooth-2012-10-R1.tar.xz
  cd ubertooth-2012-10-R1/host
  make
  sudo make install

If using the ubertooth-follow tool, the Bluetooth library headers are required and the tools need to be built with the "clock_debug" flag set:

  sudo apt-get install libbluetooth-dev
  cd ubertooth-2012-10-R1/host
  make clock_debug=true
  sudo make clock_debug=true install

Kismet

The version if kismet provided by Debian/Ubuntu is 2008-05-R1, which is too old to support the Ubertooth plugin. In order to use Ubertooth with Kismet it is nessecary to compile Kismet from source:

  sudo apt-get install libpcap0.8-dev libcap-dev pkg-config \
  build-essential libnl-dev libncurses-dev libpcre3-dev \
  libpcap-dev libcap-dev
  wget http://www.kismetwireless.net/code/kismet-2011-03-R2.tar.gz
  tar xf kismet-2011-03-R2.tar.gz
  cd kismet-2011-03-R2
  ln -s ../ubertooth-2012-10-R1/host/kismet/plugin-ubertooth kismet-2011-03-R2/
  ./configure
  make && make plugins
  sudo make suidinstall
  sudo make plugins-install
  Add "pcapbtbb" to the "logtypes=..." line in kismet.conf

Wireshark

The Wireshark plugin allows Bluetooth baseband traffic that has been captured using Kismet to be analysed and disected within the Wireshark GUI. It is built separately from the rest of the Ubertooth and libbtbb software:

  sudo apt-get install wireshark wireshark-dev \
  libwireshark1 libwireshark-dev cmake
  cd libbtbb-2012-10-R3/wireshark/plugins/btbb
  cmake -DCMAKE_INSTALL_LIBDIR=/usr/lib/wireshark/libwireshark1/plugins .
  make
  sudo make install

This completes the install of the Ubertooth tools, the next step is to look at the getting started guide. It may also be useful to update the firmware on the Ubertooth.

Fedora 17+

(RedHat/CentOS - untested)

Prerequisites

There are some prerequisites that can be installed from the yum repositories on RedHat based systems:

  su -c "yum install libusb1-devel make gcc pyside-tools \
  pyusb wget tar numpy"

Next the Bluetooth baseband library (libbtbb) needs to be built for the Ubertooth tools to decode Bluetooth packets:

  wget http://sourceforge.net/projects/libbtbb/files/libbtbb-2012-10-R3.tar.xz/download -O libbtbb-2012-10-R3.tar.xz
  tar xf libbtbb-2012-10-R3.tar.xz
  cd libbtbb-2012-10-R3
  make
  su -c "make install"

If using the ubertooth-follow tool, the Bluetooth library headers are required and the tools need to be built with the "clock_debug" flag set:

  su -c "yum install libbluetooth-dev"
  cd ubertooth-2012-10-R1/host
  make clock_debug=true
  sudo make clock_debug=true install

Ubertooth tools

There are three sets of tools that use the Ubertooth - spectrum analyzer, Bluetooth sniffing tools and firmware update. All three are built and installed by default using the following method:

  wget http://sourceforge.net/projects/ubertooth/files/ubertooth-2012-10-R1.tar.xz/download -O ubertooth-2012-10-R1.tar.xz
  tar xf ubertooth-2012-10-R1.tar.xz
  cd ubertooth-2012-10-R1/host/bluetooth_rxtx
  make

Kismet

The version if kismet provided by Fedora does not have a corresponding development package, so in order to build the Ubertooth plugin it is nessecary to compile Kismet from source:

  su -c "yum install libpcap-devel libcap-devel libnl-devel \
  libstdc++-devel gcc-c++ ncurses-devel"
  wget http://www.kismetwireless.net/code/kismet-2011-03-R2.tar.gz
  tar xf kismet-2011-03-R2.tar.gz
  cd kismet-2011-03-R2
  ln -s ../ubertooth-2012-10-R1/host/kismet/plugin-ubertooth kismet-2011-03-R2/
  ./configure
  make && make plugins
  su -c "make suidinstall"
  su -c "make plugins-install"
  Add "pcapbtbb" to the "logtypes=..." line in kismet.conf

Wireshark

The Wireshark plugin allows Bluetooth baseband traffic that has been captured using Kismet to be analysed and disected within the Wireshark GUI. It is built separately from the rest of the Ubertooth and libbtbb software:

  su -c "yum install wireshark wireshark-devel cmake"
  cd libbtbb-2012-10-R3/wireshark/plugins/btbb
  cmake .
  make
  su -c "make install"

This completes the install of the Ubertooth tools, the next step is to look at the getting started guide. It may also be useful to update the firmware on the Ubertooth.

Gentoo

Libbtbb, Ubertooth and the Kismet and Wireshark plugins are all supported out of the box in Gentoo. To install, simply use emerge as follows:

  emerge libbtbb
  emerge kismet-ubertooth

This completes the install of the Ubertooth tools, the next step is to look at the getting started guide. It may also be useful to update the firmware on the Ubertooth.


Windows

Experimental Windows support is available under Cygwin. Although this is unsupported.


Prerequisites

The first step is to download Cygwin from http://cygwin.com/setup.exe and install it. When installing Cygwin, the following tools are required:

  gcc
  automake
  python
  wget
  tar
  libusb-1.0
  libusb-1.0-dev

Libbtbb needs to be built before the Ubertooth tools, it is available from SourceForge as follows:

  wget http://sourceforge.net/projects/libbtbb/files/libbtbb-2012-10-R3.tar.xz/download -O libbtbb-2012-10-R3.tar.xz
  tar xf libbtbb-2012-10-R3.tar.xz
  cd libbtbb-2012-10-R3
  make
  make cygwin-install

Ubertooth tools

There are three sets of tools that use the Ubertooth - spectrum analyzer, Bluetooth sniffing tools and firmware upload. All three are built and installed by default using the following method:

  wget http://sourceforge.net/projects/ubertooth/files/ubertooth-2012-10-R1.tar.xz/download -O ubertooth-2012-10-R1.tar.xz
  tar xf ubertooth-2012-10-R1.tar.xz
  cd ubertooth-2012-10-R1/host/bluetooth_rxtx
  make
  make cygwin-install

Kismet

It is not possible to build Kismet with pcap support on Windows. Unfortunatley the Ubertooth plugin requires pcap support to function, so it cannot currently be built on Windows.

This completes the install of the Ubertooth tools, the next step is to look at the getting started guide. It may also be useful to update the firmware on the Ubertooth.

Mac OSX



Prerequisites

There are some prerequisites that can be installed from the MacPorts systems. The python 2.6 USB and pyside libraries have a number of large dependencies and may take a long time to build; they (and pyusb) are only required if using the spectrum analyser, otherwise they can safely be skipped.

  sudo port install libusb wget py26-pyside-tools py26-pyusb-devel

PyUSB is not yet available from the apt repositories, so it must be downloaded and built from sourece as follows:

  wget http://sourceforge.net/projects/pyusb/files/PyUSB%201.0/1.0.0-alpha-2/pyusb-1.0.0a2.tar.gz/download -O pyusb-1.0.0a2.tar.gz
  tar xvf pyusb-1.0.0a2.tar.gz
  cd pyusb-1.0.0a2
  sudo python setup.py install

Next the Bluetooth baseband library (libbtbb) needs to be built for the Ubertooth tools to decode Bluetooth packets:

  wget http://sourceforge.net/projects/libbtbb/files/libbtbb-2012-10-R3.tar.xz/download -O libbtbb-2012-10-R3.tar.xz
  tar xf libbtbb-2012-10-R3.tar.xz
  cd libbtbb-2012-10-R3
  make osx
  sudo make osx-install

Ubertooth tools

There are three sets of tools that use the Ubertooth - spectrum analyzer, Bluetooth sniffing tools and firmware update. All three are built and installed by default using the following method:

  wget http://sourceforge.net/projects/ubertooth/files/ubertooth-2012-10-R1.tar.xz/download -O ubertooth-2012-10-R1.tar.xz
  tar xf ubertooth-2012-10-R1.tar.xz
  cd ubertooth-2012-10-R1/host/bluetooth_rxtx
  make
  sudo make osx-install

Kismet

In order to use Ubertooth with Kismet it is nessecary to compile Kismet from source, with the plugin linked to the source tree:

  First, create a kismet user group
  wget http://www.kismetwireless.net/code/kismet-2011-03-R2.tar.gz
  tar xf kismet-2011-03-R2.tar.gz
  cd kismet-2011-03-R2
  ln -s ../ubertooth-2012-10-R1/host/kismet/plugin-ubertooth kismet-2011-03-R2/
  ./configure --prefix=/opt/local --with-suidgroup=kismet
  make && make plugins
  sudo make suidinstall
  sudo make plugins-install
  Add "pcapbtbb" to the "logtypes=..." line in kismet.conf

Wireshark

The Wireshark plugin allows Bluetooth baseband traffic that has been captured using Kismet to be analysed and disected within the Wireshark GUI. It is built separately from the rest of the Ubertooth and libbtbb software:

  sudo port install wireshark wireshark-devel cmake
  cd libbtbb-2012-10-R3/wireshark/plugins/btbb
  cmake -DCMAKE_INSTALL_LIBDIR=/usr/lib/wireshark/libwireshark1/plugins .
  make
  sudo make install

This completes the install of the Ubertooth tools, the next step is to look at the getting started guide. It may also be useful to update the firmware on the Ubertooth.

Firmware

Binary firmware images are available as part of the release package. They are specific to the version of the Ubertooth being used (Ubertooth one, Ubertooth zero, Toorcon 13 badge). To write a firmware image to a device, use the ubertooth-dfu tool:

  ubertooth-dfu --write bluetooth_rxtx.dfu --detach

Building firmware

Firmware images are built using the Arm Cortex M3 version of gcc, which is available here.

  wget https://launchpad.net/gcc-arm-embedded/4.6/4.6-2012-q2-update/+download/gcc-arm-none-eabi-4_6-2012q2-20120614.tar.bz2
  tar xf gcc-arm-none-eabi-4_6-2012q2-20120614.tar.bz2
  sudo cp -R gcc-arm-none-eabi-4_6-2012q2 /opt/

You will probably need to add the compiler to your path as follows:

  export PATH=$PATH:/opt/gcc-arm-none-eabi-4_6-2012q2/bin

To add this permanently to your path, run the following:

  echo "export PATH=$PATH:/opt/gcc-arm-none-eabi-4_6-2012q2/bin" >> ~/.bashrc

In order to flash a firmware image to the Ubertooth the ubertooth-dfu tool can be used; it should have been installed along with the Ubertooth tools earlier. It is used as follows:

  ubertooth-dfu --write bluetooth_rxtx --detach

If for some reason the image flashed to the Ubertooth makes the device unresponsive the inbuilt bootloader allows the device to be reflashed. To trigger bootloader (flashing) mode, use the following steps:

  Disconnect the Ubertooth from the host system
  Using a paperclip, short pins 1 and 3 on the expansion header (shown here)
  Reconnect to the  host system