Initial commit: RF Mapper v0.3.0-dev

WiFi & Bluetooth signal mapping tool for Raspberry Pi with:
- WiFi scanning via iw command
- Bluetooth Classic/BLE device discovery
- RSSI-based distance estimation
- OUI manufacturer lookup
- Web dashboard with multiple views:
  - Radar view (polar plot)
  - 2D Map (Leaflet/OpenStreetMap)
  - 3D Map (MapLibre GL JS with building extrusion)
- Floor-based device positioning
- Live BT tracking mode (auto-starts on page load)
- SQLite database for historical device tracking:
  - RSSI time-series history
  - Device statistics (avg/min/max)
  - Movement detection and velocity estimation
  - Activity patterns (hourly/daily)
  - New device alerts
  - Automatic data retention/cleanup
- REST API for all functionality

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

PROJECT.md

@@ -0,0 +1,137 @@
+# RF Mapper
+
+**WiFi & Bluetooth Signal Mapping Tool for Raspberry Pi**
+
+## Overview
+
+RF Mapper is a Python-based tool that scans, visualizes, and maps RF (Radio Frequency) signals from WiFi networks and Bluetooth devices. It provides a web-based dashboard with multiple visualization modes including radar view, 2D map, and 3D building view with floor-based positioning.
+
+## Problem Statement
+
+Understanding the RF environment around you is useful for:
+- Network troubleshooting and optimization
+- Security auditing (identifying rogue devices)
+- Asset tracking and device inventory
+- Indoor positioning research
+- Home automation device discovery
+
+## Key Features
+
+- **WiFi Scanning** - Discover networks with SSID, BSSID, RSSI, channel, encryption
+- **Bluetooth Scanning** - Classic BT and BLE device discovery with device type inference
+- **Distance Estimation** - RSSI-based distance calculation using log-distance path loss model
+- **OUI Lookup** - Manufacturer identification from MAC addresses
+- **Web Dashboard** - Real-time visualization with multiple views:
+  - Radar view (polar plot)
+  - 2D World Map (Leaflet/OpenStreetMap)
+  - 3D Building Map (MapLibre GL JS)
+- **Floor-based Positioning** - Assign devices to building floors
+- **Live Tracking** - Real-time Bluetooth tracking mode
+- **Auto-scan** - Scheduled background scanning
+- **Data Export** - JSON scan history with timestamps
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Web Browser                              │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │  Radar   │  │  2D Map  │  │  3D Map  │                   │
+│  │  View    │  │ (Leaflet)│  │(MapLibre)│                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────┬───────────────────────────────────┘
+                          │ HTTP/JSON
+┌─────────────────────────┴───────────────────────────────────┐
+│                    Flask Web Server                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+│  │ /api/scan│  │/api/latest│ │/api/config│ │/api/device│    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────┴───────────────────────────────────┐
+│                    RF Scanner Module                         │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+│  │  WiFi    │  │Bluetooth │  │   OUI    │  │ Distance │    │
+│  │ Scanner  │  │ Scanner  │  │  Lookup  │  │ Estimator│    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────┴───────────────────────────────────┐
+│                    System Tools                              │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │    iw    │  │ hcitool  │  │bluetoothctl│                  │
+│  │  (WiFi)  │  │   (BT)   │  │   (BLE)  │                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Dependencies
+
+### System
+- Linux (tested on Raspberry Pi OS / Debian)
+- Python 3.11+
+- `iw` - WiFi scanning
+- `hcitool` / `bluetoothctl` - Bluetooth scanning
+- `sudo` access for RF scanning
+
+### Python
+- Flask - Web framework
+- PyYAML - Configuration
+- dataclasses - Data structures
+
+### Frontend
+- Leaflet.js - 2D maps
+- MapLibre GL JS - 3D maps
+- Vanilla JavaScript
+
+## Installation
+
+```bash
+cd ~/git/rf-mapper
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Start web interface
+rf-mapper web
+
+# CLI scan
+rf-mapper scan
+
+# Open http://localhost:5000
+```
+
+## Configuration
+
+Config file: `config.yaml`
+
+```yaml
+gps:
+  latitude: 50.8585
+  longitude: 4.3978
+
+scanner:
+  wifi_interface: wlan0
+  bt_scan_timeout: 10
+  path_loss_exponent: 2.5
+
+building:
+  enabled: true
+  floors: 12
+  current_floor: 11
+```
+
+## Documentation
+
+- [docs/INSTALL.md](docs/INSTALL.md) - Detailed installation
+- [docs/USAGE.md](docs/USAGE.md) - Usage guide
+- [docs/CHEATSHEET.md](docs/CHEATSHEET.md) - Quick reference
+- [docs/API.md](docs/API.md) - REST API documentation
+
+## License
+
+MIT License