52df6421be
WiFi & Bluetooth signal mapping tool for Raspberry Pi with: - WiFi scanning via iw command - Bluetooth Classic/BLE device discovery - RSSI-based distance estimation - OUI manufacturer lookup - Web dashboard with multiple views: - Radar view (polar plot) - 2D Map (Leaflet/OpenStreetMap) - 3D Map (MapLibre GL JS with building extrusion) - Floor-based device positioning - Live BT tracking mode (auto-starts on page load) - SQLite database for historical device tracking: - RSSI time-series history - Device statistics (avg/min/max) - Movement detection and velocity estimation - Activity patterns (hourly/daily) - New device alerts - Automatic data retention/cleanup - REST API for all functionality Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
138 lines
6.1 KiB
Markdown
138 lines
6.1 KiB
Markdown
# 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 │ │ hcitool │ │bluetoothctl│ │
|
|
│ │ (WiFi) │ │ (BT) │ │ (BLE) │ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 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
|
|
|
|
### Frontend
|
|
- Leaflet.js - 2D maps
|
|
- MapLibre GL JS - 3D maps
|
|
- Vanilla JavaScript
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
cd ~/git/rf-mapper
|
|
python -m venv venv
|
|
source venv/bin/activate
|
|
pip install -e .
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Start web interface
|
|
rf-mapper web
|
|
|
|
# CLI scan
|
|
rf-mapper scan
|
|
|
|
# Open http://localhost:5000
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Config file: `config.yaml`
|
|
|
|
```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](docs/INSTALL.md) - Detailed installation
|
|
- [docs/USAGE.md](docs/USAGE.md) - Usage guide
|
|
- [docs/CHEATSHEET.md](docs/CHEATSHEET.md) - Quick reference
|
|
- [docs/API.md](docs/API.md) - REST API documentation
|
|
|
|
## License
|
|
|
|
MIT License
|