📡 BLE Proximity Scanner

A real-time Bluetooth Low Energy (BLE) proximity scanner for Linux. Monitors nearby BLE devices with signal strength (RSSI) and estimates distance using the Log-Distance Path Loss model.

Features

• Live Dashboard — Real-time CLI interface powered by rich
• Range Estimation — Converts RSSI to estimated distance in meters
• Proximity Highlighting — Color-coded output: 🟢 < 2m · 🟡 < 10m · 🔴 > 10m
• Async Scanning — Non-blocking BLE interaction via bleak
• Calibratable — Tune TX power and path loss exponent for your environment

Prerequisites

• OS: Linux with BlueZ
• Python: 3.8+
• Hardware: Bluetooth adapter (enabled)

Installation

git clone https://github.com/AlphaMvge/ble-proximity-scanner.git
cd ble-proximity-scanner
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Permissions (Optional)

To run without sudo, add your user to the lp group:

sudo usermod -aG lp $USER
# Log out and back in for changes to take effect

Usage

python main.py

CLI Options

Flag	Default	Description
--tx-power	-59	RSSI measured at 1 meter from transmitter
--n	2.5	Path loss exponent (2.0 = open air, 3.0+ = indoors)

Calibration

For more accurate readings, calibrate the TX power for your specific environment:

1. Place a BLE device exactly 1 meter away from your adapter
2. Note the RSSI value shown in the scanner
3. Re-run with that value:

python main.py --tx-power -62

Path Loss Exponent Reference

Environment	n Value
Free space / outdoors	2.0
Light indoor (open office)	2.5
Dense indoor (walls, furniture)	3.0 – 4.0
Multi-floor / heavy obstruction	4.0 – 6.0

How It Works

Distance is estimated using the Log-Distance Path Loss model:

d = 10 ^ ((TxPower - RSSI) / (10 * n))

Where:

• d — Estimated distance in meters
• TxPower — Signal strength at 1 meter (default: -59 dBm)
• RSSI — Received signal strength indicator
• n — Path loss exponent for the environment

License

MIT — © 2026 AlphaMvge