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

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    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘

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:
  wifi_interface: wlan0
  bt_scan_timeout: 10
  path_loss_exponent: 2.5

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