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