rf-mapper/CLAUDE.md

RF Mapper - Claude Context

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

Key Documentation (Maintain These!)

File	Purpose	When to Update
TASKS.md	Current sprint tasks, priorities (P0-P3), status	Start/end of each work session
TODO.md	Backlog by category, completed items	When adding/completing features
ROADMAP.md	Version milestones, long-term vision	When milestones change
CHANGELOG.md	Version history, notable changes	Each release
PROJECT.md	Goals, architecture, dependencies	Major architectural changes
USAGE.md	User guide, CLI, web interface, API	When adding features
docs/CHEATSHEET.md	Quick reference commands	When adding features
INVENTORY.md	Multi-node deployment info (gitignored)	When nodes change

Configuration

• config.yaml - Current configuration (GPS, web server, scanner, building settings)
• docs/HOME_ASSISTANT.md - Home Assistant webhook integration

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
├── termux.py        # Termux/Android environment detection
├── sync.py          # Multi-scanner peer sync
└── 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
Multi-scanner sync	src/rf_mapper/sync.py, web/app.py
Termux/Android support	src/rf_mapper/termux.py

Running

source venv/bin/activate
python -m rf_mapper start        # Start web server (background)
python -m rf_mapper status       # Check if running
python -m rf_mapper stop         # Stop server
python -m rf_mapper restart      # Restart server
python -m rf_mapper scan -l room # CLI scan
python -m rf_mapper --help       # All commands

Deployment

See INVENTORY.md for multi-node deployment details.

# Update and restart all nodes
cd ~/git/rf-mapper && source venv/bin/activate && git pull && python -m rf_mapper restart
ssh grokbox "cd ~/git/rf-mapper && source venv/bin/activate && git pull && python -m rf_mapper restart"
ssh jellystar "cd ~/git/rf-mapper && source venv/bin/activate && git pull && python -m rf_mapper restart"

Tech Stack

• Python 3.10+, Flask, PyYAML, requests, bleak
• 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