rf-mapper/PROJECT.md

# 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
- **Home Assistant Integration** - Webhook-based presence tracking, new device alerts, departure notifications
- **Multi-Scanner Peer Sync** - Multiple scanner instances share device metadata automatically
  - Bidirectional sync with timestamp-based conflict resolution
  - Source scanner tracking (devices positioned relative to detecting scanner)
  - Peer scanner markers on 3D map

## 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) │                   │
│  └──────────┘  └──────────┘  └──────────┘                   │
└─────────────────────────┬───────────────────────────────────┘
                          │ Webhooks
┌─────────────────────────┴───────────────────────────────────┐
│                    Home Assistant                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ Scan Results │  │ New Device   │  │ Device Gone  │       │
│  │   Webhook    │  │   Webhook    │  │   Webhook    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    Peer Scanner Sync                         │
│  ┌──────────────┐            ┌──────────────┐               │
│  │   Scanner A  │◄── sync ──►│   Scanner B  │               │
│  │   (rpios)    │            │   (grokbox)  │               │
│  └──────────────┘            └──────────────┘               │
│         Shared: floors, labels, favorites, notes            │
└─────────────────────────────────────────────────────────────┘
```

## 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
- requests - HTTP client for webhooks

### 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 server (background)
rf-mapper start

# Check status
rf-mapper status

# CLI scan
rf-mapper scan

# Open http://localhost:5000
```

## Configuration

Config file: `config.yaml`

```yaml
gps:
  latitude: 50.8585
  longitude: 4.3978

scanner:
  id: rpios
  name: "RPi OS Scanner"
  wifi_interface: wlan0
  bt_scan_timeout: 10
  path_loss_exponent: 2.5
  sync_interval_seconds: 30
  accept_registrations: true

building:
  enabled: true
  floors: 12
  current_floor: 11

home_assistant:
  enabled: true
  url: http://192.168.129.10:8123
  webhook_scan: rf_mapper_scan
  webhook_new_device: rf_mapper_new_device
  webhook_device_gone: rf_mapper_device_gone
  device_timeout_minutes: 5
```

## 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