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

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

# Install dependencies
pip install -e .
```

## Quick Start

```bash
# Activate venv
source venv/bin/activate

# Run interactive scan
rf-mapper

# Start web server
rf-mapper start
```

## CLI Commands

### Scanning

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

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

```bash
# List saved scans
rf-mapper list
```

### Web Server

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

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

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

### Profiling

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

```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:
```bash
sudo rf-mapper scan
```

### "No Bluetooth adapter found"
Ensure Bluetooth is enabled:
```bash
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