jiaoxianjun/btleBluetooth Low Energy (BLE) packet sniffer and transmitter for both standard and non standard (raw bit) based on Software Defined Radio (SDR).
BTLE is a free and open-source Bluetooth Low Energy (BLE) Software Defined Radio software suite and open BTLE chip design.
It includes:
Make sure your SDR hardware environment (driver/lib) has been setup correctly before run this project.
git clone https://github.com/JiaoXianjun/BTLE.git
cd BTLE/host
mkdir build
cd build
cmake ../ (default. for HackRF)
cmake ../ -DUSE_BLADERF=1 (only for bladeRF)
make
./btle-tools/src/btle_rx
Above command sniffs on channel 37. You should see many packets on screen if you have BLE devices (phone/pad/laptop) around.
./btle-tools/src/btle_tx 37-DISCOVERY-TxAdd-1-RxAdd-0-AdvA-010203040506-LOCAL_NAME09-SDR/Bluetooth/Low/Energy r500
Above command transmits discovery packets on ADV channel. You should see a device with name "SDR/Bluetooth/Low/Energy" in another BLE sniffer App (such as LightBlue).
To have a faster operation sequence on HACKRF, use following:
#define TRANSFER_COUNT 4
#define TRANSFER_BUFFER_SIZE 4096
in hackrf/host/libhackrf/src/hackrf.c. Then re-compile the HACKRF lib and re-install it. Don't forget to re-compile BTLE to take the HACKRF lib change.
Besides the tools, matlab directory includes algorithm evaluation and other useful scirpts
-h --help
Print all arguments/usages.
-c --chan
Channel number. Default value 37 (one of ADV channels). Valid value 0~39 (all ADV and DATA channels).
-g --gain
Rx gain in dB. HACKRF rxvga default 6, valid 0 - 62. bladeRF default is max rx gain 66dB (valid 0 - 66). Gain should be tuned very carefully to ensure best performance under your circumstance. Suggest test from low gain, because high gain always causes severe distortion and get you nothing.
-l --lnaGain
LNA gain in dB (HackRF only). Default 32, valid 0 - 40. Gain should be tuned very carefully to ensure best performance under your circumstance.
-b --amp
Enable amp (HackRF only). Default off.
-a --access
Access address. Default 8e89bed6 for ADV channel 37 38 39. You should specify correct value for data channel according to captured connection setup procedure.
-k --crcinit
Default 555555 for ADV channel. You should specify correct value for data channel according to captured connection setup procedure.
-v --verbose
Verbose mode. Print more information when there is error
-r --raw
Raw mode. After access addr is detected, print out following raw 42 bytes (without descrambling, parsing)
-f --freq_hz (need argument)
This frequency (Hz) will override channel setting (In case someone want to work on freq other than BTLE. More general purpose).
-m --access_mask (need argument)
If a bit is 1 in this mask, corresponding bit in access address will be taken into packet existing decision (In case someone want a shorter/sparser unique word to do packet detection. More general purpose).
-o --hop
This will turn on data channel tracking (frequency hopping) after link setup information is captured in ADV_CONNECT_REQ packet on ADV channel.
-s --filename
Store packets to pcap file.
btle_tx packet1 packet2 ... packetX ... rN
or
btle_tx packets.txt
packets.txt is a text file which has command line parameters (packet1 packet2 ... rN) text. One parameter one line. A line start with "#" is regarded as comment. See packets.txt example
packetX
is one string which describes one packet. All packets compose a packets sequence.
rN
means the sequence will be repeated for N times. If it is not specified, the sequence will only be sent once.
packetX string format
channel_number-packet_type-field-value-field-value-...-Space-value
Each descriptor string starts with BTLE channel number (0~39), then followed by packet_type (RAW/iBeacon/ADV_IND/ADV_DIRECT_IND/etc. See all format examples AT THE END: Appendix ), then followed by field-value pair which is packet_type specific, at last there is Space-value pair (optional) where the value specifies how many millisecond will be waited after this packet sent.
DO NOT use space character " " in a command line packet descriptor. You CAN use space in the txt file packet descriptor.
DO NOT use "-" inside each field. "-" is magic character which is used to separate different fields in packet descriptor.
Open LightBlue APP (or other BLE sniffer) in your iPhone/device before this command:
./btle-tools/src/btle_tx ../btle-tools/src/packets_discovery.txt
You will see a device named as "SDR Bluetooth Low Energy" in your LightBlue APP.
Corresponding Command line:
./btle-tools/src/btle_tx 37-DISCOVERY-TxAdd-1-RxAdd-0-AdvA-010203040506-LOCAL_NAME09-SDR/Bluetooth/Low/Energy r40
Note: space " " is replaced by "/" because space " " is not supported in command line.
btle_tx 37-ADV_IND-TxAdd-0-RxAdd-0-AdvA-90D7EBB19299-AdvData-0201050702031802180418-Space-1 37-CONNECT_REQ-TxAdd-0-RxAdd-0-InitA-001830EA965F-AdvA-90D7EBB19299-AA-60850A1B-CRCInit-A77B22-WinSize-02-WinOffset-000F-Interval-0050-Latency-0000-Timeout-07D0-ChM-1FFFFFFFFF-Hop-9-SCA-5-Space-1 9-LL_DATA-AA-60850A1B-LLID-1-NESN-0-SN-0-MD-0-DATA-XX-CRCInit-A77B22-Space-1
Above simulates a Connection establishment procedure between device 1 and device 2. Corresponding descriptor file BTLE/host/btle-tools/src/packets.txt.
The 1st packet -- device 1 sends ADV_IND packet in channel 37.