The STM32WB0 Sniffer for Bluetooth® Low Energy allows you to learn, analyze, and debug Bluetooth LE communications. You are able to listen to advertising packets or follow communications between two devices. If the devices are paired, it may even be possible to decrypt the packets.
The following features are supported on STM32WB0 Bluetooth LE Sniffer:
- Capture advertising PDUs transmitted on a selected primary advertising channel
- Track a single ACL connection initiated by or established with a selected device address
- Capture data PDUs transmitted over a tracked ACL connection
- Support LE 1M, 2M, and Coded PHYs
- Support Channel Selection Algorithms #1 and #2
- Track the following control procedures:
- Connection Update
- Channel Map Update
- Encryption Start and Pause
- ACL Termination
- PHY Update
- Reassemble L2CAP packet fragments
- Tracking of pairing procedures based on the following methods:
- Legacy Pairing: Just Works, Passkey Entry, Out of Band
- Secure Connections (Debug Mode): Just Works, Numeric Comparison, Passkey, Out of Band
- Filter signals using a selected RSSI threshold
- Packet loss while tracking an ACL connection may severely affect the sniffer’s ability to keep tracking.
- For example, if a control PDU that updates connection parameters at a given instant is missed, the sniffer may continue using outdated parameters and fail to receive packets after the instant. For encrypted connections, a lost packet can desynchronize the packet counter, preventing decryption of subsequent packets.
- If the sniffer misses too many consecutive packets on a connection (threshold is 50), it resets and stops tracking the connection, then resumes scanning primary advertising channels. If the connection remains active, no packets are captured until it terminates.
The STM32WB0 Bluetooth LE Sniffer application can run on this board:
- NUCLEO-WB09KE (image files are under firmware/)
- [STM32CubeProgrammer] (https://www.st.com/en/development-tools/stm32cubeprog.html) to program the prebuilt binaries.
- [Wireshark] Version 4.6.0 or later (https://www.wireshark.org/ Wireshark)
- [Python] version 3.11.2 or later (https://www.python.org/downloads) [Make sure that PySerial is installed on the correct version of Python if you have multiple installations. Use pip3 for example to force install on Python3].
- [Pyserial] Version 3.5 or later (https://pyserial.readthedocs.io/en/latest/pyserial.html PySerial)
- [libscrc python library] Version 1.8.1 [Also make sure Microsoft C++ 14.0 or later Build Tools - Visual Studio libraries are installed on your PC (https://visualstudio.microsoft.com/visual-cpp-build-tools/ - Microsoft Q&A)]
This section describes the steps to set-up and run the STM32WB0 Bluetooth LE Sniffer.
The STM32WB0 Bluetooth LE Sniffer for Bluetooth® Low Energy consists of two main parts:
- The software part, running on the computer, which captures, analyzes, and displays packets.
- The firmware part, running on the STM32WB09 MCU, which intercepts over-the-air packets.
A general STM32WB0 Bluetooth LE Sniffer description with an associated list of available sources of information is available on the STM32 Wiki article: https://wiki.st.com/stm32mcu/wiki/Connectivity:STM32_Sniffer_for_BLE.
The step-by-step installation guide is available on the STM32 Wiki article: https://wiki.st.com/stm32mcu/wiki/Connectivity:STM32_Sniffer_for_BLE_Setup_guide. The user has to perform the same steps using the equivalent STM32WB09 image files available in the firmware folder, and the Wireshark software files available in the wireshark folder. It is important to create a Python virtual environment inside your personal Extcap folder by following these steps:
- Create virtual environment:
- python -m venv venv
- Activate virtual environment:
- venv\Scripts\activate
- Install required python libraries:
- pip install -r requirements.txt
After installation, the user can follow a dedicated user guide to discover how to use the sniffer through Wireshark. The user guide is available on the STM32 Wiki article: https://wiki.st.com/stm32mcu/wiki/Connectivity:STM32_Sniffer_for_BLE_User_guide.
Caution : Issues and the pull-requests are not supported to submit problems or suggestions related to the software delivered in this repository. The STM32WB0 Bluetooth LE Sniffer firmware is being delivered as-is, and not necessarily supported by ST.
For any other questions related to the product, hardware performance or characteristics, tools, or environment, you can submit them to the ST Community on the STM32 MCUs related page.