This page is for the V1 Sniffer firmware only! If you have V2, check the other page - the process has changed between versions.
The Python interface requires a custom Wireshark library for Linux. We're currently working on adding support for this. Please use the Windows or OS X utility until the update is available.

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:

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)

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

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

Windows

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

You can find the serial port used by the Bluefruit LE Sniffer by opening the Device Manager on your system and looking in the 'Ports' category:
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
> 

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
.................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
............................
..............................
...........................
..............................

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:

Note that the utility will start sniffing data as soon as you connect to the Bluefruit LE Sniffer, so early packets in the log file might contain advertising packets from other devices in range. It will only start filtering packets once you select a specific device via the selection dialogue.

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.

This guide was first published on Nov 19, 2014. It was last updated on Nov 28, 2014.

This page (V1 Python API) was last updated on Nov 28, 2014.

Text editor powered by tinymce.