Using The Nordic nRF Sniffer For BLE
The Nordic Semiconductor nRF Sniffer for BLE is a great low-cost tool for working with BLE. Once you set it up, capturing and analyzing BLE traffic is easy.
A Great Low-Cost Tool for Working with BLE
The Nordic Semiconductor nRF52840 Dongle can be used as a BLE sniffer. (Source)
When working with communications devices, it’s helpful to be able to observe the communications traffic. This is useful for developers and testers doing development, researchers studying system behavior, and students or professionals learning the protocol and device software.
A sniffer allows you to capture traffic from the communications medium and analyze it. For RF (Radio Frequency) wireless communications like Bluetooth Low Energy, the medium is the open air. The sniffer receives and records the data being broadcast by other nearby BLE devices.
Once you’ve captured that data, you can analyze it with tools like Wireshark. That allows you to see the protocol activity, and for unencrypted data, the data contents. This is a great way to learn how the protocol works or to verify that the devices are communicating properly.
Nordic provides the free nRF Sniffer for Bluetooth LE software package for turning several of their low-cost boards containing an nRF SoC (System-on-Chip) into BLE sniffers, using the Programmer app in the free nRF Connect for Desktop package. This post shows using the nRF52840 USB dongle.
The Sniffer package consists of firmware to load onto the device that provides the sniffing functionality, and Wireshark plugin and profile to control the sniffer and analyze the captured traffic.
You can also use the free Nordic nRF Connect for Mobile app on an iOS or Android mobile device to act as either side of a BLE connection, central or peripheral, to provide traffic.
The sniffer, app, and protocol analyzer make a powerful combination. They allow you to work on custom central or peripheral development using tools that behave as known-good references.
Nordic Resources
Product web pages:
- nRF Sniffer for Bluetooth LE main page.
- nRF52840 Dongle main page.
- nRF Connect for Desktop main page.
- nRF Connect for Mobile main page.
Infocenter documentation:
- nRF Sniffer for Bluetooth LE main page.
- Installing the nRF Sniffer detail page.
- Running the nRF Sniffer detail page.
- nRF Sniffer usage detail page.
- Common sniffing actions detail page.
- Complete nRF Sniffer for Bluetooth LE User Guide PDF.
Wireshark Resources
Wireshark main page.
Setup
Nordic provides the Sniffer package as a downloadable zip file, and the Connect for Desktop package as a downloadable file for Mac, Linux, and Windows platforms, no registration required. It provides the Connect app on the Apple App Store and Google Play Store.
To set up the Sniffer, download and extract the package zip file, then download the desktop tools for your platform. Install the tools and use them to flash the Sniffer firmware to the Nordic board.
The tools consist of the Nordic Desktop package with Programmer app, and Segger J-Link software (J-Link device not required). The specific combination of downloads depends on your platform.
Then install Wireshark and configure it with the plugin and profile included in the Sniffer package. The package also provides information on using the Sniffer Python API for scripted control (Python 3.5 and above).
When setting up the dongle, you can plug it directly into a USB port on your computer. However, for use, you may want to plug it into a USB extension cable so that you can move it around in closer proximity to other devices for better signal strength.
Download Sniffer Package
Download the Sniffer package from the Sniffer product page Downloads tab.
The package contains firmware images for all the supported Nordic boards.
Install nRF Connect Programmer
Download and install the nRF Connect for Desktop package for your platform from the Desktop product page Downloads tab.
For Windows, the Desktop package includes Segger J-Link Software. For other platforms, download and install the Segger J-Link Software package.
Follow the instructions on the Installing the Programmer app Infocenter page to install the Programmer.
See the nRF Connect Programmer overview Infocenter page for details on the app.
Program Sniffer
NOTE: The specific procedure for programming the nrf52840 USB dongle is different from the procedure for other boards. Be sure to follow the procedure specific to your board.
Follow the instructions on the Programming the nRF Sniffer firmware Infocenter page.
Install Wireshark
Download Wireshark for your platform from the Wireshark main page Download section, selecting from the Stable Release list.
In the same section, select a format for the Wireshark User’s Guide from the Documentation list. Follow the guide’s installation instructions for your platform.
Setup Wireshark
Follow the instructions on the Installing the nRF Sniffer capture tool Infocenter page. For Mac/Linux, you may need to prefix the command in step 3b with dot slash, like this:./nrf_sniffer_ble.sh --extcap-interfaces
For example, this is the output from running that on a Mac (note that the dongle LED begins flashing green rapidly, indicating packet captures):username@MacBook-Pro extcap % ./nrf_sniffer_ble.sh --extcap-interfaces
Running script with: </usr/local/bin/python3> with PATH: </Users/username/.pyenv/shims:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin:/Applications/Wireshark.app/Contents/MacOS>
extcap {version=4.1.0}{display=nRF Sniffer for Bluetooth LE}{help=https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Sniffer-for-Bluetooth-LE}
interface {value=/dev/cu.usbmodem1301-None}{display=nRF Sniffer for Bluetooth LE}
control {number=0}{type=selector}{display=Device}{tooltip=Device list}
control {number=1}{type=selector}{display=Key}{tooltip=}
control {number=2}{type=string}{display=Value}{tooltip=6 digit passkey or 16 or 32 bytes encryption key in hexadecimal starting with '0x', big endian format.If the entered key is shorter than 16 or 32 bytes, it will be zero-padded in front'}{validation=b^(([0-9]{6})|(0x[0-9a-fA-F]{1,64})|([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2}) (public|random))$b}
control {number=3}{type=string}{display=Adv Hop}{default=37,38,39}{tooltip=Advertising channel hop sequence. Change the order in which the sniffer switches advertising channels. Valid channels are 37, 38 and 39 separated by comma.}{validation=^s*((37|38|39)s*,s*){0,2}(37|38|39){1}s*$}{required=true}
control {number=7}{type=button}{display=Clear}{tooltop=Clear or remove device from Device list}
control {number=4}{type=button}{role=help}{display=Help}{tooltip=Access user guide (launches browser)}
control {number=5}{type=button}{role=restore}{display=Defaults}{tooltip=Resets the user interface and clears the log file}
control {number=6}{type=button}{role=logger}{display=Log}{tooltip=Log per interface}
value {control=0}{value= }{display=All advertising devices}{default=true}
value {control=0}{value=[00,00,00,00,00,00,0]}{display=Follow IRK}
value {control=1}{value=0}{display=Legacy Passkey}{default=true}
value {control=1}{value=1}{display=Legacy OOB data}
value {control=1}{value=2}{display=Legacy LTK}
value {control=1}{value=3}{display=SC LTK}
value {control=1}{value=4}{display=SC Private Key}
value {control=1}{value=5}{display=IRK}
value {control=1}{value=6}{display=Add LE address}
value {control=1}{value=7}{display=Follow LE address}
After performing step 4a to refresh the Wireshark capture interfaces, Wireshark listed the following device:nRF Sniffer for Bluetooth LE: /dev/cu.usbmodem1301-3.6
Then follow the instructions on the Adding a Wireshark profile for the nRF Sniffer Infocenter page.
Install nRF Connect For Mobile
You don’t need this to use the sniffer, but it’s a helpful tool for simulating a BLE device. It allows you to control the data being sent, which you can then observe with the sniffer. It also allows you to find other devices and get information about them.
Find the app on the Apple App Store or Google Play Store and install it from there.
Capturing And Analyzing Traffic
Below is a quick tour to show how to use the sniffer. For more details, see these Infocenter sections:
- Running the nRF Sniffer
- nRF Sniffer usage
- Inspecting captured data
- Troubleshooting
- Common sniffing actions will go through a number of typical BLE scenarios.
The real power in the sniffer comes from using it with Wireshark through the sniffer capture tool plugin and profile that you set up.
Wireshark is a very powerful tool, with many capabilities and many options. If you’ve never used it before, spend some time just exploring with it and getting used to the GUI. Browse through the user guide to see what it can do. The detail it provides can be overwhelming, so take it a bit at a time.
If you’re new to BLE, or to data communications in general, those are separate dimensions to the learning curve.
Capturing Traffic
When you start Wireshark, you’ll see the “Welcome to Wireshark” screen, listing the Capture interfaces available. These are the various network interfaces, physical and virtual, wired and wireless, that it can capture data from your computer. You may have a number available.
Scroll down the list and click on the one identified as “nRF Sniffer for Bluetooth LE:” to select it. The label will include additional platform-dependent device information.
If you don’t see the sniffer listed, you may need to unplug and plug it in again, then select “Capture > Refresh Interfaces” from the menu. The sniffer should appear in the list, and its LED should start blinking fast green as it receives packets.
In the toolbar at the top of the window, click on the blue shark-fin shaped icon on the left. That’s the capture “Start” button. The red square icon to its right is the capture “Stop” button. The green shark-fin icon to the right of that is the capture “Restart” button.
Any time you start a capture with data already captured, if you haven’t saved it, Wireshark will ask if you want to save the captured data first. This is very important, because depending on what you’re doing, that captured data may be very valuable for the task at hand and may be hard to reproduce.
Data can be saved in the pcapng or pcap format and may be compressed with gzip. Captures can have very large amounts of data. Once saved, you can reload captured data later for examination.
You can capture all advertising devices, or just a specific one. In a “noisy” environment with lots of BLE devices nearby, there may be a lot of advertisement traffic.
Wireshark will list packets received from the selected device or devices. It will list the various decoded protocol layers for the currently selected packet, and show the raw hex/text dump of the packet data.
Analyzing Traffic
You can click on any line in the decoded protocol layers to expand it further. Information can be nested several layers deep. The hex/text dump will highlight the bytes corresponding to the currently selected item. You can also click on a byte in the dump, and Wireshark will expand the protocol decode to show what item contains it.
You can examine data live while a capture is in progress, after stopping the capture, or after reloading a saved capture.
You can filter the data displayed to focus in on specific types of packets. Then you can export packets based on display filters.
The filter syntax may be obscure to you as you’re learning to use the tool and learning the protocol details. A very helpful feature is that you can right-click on a protocol decode line or in the hex dump and select “Apply as Filter” from the pop-up menu. Then select “Selected” or “Not Selected” to either include or exclude packets meeting the filter criteria.
Here’s a closeup of right-clicking on the “Data:” line in the window, then applying that as a filter to select all packets with matching Data field:
This constructs filters automatically in the display filter box across the top of the window. As you learn the filters, you can combine them with logical operators to create more sophisticated filters.
Filtering is a powerful way to dig into all the data. It’s like searching a document and extracting just the parts you want to look at.
Packet analysis is an art, in part because of the enormous volume of information in the captured data. High-speed devices can transmit megabits per second (mbps). For example, a single HD video stream can be 5 mpbs. That can be thousands of packets per second.
An understanding of the protocols in use, and the ability to filter on them, is key to wading through all that data.
BLE over-the-air raw data rate ranges from 125 kbps to 2 mpbs. Normally, a BLE device doesn’t transmit packets continuously. Depending on its connection state and configuration, it may only transmit small packets periodically.
A useful strategy is to focus on particular BLE communication scenarios, such as advertising, pairing, connecting, and data exchanges.
Using nRF Connect For Mobile
The nRF Connect for Mobile app can be used in several ways. A simple start is to create a BLE advertising packet on it. A device transmits advertisements so that other devices can find it, or can collect the data it advertises.
Advertisements are broadcasts, not directed to any particular destination. In contrast, connections are point-to-point transmissions and data exchanges with specific destinations. At the physical layer, the RF signals are broadcast for all traffic (which is why the sniffer can sniff them), but at higher protocol layers only the destination device will pay attention to the data on a connection. The sniffer operates in promiscuous mode, where it pays attention to all traffic.
Once you’ve created an advertisement packet with known data, you can filter for it in Wireshark.
Get Some D5 Coffee
Let’s get some D5 coffee to see how to use the app, sniffer, and Wireshark.
BLE protocol standards define a number of existing services that devices can advertise and provide. Services are identified by UUID (Universally Unique Identifier) and provide service-specific data. For instance, a BLE heart-rate monitor would advertise the well-known heart-rate service, which would provide the heart-rate data.
We can take advantage of this to create a custom advertising packet, reusing a well-known UUID.
In the app, tap on “Advertiser”. On the Advertiser screen, tap on the + sign to add an advertising packet.
For “Display name,” enter “Dojo Five Test”. Tap on “ADD RECORD” and select “Complete Local Name”.
Tap on “ADD RECORD” again and select “Service Data”. For “UUID or service name,” enter “1800” (this is interpreted as hex value 0x1800). For “Data (HEX),” enter “D5C0FFEE” (note the zero, not letter ‘O’). Tap on “OK”.
The app now has an advertising packet to send. The display name is just for identifying it in the app.
Notice that it’s listed as “RANDOM ADDRESS” and “NON-CONNECTABLE”. Random address means the advertisements will use a new random source address whenever you start advertising. This is a security measure to prevent device tracking. A device can also use its public address, which is based on the BLE device’s hardware address. NON-CONNECTABLE means it won’t accept a connection request from another device.
The “Complete Local Name” is taken from the mobile device, in this case, a “moto g(7) power” Android phone. The advertisement will contain this name and the D5C0FFEE service data.
Tap the slider next to “RANDOM ADDRESS” to start advertising. The default is to leave it running until manually turned off. Tap OK. The app will start advertising, showing the slider moved to the right.
Now that the D5 coffee is flowing, let’s find it with the sniffer. Enter the following in the Wireshark display filter box:btcommon.eir_ad.entry.service_data == d5:c0:ff:ee
This filter looks for the service data the phone is advertising. Wireshark will display only those packets that contain this data.
The name of the filter field is obscure, so this is why it’s nice to simply highlight some data in the Wireshark window and use the “Apply as Filter” feature to create a correctly-specified filter. Once you learn how to take advantage of that, you can start learning the field names and understand how they relate to the protocol layers.
The screenshot below highlights the captured data:
- The green filter box contains the filter rule.
- The packet list “Source” column shows the random address that the phone is currently using for this advertisement.
- The protocol decode “Service Data” field for UUID 0x1800 contains “d5c0ffee”. You may need to click on protocol decode lines to expand them to see this; it’s in the “Bluetooth Low Energy Link Layer > Advertising Data > Service Data – 16-bit UUID”.
- The packet hex/text dump shows the hex value “d5 c0 ff ee” and the string “moto g(7) power”.
Now that you’ve captured a known packet, you can click on various parts of it to explore it. You can change the advertisement in the app and see how that affects the data that shows up in captures. You can also do more complex things like observing pairing, connection, and data exchanges.
By default, Wireshark’s capture target “Device” is “All advertising devices”. You can click on that and select just this specific device from the list, using its source address.
However, the use of random addresses complicates things. Click on the “Device” list box to see the addresses Wireshark has collected. In this case, “moto g(7) power” shows up several times:
The one selected at the bottom is the current random address that was in the captured data. The other ones are from previous advertising starts.
This can make isolating traffic for a specific device more difficult. When you’re doing development, you might find it helpful to configure the device to use its fixed public address if you can.
The other thing that can make analyzing traffic more difficult is the use of encryption. By design, advertisements are sent in the clear, unencrypted, so that anyone can receive and decode them. They are by definition insecure.
Connections can use encryption for secure communications. There are several types of security depending on the pairing mode. Wireshark is able to decrypt some types of connection if given the encryption key.
Summary
The Nordic Semiconductor nRF Sniffer for BLE is a great low-cost tool for working with BLE. Once you set it up, capturing and analyzing BLE traffic is easy.
This just touches the surface of what you can do with the sniffer. The details of BLE protocols, Wireshark, and the nRF Connect for Mobile app are beyond the scope of this post, but it gives you the tools to start learning and working with them.
Dojo Five can help you with BLE and Nordic products; we are a Nordic Design Partner. We bring modern tools, techniques, and best practices from the web and mobile development environments, paired with leading-edge innovations in firmware to our customers to help them build successful products and successful clients. Our talented engineers are on hand ready to help you with all aspects of your EmbedOps journey. Bring your interesting problems that need solving – we are always happy to help out. You can reach out at any time on LinkedIn or through email!