Menu ▾ ▴

ble_sniffer

Introduction

nrf-ble-sniffer-osx is an OS X program which interfaces with the BTLE sniffer software released by Nordic for use on their development boards and allows you to view and follow BTLE packets and conversations, dump them to a PCAP file or view them decoded in Wireshark.

What you needf

Nordic development board

You need one of the development boards sold by Nordic for their nRF51822 Bluetooth Low Energy chip. They have a variety of kits, their Development Kit comes with a dongle which you can use, their Evaluation Kit has both a dongle and an evaluation board and both of them work with the sniffer software.

Nordic sniffer software

Once you have a Nordic kit you can access their software and download the sniffer. The sniffer software is some code which is loaded onto the development board plus an applications to use it under Windows and a user guide. I recommend, if you have access to a Windows box, that you start by running it that way so you can ensure your board is working properly and you have the software on it, tested. But you can still do this entire task in OS X if you don't.

You need at least version 1.0.1 of the sniffer software*.

Versions prior to 1.x.x won't be recognised by the software.

You can program the software onto the device using Nordic's Windows software (follow the guide) or you can use my RKNRFGO project also on SourceForge, if you do that, loading the software looks something like this, just hit the 'Both' button to wipe and upload the software.

Wireshark

To display packets you need the free, excellent, packet analyser, Wireshark. You can run the sniffer without it, but it's pretty limited. I recommend getting Wireshark set up and running before you even try installing the ble sniffer program.

You need version 1.10.x, 1.12.x or 2.0.x of Wireshark.

2.0.x

2.0 doesn't need X11, you should be able to download, install and use it out of the box.

1.10.x, 1.12.x

1.10 and 1.12 was written to be cross-platform using X-windows (X11). I very highly recommend 1.12.x as it has better bluetooth support. Wireshark has a downloads page, download and install.

Wireshark needs X11 in order to run, X11 does not come pre-installed on OSX anymore, however OSX recognises programs which need it and points you to XQuartz which is the official site for X11 for OSX now. You need to install X11 as well in order to get Wireshark working.

I recommend getting Wireshark and X11 installed, rebooting (annoying but it's the best way to get the X11 service properly started) then checking that the Wireshark app works from the dock. The sniffer software makes some assumptions about a standard install of Wireshark in order to run it, so getting it working first really helps later.

once installed

Once it's installed, one good test is to start the Terminal app and type the following 

tshark -v

Which checks that tshark, part of the Wireshark package, is installed and available. You should get output something like this

$ tshark -v
TShark 1.12.0 (v1.12.0-0-g4fab41a from master-1.12)

Copyright 1998-2014 Gerald Combs <gerald@wireshark.org> and contributors.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

......


If this works, the sniffer software should be able to find Wireshark and launch it.

Installation

ble-sniffer-osx

Download the package from Sourceforge




It's a package installer which installs the application in /Applications. The package is Gatekeeper-signed and should install on a Mac with default install parameters. If you want to delete it again, just remove the app from /Applications

Running

When you run the application you can start it with or without a sniffer plugged into one of the USB ports. On startup the app checks for an installed Wireshark and installs the correct plugins into the wireshark support directory, and updates any plugins which are old.

About box and wireshark information

Selecting 'about ble-sniffer-osx' from the main menu gives you an about box which tells you what the app knows about your Wireshark install. A working version looks like this

This shows the current version of Wireshark found, if it's found at all, and the plug-in which has been installed to decode packets. if there's an error here, no Wireshark, or some other issue, that needs to be fixed before you will be able to decode packets. You can hit the 'Check Wireshark' button to perform the check again after you re-install Wireshark or make other fixes and the app will show the new status.

Main screen

With no sniffer plugged in the main screen will show

As soon as you plug a sniffer in the screen should show it. If it doesn't there are a few possibilities

  • the board you plugged in doesn't have the sniffer software on it, or the version is too old (or possibly too new) for the code to recognise it.
  • you have an older version of JLink than V4.90 on your machine. Please upgrade. Versions prior to that required that specific drivers (the CDC drivers) on OSX were enabled or disabled in order to use JLink or use the USB for data. In order for the app to read data, the CDC drivers need to be enabled. V4.90 and later of the JLink software fixed these issues so that you can leave the CDC drivers enabled and use both the JLink/Segger and read data.
  • the app is broken, please file a bug report.

Each board you plug in should show a tab with details about the board and the devices it's currently seeing. The view below has the disclosure triangle opened to show all the information, usually only a subset is shown.

Device Tabs

The top of this screen shows there's one device plugged in, usbmodem1451, if there were more than one, there would be more than one tab. usbmodem1451 is the internal name for the plugged-in USB device.

Basic device information

  • Status: shows what the sniffer is doing. It can be

    • Listing All Devices - the sniffer is showing basic information about all the devices it sees
    • Sniffing <device></device> - the sniffer is focussed on one single device and showing all packets from that
    • Connection - the device being sniffed is in a connection and the sniffer is following that.

  • Packet Count - should tick up as data comes from the USB device

  • USB Device - this is the name/serial number/type taken from the device if it can be read
  • Device Name - the full name of the device on OSX
  • Software Version - the version of the sniffer software on the device
  • Logging pipe - when the device is logging to Wireshark it uses a pipe to send data, this is the name of the pipe.
  • Logging port - the app can send data out via a UDP port, if it does, this is the port used
  • Logging file - if data is being dumped to a file for later analysis, this is the name of the temporary file used. Use the menu item Capture .. Save to save this to a permanent file.
  • Dropped Bytes - should be somewhere near zero. If this starts to count up then the data coming from the device is causing errors and is unreliable. Unplug and re-plug the device or restart the app.

Advertisers

The table shows all the advertisers the app can see in Listing All Devices mode. You can select one advertiser and then the 'Sniff Device' button should enable to allow you to focus in on that one device. The name and address are shown if there is a name, the RSSI is displayed and the triplet of numbers shows the interval between advertising packets on each of the three Bluetooth advertising channels.

Buttons

  • List Devices - switches to list mode, the scanner shows advertising packets from all devices
  • Sniff Device - enabled when one device in the table is selected. This changes the scanner into sniffing mode where it only looks at packets from the selected device. If the device goes into a connection, that will be followed and the status will change to 'connection'.
  • Capture to Wireshark - starts Wireshark and begins feeding it with packets. The packets represent the current mode, listening or sniffing and change as the mode changes.
  • Capture to PCAP - the packets are dumped to a temporary file which can be saved in the Capture .. Save menu item. The file generated can be loaded into Wireshark later for analysis. You can also capture to Wireshark and then save the file from there.
  • Enter Passkey - if the device is going into an authenticated mode you can input the passkey here and the sniffer will attempt to follow the encrypted connection.

Wireshark

When the 'Capture to Wireshark' button is pressed then Wireshark should start (it may take a little longer the first time) and packets are piped to it. You can press the button again to stop the packets and again to restart them into the same session. When you close Wireshark, the next time you hit the button, a new session will be created with a fresh Wireshark.

The Wireshark screen looks like this with decoded packets

After you have run the app and it's installed the correct Wireshark extensions, it should be possible to open a file dumped in the Windows version of the sniffer software.