BTLE-R

BTLE-Radio is an open source software-defined radio (HackRF One) Bluetooth low energy software experiment kit. Implement BLE baseband using software definition. In the BLE protocol stack, it corresponds to the physical layer and the link layer.

Currently, it supports sniffing and parsing of air interface packets in three frequency bands, and sends packets in any frequency band, so stay tuned!

Refer to Bluetooth Core Specification v 5.3

Requirements

Tested runtime environment (but not required) :

• gnuradio v3.8.5.0
• gr-osmosdr v0.2.0.0
• HackRF One with firmware 2021.03.1

BUILD&RUN

Install the HackRF driver and GNURadio components, and the default firmware of HACKRF ONE can be used.

OSX

There are many OSX installation problems, it is recommended to upgrade macport to the latest version. My test environment is OSX12.4.

Install hackrf driver

sudo port install hackrf

The GNURadio suite can be installed using the command, but it is recommended to download and install the DMG version.

sudo port install gnuradio

To use HackRF One on OSX platform, additionally install gr-osmosdr for GNURadio

sudo port install gr-osmosdr

Ubuntu

Compile the hackrf driver

cd ~/hackrf_files && git clone https://github.com/mossmann/hackrf.git
cd ~/hackrf_files/hackrf/host && mkdir build && cd build && cmake .. && make && sudo make install && sudo ldconfig

Install GNURadio Suite

 sudo aptitude install gnuradio

run gnuradio companion

sudo gnuradio-companion

RUN

Run BTLE-R (in development). Use python to customize the baseband logic, and currently can complete the frequency hopping of the broadcast channel.

USAGE

usage: BTLE-R.py [-h] [-v] [-m MAC] [-c CH] [-t FILE]

Command Line Interface for BTLE-Radio Bluetooth Baseband Experiment Kit

optional arguments:
  -h, --help                Show this help message and exit
  -v, --version             Show version and exit
  -m MAC, --mac MAC         Filter packets by advertiser MAC
  -c CH, --channel CH       Monitor the broadcast channel CHA, the range is 0-39, the default is 37-39
  -t FILE, --transfer FILE  Send link layer data, data from JSON file [ Example in src/transfer/packets.txt ]

Example

Monitor the content of all broadcast channels

 $ ./BTLE-R.py

Monitor the content of a broadcast channel of a mac address

 $ ./BTLE-R.py --mac e4:00:20:44:7c:d4

Send BLE link layer packets, on any channel，Content format see packets.txt.

$ ./BTLE-R.py -t transfer/packets.txt

After running the command, you can use LightBlue (or other BLE sniffer) to discover the broadcast with the name SDR/Bluetooth/Low/Energy. Sending other link layer signals is also supported.

[Warning]

My test environment is MacOSX. If an error occurs when running (especially when switching to Ubuntu), please use GNURadio Companion to rebuild the code, and then use BTLE-R.py again.

[For Debug and Dev]

Run GRC. The flow chart is mainly used to develop and debug BTLE-R. You can manually set the frequency band, AccessAddress, etc. in the parameters. If you need to perform automatic channel selection and connection tracking, please use BTLE-R directly.

To run the flow graph in GNURadioCompanion or run the python script ble_decode.py, use the following command.

$ python3 ble_decode.py

A BLE sending interface is provided. Use the following commands to use this interface for secondary development.

$ python3 trans_interface.py packets.txt

SNIFF

BTLE Air Interface Capture

1. Advertising physical channel packets Capture

   • Advertising/Scanning PDUs Capture

   

   • Initiating PDUs Capture

     e.g. CONNECT_IND packet capture，parsing the packet can be used to obtain key information of the link connection, including frequency hopping algorithm (and ChannelMap), CRC initial data and Connect Interval, etc.

     

Transfer

Link Layer Data Transfer

Doc

Sniffer Moudle Design

• GFSKDemod (GNURadio Default)
• BlE Packets Gain
• Data Whiting/De-Whiting
• CRC Check
• PDU Parse(Only Advertising Physical Channel，so far)
• Hop channel

Transfer Moudle Design

• BLE_Radio_Source（Requires PDU, transmit channel, Access Address, CRCinit and other information）
  • LL_Data Package
  • CRC calculation
  • Data Whitening
  • Hop channel

In the Plan

• Data Physical Channel
• Channel Selection