rf-mapper/USAGE.md

RF Mapper Usage Guide

RF Mapper is a WiFi and Bluetooth signal mapper for Linux. It scans nearby devices, estimates distances, and visualizes results in multiple views including radar, 2.5D, world map, and 3D map with building support.

Requirements

• Linux with WiFi and Bluetooth hardware
• Python 3.10+
• sudo access (required for scanning)
• System tools: iw, hcitool, bluetoothctl

Installation

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e .

Quick Start

# Activate venv
source venv/bin/activate

# Run interactive scan
rf-mapper

# Start web server
rf-mapper start

CLI Commands

Scanning

# Basic scan (interactive mode)
rf-mapper

# Scan with location label
rf-mapper scan -l kitchen

# Scan WiFi only
rf-mapper scan --no-bt

# Scan Bluetooth only
rf-mapper scan --no-wifi

# Use specific WiFi interface
rf-mapper scan -i wlan1

Visualization (CLI)

# Visualize latest scan (ASCII radar + charts)
rf-mapper visualize

# Visualize specific scan file
rf-mapper visualize -f data/scan_20240131_120000_kitchen.json

# Analyze RF environment
rf-mapper analyze

Scan History

# List saved scans
rf-mapper list

Web Server

# Start web server (background daemon)
rf-mapper start

# Start in foreground (for debugging)
rf-mapper start --foreground

# Custom host/port
rf-mapper start -H 127.0.0.1 -p 8080

# With debug mode
rf-mapper start --foreground --debug

# With request profiling
rf-mapper start --profile-requests

# With request logging
rf-mapper start --log-requests

# Stop the server
rf-mapper stop

# Restart the server
rf-mapper restart

# Check server status
rf-mapper status

Configuration

# Show current configuration
rf-mapper config

# Set GPS coordinates
rf-mapper config --set-gps 50.8585 4.3978 --save

Profiling

# Profile CPU usage
rf-mapper --profile scan

# Profile memory usage
rf-mapper --profile-memory scan

# Save profile to file
rf-mapper --profile --profile-output scan.prof scan

Web Interface Views

The web dashboard offers 3 visualization modes:

View	Description
Radar	Classic radar display with distance rings
World Map	Leaflet map with device markers on real geography
3D Map	MapLibre GL 3D view with building extrusion

Features

• Real-time scanning via "New Scan" button
• Auto-scan mode with configurable interval
• WiFi/Bluetooth filter toggles
• Floor filtering for multi-story buildings
• Click devices for detailed info popups
• Device lists with signal strength indicators

Configuration File

Configuration is loaded from (in order):

1. ./config.yaml
2. ~/.config/rf-mapper/config.yaml
3. /etc/rf-mapper/config.yaml

Example config.yaml

gps:
  latitude: 50.8585853
  longitude: 4.3978724

web:
  host: "0.0.0.0"
  port: 5000
  debug: false

scanner:
  wifi_interface: "wlan0"
  bt_scan_timeout: 10
  path_loss_exponent: 2.5
  auto_identify_bluetooth: true

data:
  directory: "data"
  max_scans: 100

building:
  enabled: false
  name: "My Building"
  floors: 3
  floor_height_m: 3.0
  ground_floor_number: 0

Environment Variables

Variable	Description
RF_MAPPER_LAT	Override GPS latitude
RF_MAPPER_LON	Override GPS longitude
RF_MAPPER_HOST	Override web server host
RF_MAPPER_PORT	Override web server port
HA_TOKEN	Home Assistant API token
HA_URL	Home Assistant URL

API Endpoints

The web server exposes a REST API:

Method	Endpoint	Description
POST	/api/scan	Trigger new scan
GET	/api/latest	Get most recent scan
GET	/api/scans	List all scans
GET	/api/scans/<filename>	Get specific scan
GET/POST	/api/position	Get/set GPS position
GET/POST	/api/config	Get/update configuration
GET/POST	/api/building	Get/update building config
POST	/api/device/<id>/floor	Assign floor to device
GET	/api/autoscan	Get auto-scan status
POST	/api/autoscan/start	Start auto-scanning
POST	/api/autoscan/stop	Stop auto-scanning
GET	/api/bluetooth/identify/<addr>	Identify BT device

Data Storage

Scan results are saved as JSON in the data directory:

• Default: ./data/
• Files: scan_YYYYMMDD_HHMMSS_<location>.json

Troubleshooting

"WiFi scan error: Operation not permitted"

Run with sudo or ensure your user has permissions:

sudo rf-mapper scan

"No Bluetooth adapter found"

Ensure Bluetooth is enabled:

sudo systemctl start bluetooth
sudo hciconfig hci0 up

Web interface shows no devices

1. Run a scan first: click "New Scan" or use CLI
2. Check if data directory has scan files
3. Verify filters aren't hiding devices

3D buildings not showing

• Zoom in to level 15+ for buildings to appear
• Not all areas have building data in OpenStreetMap
• The map style must support vector tiles with building data