diff --git a/USAGE.md b/USAGE.md index 02f7745..e4aa8e7 100644 --- a/USAGE.md +++ b/USAGE.md @@ -281,6 +281,131 @@ The web server exposes a REST API: | POST | `/api/autoscan/stop` | Stop auto-scanning | | GET | `/api/bluetooth/identify/` | Identify BT device | +## Multi-Node Master Dashboard + +RF Mapper supports a multi-node architecture where one designated "master" node can view and control scanning on peer nodes without page redirects. + +### Architecture Overview + +``` +┌─────────────────────────────────────────────────────────┐ +│ Master Node (rpios) │ +│ ┌───────────────────────────────────────────────────┐ │ +│ │ Node Selector: [📍 rpios ▼] │ │ +│ │ ├─ 📍 rpios (local) │ │ +│ │ ├─ 📡 grokbox │ │ +│ │ └─ 📡 jellystar │ │ +│ └───────────────────────────────────────────────────┘ │ +│ │ │ │ │ +│ [Radar] [3D Map] [Device Lists] │ +└─────────────────────────────────────────────────────────┘ + │ + ┌────────────────┼────────────────┐ + ▼ ▼ ▼ + grokbox:5000 jellystar:5000 (local) +``` + +### Enabling Master Mode + +Set `is_master: true` in `config.yaml` on the master node: + +```yaml +scanner: + id: 'rpios' + name: 'Master Scanner' + is_master: true # Enable master dashboard features + peers: [] # Peers auto-register via API + accept_registrations: true +``` + +Peer nodes do NOT need this flag (defaults to `false`). + +### Node Selector + +When `is_master: true` and peers are registered, a node selector dropdown appears in the header: + +| Indicator | Meaning | +|-----------|---------| +| 📍 | Local scanner (this node) | +| 📡 | Peer scanner (remote node) | +| ● (green) | Connected and responding | +| ● (yellow) | Connecting/loading | +| ○ (red) | Peer unreachable | + +### Switching Between Nodes + +1. Click the node selector dropdown +2. Select a peer node (e.g., "📡 grokbox") +3. Dashboard recenters on peer's GPS location +4. Device lists show peer's scanned devices +5. WebSocket connects to peer for real-time updates + +When viewing a peer: +- Map centers on peer's coordinates +- Radar shows devices relative to peer +- "New Scan" triggers scan on peer node +- Live tracking runs scans on peer + +### Live Tracking on Remote Nodes + +Live tracking works across nodes: + +1. Select a peer from node selector +2. Enable "Live BT Track" toggle +3. Scans run on the selected peer (not locally) +4. Results stream back via WebSocket +5. Map updates in real-time with peer's devices + +### Proxy API Endpoints + +The master node provides proxy endpoints to access peer data: + +| Endpoint | Description | +|----------|-------------| +| `/api/node//latest` | Get latest scan from peer | +| `/api/node//scan/bt` | Trigger BT scan on peer | +| `/api/node//device/floors` | Get device floor assignments | +| `/api/node//positions/trilaterated` | Get trilaterated positions | + +Example: +```bash +# Get grokbox's latest scan via master +curl http://rpios:5000/api/node/grokbox/latest | jq + +# Trigger BT scan on grokbox +curl -X POST http://rpios:5000/api/node/grokbox/scan/bt +``` + +### Peer Registration + +Peers register with the master automatically or manually: + +```bash +# Manual registration from peer +curl -X POST http://rpios:5000/api/peers/register \ + -H "Content-Type: application/json" \ + -d '{ + "id": "grokbox", + "name": "Grokbox Scanner", + "url": "http://grokbox:5000", + "latitude": 50.858495, + "longitude": 4.397614, + "floor": 11 + }' + +# List registered peers +curl http://rpios:5000/api/peers | jq '.peers' +``` + +### WebSocket Peer Connections + +When viewing a peer node, the dashboard: + +1. Disconnects from local WebSocket +2. Connects to peer's WebSocket at `peer_url/ws/scan` +3. Receives real-time scan updates from peer +4. Falls back to HTTP polling if WebSocket fails + ## Data Storage Scan results are saved as JSON in the data directory: @@ -333,3 +458,21 @@ adb shell "settings put global settings_enable_monitor_phantom_procs false" 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 + +### Master Dashboard: Node selector not appearing +1. Verify `is_master: true` in config.yaml +2. Restart rf-mapper: `rf-mapper restart` +3. Check peers are registered: `curl http://localhost:5000/api/peers | jq '.peers | length'` +4. At least one peer must be registered for selector to appear + +### Master Dashboard: Peer shows red status +1. Check peer is running: `curl http://peer:5000/api/peers` +2. Check network connectivity: `ping peer` +3. Check firewall allows port 5000 +4. Re-register peer if needed (see Peer Registration above) + +### Master Dashboard: WebSocket to peer fails +1. Check peer WebSocket endpoint: `curl http://peer:5000/socket.io/` +2. Browser console shows connection errors +3. Falls back to HTTP polling automatically +4. Ensure peer is running with WebSocket support enabled