# RF Mapper - Claude Context

RF Environment Scanner for WiFi and Bluetooth signal mapping on Linux.

## Key Documentation

- **[USAGE.md](USAGE.md)** - User guide with CLI commands, web interface, configuration, and API reference
- **[TODO.md](TODO.md)** - Pending features and improvements
- **[config.yaml](config.yaml)** - Current configuration (GPS, web server, scanner, building settings)

## Project Structure

```
src/rf_mapper/
├── __main__.py      # CLI entry point and argument parsing
├── scanner.py       # WiFi/Bluetooth scanning (WifiNetwork, BluetoothDevice dataclasses)
├── config.py        # Configuration management (Config, BuildingConfig, etc.)
├── database.py      # SQLite database for device history and tracking
├── distance.py      # RSSI to distance estimation
├── homeassistant.py # Home Assistant webhook integration
├── oui.py           # MAC address manufacturer lookup
├── bluetooth_*.py   # Bluetooth device identification and classification
├── visualize.py     # ASCII radar and chart generation
├── profiling.py     # CPU/memory profiling utilities
└── web/
    ├── app.py       # Flask application and API endpoints
    ├── templates/   # Jinja2 HTML templates (base.html, index.html)
    └── static/      # CSS, JS, vendor libraries (Leaflet, MapLibre GL)
```

## Key Files for Common Tasks

| Task | Files |
|------|-------|
| Add CLI command | `src/rf_mapper/__main__.py` |
| Add API endpoint | `src/rf_mapper/web/app.py` |
| Modify data model | `src/rf_mapper/scanner.py`, `config.py` |
| Change web UI | `web/templates/index.html`, `static/js/app.js`, `static/css/style.css` |
| Add configuration | `src/rf_mapper/config.py`, `config.yaml` |
| Home Assistant integration | `src/rf_mapper/homeassistant.py`, `docs/HOME_ASSISTANT.md` |

## Running

```bash
source venv/bin/activate
rf-mapper start        # Start web server (background)
rf-mapper status       # Check if running
rf-mapper stop         # Stop server
rf-mapper scan -l room # CLI scan
rf-mapper --help       # All commands
```

## Tech Stack

- Python 3.10+, Flask, PyYAML, requests
- Leaflet.js (2D maps), MapLibre GL JS (3D maps)
- Linux tools: `iw`, bleak (BLE via D-Bus)
- SQLite for device history
- Home Assistant webhooks for integration