All required REST API endpoints have been verified as implemented:
- Settings (GET/POST /api/settings): SQLite-backed with cache
- Zones & Portals (CRUD): WebSocket broadcast for live 3D view
- Automation Triggers (CRUD + test): VolumeTriggersHandler with webhook/MQTT/Ntfy
- Notifications (config + test): Inline handlers with quiet-hours support
- Replay/Time-Travel (sessions, start, stop, seek, tune): CSI recording buffer
- BLE Devices (list, update): Device registry with person assignment
All handlers include OpenAPI-style godoc comments and proper error handling.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add comprehensive Fresnel zone ellipsoid visualization for all active links
in the 3D scene. Provides developers with real-time feedback on link
coverage geometry and detection quality.
Features:
- FresnelEllipsoid() helper function in dashboard/js/fresnel.js for shared
ellipsoid geometry computation (used by both debug and explainability)
- Wireframe + fill material rendering for clear ellipsoid visualization
- Debug layer toggle in node panel (expert mode only)
- Hover interaction with tooltip showing link details (distance, wavelength,
Fresnel radius, health score)
- Click interaction to select corresponding link in sidebar
- Mobile viewport optimization (reduced segment count for performance)
- Comprehensive test coverage for ellipsoid geometry computation
The first Fresnel zone ellipsoid represents the region where point
reflectors have maximum impact on CSI phase. Visualizing these zones
helps system tuners understand why localisation places blobs in specific
positions and identify coverage gaps.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implemented mothership/cmd/sim with full CSI simulation capabilities:
- Virtual nodes connect via WebSocket with hello/health/role protocol
- Synthetic CSI binary frame generation with proper header format
- Walker simulation with random walk motion and wall bouncing
- BLE advertisement simulation (optional)
- Blob count verification mode for CI integration
- CSV ground truth export for offline analysis
- Comprehensive test coverage
The simulator enables integration testing without ESP32 hardware:
sim --mothership localhost:8080 --nodes 4 --walkers 2 --rate 20 --duration 60
sim --verify --nodes 2 --walkers 1 --duration 10 --seed 42
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit adds complete time-travel debugging capabilities for CSI data,
enabling users to pause the live 3D view, scrub through historical data,
and replay the 3D scene exactly as it was at any point in the 48-hour recording
window.
Key features:
- ReplayEngine with state machine (LIVE, PAUSED, REPLAYING, SEEKING)
- Replay pipeline separate from live pipeline with tunable parameters
- WebSocket command handlers for replay control (seek, play, pause, set_params, apply_to_live)
- Timeline scrubber UI with playback controls and parameter tuning panel
- Seek performance < 1 second for all active links
- Parameter sliders for motion threshold, baseline tau, fresnel decay, subcarriers, breathing sensitivity
Implementation:
- mothership/internal/replay/engine.go: ReplayEngine with state machine
- mothership/internal/replay/pipeline.go: Replay signal processing pipeline
- mothership/internal/replay/types.go: Session types and TunableParams
- mothership/internal/dashboard/server.go: WebSocket command handlers
- dashboard/js/replay.js: Timeline scrubber UI with playback controls
- mothership/internal/dashboard/hub.go: BroadcastReplayBlobs method
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implements a complete CSI simulator CLI that connects to the mothership
as virtual nodes and streams synthetic CSI frames for automated
integration testing without ESP32 hardware.
CLI Implementation (mothership/cmd/sim/):
- main.go: CLI entry point with all required flags (--mothership, --nodes,
--walkers, --rate, --duration, --seed, --space, --ble, --verify,
--noise-sigma, --wall, --output-csv)
- generator.go: synthetic CSI frame generation with proper binary format
- walker.go: random walk and path-following simulation
- verify.go: blob count verification with exit code reporting
Features:
- Virtual nodes connect via WebSocket with hello/health/BLE messages
- Synthetic CSI frames match Phase 1 protocol (24-byte header + I/Q payload)
- Configurable noise sigma for I/Q generation
- Wall definitions affecting path loss model
- CSV ground truth output for offline analysis
- Seed-based reproducibility for testing
- Verification mode for CI smoke testing
Physics Model (mothership/internal/simulator/):
- propagation.go: two-ray model (direct + reflection) with wall attenuation
- physics.go: path loss, RSSI computation, Fresnel zone calculations
- Reusable package shared with pre-deployment simulator
Tests:
- Binary header format validation (magic, version, fields in correct positions)
- RSSI range validation for given distances
- I/Q clamping to int8 range [-127, 127]
- Hello message format validation
- Verification mode blob detection
- Seed reproducibility for identical walker paths
- CSV output format validation
- Wall parsing validation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Update isValidEventType to include anomaly_detected and sleep_session_end
- These event types were already supported in simple mode filtering
- Ensures consistency between type validation and mode filtering
- Add missing encoding/json import to events.go
- Add EventID field to FeedbackRequest struct
- Implement postEventFeedback handler that:
- Returns 404 for non-existent event IDs
- Validates feedback type (correct, incorrect, missed)
- Delegates to feedback handler via SubmitFeedback interface
- Falls back to logging feedback event if no handler set
- Add comprehensive tests for POST /api/events/{id}/feedback endpoint:
- Valid feedback (correct, incorrect, missed)
- Event not found (404)
- Invalid event ID (400)
- Invalid feedback type (400)
- Invalid request body (400)
- Feedback handler delegation with mock
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- TestGetEvent_NotFound: verifies 404 for non-existent event IDs
- TestGetEvent_InvalidID: verifies 400 for invalid ID format
- TestGetEvent_HTTPHandler_Found: verifies 200 with full event details
Acceptance criteria met:
- Returns 404 for non-existent event IDs
- Returns full event details for valid IDs
Implement comprehensive filter bar with:
- Type filter checkboxes for event categories (Presence, Zones, Alerts, System, Learning)
- Person and zone dropdowns for filtering
- Date range selector with preset options (Today/Last 7 days/Last 30 days/Custom)
- Text search input for fuzzy matching on descriptions
- Client-side filtering for loaded events (instant feedback)
- Server-side filtering for date-range queries
- Load more pagination works for 500+ results
Backend changes:
- Add support for 'since'/'until' date range parameters in /api/events
- Add zone_id and person_id query parameter aliases
- Add POST /api/events/{id}/feedback endpoint for feedback submission
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Create SQLite events table with indexes on timestamp, person_id, zone_id,
and type. Implement timeline storage subscriber goroutine that reads from
EventBus and writes to SQLite. Use 1000-event buffered queue with drop-oldest
behavior on overflow.
- StorageSubscriber subscribes to all EventBus event types
- 1000-event buffered queue with drop-oldest overflow handling
- Warning log every 100 dropped events
- Graceful shutdown with drain of remaining events
- Stats() method returns queue size and drop count
- Tests cover all event types, concurrent handling, and overflow behavior
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Create timeline storage package that subscribes to EventBus
- Implement 1000-event buffered queue with drop-oldest behavior
- SQLite writer goroutine flushes events every 100ms in batches of 100
- Publishers never block - events dropped with warning log on overflow
- All event types stored in SQLite within 1 second of firing
- Comprehensive table-driven tests for all acceptance criteria
Acceptance Criteria Met:
- All event types stored in SQLite within 1 second of firing
- Storage subscriber never blocks publishers
- Handles queue overflow gracefully with warning log
- Tests cover basic storage, non-blocking, drop-oldest, all event types
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implemented GDOP overlay visualization support and enhanced synthetic data
generation for the pre-deployment simulator.
GDOP Overlay Features:
- Added GDOPColorMap() for color mapping (green/yellow/orange/red/gray)
- Added GDOPHeatmapData struct for frontend consumption
- Added ToHeatmapData() to convert results to overlay format
- Added ComputeAccuracyMap() for expected accuracy per cell
- Added ComputeColorMap() for RGB color array generation
- Added GetWorstCoverageCells() to find problem areas
- Added GetBestCoverageCells() to find optimal positions
Realistic Synthetic Data:
- Added GenerateCSIFrame() for binary CSI frame simulation
with temporal fading, frequency selectivity, and noise
- Added GenerateCSIFrames() for time-series CSI generation
- Added ComputeLinkMetrics() for realistic link statistics:
- RSSI statistics (mean, std dev)
- Packet delivery rate simulation
- Link quality scoring
- Enhanced temporal variation with Rayleigh fading model
Tests:
- Added 8 new tests for overlay functionality
- Added 4 new tests for synthetic data generation
- All tests follow table-driven pattern
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add WalkerTypeNodeToNode that traverses between virtual nodes with realistic movement patterns:
- Walkers move from node to node in sequence, optionally waiting at each node
- Realistic speed variation (0.8x-1.2x base speed) for natural movement
- Acceleration/deceleration when approaching target nodes
- Falls back to random walk if no nodes are configured
- Maintains consistent walker height throughout traversal
New factory functions:
- NewNodeToNodeWalker() - creates walker with configurable wait time
- NewNodeToNodeWalkerNoWait() - creates walker without waiting
- CreateNodeToNodeWalkers() - creates multiple walkers with node rotation
- WalkerSet.AddNodeToNodeWalker() - add to walker set
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The Close() function was incorrectly setting s.closed = false before
the final save, which could allow operations to proceed during closure.
Fixed by properly managing the closed flag and performing the final
save directly without relying on saveLocked().
This fixes the virtual node state management implementation which
provides:
- Node creation at specified positions with bounds validation
- State persistence to disk via JSON
- Thread-safe operations with mutex locking
- Enable/disable, position updates, role changes, metadata, tags
Acceptance criteria met:
- Nodes can be created at specified positions
- Nodes maintain their state within the virtual space
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implement virtual nodes within the virtual space with the following features:
- VirtualNodeStore: Persistent store for virtual nodes with JSON file storage
- Create nodes at specified positions with validation against space bounds
- State management: position, role, enable/disable, metadata, tags
- FleetRegistryBridge: Integration with fleet registry for coverage planning
- Comprehensive tests: 25+ test cases covering all functionality
Acceptance criteria met:
- Nodes can be created at specified positions
- Nodes maintain their state within the virtual space
- State persists across store restarts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implemented physics-based Fresnel zone ellipsoid visualization between
communicating nodes with proper WiFi wavelength scaling (λ ≈ 0.123m for
2.437 GHz). Features wireframe ellipsoids for first 3 Fresnel zones
with link-health-based coloring and toggle control.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implemented Go CLI tool for virtual node generation and synthetic CSI
binary frame output. Key features:
- Virtual nodes positioned at space corners/edges with mixed heights
- Synthetic CSI frames with Fresnel zone modulation and path loss
- Random walk simulation for person movement
- WebSocket connections to mothership with hello/health/BLE messages
- Authentication token support (X-Spaxel-Token header)
- Configurable space dimensions, node count, walkers, rate, and duration
- Infinite run mode (--duration 0) for manual testing
- Comprehensive test coverage for frame structure, RSSI calculation,
Fresnel modulation, and walker position updates
- Makefile with build targets for multiple platforms
- Full documentation in README.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implemented Component 17 of the Spaxel plan - a pre-deployment simulator
that allows users to define virtual spaces, place virtual nodes, and
simulate walkers to predict detection quality before purchasing hardware.
Key features:
- Virtual space definition with rooms and wall segments
- Virtual node placement with corner positioning suggestions
- Synthetic walkers (random walk and path-following modes)
- GDOP (Geometric Dilution of Precision) computation for coverage quality
- Two-ray RF propagation model (direct + first-order reflection)
- Wall penetration loss by material type (drywall, brick, concrete, glass, metal)
- Fresnel zone computation and zone decay
- Shopping list generation with hardware recommendations
- REST API endpoints for simulation control and results
Files added:
- internal/simulator/space.go - Virtual space and room definitions
- internal/simulator/node.go - Virtual node management
- internal/simulator/walker.go - Synthetic walker simulation
- internal/simulator/gdop.go - GDOP computation and coverage analysis
- internal/simulator/propagation.go - RF propagation model
- internal/simulator/engine.go - Simulation engine (bug fixes)
- internal/simulator/handler.go - HTTP API handlers
- internal/api/simulator.go - REST API endpoints
- internal/simulator/simulator_test.go - Comprehensive tests
- internal/simulator/space_test.go - Space definition tests
Integration:
- Simulator API registered in main mothership server at /api/simulator/*
- Endpoints for space, nodes, walkers, GDOP computation, and simulation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add X-ray overlay showing contributing links to detections with confidence breakdown.
- Users can click "Why?" on any blob to see detailed explanation
- Contributing links are highlighted with Fresnel zone visualization
- Per-link contribution breakdown shows deltaRMS, zone number, weight
- BLE identity match details displayed when available
- Confidence gauge shows overall detection certainty
Explainability is accessible via:
- Right-click context menu on blob figures
- "Why?" button in blob hover tooltip
- Click directly on humanoid blob figures
- Timeline event "Why?" buttons
Accepts: Users can see exactly why a detection was triggered with visual overlays and confidence metrics.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase 8 implementation: Activity Timeline (Component 27)
- Tap-to-jump navigation: Click any event to create replay session and seek to that moment
- Inline feedback display: Thumbs up/down buttons on each event for detection feedback
- Replay API integration: Creates replay window around event timestamp (±5 seconds)
- Feedback API: New /api/feedback endpoint for correct/incorrect/missed detection reports
- Event loading improvements: Real-time WebSocket event insertion with animation
- Filter UI: Type, zone, person, time range, and search filters
- Load more pagination: Keyset cursor-based pagination for large event sets
Acceptance criteria met:
- Users can view all system events chronologically
- Tap any event to jump to that moment in time via replay mode
- Inline feedback buttons allow marking detections correct/incorrect
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implement time-travel debugging, CSI simulator, and pre-deployment
simulator for deep system analysis and tuning.
Time-Travel Debugging:
- Replay session management with seek/play/pause controls
- Parameter tuning overlay with instant preview
- CSI replay store with circular buffer for 48h retention
- REST API for replay control (/api/replay/*)
CSI Simulator CLI (cmd/sim/main.go):
- Virtual ESP32-S3 nodes with synthetic CSI generation
- Walker simulation with random walk or path-following
- Fresnel zone modulation based on walker positions
- BLE advertisement simulation for identity testing
- WebSocket integration with mothership
Pre-Deployment Simulator:
- Virtual space definition with 3D node placement
- Synthetic walker generation and movement simulation
- Fresnel zone accumulation for blob detection
- GDOP map computation for coverage quality visualization
- Deployment recommendations based on coverage analysis
- SSE endpoint for real-time simulation updates
Dashboard Integration:
- Fresnel zone ellipsoid rendering (already in viz3d.js)
- Activity timeline with tap-to-jump (already in timeline.js)
- Detection explainability with X-ray overlay (already in explainability.js)
Exit Criteria Met:
- Time-travel replays historical CSI data with seek/play/pause
- Simulator produces realistic synthetic CSI and blob detections
- Fresnel zone overlay renders wireframe ellipsoids between links
- Developers can tune parameters and see instant results
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
