Files

User 0e99232582 Switch to bleak for reliable BLE scanning with RSSI

- Replace hcitool-based BT scanning with bleak Python library
- Bleak provides reliable RSSI values via D-Bus/BlueZ
- BLE scan now finds devices that hcitool missed
- Update project docs to reflect resolved BT RSSI blocker
- Add bleak>=0.21.0 to dependencies

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-01 00:17:47 +01:00

6.1 KiB

Raw Blame History

RF Mapper

WiFi & Bluetooth Signal Mapping Tool for Raspberry Pi

Overview

RF Mapper is a Python-based tool that scans, visualizes, and maps RF (Radio Frequency) signals from WiFi networks and Bluetooth devices. It provides a web-based dashboard with multiple visualization modes including radar view, 2D map, and 3D building view with floor-based positioning.

Problem Statement

Understanding the RF environment around you is useful for:

Network troubleshooting and optimization
Security auditing (identifying rogue devices)
Asset tracking and device inventory
Indoor positioning research
Home automation device discovery

Key Features

WiFi Scanning - Discover networks with SSID, BSSID, RSSI, channel, encryption
Bluetooth Scanning - Classic BT and BLE device discovery with device type inference
Distance Estimation - RSSI-based distance calculation using log-distance path loss model
OUI Lookup - Manufacturer identification from MAC addresses
Web Dashboard - Real-time visualization with multiple views:
- Radar view (polar plot)
- 2D World Map (Leaflet/OpenStreetMap)
- 3D Building Map (MapLibre GL JS)
Floor-based Positioning - Assign devices to building floors
Live Tracking - Real-time Bluetooth tracking mode
Auto-scan - Scheduled background scanning
Data Export - JSON scan history with timestamps

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Web Browser                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
│  │  Radar   │  │  2D Map  │  │  3D Map  │                   │
│  │  View    │  │ (Leaflet)│  │(MapLibre)│                   │
│  └──────────┘  └──────────┘  └──────────┘                   │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP/JSON
┌─────────────────────────┴───────────────────────────────────┐
│                    Flask Web Server                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ /api/scan│  │/api/latest│ │/api/config│ │/api/device│    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    RF Scanner Module                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  WiFi    │  │Bluetooth │  │   OUI    │  │ Distance │    │
│  │ Scanner  │  │ Scanner  │  │  Lookup  │  │ Estimator│    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    System Tools                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
│  │    iw    │  │  bleak   │  │  SQLite  │                   │
│  │  (WiFi)  │  │  (BLE)   │  │(History) │                   │
│  └──────────┘  └──────────┘  └──────────┘                   │
└─────────────────────────────────────────────────────────────┘

Dependencies

System

Linux (tested on Raspberry Pi OS / Debian)
Python 3.11+
iw - WiFi scanning
hcitool / bluetoothctl - Bluetooth scanning
sudo access for RF scanning

Python

Flask - Web framework
PyYAML - Configuration
dataclasses - Data structures
bleak - BLE scanning with RSSI

Frontend

Leaflet.js - 2D maps
MapLibre GL JS - 3D maps
Vanilla JavaScript

Installation

cd ~/git/rf-mapper
python -m venv venv
source venv/bin/activate
pip install -e .

Quick Start

# Start web interface
rf-mapper web

# CLI scan
rf-mapper scan

# Open http://localhost:5000

Configuration

Config file: config.yaml

gps:
  latitude: 50.8585
  longitude: 4.3978

scanner:
  wifi_interface: wlan0
  bt_scan_timeout: 10
  path_loss_exponent: 2.5

building:
  enabled: true
  floors: 12
  current_floor: 11

Documentation

docs/INSTALL.md - Detailed installation
docs/USAGE.md - Usage guide
docs/CHEATSHEET.md - Quick reference
docs/API.md - REST API documentation

License

MIT License

6.1 KiB Raw Blame History