Troubleshooting Tools for Your Next Bluetooth LE Project: Ubertooth and the Nordic nRF Sniffer

Learn how to use the Ubertooth One and the Nordic nRF sniffer tools to troubleshoot your next BLE project.

Bluetooth LE is a lower-power data-burst version of the Bluetooth protocol. It's designed to allow products to function for months to years on a single battery. As costs continue to decrease, engineers are increasingly incorporating Bluetooth functionality into their designs. This article presents a few troubleshooting options when your design does not work as expected.

About This Project

When developing a new product or troubleshooting a project, engineers often need access to expensive test equipment. Most have access to an oscilloscope, but once the data leaves an antenna and becomes part of the electromagnetic spectrum, it is difficult to inspect. While there will never be a substitute for proper tools such as spectrum analyzers, oscilloscopes, and protocol analyzers, the cost of those tools puts them outside the reach of some, especially small businesses. This project will introduce tools that allow you to inspect some aspects of your traffic with solutions that are affordable to almost everyone.

Bluetooth LE Frequency Spectrum and Sources of Interference (Mac and Linux)

Bluetooth Low Energy (BLE) utilizes the 2.4 GHz Industrial-Scientific-Medical band. It was developed after Classic Bluetooth with the goal of using as little power as possible to radically extend the lifetime of batteries. BLE favors short, intermittent low-power transmissions over Classic Bluetooth's high-power, sometimes continuous transmission. The lower power transmitted BLE signal can easily become lost in a sea of electromagnetic noise.
BLE has 3 advertising channels (37-39) and 37 data channels (0-36), each with a 2 MHz spacing. 802.11bgn use the same frequency space divided into 14 overlapping channels spaced 5 MHz apart. The Bluetooth LE advertising channels fit into the gaps created between the Wi-Fi channels 1, 6, and 11.

Image shows Wi-Fi channels 1, 6, and 11 set atop the Bluetooth LE channels. Image courtesy of Digikey.com.

Classic Bluetooth uses the same frequency space with 32 advertising channels and 47 channels spaced 1 MHz apart (79 total channels). Other sources of possible interference for Bluetooth LE projects include other ISM-band transmitters (nRF24, Zigbee, etc...), USB3.0 noise caused by plugs, cables, and circuitry acting as unintentional radiators (raises the noise floor by 20 dB in this study), and the ubiquitous microwave oven 2400 MHz - 2480 MHz where poor shielding might allow a fractional part of its 1000 W magnetron to create more noise than our tiny transmitters could ever hope to rise above.

Ubertooth One

Parts Required	Cost	More Information
Ubertooth One	$125	Product Homepage
Raspberry Pi Zero Wireless Kit (Or a computer running Linux)	$28	A computer running Linux/Mac is required. Windows will not work.
Powered Raspberry Pi Zero USB Hub (Or a USB-A female-to-micro-B-male adapter)	$15	Any powered USB2.0 or greater hub should work.

Getting Started With Ubertooth One 

The Ubertooth One, by Great Scott Gadgets, was purchased for this article. This device requires Linux operating system (OS) or Mac OS X to function. It is possible to run this device off of a Live USB or Live CD operating system. The Ubertooth authors recommend Kali or Pentoo and provide installation instructions on the Ubertooth GitHub page.

It takes several hours to download and several minutes to write and create the CD or USB drive. At that point, you have the option of installing the distributions (which would provide the best user experience) or leaving the installation in memory (Live) and losing all changes everytime you turn off the power.

A third option exists for Kali, Kali persistence, where OS changes and updates are saved to the USB drive. This allows you to update software and save files that will persist from one reboot to the next.
I chose to use a spare Raspberry Pi Zero Wireless to create a no-keyboard, no-mouse installation for my Ubertooth One that I can remotely connect to from my desktop and view on a small screen near my computer. This way, I can have a final product that does not take over my desktop or laptop computer each time I use it.

For information on how to set up a no-keyboard, no-mouse Pi Zero Wireless installation, see my post on creating an RPi Zero software-defined radio and go through Project 1, Step 1 through Step 5. Connect to a monitor with an HDMI cable and then install the Ubertooth according to the Ubertooth wiki Build Guide for Debian OS (as Raspbian is based on Debian). You can connect to the Pi using an SSH client such as PuTTY.

Ubertooth Commands

After going through the Ubertooth build on the Pi, you now have a device that can intercept Bluetooth and Bluetooth LE packets, as well as function as a spectrum analyzer. See the Ubertooth Getting Started Guide for more information and an explanation of various commands.
The following commands are either available through the software included in the default distribution or will be available after you have updated the Ubertooth software.

