rf-mapper/docs/CHEATSHEET.md

# RF Mapper Cheatsheet

Quick reference for RF Mapper commands and configuration.

---

## CLI Commands

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

---

## Web Server

```bash
# Lifecycle
rf-mapper start                  # Start (background daemon)
rf-mapper stop                   # Stop
rf-mapper restart                # Restart
rf-mapper status                 # Check if running

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

---

## Configuration Commands

```bash
# Show current config
rf-mapper config

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

---

## Profiling

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

---

## Common API Calls

```bash
# 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

```yaml
# 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)

```bash
sudo rf-mapper scan
```

### No Bluetooth adapter

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

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

### Database issues

```bash
# 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 |