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 (or Android via Termux)
- Python 3.10+
- `sudo` access (required for scanning on Linux)
- System tools: `iw`, `hcitool`, `bluetoothctl`

### Android/Termux Requirements

For running RF Mapper on Android via Termux:

| Requirement | Description |
|-------------|-------------|
| **Termux** | From F-Droid (NOT Play Store) |
| **Termux:API** | From F-Droid (same source as Termux) |
| **Termux:Boot** | Optional, for auto-start on boot |
| **termux-api package** | `pkg install termux-api` |
| **Location permission** | Grant to Termux:API app |
| **GPS enabled** | Enable Location in Android settings |

**Important:** All Termux apps must be from the same source (F-Droid recommended). Mixing Play Store and F-Droid versions causes API communication failures.

#### ADB Configuration for Android 12+

Android 12+ has a "phantom process killer" that terminates background processes. Disable it for stable Termux operation:

```bash
# Connect via ADB and run:
adb shell "settings put global settings_enable_monitor_phantom_procs false"
```

This setting persists across reboots but may reset after Android updates.

#### Verify Termux Prerequisites

```bash
# Check if all prerequisites are met
rf-mapper check-termux
```

Output shows status of each requirement:
```
==================================================
TERMUX ENVIRONMENT DETECTED
Checking prerequisites...
==================================================
  ✓ Termux:API package: OK
  ✓ Location services: OK (lat: 50.8585)
  ✓ Wake lock: OK (wake lock acquired)
  ✓ Termux:Boot: OK (boot directory exists)
==================================================
All prerequisites met. Starting RF Mapper...
```

#### Termux Boot Script

For auto-start on device boot, create `~/.termux/boot/start-rf-mapper.sh`:

```bash
#!/data/data/com.termux/files/usr/bin/bash
termux-wake-lock
cd ~/git/rf-mapper
source venv/bin/activate
rf-mapper start
```

Make it executable:
```bash
chmod +x ~/.termux/boot/start-rf-mapper.sh
```

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

# Check Termux prerequisites (Android only)
rf-mapper check-termux
```

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

### Termux: "Termux:API app not responding"
1. Ensure Termux:API is from F-Droid (not Play Store)
2. Grant all permissions to Termux:API in Android settings
3. Restart Termux after installing Termux:API

### Termux: Process killed in background
Android's phantom process killer terminates background processes. Fix:
```bash
adb shell "settings put global settings_enable_monitor_phantom_procs false"
```

### Termux: Location services failing
1. Enable GPS/Location in Android settings
2. Grant location permission to Termux:API
3. Test with: `termux-location -p passive`
4. Ensure you're outdoors or near windows for GPS signal

### Termux: Wake lock not working
1. Disable battery optimization for Termux in Android settings
2. Run `termux-wake-lock` before starting RF Mapper
3. The app acquires wake lock automatically on start