Using a special firmware image provided by Nordic Semiconductors and the open source network analysis tool Wireshark, the Bluefruit LE Sniffer can be used as a low cost Bluetooth Low Energy sniffer.

Once things are all setup, usage is fairly easy. However, there are numerous separate items that need to be installed and configured. So the initial setup can be a bit cumbersome. We'll go through each step, but it can also help to have a general understanding of the overall setup.

Here's a simplified diagram of the setup:

Here's a summary of all the parts needed:

1. The actual BLE sniffing hardware. This guide uses the Adafruit Bluefruit LE Sniffer with V2 firmware.
2. The BLE Sniffer uses a Silicon Labs CP2104 to provide USB to serial conversion. In order for this to show up as a COM port, the Silicon Labs Virtual COM Port driver is needed.
3. The BLE sniffing plugin uses Python.
4. To talk to the virtual com port from Python, the pyserial module needs to be installed.
5. Wireshark is the main software front end used to facilitate BLE sniffing and decoding.
6. To talk to the BLE sniffer from Wireshark, the Nordic Semiconductor nRF Sniffer for BLE plugin in is used.

These parts come from numerous different sources - at least 5 different vendors are shown in the diagram above. So this will be quite the journey. Here we go...

BLE Sniffer Hardware

You'll need one of these:

Silicon Labs VCP Driver

This driver allows the CP2104 chip on the Adafruit BLE Sniffer to show up as a COM port on your PC.

Once installed, a COM port should show up on your PC when the Adafruit BLE Sniffer is plugged into a USB port. It should have CP210x in the name.

This check does not require any of the other software components we install later. So if a COM port is not showing up at this point, do not proceed further until determining why.

Python 3

If Python 3 is not already installed on your system, go to the Python main page to learn how to download and install it for your specific system:

It should now be possible to launch Python and run some simple commands:

On Windows, try using py to launch Python.

Python Serial Support

To provide access to the COM port, install the pyserial package.

It should now be possible to launch Python and import the pyserial package:

NOTE: the import is actually serial, not pyserial.

Install Wireshark

Go to the Wireshark main page to learn how to download and install Wireshark for your specific system:

Once complete, it should be possible to run Wireshark and at least get the start screen:

Install BLE Sniffer Plugin

OK, finally, the thing we actually care about. The thing that will let us talk to the Adafruit BLE Sniffer and do some actual BLE sniffing. Let's download and install that BLE sniffing plugin!

Download Plugin from Nordic

Start by downloading the nRF Sniffer for BLE package from Nordic Semiconductor:

This will be a ZIP file. At the time of this guide, the version is 4.0.

Determine Wireshark Plugin Folder Location (extcap)

We need to install items from the ZIP file downloaded from Nordic into a specific Wireshark folder location.  This location is different on different systems. To determine it for your system, do this:

We'll refer to this folder location as the Wireshark extcap folder.

Install BLE Sniffer Plugin into Wireshark

To install the plugin, simply copy the files shown below from the ZIP downloaded from Nordic into the Wireshark extcap folder location determined above.

Open the ZIP file downloaded from Nordic:

Final Check and Test Capture

OK, now we can test things out with some real actual BLE sniffing! woot!

interface, extcap_version = interface.split('-')

interface, extcap_version = interface.split('-')

interface, extcap_version = interface.rsplit('-', 1)

interface, extcap_version = interface.rsplit('-', 1)

Next Steps

Once everything is working as shown above, you are ready to move on to working with these BLE packets.

Working with Wireshark

Once Wireshark has loaded, you should see the advertising packets streaming out from the selected BLE device at a regular interval, as shown in the image below:

One of the key benefits of WireShark as an analysis tool is that it understands the raw packet formats and provides human-readable displays of the raw packet data.

The main way to interact with BLE data packets is to select one of the packets in the main window, and then expand the Bluetooth Low Energy Link Layer treeview item in the middle of the UI, as shown below:

Clicking on the Advertising Data entry in the treeview will highlight the relevant section of the raw payload at the bottom of the screen, but also provides human readable information about the payload that can save you a lot of time trying to debug or reverse engineer a device.

We can see, for example, that the device is advertising itself as a Bluetooth Low Energy only device ('BR/EDR Not Supported'), with a TX Power Level of 0dBm, and a single service is being advertised using a 128-bit UUID (the UART service in this case).

