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

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

Quick Start

# Start web interface
rf-mapper web

# 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

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