rf-mapper/docs/CHEATSHEET.md

RF Mapper Cheatsheet

Quick reference for RF Mapper commands and configuration.

---

CLI Commands

All commands require activating the virtual environment first:

source venv/bin/activate

Command	Description
python -m rf_mapper	Interactive scan mode
python -m rf_mapper scan	Run scan with defaults
python -m rf_mapper scan -l kitchen	Scan with location label
python -m rf_mapper scan --no-bt	WiFi only
python -m rf_mapper scan --no-wifi	Bluetooth only
python -m rf_mapper visualize	ASCII radar display
python -m rf_mapper analyze	RF environment analysis
python -m rf_mapper list	List saved scans
python -m rf_mapper start	Start web server (background)
python -m rf_mapper stop	Stop web server
python -m rf_mapper restart	Restart web server
python -m rf_mapper status	Check if server is running
python -m rf_mapper config	Show configuration

---

Web Server

# Lifecycle
python -m rf_mapper start                  # Start (background daemon)
python -m rf_mapper stop                   # Stop
python -m rf_mapper restart                # Restart
python -m rf_mapper status                 # Check if running

# Start options
python -m rf_mapper start -f               # Foreground mode
python -m rf_mapper start -H 127.0.0.1     # Bind to localhost only
python -m rf_mapper start -p 8080          # Custom port
python -m rf_mapper start --debug          # Debug mode (requires -f)
python -m rf_mapper start --profile-requests # Per-request profiling
python -m rf_mapper start --log-requests   # Request logging

---

Configuration Commands

# Show current config
python -m rf_mapper config

# Set GPS coordinates
python -m rf_mapper config --set-gps 50.8585 4.3978 --save

---

Profiling

rf-mapper --profile scan              # CPU profiling
rf-mapper --profile-memory scan       # Memory profiling
rf-mapper --profile --profile-output scan.prof scan

---

Common API Calls

# Trigger scan
curl -X POST http://localhost:5000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"location": "office"}'

# Get latest scan
curl http://localhost:5000/api/latest

# Quick BT scan (real-time tracking)
curl -X POST http://localhost:5000/api/scan/bt

# List scans
curl http://localhost:5000/api/scans

# Get auto-scan status
curl http://localhost:5000/api/autoscan

# Start auto-scan
curl -X POST http://localhost:5000/api/autoscan/start \
  -H "Content-Type: application/json" \
  -d '{"interval_minutes": 5}'

# Stop auto-scan
curl -X POST http://localhost:5000/api/autoscan/stop

# Set device floor
curl -X POST http://localhost:5000/api/device/AA:BB:CC:DD:EE:FF/floor \
  -H "Content-Type: application/json" \
  -d '{"floor": 2}'

# Get all floor assignments
curl http://localhost:5000/api/device/floors

# Get device history
curl "http://localhost:5000/api/history/devices?type=bluetooth&limit=20"

# Get RSSI history for device
curl http://localhost:5000/api/history/devices/AA:BB:CC:DD:EE:FF/rssi

# Get database stats
curl http://localhost:5000/api/history/stats

---

Config File Locations

Checked in order:

1. ./config.yaml (project directory)
2. ~/.config/rf-mapper/config.yaml
3. /etc/rf-mapper/config.yaml

---

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

---

Key Config Options

# GPS position
gps:
  latitude: 50.8585
  longitude: 4.3978

# Web server
web:
  host: "0.0.0.0"
  port: 5000
  debug: false

# Scanner settings
scanner:
  wifi_interface: "wlan0"
  bt_scan_timeout: 10
  path_loss_exponent: 2.5  # 2.0=open, 2.5=indoor, 3.5=walls
  auto_identify_bluetooth: true

# Data storage
data:
  directory: "data"
  max_scans: 100

# Database
database:
  enabled: true
  filename: "devices.db"
  retention_days: 30
  auto_cleanup: true

# Building (3D view)
building:
  enabled: true
  floors: 3
  floor_height_m: 3.0
  current_floor: 1

---

Data Locations

Path	Content
data/	Scan JSON files
data/devices.db	SQLite database
data/profiles/	Request profiles
data/logs/	Request logs

---

Troubleshooting

Permission denied (WiFi/BT)

sudo rf-mapper scan

No Bluetooth adapter

sudo systemctl start bluetooth
sudo hciconfig hci0 up

No RSSI from Bluetooth

The app uses bleak library for BLE scanning. Ensure:

• BlueZ service running: systemctl status bluetooth
• D-Bus available
• Bluetooth adapter powered on

Check WiFi interface

iw dev                    # List interfaces
sudo iw dev wlan0 scan    # Test scan

Database issues

# Check database
sqlite3 data/devices.db ".tables"
sqlite3 data/devices.db "SELECT COUNT(*) FROM devices"

# Manual cleanup
curl -X POST http://localhost:5000/api/history/cleanup \
  -H "Content-Type: application/json" \
  -d '{"retention_days": 7}'

---

Web Interface Views

View	Description	Best For
Radar	Distance rings	Quick overview
World Map	Leaflet 2D	Geographic context
3D Map	MapLibre GL	Building/floor view

Keyboard Shortcuts (Web UI)

Key	Action
R	Refresh scan
1	Radar view
2	World map view
3	3D map view

---

Signal Quality Reference

RSSI Range	Quality	Est. Distance
-30 to -50	Excellent	< 2m
-50 to -60	Good	2-5m
-60 to -70	Fair	5-10m
-70 to -80	Weak	10-20m
< -80	Poor	> 20m

---

Path Loss Exponent Guide

Value	Environment
2.0	Free space (outdoor)
2.5	Light indoor (open plan)
3.0	Normal indoor
3.5	Dense indoor (walls)
4.0+	Heavy obstructions