• "hcitool": A host-controller interface tool that offers a variety of options for classic Bluetooth and Bluetooth LE devices. It is installed on computers with Bluetooth connections and will work whether or not you have an Ubertooth device. Depending on your configuration and user priveledges, you might need to elevate your user privileges by prepending "sudo" to these commands (e.g. "sudo hcitool lescan"). The full list of commands can be viewed by typing "hcitool --help" or "man hcitool". However here are a few that you might find useful:
  • "hcitool scan": Scans for and displays the MAC address and name (if known) of classic Bluetooth devices
  • "hcitool lescan": Scans for and displays the MAC address and name (if known) of Bluetooth LE devices (Here's an example output: "24:71:89:D0;D7:68 DATAEXCHANGER")
  • "hcitool dev": Shows the MAC address of the Bluetooth device attached directly to the computer
  • "hcitool con": Shows active connections between the local Bluetooth device and a remote Bluetooth device
  • "hcitool cc": Creates a connection between the local Bluetooth device and a remote Classic Bluetooth device
  • "hcitool lecc": Creates a connection between the local Bluetooth device and a remote Bluetooth Low Energy device (Example input: "hcitool lecc 24:71:89:D0:D7:68"; Example output:  "Connection handle 64")
  • "hcitool ledc": Disconnect from a remote Bluetooth Low Energy device (Example input: "hcitool ledc 64")
• "ubertooth-specan": Uses Ubertooth to perform a spectral analysis and output data to stdout. This is a raw list of signal strength data that isn't very useful by itself. You can save it to file with the -d option, or send it to feedgnuplot (you might need to install with "sudo apt-get install gnuplot feedgnuplot -y"). More information about feedgnuplot is available at cpan.org. The most likely use case of this command is for someone remotely monitoring a location with a text-only terminal and no access to an x-server. It is not a command that is commonly used, as it is quite limited in capability
  • "ubertooth-specan -d /home/pi/specandata.txt": Saves the data to a txt file for analysis by another program at a later time
  • "ubertooth-specan -g | feedgnuplot --stream 0.5 --set xrange["2402":"2480"] --set yrange["-100":"0"] --terminal 'dumb 80,40'": Uses ubertooth-specan -g to generate a two-column list of data and pipes it to feedgnuplot. feedgnupilot then looks at the stream, refreshes the plot every 0.5 seconds, and plots the area of interest (xrange, yrange). Data is sent to the terminal as ASCII-art 80 columns wide and 40 rows high.
  • ubertooth-specan-ui: Uses Ubertooth to perform a spectral analysis and display the results on the graphical user interface. This command is used to show the average and peak signal strength in 2.4 GHz band as well as detailed information about specific points of interest.

Screen capture of limited range of data fed from the ubertooth-specan command above. As you can see, it lacks detail and is of limited usefulness.

Screen capture of 2.4 GHz spectrum using ubertooth-specan-ui. This command provides much more detailed information and is used to graphically show signal strength in the range of 2400 MHz to 2480 MHz.

 

• ubertooth-util -a: Gets or sets the power amplifier level (Example input: "ubertooth-util -a" gets current level, "ubertooth-util -a4" sets amplifier level 4). This command can be used to limit the range of any transmissions sent from the device.
• ubertooth-util -z: Gets or sets the squelch level (Example input: "ubertooth--util -z-110"). By increasing the squelch level, this command can be used to adjust the reception range of the Ubertooth device.  This is useful if you are in an environment that has a lot of traffic that you are not interested in.
• ubertooth-btle: Monitors and records BTLE data (Example input: "ubertooth-btle -f -c packets.pcap"). This command follows connections and saves data to a .pcap file for inspection in a program such as Wireshark.

All Ubertooth commands installed after build include ubertooth-afh, ubertooth-btle, ubertooth-debug, ubertooth-dfu, ubertooth-dump, ubertooth-ego, ubertooth-follow, ubertooth-rx, ubertooth-scan, ubertooth-specan, ubertooth-specan-ui, ubertooth-tx, ubertooth-util.
Additional default linux commands include: hciconfig, l2ping

Handy tip! For more information about any of these tools, you can prepend the command "man" or append the switch "--help". For example, "man l2ping" will bring up a manual page that gives detailed instructions about the tool and example commands with their explanation. The command "ubertooth-util --help" will give a list of command-line switches and a brief explanation of their use.
You can also use the Ubertooth to capture packets in Wireshark. Instructions are available on the Ubertooth wiki GitHub page.

In the example below, Ubertooth is used to capture packets and store them in a .pcap file for later analysis by Wireshark.

Using the Nordic nRF Sniffer (Windows)

Parts Required	Cost	More Information
Nordic nRF51-Dongle	$52	Brief

The Nordic nRF Sniffer is a small USB dongle based on the Nordic nRF51. It is meant to work on Windows based systems and allows monitoring of any nearby BTLE traffic using Nordic specific utilities and Wireshark 1.12.

Dongle image from mbed.org

Installation

1. Download and install an older version of Wireshark (1.12) at Wireshark.org. (The sniffer can send information directly to Wireshark 1.1x.x, but apparently the software was never updated for Wireshark 2.x.)
2. Download and install nRFgo Studio.
3. Download nRF dongle tools from Nordic's website. Follow the installation instructions that begin in section 1 of the nRF user guide.
4. If you need it, download the latest mBed serial port driver, mbedWinSerial_16446.
5. See the video below from Nordic about the nRF51 dongle:

First, plug in the dongle and load the firmware with nRFgo Studio according to the instructions in the installation guide.
Next, navigate to the folder created by decompressing the dongle tools you downloaded earlier and navigate to ble-sniffer_win_1.0.1/Sniffer. Execute the file named "Plugins.exe" to load the Wireshark bindings. Then execute the file named "ble-sniffer_win_1.0.1_1111_sniffer.exe". If everything worked as it should, you should see a screen similar to the following:

 

Screenshot of Nordic nRF BLE sniffer program.

Any nearby BLE devices will be listed at the bottom under "Available Devices". Use the keyboard arrow keys or the numeric keypad to select the device that you are interested in viewing and then use the "w" key to launch Wireshark 1.12.

Screenshot of Wireshark 1.12 showing a view of received packets.

You can stop the capture at any time by clicking on the red square icon in the upper left corner of the Wireshark program. Each packet is displayed as a new row, and you can get a detailed view of any packet by double clicking anywhere on the row.

Screenshot of Wireshark showing detailed packet view.

Wireshark does the packet protocol analysis for you, allowing you to focus on the data of interest to you while ignoring extraneous information.

Conclusion

The Ubertooth One and the nRF51 user dongles allow users on Mac, Linux, and Windows to intercept and analyze BLE packets on their favorite operating system. They each provide a crucial peak at BLE traffic in the 2.4GHz ISM band. If you create your own BLE projects or need to troubleshoot an existing device, consider one or both of these dongles for your personal toolkit.