feat: add Home Assistant integration and improve CLI/UI
Home Assistant Integration: - New homeassistant.py module with webhook support - Webhooks for scan results, new devices, and device departures - Absence detection with configurable timeout - Documentation in docs/HOME_ASSISTANT.md CLI Improvements: - Replace 'web' command with start/stop/restart/status - Background daemon mode with PID file management - Foreground mode for debugging (--foreground) Web UI Enhancements: - Improved device list styling and layout - Better floor assignment UI - Enhanced map visualization Documentation: - Add CHANGELOG.md - Add docs/API.md with full endpoint reference - Add docs/CHEATSHEET.md for quick reference - Update project documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
User
277
docs/CHEATSHEET.md
Normal file
277
docs/CHEATSHEET.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# RF Mapper Cheatsheet
|
||||
|
||||
Quick reference for RF Mapper commands and configuration.
|
||||
|
||||
---
|
||||
|
||||
## CLI Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `rf-mapper` | Interactive scan mode |
|
||||
| `rf-mapper scan` | Run scan with defaults |
|
||||
| `rf-mapper scan -l kitchen` | Scan with location label |
|
||||
| `rf-mapper scan --no-bt` | WiFi only |
|
||||
| `rf-mapper scan --no-wifi` | Bluetooth only |
|
||||
| `rf-mapper visualize` | ASCII radar display |
|
||||
| `rf-mapper analyze` | RF environment analysis |
|
||||
| `rf-mapper list` | List saved scans |
|
||||
| `rf-mapper start` | Start web server (background) |
|
||||
| `rf-mapper stop` | Stop web server |
|
||||
| `rf-mapper restart` | Restart web server |
|
||||
| `rf-mapper status` | Check if server is running |
|
||||
| `rf-mapper config` | Show configuration |
|
||||
|
||||
---
|
||||
|
||||
## Web Server
|
||||
|
||||
```bash
|
||||
# Lifecycle
|
||||
rf-mapper start # Start (background daemon)
|
||||
rf-mapper stop # Stop
|
||||
rf-mapper restart # Restart
|
||||
rf-mapper status # Check if running
|
||||
|
||||
# Start options
|
||||
rf-mapper start -f # Foreground mode
|
||||
rf-mapper start -H 127.0.0.1 # Bind to localhost only
|
||||
rf-mapper start -p 8080 # Custom port
|
||||
rf-mapper start --debug # Debug mode (requires -f)
|
||||
rf-mapper start --profile-requests # Per-request profiling
|
||||
rf-mapper start --log-requests # Request logging
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Commands
|
||||
|
||||
```bash
|
||||
# Show current config
|
||||
rf-mapper config
|
||||
|
||||
# Set GPS coordinates
|
||||
rf-mapper config --set-gps 50.8585 4.3978 --save
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Profiling
|
||||
|
||||
```bash
|
||||
rf-mapper --profile scan # CPU profiling
|
||||
rf-mapper --profile-memory scan # Memory profiling
|
||||
rf-mapper --profile --profile-output scan.prof scan
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common API Calls
|
||||
|
||||
```bash
|
||||
# Trigger scan
|
||||
curl -X POST http://localhost:5000/api/scan \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"location": "office"}'
|
||||
|
||||
# Get latest scan
|
||||
curl http://localhost:5000/api/latest
|
||||
|
||||
# Quick BT scan (real-time tracking)
|
||||
curl -X POST http://localhost:5000/api/scan/bt
|
||||
|
||||
# List scans
|
||||
curl http://localhost:5000/api/scans
|
||||
|
||||
# Get auto-scan status
|
||||
curl http://localhost:5000/api/autoscan
|
||||
|
||||
# Start auto-scan
|
||||
curl -X POST http://localhost:5000/api/autoscan/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"interval_minutes": 5}'
|
||||
|
||||
# Stop auto-scan
|
||||
curl -X POST http://localhost:5000/api/autoscan/stop
|
||||
|
||||
# Set device floor
|
||||
curl -X POST http://localhost:5000/api/device/AA:BB:CC:DD:EE:FF/floor \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"floor": 2}'
|
||||
|
||||
# Get all floor assignments
|
||||
curl http://localhost:5000/api/device/floors
|
||||
|
||||
# Get device history
|
||||
curl "http://localhost:5000/api/history/devices?type=bluetooth&limit=20"
|
||||
|
||||
# Get RSSI history for device
|
||||
curl http://localhost:5000/api/history/devices/AA:BB:CC:DD:EE:FF/rssi
|
||||
|
||||
# Get database stats
|
||||
curl http://localhost:5000/api/history/stats
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Config File Locations
|
||||
|
||||
Checked in order:
|
||||
|
||||
1. `./config.yaml` (project directory)
|
||||
2. `~/.config/rf-mapper/config.yaml`
|
||||
3. `/etc/rf-mapper/config.yaml`
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
||||
---
|
||||
|
||||
## Key Config Options
|
||||
|
||||
```yaml
|
||||
# GPS position
|
||||
gps:
|
||||
latitude: 50.8585
|
||||
longitude: 4.3978
|
||||
|
||||
# Web server
|
||||
web:
|
||||
host: "0.0.0.0"
|
||||
port: 5000
|
||||
debug: false
|
||||
|
||||
# Scanner settings
|
||||
scanner:
|
||||
wifi_interface: "wlan0"
|
||||
bt_scan_timeout: 10
|
||||
path_loss_exponent: 2.5 # 2.0=open, 2.5=indoor, 3.5=walls
|
||||
auto_identify_bluetooth: true
|
||||
|
||||
# Data storage
|
||||
data:
|
||||
directory: "data"
|
||||
max_scans: 100
|
||||
|
||||
# Database
|
||||
database:
|
||||
enabled: true
|
||||
filename: "devices.db"
|
||||
retention_days: 30
|
||||
auto_cleanup: true
|
||||
|
||||
# Building (3D view)
|
||||
building:
|
||||
enabled: true
|
||||
floors: 3
|
||||
floor_height_m: 3.0
|
||||
current_floor: 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Locations
|
||||
|
||||
| Path | Content |
|
||||
|------|---------|
|
||||
| `data/` | Scan JSON files |
|
||||
| `data/devices.db` | SQLite database |
|
||||
| `data/profiles/` | Request profiles |
|
||||
| `data/logs/` | Request logs |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Permission denied (WiFi/BT)
|
||||
|
||||
```bash
|
||||
sudo rf-mapper scan
|
||||
```
|
||||
|
||||
### No Bluetooth adapter
|
||||
|
||||
```bash
|
||||
sudo systemctl start bluetooth
|
||||
sudo hciconfig hci0 up
|
||||
```
|
||||
|
||||
### No RSSI from Bluetooth
|
||||
|
||||
The app uses `bleak` library for BLE scanning. Ensure:
|
||||
- BlueZ service running: `systemctl status bluetooth`
|
||||
- D-Bus available
|
||||
- Bluetooth adapter powered on
|
||||
|
||||
### Check WiFi interface
|
||||
|
||||
```bash
|
||||
iw dev # List interfaces
|
||||
sudo iw dev wlan0 scan # Test scan
|
||||
```
|
||||
|
||||
### Database issues
|
||||
|
||||
```bash
|
||||
# Check database
|
||||
sqlite3 data/devices.db ".tables"
|
||||
sqlite3 data/devices.db "SELECT COUNT(*) FROM devices"
|
||||
|
||||
# Manual cleanup
|
||||
curl -X POST http://localhost:5000/api/history/cleanup \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"retention_days": 7}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Web Interface Views
|
||||
|
||||
| View | Description | Best For |
|
||||
|------|-------------|----------|
|
||||
| Radar | Distance rings | Quick overview |
|
||||
| World Map | Leaflet 2D | Geographic context |
|
||||
| 3D Map | MapLibre GL | Building/floor view |
|
||||
|
||||
### Keyboard Shortcuts (Web UI)
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `R` | Refresh scan |
|
||||
| `1` | Radar view |
|
||||
| `2` | World map view |
|
||||
| `3` | 3D map view |
|
||||
|
||||
---
|
||||
|
||||
## Signal Quality Reference
|
||||
|
||||
| RSSI Range | Quality | Est. Distance |
|
||||
|------------|---------|---------------|
|
||||
| -30 to -50 | Excellent | < 2m |
|
||||
| -50 to -60 | Good | 2-5m |
|
||||
| -60 to -70 | Fair | 5-10m |
|
||||
| -70 to -80 | Weak | 10-20m |
|
||||
| < -80 | Poor | > 20m |
|
||||
|
||||
---
|
||||
|
||||
## Path Loss Exponent Guide
|
||||
|
||||
| Value | Environment |
|
||||
|-------|-------------|
|
||||
| 2.0 | Free space (outdoor) |
|
||||
| 2.5 | Light indoor (open plan) |
|
||||
| 3.0 | Normal indoor |
|
||||
| 3.5 | Dense indoor (walls) |
|
||||
| 4.0+ | Heavy obstructions |
|
||||
Reference in New Issue
Block a user