Using The Nordic nRF Sniffer For BLE

Original Author: Steve Branam, Updated by Aaron Fontaine

Introduction

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.

With BLE especially it can be hard to know what’s happening under the hood when our only view is the information provided by high-level APIs. There are a lot of parameters that can be adjusted: connection interval, MTU size, PHY selection, etc. On top of that, many of the details such as buffering, fragmeting of packets, or sending multiple packets per event are handled automatically by BLE stacks. When we have difficulty diagnosing throughput issues or range issues or if we just want to do some performance analysis, it’s time to get the low-level view of the actual traffic.

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.

💡 Note: A sniffer works by listening on the same frequency on which another device is transmitting. There is no guarantee that the sniffer will see all of the packets sent. Similarly, it’s possible that the receiver will miss packets that the sniffer does see. Keep these points in mind as you troubleshoot BLE issues.

Why Use the Nordic nRF Sniffer?

There are two main reasons to use the Nordic nRF Sniffer. First, it’s low cost. As of the time of this writing, the nRF52840 dongle lists for $10 on DigiKey. You’ll be hard-pressed to find a more cost effective general purpose BLE sniffer than this.

Another common result when searching BLE sniffers is the Adafruit Bluefruit LE Friend. Although the BLEFriend can be used for BLE sniffing, it is based off the older nRF51822 technology, which means it does not support BLE 5.0 features. This makes it practically useless for any modern BLE application. See Nordic’s feature chart here (the relevant column is labeled “nRF51 Dongle”). Also, it’s more than twice the price.

The main limitation with the nRF52840 for BLE sniffing is that it can listen on only one channel at a time. This means that some packets of interest may be missed. There are solutions that can listen on all channels simultaneously, but they are not low cost.

The second main reason to use the Nordic nRF Sniffer is that it has a Wireshark plugin. Wireshark is an award-winning free and open source network protocol analyzer with a GUI front end that is straightforward and simple to use. It has become a go-to standard for network packet analysis. With Nordic’s plugin, it can be used for BLE packet analysis as well.

Setting Up the Nordic nRF Sniffer

The following diagram shows a conceptual overview of setup and operation of the nRF BLE sniffer.

There are two components to be installed into Wireshark. The first is the extcap (external capture) interface. This is the bridge between the serial command interface used by the nRF Sniffer firmware and the Wireshark GUI. The second is a profile configuration. This allows you to quickly change the layout (toolbars, columns, etc.) to support BLE packet analysis. Additionally, you will need to load the nRF Sniffer firmware onto the nRF52840 dongle. It does not come pre-loaded.

To get started, first download and install the nRF Util command line utility. Follow the instructions for your platform.

Important: make sure that the nrfutil command works from the command line before moving on with the rest of the setup. Open a terminal (or command prompt) and enter nrfutil --version.

% nrfutil --version
nrfutil 7.11.0 (a35d9f1 2024-05-20)
commit-hash: a35d9f1de76658e553c6707bd4850c2bf5cf2bad
commit-date: 2024-05-20
host: aarch64-apple-darwin
build-timestamp: 2024-05-20T12:44:41.018367000Z
classification: nrf-external

Once nRF Util is installed, you are ready to go through Nordic’s instructions on setting up the sniffer and Wireshark plugins. Before you do that, though, its worth reading through the next section that will guide you through some of the gaps and inconsistencies in the process.

Important Details for the Setup Process

Tools and Documentation Migrations

As with most companies, Nordic is constantly evolving their ecosystem. Two recent transitions to be aware of when going through this process are:

• The transition to using nRF Util. Prior to this Nordic had a command line tool called nrfjprog and the extcap plugin for Wireshark was handled with a Python script. The new methodology does away with the script and instead installs an executable shim that connects nRF Util’s ble-sniffer to Wireshark.
• The transition from InfoCenter to Tech Docs. These do not provide the same instructions. The InfoCenter docs have no mention of nRF Util and will walk you through the older process of installing the Python script into Wireshark. Stick with the Tech Docs.

Note: The first page of the Tech Docs provides links to older documentation archived as PDFs. These are all archived forms of the InfoCenter docs. Avoid these as well.

Note: It is strongly recommended to avoid the Python-based Wireshark plugin. There are multiple possible troubleshooting issues that are avoided by using nRF Util.

Local vs Global Settings for Wireshark

Another change with the Tech Docs instructions is that they have you install to the user local configuration directory for Wireshark. (The InfoCenter instructions have you modifying the global configuration.) The “Folders” tab of the About Wireshark dialog gives the global and local (a.k.a “Personal”) paths for both extcap plugins and configuration profiles. Ensure that you are using the personal/local paths for modifying Wireshark.

