Files

User 98e2c6fc42 docs: update project docs for v1.0.0 release

- PROJECT.md: Add peer sync feature description and architecture
- ROADMAP.md: Update to v1.0.0, mark peer sync complete
- TASKS.md: Add peer sync completed tasks, update sprint
- TODO.md: Add multi-scanner section, mark items done
- CHANGELOG.md: Add v0.4.0 (HA) and v1.0.0 (peer sync) entries

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

2026-02-01 04:41:24 +01:00

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

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

Quick Start

# 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

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 - Detailed installation
docs/USAGE.md - Usage guide
docs/CHEATSHEET.md - Quick reference
docs/API.md - REST API documentation

License

MIT License

9.0 KiB Raw Blame History