Capturing Exchanges Between Two Devices

If you wish to sniff data being exchanged between two BLE devices, you will need to establish a connection between the original device we selected above and a second BLE device (such as an iPhone or an Android tablet with BLE capabilities).

The nRF-Sniffer firmware is capable is listening the all of the exchanges that happen between these devices, but can not connect with a BLE peripheral or central device itself (it's a purely passive device).

Scan Response Packets

If you open up nRF UART on an Android or iOS device, and click the Connect button, the phone or tablet will start scanning for devices in range.  One of the side effects of this scanning process is that you may spot a new packet in Wireshark on an irregular basis, the 'SCAN_REQ' and 'SCAN_RSP' packets:

The Scan Response is an optional second advertising packet that some Bluetooth Low Energy periperhals use to provide additional information during the advertising phase.  The normal mandatory advertising packet is limited to 31 bytes, so the Bluetooth SIG includes the possibility to request a second advertising payload via the Scan Request.

You can see both of these transactions in the image above, and the Device Name that is included in the Scan Response payload (since the 128-bit UART Service UUID takes up most of the free space in the main advertising packet).

For more information on Scan Responses and the advertising process in Bluetooth Low Energy see our Introduction to Bluetooth Low Energy Guide.

Connection Request

Once we click on the UART device in nRF UART, the two device will attempt to connect to each other by means of a Connection Request, which is initiated by the central device (the phone or tablet).

We can see this CONNECT_REQ in the timeline in the image below:

Write Request

Once the connection has been established, we can see that the nRF UART application tries to write data to the BLEFriend via a Write Request to handle '0x001E' (which is the location of an entry in the attribute table since everything in BLE is made up of attributes).

What this write request is trying to do is enable the 'notify' bit on the UART service's TX characteristic  (0x001E is the handle for the CCCD or 'Client Characteristic Configuration Descriptor'). This bit enables an 'interrupt' of sorts to tell the BLEFriend that we want to be alerted every time there is new data available on the characteristic that transmits data from the BLEFriend to the phone or tablet.

Regular Data Requests

At this point you will start to see a lot of regular Empty PDU requests.  This is part of the way that Bluetooth Low Energy works.

Similar to USB, all BLE transaction are initiated by the bus 'Main', which is the central device (the tablet or phone).

In order to receive data from the bus secondary (the peripheral device, or the BLEFriend in this particular case) the central device sends a 'ping' of sorts to the peripheral at a delay known as the 'connection interval' (not to be confused with the one-time connection highlighted earlier in this tutorial).

We can see pairs of transaction that happen at a reasonably consistent interval, but no data is exchanged since the BLEFriend (the peripheral) is saying 'sorry, I don't have any data for you':

Notify Event Data

To see an actual data transaction, we simply need to enter some text in our terminal emulator SW which will cause the BLEFriend to send the data to nRF UART using the UART service.

Entering the string 'This is a test' in the terminal emulator, we can see the first packet being sent below (only the 'T' character is transmitted because the packets are sent out faster than we enter the characters into the terminal emulator):

What this 4-byte 'Bluetooth Attribute Protocol' packet is actually saying is that attribute 0x001C (the location of the TX characteristic in the attribute table) has been updated, and the new value is '0x54', which corresponds to the letter 'T'.

Scrolling a bit further down we can see an example where more than one character was sent in a single transction ('te' in this case):

The results of this transaction in the nRF UART application can be seen below:

Closing Wireshark and nRF-Sniffer

When you're done debugging, you can save the session to a file for later analysis, or just close Wireshark right away and then close the nRF-Sniffer console window to end the debug session.

Moving Forward

A sniffer is an incredibly powerful and valuable tool debugging your own hardware, reverse engineering existing BLE peripherals, or just to learn the ins and outs of how Bluetooth Low Energy actually works on the a packet by packet level.

You won't learn everything there is to know about BLE in a day, but a good book on BLE, a copy of the Bluetooth 4.1 Core Specification and a sniffer will go a long way to teaching you most of the important things there is to know about BLE in the real world.

In mid 2018, Nordic release new Bluetooth LE sniffer firmware - this firmware works way better with Wireshark.

As of August 2018 we are only selling Sniffers pre-prorgrammed with Firmware version 2

If you have a firmware V1 (packaging doesn't say firmware V2,  or you bought before August 2018) see the previous sections!

Nordic User Manual

You can grab the 'official' user manual from Nordic at https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF-Sniffer we include a mirror of the v2.1 instructions below

nRF Sniffer V2 Multi-Target Application

When downloading the desktop/Wireshark Sniffer tool, make sure to download BETA 1, which matches the firmware image below. You can select this version via the drop down selector shown below:

For convenience sake, the extcap folder contents for BETA 1 are also available for download here using the button below. See the user guide on how to install this in the correct location for Wireshark.

V2 Firmware

If by chance you have an nRF51822 board you want to load the firmware on, here's a hex that does not require the 32khz crystal (but does require the 16 mhz crystal)

This firmware is from the nrf_sniffer_2.0.0-beta-1_51296aa package

Again, we don't have a guide or tutorial on loading the firmware onto an nRF51. We don't have the original source code, that hex is from Nordic and they only release hex files

For the V2 firmware, its recommended that you use Wireshark - the V1 had various methods such as a Python API but really they were all mediocre compared to the abilities of Wireshark

Install Wireshark

Start by installing Wireshark, a great cross-platform monitoring tool

Visit https://www.wireshark.org/ and download the latest version of Wireshark for your operating system

When installing on windows, check the box to also install WinPcap

Install Wireshark Plugin

Next up, you'll need the Nordic plugin software. We need to work with a specific release - 2.0.0 Beta 1. For convenience sake, the extcap folder contents for BETA 1 are available for download using the button below.

Download that zip file to your computer and see below for how to install the files into the necessary Wireshark folder.

For complete reference, the Nordic main page for the plugin software is here:

If you decide to go there, be sure to select the correct version for download.

WARNING this file is huge - over 200MB! We suggest just using the extcap.zip file linked above.

Now to find the Wireshark folder location to unzip these files into.

Open that directory up, then copy over the files within the extcap.zip  extcap folder into the Wireshark extcap folder

In the end, your Wireshark/extcap directory should contain nrf_sniffer.bat, nrf_sniffer.py and SnifferAPI folder.

Now quit Wireshark so we can get things tested!

Dealing With Python 2 vs 3

Nordic's sniffer code is Python 2 only, so if you have Python 3 your default (which, by now, you probably do) you'll need to install Python 2.

The best way to test is to go to the extcap directory in your terminal software and try running nrf_sniffer.bat (Windows) or python nrf_sniffer.py (Mac/Linux)

If you get the error on the print "LOGGING FAILED" line

or the "No module named 'Logger'" error

Then you'll need to trick the sniffer software into using Python 2

For Windows, at least, I installed Python 2.7 into C:\Python27 (the default) and then edited the nrf_sniffer.bat file to say:

@echo off
C:\Python27\python "%~dp0nrf_sniffer.py"  %*

@echo off
C:\Python27\python "%~dp0nrf_sniffer.py"  %*

note the explicit path!

Installing Dependancies

Once you get past that part, you can try rerunning the bat/py script and you may get other missing module errors like No module named serial

You'll need to install these with pip

Warning! Because you have to use Python2 here, make sure you're using pip2 or on windows, use the full path C:\python27\Scripts\pip2.exe

e.g. C:\python27\Scripts\pip2.exe install pyserial

Eventually you'll get No arguments given! which means the script is, at least, fully running

Test Capture

OK finally once that works, start Wireshark again.

This time you'll see the nRF Sniffer capture device!

Double Click on that line to start the Capture!

Windows Install Supplemental Information

Adafruit forums user @TomHildebrand put together a nice write up on their experience installing and setting up everything on Windows 10. It's generally the same info as above, but may have some more explicit info that is useful. Checkout it out here:

The original Bluetooth LE sniffer firmware from Nordic had some restrictions such as only being usable by Wireshark 1.

As of August 2018 we are only selling Sniffers pre-prorgrammed with Firmware version 2

However, we'll keep this documentation up in case its useful for people with old boards

If by chance you have an nRF51822 board you want to load the firmware on, here's a hex that does not require the 32khz crystal (but does require the 16 mhz crystal)

Again, we don't have a guide or tutorial on loading the firmware onto an nRF51. We don't have the original source code, that hex is from Nordic and they only release hex files

CP2104 Driver Requirements (Black Boards) 

The latest version of the sniffer uses the CP2104 USB to Serial bridge and drops the SWD connector, allowing us to sell the boards at a significant discount compared to version 1.0. To use these boards, though, you will need to install the CP2104 VCP driver from Silicon Labs:

FTDI Driver Requirements (Blue Boards)

Before you can start talking to the sniffer, you'll need to install a standard FTDI driver for the FT231x located on the device.

Find the appropriate FTDI VCP installer on the FTDI Driver Download Page, install it on you system, and then insert the sniffer in any USB port on your system.

Using the Firmware V1 Sniffer

There are currently two ways to use the sniffer:

Nordic's nRF Sniffer Utility (Windows only)

If you are on Windows, the best user experience will be had by using the official Nordic nRFSniffer application, available as a download from Nordic Semiconductors after creating a 'My Pages' account, and registering your device using the product ID located on the Bluefruit LE Sniffer packaging.

More information on using Nordic's nRF Sniffer application.

Python API (Cross-Platform, no Registration)

If you are not using Windows, or don't wish to create a MyPages account, the alternative is to use a Python interface to communicate with the nRFSniffer firmware, which will log any traffic to a libpcap file that can be opened directly in Wireshark.  This has been tested on OS X 10.10, Ubuntu 14.04 and Windows 7, but it currently doesn't support streaming data directly into Wireshark via named pipes (though this is possible with some platform-specific effort).

More information on using the Python API.

The following guide will walk you through downloading, installing and using the official nRF Sniffer application for Nordic Semiconductors.

Getting the Sniffer Utility

The Bluefruit LE Sniffer comes pre-flashed with the special sniffer firmware image, but you'll need to go to Nordic's website and download the nRF-Sniffer package to capture the data on Windows and push it out into Wireshark for packet by packet analysis.

Go to the nRF Sniffer product page downloads tab, then download the latest V1 version of the utility, and unzip it.

Inside this downloaded file you'll find the sniffer executable, which will open up the command-line tool when you click on it.

Getting Wireshark

In order to use the sniffer utility you'll also need to download Wireshark, preferably verison 1.12.1 (the same one used in this tutorial).

You may need to explore the download mirrors, such as https://1.na.dl.wireshark.org/ to find the  download link since they dont have a direct v1 link

Simply select the 32-bit or 64-bit Windows Installer and install it on your machine using the default settings:

Running the Sniffer

Now that everything is installed, you can get started using the Bluefruit LE Sniffer and the sniffer bridge SW that pushes any sniffed data out into Wireshark ...

Select the Sniffer Target

The nRF-Sniffer can only sniff one device at a time, so the first step is getting the sniffer running and then selecting the device that you want to debug.

Start nRF-Sniffer by running the ble-sniffer_win executable (for example: ble-sniffer_win_1.0.1_1111_Sniffer.exe).

This will try to detect the device running the nRF-Sniffer firmware over a UART COM port.

If the board isn't detected right away type 'f' to erase any previous com port settings, or try removing and then re-inserting the sniffer while the console application is running.

Once the sniffer is found, you should see a list of all BLE devices that were detected in listening range:

In this particular case, we'll select device number 2, which is a BLEFriend running the standard UART firmware.

Type the device number you want to sniffer (in this case '2'), and you should see the device highlighted in the list, similar to the image below:

At this point you can type 'w', which will try to open wireshark and start pushing data out via a dedicate pipe created by the nRF-Sniffer utility.

If you are running OS X 10.9 or higher, you can also use the sniffer on OS X using the nrf-ble-sniffer-osx package from Roland King.  (Make sure you have the latest version, as of 20 June 2015, which is now compatible with the FTDI chip used on the Adafruit board.)

Setup instructions are available on the wiki page for the project.

Nordic provides a Python API for their sniffer firmware that makes it possible for us to use the sniffer on any platform, and we've put together a basic wrapper for this API to help you get started.

We've tested this wrapper with Python 2.7 on the following platforms:

• OS X 10.10
• Windows 7 x64
• Ubuntu 14.04

To stream live data into Wireshark the way the official Windows app from Nordic does you will need to compile a Wireshark utility that creates a name pipe that data gets pushed through.  

To keep things simple, though, you can also just log sniffed traffic directly to a libpcap file, which can be opened directly in Wireshark when you are done, which is the easiest solution and what we'll be demonstrating here:

Requirements

To use the example we provide for the Python API, you will require the following utilities:

• Python 2.7.x (we tested with 2.7.6)
• pySerial

If you're new to Python and pySerial, have a look at our Instaling Python and PySerial guide by Simon Monk.

Download the API

Once you have Python and pySerial installed on your system, you will need to download a copy of the Python API.

The latest version of the API is always available on Github, but you can also download a .zip file of the latest code directly using the button below:

Unzipping the file should give you a file structure resembing the image below:

Using the sniffer.py Wrapper

To help you get started, we've made an easy to use wrapper called sniffer.py:

$ sudo python sniffer.py -h
usage: sniffer.py [-h] [-v] serialport

Interacts with the Bluefruit LE Friend Sniffer firmware

positional arguments:
  serialport     serial port location ('COM14', '/dev/tty.usbserial-DN009WNO',
                 etc.)

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  verbose mode (all serial traffic is displayed)

$ sudo python sniffer.py -h
usage: sniffer.py [-h] [-v] serialport

Interacts with the Bluefruit LE Friend Sniffer firmware

positional arguments:
  serialport     serial port location ('COM14', '/dev/tty.usbserial-DN009WNO',
                 etc.)

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  verbose mode (all serial traffic is displayed)

It takes a single argument, the COM port location, which will be something like 'COM15' on Windows, '/dev/ttyACM*' on Linux, or '/dev/tty.usbserial*' on OS X.

Linux

To run the sniffer wrapper on Linux, enter the following command (changing the serial port as necessary):

$ sudo python sniffer.py /dev/ttyACM0

$ sudo python sniffer.py /dev/ttyACM0

OS X

To run the sniffer wrapper on OS X, enter the following command (changing the serial port as necessary):

$ python sniffer.py /dev/tty.usbserial-DN009MP6

$ python sniffer.py /dev/tty.usbserial-DN009MP6

Windows

To run the sniffer wrapper on Windows, enter the following command (changing the serial port as necessary):

python sniffer.py COM30

python sniffer.py COM30

Scanning for Devices

If the wrapper was able to connect to the Bluefruit LE Sniffer, it will perform a 5 second scan for Bluetooth Low Energy devices in range, and ask you which device you want to listen to:

$ sudo python sniffer.py /dev/ttyACM0
[sudo] password for ktown: 
Logging data to logs/capture.pcap
Connecting to sniffer on /dev/ttyACM0
Scanning for BLE devices (5s) ...
Found 2 BLE devices:

  [1] "" (E7:0C:E1:BE:87:66, RSSI = -52)
  [2] "" (14:99:E2:05:29:CF, RSSI = -94)

Select a device to sniff, or '0' to scan again
> 

$ sudo python sniffer.py /dev/ttyACM0
[sudo] password for ktown: 
Logging data to logs/capture.pcap
Connecting to sniffer on /dev/ttyACM0
Scanning for BLE devices (5s) ...
Found 2 BLE devices:

  [1] "" (E7:0C:E1:BE:87:66, RSSI = -52)
  [2] "" (14:99:E2:05:29:CF, RSSI = -94)

Select a device to sniff, or '0' to scan again
> 

Once you select a device, it will start scanning that specific device, and you will see an update every second of the number of packets 'sniffed' from the device (where each '.' represents a packet):

Select a device to sniff, or '0' to scan again
> 1
Attempting to follow device E7:0C:E1:BE:87:66
.................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
............................
..............................
...........................
..............................

Select a device to sniff, or '0' to scan again
> 1
Attempting to follow device E7:0C:E1:BE:87:66
.................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
............................
..............................
...........................
..............................

Locating the Log File

Once you've sniffed enough data, simply type CTRL+C to stop, and locate the libpcap log file at the path mentionned by the tool. This will normally be:

• Windows: 'C:\Users\ktown\AppData\Roaming\Nordic Semiconductor\Sniffer\logs \capture.pcap' (this will of course change based on your username)
• OS X/Linux: 'logs/capture.pcap' (relative to the location of the Python API)

Analyze Data in Wireshark

At this point, you simply need to open the capture.pcap file in Wireshark, and you can analyze the sniffed data!

The image below shows an advertising packet from a factory default Bluefruit LE Friend board:

For information on how to use Wireshark, have a look at the notes on the official nRF Sniffer utility, which describes some of the packet types you might encounter working with Bluetooth Low Energy.

Files

• EagleCAD PCB files on GitHub
• Bluetooth LE module Datasheet

Schematic C2104 Rev

Click to embiggen