Note: You may get an error when running the nrfutil ble-sniffer bootstrap command that the extcap directory does not exist. This is pretty simple to correct. The full path for the expected directory is provided. You just need to go into Finder/File Explorer and create it. (Or use mkdir).

Finding the Sniffer Firmware

When you get to Programming the Sniffer Firmware, you may be asking yourself, where exactly are the hex files? The instructions say you can use the $NRFUTIL_HOME environment variable to find the nrfutil root folder, but as I can tell, no such env var is set up. Here I would recommend skipping this step and coming back after you’ve completed Installing the nRF Sniffer Capture Tool.

After it completes, the nrfutil ble-sniffer bootstrap command will output a list of supported devices along with the full paths to their hex files. Now you have something to copy-paste into the nrfutil device program command in the Programming the Sniffer Firmware step.

Note: The firmware image for loading the nRF52840 Dongle ends in .zip, not .hex.

Setting the Dongle in Bootloader Mode

Dev kits such as the nRF52840 DK are programmed through an onboard JLink. This means they can be reprogrammed regardless of their current state. The nRF52840 Dongle, by contrast, is programmed directly through the nRF52840’s USB interface using the preprogrammed bootloader. This means the dongle must be in bootloader mode for Nordic utilities to see it.

If you have not yet loaded the dongle, it will be in bootloader mode by default. You should see a pulsing red LED. If you do not see this, you will need to press the reset button after connecting it to your computer. The reset button faces sideways and is next to the big N.

nRF Device Serial Numbers

The instructions for programming the dongle recommend you to use the --serial-number option to identify the correct device to be loaded. This option is only necessary if you have more than one Nordic device connected. You can get the serial numbers using nrfutil device list.

Important: If loading the nRF52840 Dongle, ensure that it is in bootloader mode before listing serial numbers or you will get the wrong serial number. Note also that the serial device/COM port will change when the dongle resets into bootloader mode.

Finding the Wireshark Configuration Profile

When you get to step 4 of Adding a Wireshark profile for the nRF Sniffer, you may be asking yourself, where exactly is this Sniffer_Software/Profile_nRF_Sniffer_Bluetooth_LE profile folder that I’m copying from? Tech Docs does not contain a link to this content. This is a documentation gap that resulted during the migration from InfoCenter to Tech Docs.

Prior to nRF Util, the InfoCenter had you download a zip file containing all the necessary components. The configuration profile is only available through this download. Fortunately, these downloads are still available.

Additionally, it is not necessary to manually copy the contents to Wireshark’s profiles folder. You can just use the Import feature of the Configuration Profiles dialog.

To add the nRF Sniffer Wireshark profile:

• Go to the download page for the nRF Sniffer zip packages.
• Download and unzip the latest package. Inside is a folder named Profile_nRF_Sniffer_Bluetooth_LE . This is what you will import.

💡 Note: Ignore everything else in this zip package. It is already handled by nRF Util.

• In Wireshark, open the Configuration Profiles dialog from the Edit menu: Edit > Configuration Profiles…
• Select From Directory… on the Import list box.

• Select the Profile_nRF_Sniffer_Bluetooth_LE folder mentioned above. This copies the entire folder to your personal/local Wireshark profiles folder.
• The nRF Sniffer profile is now ready to use.

Getting Started with the Nordic nRF Sniffer

Once you have everything set up, it’s time to try out the sniffing capabilities. Be sure to give the Running the nRF Sniffer and nRF Sniffer usage sections of the docs a good read through.

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.

Tips for Capturing and Analyzing Traffic

The following section gives some extra tips and pointers for using the sniffer.

Correctly Connecting the nRF52840 DK

If you are using the nRF52840 DK rather than the dongle, make sure you connect to the *nRF USB *****port and not the IMCU USB port. The docs have a note about this, but their diagram makes it seem as though you should be connecting to the IMCU USB port. Both will work, but the IMCU USB port has lower throughput and may drop packets.

Note: If you connect to the wrong USB port, there is no warning or indication of the lower bandwidth.

Selecting the Hardware Interface

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.

The Tech Docs look for an interface named “nRF Sniffer for Bluetooth LE COM17”. This is just an example. The exact name will differ depending on your OS and the sniffer that is connected. Importantly, it will start with “nRF Sniffer for Bluetooth LE”.

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.

Note: If you have more than one nRF Sniffer device connected, they should all appear in the list.

