5eb5cd2351
- Popups now stay open during live BT tracking updates - Track open popup device ID and restore after marker refresh - Update TASKS.md, TODO.md, PROJECT.md, ROADMAP.md - Mark position smoothing, floor persistence as complete Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
141 lines
6.3 KiB
Markdown
141 lines
6.3 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** - BLE device discovery via bleak library with reliable RSSI
|
|
- **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 (persisted in database)
|
|
- **Live Tracking** - Real-time Bluetooth tracking (auto-starts, 4-second intervals)
|
|
- **Movement Detection** - Statistical analysis to detect moving devices (purple markers)
|
|
- **Historical Database** - SQLite storage for device history, RSSI time-series, statistics
|
|
- **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
|
|
- BlueZ/D-Bus - Bluetooth (via bleak library)
|
|
- `sudo` access for WiFi 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
|
|
|
|
```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
|