Toolbar and Configuration Profile

Before you start sniffing packets, you’ll want to make sure that you have the nRF Sniffer configuration profile selected and that the nRF Sniffer toolbar is visible. Go to Edit > Configuration Profiles, make sure “Profile_nRF_Sniffer_Bluetooth_LE” is selected, then press “OK”.

The nRF Sniffer toolbar appears below the display filter. It can be enabled and disabled from the View menu. If it is not visible, go to View > Interface Toolbars > nRF Sniffer for Bluetooth LE to enable it.

Display Filter vs Capture Filter

Wireshark provides both a display filter and a capture filter. The display filter is always available right below the main toolbar. The capture filter exists only on the welcome screen before you start capturing packets.

• Capture Filter: Selected before you begin sniffing. Cannot be changed once sniffing starts. This limits the packets captured in the packet list.
• Display Filter: Can be changed at any time before or after sniffing is started. Only affects the display. Does not affect the packets captured in the packet list.

Additionally, you’ll notice that the nRF Toolbar has a Device dropdown list. Once sniffing is started, this list is updated as new devices are seen. Selecting a device in the list acts as an on-the-fly capture filter, meaning that traffic from other devices won’t be recorded. It also instructs the sniffer that you are interested in following any connection that occurs with that device.

Using Packet Details to Set Display Filters

The Tech Docs note that you can turn any field in the packet details pane into a display filter by right-clicking the field and selecting Apply as Filter.

One note about this. You can do this from the packet list pane as well, but be careful of the “Source” column. It is tied to eth.src and not btle.advertising_address. Selecting Apply as Filter on it will give an invalid filter and show no packets. It is best to stick with the packet details pane or the Device dropdown.

Demonstration

This section will walk you though verifying the advertising data of a BLE device. It uses the nRF Connect for Mobile app to make your phone act as the device.

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.

Analyze an Advertising Packet (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 “Galaxy A04” 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 “Galaxy A04”.

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.

Note however, the use of random addresses complicates things. Every time that advertising is stopped and started again, the nRF Connect app assigns a new random address. This will appear as multiple of the same device in the “Device” list box. In this case, “Galaxy A04” 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.

Analyzing Throughput on a Connection

Throughput Test Setup Details

This section demonstrates use of the sniffer to analyze Nordic’s Bluetooth: Throughput example. It was modified to create an unencrypted connection to allow the sniffer to follow the connection easily. The throughput test was run between an nRF52840 DK and an nRF5340 DK.

Setup of the Bluetooth Throughput example is beyond the scope of this guide. For those familiar with the nRF Connect SDK, the example can be found in <ncs_root>/nrf/samples/bluetooth/throughput. The following modification must be made to the connected() function in main.c to force an unencrypted connection.

Test procedure:

• Build and load the Throughput example on both dev boards.
• Connect both boards to a laptop and open a serial terminal to each board. This connects to the command shell provided by the demo.
• Start the BLE sniffer in Wireshark.
• Issue the peripheral command to the nRF5340 DK.
• Select the newly created device in the “Device” list box in Wireshark. It should be at the bottom of the list.
• Issue the central command to8 the nRF52840 DK.
• Ensure that the BLE sniffer follows the connection. If it does not repeat the above steps.
• Issue the run command to the nRF52840 DK.
• Wait for the test to complete and ensure that Wireshark is capturing the packets.
• Stop Wireshark and, optionally, save the capture results.

Test details:

• The nRF5340 DK was set as the Peripheral.
• The nRF52840 DK was set as the Central.
• The run command was issued to the nRF52840 DK.
• Packets were sent from the Central (nRF52840) to the Peripheral (nRF5340).
• The test achieved a throughput of ~167 KB/s.
• The test established a connection interval of 400 ms and used an L2CAP MTU of 498 bytes.

Following the Connection

It is enough to have a device selected in the Devices list box for the BLE sniffer to follow a connection. Here is what the traces look like. Note that some columns have been removed.

At first the peripheral device is advertising. It then receives a CONNECT_IND from the central. This initiates a connection procedure and service discovery. After the service discovery, the two DK boards negotiate RX and TX MTU sizes of 498 bytes.

Note that at this point the connection interval is 7.5 ms and is still using the 1M PHY. This can be confirmed from the packet timestamps. The interval and PHY will be updated before the test starts.

Analyzing the Throughput

Here is a snapshot of the packets once the transfer is started.

There are several things to note here:

• With DLE (data length extension) enabled, each BLE packet PDU (protocol data unit) has a maximum payload of 251 bytes. This includes L2CAP and ATT headers and leaves a maximum of 244 bytes for MTU data. This is less than the negotiated 498 byte ATT MTU size.
• Because of this, each ATT packet is framgented into two separate packets to be sent over-the-air. See the purple outlines. Between these fragments, the 4-byte L2CAP header appears once, giving 498 for the ATT data. Of this, the 3-byte ATT header appears once, leaving 495-bytes available for ATT payload. Or, in other words, we can fit up to 495 bytes every ATT payload.
• Even if only one side is transmitting, the central and peripheral must continuously alternate sender and receiver roles. Those forces the peripheral in this case to send packets with an empty PDU. These packets still contain BLE headers and take up about 44µs on the 2M PHY.
• Every time the transmitter role changes, there is a mandatory inter-frame spacing (IFS) of 150µs.
• The event counter designates the connection interval (i.e. the event) that the packets belong to. The throughput test is sending hundreds of packets back-to-back in the same connection interval. This is why a long connection interval does not mean low throughput. It depends on how long the connection event is and how many packets are allowed per event. It is more important to maximize MTU size thus minimizing BLE overhead.
• When the end of the connection interval is reached and a new event is started, there is a waste of only 1820µs (see the green outline). This is very efficient. At most this could fit one more packet. We can view the on-air time in Wireshark for one 251-byte packet as 1048µs. Adding the 44µs for the empty packet back from the peripheral and two inter-frame spaces gives us 1392µs.

• However, this gap is not actually available for two reasons.
  • The MTU size is not actually 251 but 498. It needs time for two exchanges.
  • The central must account for the fact that the peripheral may decide to send back its own 498-byte packet. Remember, the Rx MTU was also set to 498 and the peripheral is allowed to send data to the central at any time.

Throughput Test Summary

This has been a brief example of how to use a Wireshark BLE capture to analyze throughput. Hopefully it gives some ideas the next time you need to troubleshoot a throughput issue. Things to look out for when diagnosing an issue are:

• PHY selection: Is it running with 1M or 2M?
  • Note that 1M provides better range than 2M at half the bandwith. This tradeoff can be carried further with CODED PHY.
• Packet fragmentation:
  • Is the MTU size set correctly?
  • Are Data Length Extensions (DLE) enabled? This allows MTUs larger than 23 bytes.
  • Are the packets being fragmented efficiently? In this example, the fragmentation was highly efficient. You’ll want to watch out for packets that fragment only a few bytes into the next PDU. Fragmentation is not apparent from the higher-level Bluetooth APIs so double-check it with the sniffer. Try to maximize the use of each PDU and adjust both the buffer size you use to send data and the MTU size to achieve a good balance.
• Connection interval utilization: What is the delay between the end of the last packet of one event and the start of the first packet of the next event? How does that compare to the connection interval?
  • Bear in mind that 1 unit is 1.25ms. Thus a connection interval of “320” is 400ms.

Throughput Considerations in the Real World

For all intents and purposes, this test has achieved the maximum throughput possible for unidirectional data sent over a GATT characteristic using the 2M PHY. This is because it was run between two dev kits, both of which had its BLE radio entirely to itself.

In reality, your devices will be talking to a mobile phone (iOS or Android), a laptop, or possibly a Raspberry Pi. Bear in mind that the OS on these devices will not allow exclusive use of their radio. They will place restrictions on minimum connection interval, maximum event window, and so forth. You should test interoperability on a range of devices you expect your device to work with. This is because each OS has different restrictions.

Encrypted Connections

Another factor that can complicate traffic analysis is the use of encryption. Several types of security depending on pairing mode can be utilized. Wireshark can decrypt and follow some types of connection if given the encryption key. How to do this is beyond the scope of this article.

Summary

Nordic Semiconductor nRF Sniffer for BLE is a great low-cost tool for working with BLE, and once set it up, capturing and analyzing BLE traffic is easy.

This just touches the surface of what one can do with Nordic’s nRF Sniffer. Details of BLE protocols, Wireshark, and nRF Connect for Mobile app are beyond the scope of this post.

Dojo Five can help with BLE and Nordic Semiconductor products; we are a Nordic Design Partner. Dojo Five brings modern tools, techniques, and best practices from web and mobile development environments, paired with leading-edge innovations in firmware to our customers helping them build successful products and successful clients. Our talented engineers are on hand ready to help with all aspects of your EmbedOps journey. Bring us your interesting problems needing solutions – we are always happy to help. Dojo Five can be reach any time through our LinkedIn or email!