diff --git a/dashboard/js/router.js b/dashboard/js/router.js
index 575c651..b745b67 100644
--- a/dashboard/js/router.js
+++ b/dashboard/js/router.js
@@ -41,6 +41,11 @@
title: 'Replay',
icon: '⏵',
description: 'Time-travel debugging mode'
+ },
+ simulate: {
+ title: 'Simulate',
+ icon: '⚛',
+ description: 'Pre-deployment simulator'
}
};
diff --git a/dashboard/js/simulate.js b/dashboard/js/simulate.js
new file mode 100644
index 0000000..51676ac
--- /dev/null
+++ b/dashboard/js/simulate.js
@@ -0,0 +1,1021 @@
+/**
+ * Spaxel Dashboard - Pre-Deployment Simulator
+ *
+ * Allows users to model their space, place virtual nodes, and run synthetic walkers
+ * to estimate expected accuracy before purchasing hardware.
+ */
+
+(function() {
+ 'use strict';
+
+ // ============================================
+ // Configuration
+ // ============================================
+ const CONFIG = {
+ // Simulation tick rate (Hz)
+ tickRateHz: 10,
+ // Default simulation duration (seconds)
+ defaultDurationSec: 30,
+ // Walker speed (m/s)
+ walkerSpeed: 1.0,
+ // Grid resolution for GDOP calculation (meters)
+ gridResolutionM: 0.2,
+ // Fresnel zone parameters
+ fresnelSigma: 0.3,
+ signalAmplitude: 0.05,
+ };
+
+ // ============================================
+ // State
+ // ============================================
+ const state = {
+ // Space definition
+ space: {
+ width: 10,
+ depth: 10,
+ height: 2.5,
+ walls: [],
+ },
+
+ // Virtual nodes
+ nodes: [],
+
+ // Walkers
+ walkers: [],
+
+ // Simulation state
+ simulationRunning: false,
+ simulationPaused: false,
+ simulationTime: 0,
+ simulationResults: null,
+
+ // UI state
+ currentTool: 'select', // select, wall, node, walker
+ editingWall: null,
+ editingNode: null,
+ editingWalker: null,
+
+ // GDOP overlay
+ showGDOP: false,
+ gdopData: null,
+
+ // Session ID
+ sessionId: null,
+ };
+
+ // ============================================
+ // DOM Elements
+ // ============================================
+ let elements = {};
+
+ // ============================================
+ // Three.js references
+ // ============================================
+ let _scene = null;
+ let _camera = null;
+ let _renderer = null;
+ let _controls = null;
+ let _wallMeshes = [];
+ let _nodeMeshes = [];
+ let _walkerMeshes = [];
+ let _gdopMesh = null;
+
+ // ============================================
+ // Initialization
+ // ============================================
+ function init() {
+ console.log('[Simulate] Initializing pre-deployment simulator');
+
+ // Wait for Three.js scene to be ready
+ if (window.Viz3D) {
+ initAfterViz3D();
+ } else {
+ document.addEventListener('viz3d-ready', initAfterViz3D);
+ }
+ }
+
+ function initAfterViz3D() {
+ // Get Three.js references from Viz3D
+ const container = document.getElementById('scene-container');
+ if (!container) return;
+
+ // Create simulator UI
+ createSimulatorUI();
+
+ // Listen for router mode changes
+ if (window.SpaxelRouter) {
+ window.SpaxelRouter.onModeChange(onModeChange);
+ }
+
+ console.log('[Simulate] Ready');
+ }
+
+ // ============================================
+ // Simulator UI
+ // ============================================
+ function createSimulatorUI() {
+ // Create simulator panel (hidden by default)
+ const panel = document.createElement('div');
+ panel.id = 'simulator-panel';
+ panel.className = 'simulator-panel';
+ panel.style.display = 'none';
+
+ panel.innerHTML = `
+
+
+
+
+
+
+
+
+
Virtual Nodes
+
+
+
+
+
+
+
+
+
+
Synthetic Walkers
+
+
+
+
+
+
+
+
+
+
+
Coverage Analysis
+
+
+
+
+
+
+
+
+
Simulation
+
+
+
+
+
+
+
+
+
+
+
Results
+
+
+ Expected Accuracy:
+ --
+
+
+ Coverage Score:
+ --
+
+
+
+
+
+
+
+
+
+
+ `;
+
+ document.body.appendChild(panel);
+
+ // Store element references
+ elements = {
+ panel: panel,
+ closeBtn: document.getElementById('sim-close-btn'),
+ spaceWidth: document.getElementById('sim-space-width'),
+ spaceDepth: document.getElementById('sim-space-depth'),
+ spaceHeight: document.getElementById('sim-space-height'),
+ applySpace: document.getElementById('sim-apply-space'),
+ toolBtns: document.querySelectorAll('.sim-tool-btn'),
+ addNode: document.getElementById('sim-add-node'),
+ clearNodes: document.getElementById('sim-clear-nodes'),
+ nodesContainer: document.getElementById('sim-nodes-container'),
+ walkerType: document.getElementById('sim-walker-type'),
+ addWalker: document.getElementById('sim-add-walker'),
+ clearWalkers: document.getElementById('sim-clear-walkers'),
+ walkersContainer: document.getElementById('sim-walkers-container'),
+ showGDOP: document.getElementById('sim-show-gdop'),
+ updateGDOP: document.getElementById('sim-update-gdop'),
+ startBtn: document.getElementById('sim-start-btn'),
+ pauseBtn: document.getElementById('sim-pause-btn'),
+ stopBtn: document.getElementById('sim-stop-btn'),
+ time: document.getElementById('sim-time'),
+ progressFill: document.getElementById('sim-progress-fill'),
+ resultsSection: document.getElementById('sim-results-section'),
+ resultAccuracy: document.getElementById('sim-result-accuracy'),
+ resultCoverage: document.getElementById('sim-result-coverage'),
+ recommendationsSection: document.getElementById('sim-recommendations-section'),
+ recommendations: document.getElementById('sim-recommendations'),
+ shoppingSection: document.getElementById('sim-shopping-section'),
+ shoppingList: document.getElementById('sim-shopping-list'),
+ };
+
+ // Attach event listeners
+ elements.closeBtn.addEventListener('click', exitSimulator);
+ elements.applySpace.addEventListener('click', applySpace);
+ elements.toolBtns.forEach(btn => {
+ btn.addEventListener('click', () => selectTool(btn.dataset.tool));
+ });
+ elements.addNode.addEventListener('click', addNode);
+ elements.clearNodes.addEventListener('click', clearNodes);
+ elements.addWalker.addEventListener('click', addWalker);
+ elements.clearWalkers.addEventListener('click', clearWalkers);
+ elements.showGDOP.addEventListener('change', toggleGDOP);
+ elements.updateGDOP.addEventListener('click', updateGDOP);
+ elements.startBtn.addEventListener('click', startSimulation);
+ elements.pauseBtn.addEventListener('click', pauseSimulation);
+ elements.stopBtn.addEventListener('click', stopSimulation);
+
+ // Set default tool
+ selectTool('select');
+ }
+
+ // ============================================
+ // Router Integration
+ // ============================================
+ function onModeChange(newMode, oldMode) {
+ if (newMode === 'simulate') {
+ enterSimulator();
+ } else if (oldMode === 'simulate') {
+ exitSimulator();
+ }
+ }
+
+ function enterSimulator() {
+ console.log('[Simulate] Entering simulator mode');
+ elements.panel.style.display = 'block';
+
+ // Apply default space
+ applySpace();
+
+ // Create session
+ createSession();
+ }
+
+ function exitSimulator() {
+ console.log('[Simulate] Exiting simulator mode');
+ elements.panel.style.display = 'none';
+
+ // Stop simulation if running
+ if (state.simulationRunning) {
+ stopSimulation();
+ }
+
+ // Clear visualization
+ clearSimulationMeshes();
+ }
+
+ // ============================================
+ // Session Management
+ // ============================================
+ async function createSession() {
+ try {
+ const response = await fetch('/api/simulator/session', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ space: state.space,
+ }),
+ });
+
+ if (!response.ok) throw new Error('Failed to create session');
+
+ const data = await response.json();
+ state.sessionId = data.session_id;
+ console.log('[Simulate] Session created:', state.sessionId);
+ } catch (err) {
+ console.error('[Simulate] Failed to create session:', err);
+ }
+ }
+
+ // ============================================
+ // Space Management
+ // ============================================
+ function applySpace() {
+ const width = parseFloat(elements.spaceWidth.value);
+ const depth = parseFloat(elements.spaceDepth.value);
+ const height = parseFloat(elements.spaceHeight.value);
+
+ state.space = { width, depth, height, walls: [] };
+
+ // Update 3D visualization
+ if (window.Viz3D) {
+ window.Viz3D.applyRoom({
+ width: width,
+ depth: depth,
+ height: height,
+ origin_x: 0,
+ origin_z: 0,
+ });
+ }
+
+ console.log('[Simulate] Space applied:', state.space);
+ }
+
+ // ============================================
+ // Tool Selection
+ // ============================================
+ function selectTool(tool) {
+ state.currentTool = tool;
+
+ // Update button states
+ elements.toolBtns.forEach(btn => {
+ if (btn.dataset.tool === tool) {
+ btn.classList.add('active');
+ } else {
+ btn.classList.remove('active');
+ }
+ });
+
+ console.log('[Simulate] Tool selected:', tool);
+ }
+
+ // ============================================
+ // Node Management
+ // ============================================
+ function addNode() {
+ const id = 'node_' + Date.now();
+ const node = {
+ id: id,
+ name: 'Node ' + (state.nodes.length + 1),
+ position: {
+ x: state.space.width / 2,
+ y: 1.0,
+ z: state.space.depth / 2,
+ },
+ role: 'tx_rx',
+ };
+
+ state.nodes.push(node);
+ renderNodes();
+ updateNodeVisualization(node);
+
+ // Sync with backend
+ syncNode(node);
+
+ console.log('[Simulate] Node added:', node);
+ }
+
+ function removeNode(nodeId) {
+ state.nodes = state.nodes.filter(n => n.id !== nodeId);
+ renderNodes();
+ removeNodeVisualization(nodeId);
+
+ // Sync with backend
+ deleteNode(nodeId);
+
+ console.log('[Simulate] Node removed:', nodeId);
+ }
+
+ function updateNodePosition(nodeId, position) {
+ const node = state.nodes.find(n => n.id === nodeId);
+ if (node) {
+ node.position = position;
+ updateNodeVisualization(node);
+ syncNode(node);
+ }
+ }
+
+ function clearNodes() {
+ state.nodes.forEach(n => removeNodeVisualization(n.id));
+ state.nodes = [];
+ renderNodes();
+ console.log('[Simulate] All nodes cleared');
+ }
+
+ function renderNodes() {
+ elements.nodesContainer.innerHTML = '';
+ state.nodes.forEach(node => {
+ const div = document.createElement('div');
+ div.className = 'sim-item';
+ div.innerHTML = `
+
${node.name}
+
+ (${node.position.x.toFixed(1)}, ${node.position.y.toFixed(1)}, ${node.position.z.toFixed(1)})
+
+
+ `;
+ elements.nodesContainer.appendChild(div);
+ });
+
+ // Attach delete handlers
+ elements.nodesContainer.querySelectorAll('.sim-item-delete').forEach(btn => {
+ btn.addEventListener('click', () => removeNode(btn.dataset.id));
+ });
+ }
+
+ async function syncNode(node) {
+ try {
+ await fetch('/api/simulator/nodes', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(node),
+ });
+ } catch (err) {
+ console.error('[Simulate] Failed to sync node:', err);
+ }
+ }
+
+ async function deleteNode(nodeId) {
+ try {
+ await fetch(`/api/simulator/nodes/${nodeId}`, {
+ method: 'DELETE',
+ });
+ } catch (err) {
+ console.error('[Simulate] Failed to delete node:', err);
+ }
+ }
+
+ // ============================================
+ // Walker Management
+ // ============================================
+ function addWalker() {
+ const type = elements.walkerType.value;
+ const id = 'walker_' + Date.now();
+ const walker = {
+ id: id,
+ type: type,
+ position: {
+ x: state.space.width / 2,
+ y: 1.0,
+ z: state.space.depth / 2,
+ },
+ velocity: {
+ x: (Math.random() - 0.5) * CONFIG.walkerSpeed,
+ y: 0,
+ z: (Math.random() - 0.5) * CONFIG.walkerSpeed,
+ },
+ };
+
+ if (type === 'path') {
+ // Create default path
+ walker.path = [
+ { x: 2, y: 1, z: 2 },
+ { x: state.space.width - 2, y: 1, z: 2 },
+ { x: state.space.width - 2, y: 1, z: state.space.depth - 2 },
+ { x: 2, y: 1, z: state.space.depth - 2 },
+ ];
+ walker.path_index = 0;
+ } else if (type === 'zone') {
+ walker.target_zones = [];
+ }
+
+ state.walkers.push(walker);
+ renderWalkers();
+ updateWalkerVisualization(walker);
+
+ // Sync with backend
+ syncWalker(walker);
+
+ console.log('[Simulate] Walker added:', walker);
+ }
+
+ function removeWalker(walkerId) {
+ state.walkers = state.walkers.filter(w => w.id !== walkerId);
+ renderWalkers();
+ removeWalkerVisualization(walkerId);
+
+ // Sync with backend
+ deleteWalker(walkerId);
+
+ console.log('[Simulate] Walker removed:', walkerId);
+ }
+
+ function clearWalkers() {
+ state.walkers.forEach(w => removeWalkerVisualization(w.id));
+ state.walkers = [];
+ renderWalkers();
+ console.log('[Simulate] All walkers cleared');
+ }
+
+ function renderWalkers() {
+ elements.walkersContainer.innerHTML = '';
+ state.walkers.forEach(walker => {
+ const div = document.createElement('div');
+ div.className = 'sim-item';
+ div.innerHTML = `
+
${walker.type} walker
+
+ (${walker.position.x.toFixed(1)}, ${walker.position.z.toFixed(1)})
+
+
+ `;
+ elements.walkersContainer.appendChild(div);
+ });
+
+ // Attach delete handlers
+ elements.walkersContainer.querySelectorAll('.sim-item-delete').forEach(btn => {
+ btn.addEventListener('click', () => removeWalker(btn.dataset.id));
+ });
+ }
+
+ async function syncWalker(walker) {
+ try {
+ await fetch('/api/simulator/walkers', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(walker),
+ });
+ } catch (err) {
+ console.error('[Simulate] Failed to sync walker:', err);
+ }
+ }
+
+ async function deleteWalker(walkerId) {
+ try {
+ await fetch(`/api/simulator/walkers/${walkerId}`, {
+ method: 'DELETE',
+ });
+ } catch (err) {
+ console.error('[Simulate] Failed to delete walker:', err);
+ }
+ }
+
+ // ============================================
+ // GDOP Visualization
+ // ============================================
+ function toggleGDOP() {
+ state.showGDOP = elements.showGDOP.checked;
+ if (state.showGDOP) {
+ updateGDOP();
+ } else {
+ clearGDOPMesh();
+ }
+ }
+
+ async function updateGDOP() {
+ if (state.nodes.length < 2) {
+ console.warn('[Simulate] Need at least 2 nodes for GDOP');
+ return;
+ }
+
+ try {
+ const response = await fetch('/api/simulator/gdop', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ nodes: state.nodes,
+ space: state.space,
+ }),
+ });
+
+ if (!response.ok) throw new Error('Failed to compute GDOP');
+
+ const data = await response.json();
+ state.gdopData = data;
+ renderGDOP(data);
+
+ console.log('[Simulate] GDOP updated:', data);
+ } catch (err) {
+ console.error('[Simulate] Failed to update GDOP:', err);
+ }
+ }
+
+ function renderGDOP(data) {
+ clearGDOPMesh();
+
+ if (!data.gdop_map) return;
+
+ // Create texture from GDOP data
+ const canvas = document.createElement('canvas');
+ const size = 256;
+ canvas.width = size;
+ canvas.height = size;
+ const ctx = canvas.getContext('2d');
+
+ const imageData = ctx.createImageData(size, size);
+ const gridWidth = data.gdop_map.length;
+ const gridHeight = data.gdop_map[0]?.length || 0;
+
+ for (let y = 0; y < size; y++) {
+ for (let x = 0; x < size; x++) {
+ const gridX = Math.floor((x / size) * gridWidth);
+ const gridY = Math.floor((y / size) * gridHeight);
+ const gdop = data.gdop_map[gridX]?.[gridY] || 10;
+
+ // Color based on GDOP quality
+ let color;
+ if (gdop < 2) {
+ color = { r: 76, g: 175, b: 80 }; // Excellent - green
+ } else if (gdop < 4) {
+ color = { r: 139, g: 195, b: 74 }; // Good - light green
+ } else if (gdop < 6) {
+ color = { r: 255, g: 235, b: 59 }; // Fair - yellow
+ } else if (gdop < 8) {
+ color = { r: 255, g: 152, b: 0 }; // Poor - orange
+ } else {
+ color = { r: 244, g: 67, b: 54 }; // None - red
+ }
+
+ const i = (y * size + x) * 4;
+ imageData.data[i] = color.r;
+ imageData.data[i + 1] = color.g;
+ imageData.data[i + 2] = color.b;
+ imageData.data[i + 3] = 180; // Alpha
+ }
+ }
+
+ ctx.putImageData(imageData, 0, 0);
+
+ const texture = new THREE.CanvasTexture(canvas);
+ const material = new THREE.MeshBasicMaterial({
+ map: texture,
+ transparent: true,
+ opacity: 0.7,
+ side: THREE.DoubleSide,
+ });
+
+ const geometry = new THREE.PlaneGeometry(state.space.width, state.space.depth);
+ _gdopMesh = new THREE.Mesh(geometry, material);
+ _gdopMesh.rotation.x = -Math.PI / 2;
+ _gdopMesh.position.set(state.space.width / 2, 0.01, state.space.depth / 2);
+
+ // Get scene from Viz3D
+ if (window.Viz3D) {
+ const scene = window.Viz3D.getScene?.();
+ if (scene) scene.add(_gdopMesh);
+ }
+ }
+
+ function clearGDOPMesh() {
+ if (_gdopMesh) {
+ const scene = window.Viz3D?.getScene?.();
+ if (scene) scene.remove(_gdopMesh);
+ _gdopMesh.geometry.dispose();
+ _gdopMesh.material.dispose();
+ _gdopMesh = null;
+ }
+ }
+
+ // ============================================
+ // Simulation Control
+ // ============================================
+ async function startSimulation() {
+ if (state.nodes.length < 2) {
+ alert('Please add at least 2 nodes before starting simulation');
+ return;
+ }
+
+ if (state.walkers.length === 0) {
+ alert('Please add at least 1 walker before starting simulation');
+ return;
+ }
+
+ try {
+ const response = await fetch('/api/simulator/simulate', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ duration_sec: CONFIG.defaultDurationSec,
+ tick_rate_hz: CONFIG.tickRateHz,
+ }),
+ });
+
+ if (!response.ok) throw new Error('Failed to start simulation');
+
+ const data = await response.json();
+ state.simulationRunning = true;
+ state.simulationPaused = false;
+ state.simulationTime = 0;
+
+ // Update UI
+ elements.startBtn.disabled = true;
+ elements.pauseBtn.disabled = false;
+ elements.stopBtn.disabled = false;
+ elements.resultsSection.style.display = 'none';
+ elements.recommendationsSection.style.display = 'none';
+ elements.shoppingSection.style.display = 'none';
+
+ // Start progress update
+ startProgressLoop();
+
+ // Poll for results
+ pollSimulationResults();
+
+ console.log('[Simulate] Simulation started');
+ } catch (err) {
+ console.error('[Simulate] Failed to start simulation:', err);
+ alert('Failed to start simulation: ' + err.message);
+ }
+ }
+
+ function pauseSimulation() {
+ if (!state.simulationRunning) return;
+
+ state.simulationPaused = !state.simulationPaused;
+ elements.pauseBtn.textContent = state.simulationPaused ? 'Resume' : 'Pause';
+
+ console.log('[Simulate] Simulation', state.simulationPaused ? 'paused' : 'resumed');
+ }
+
+ async function stopSimulation() {
+ state.simulationRunning = false;
+ state.simulationPaused = false;
+ state.simulationTime = 0;
+
+ // Update UI
+ elements.startBtn.disabled = false;
+ elements.pauseBtn.disabled = true;
+ elements.pauseBtn.textContent = 'Pause';
+ elements.stopBtn.disabled = true;
+
+ // Reset progress
+ elements.time.textContent = '0:00 / 0:30';
+ elements.progressFill.style.width = '0%';
+
+ console.log('[Simulate] Simulation stopped');
+ }
+
+ function startProgressLoop() {
+ const interval = setInterval(() => {
+ if (!state.simulationRunning) {
+ clearInterval(interval);
+ return;
+ }
+
+ if (!state.simulationPaused) {
+ state.simulationTime += 0.1;
+ updateProgress();
+ }
+ }, 100);
+ }
+
+ function updateProgress() {
+ const duration = CONFIG.defaultDurationSec;
+ const progress = Math.min(state.simulationTime / duration, 1);
+
+ const elapsed = Math.floor(state.simulationTime);
+ const total = Math.floor(duration);
+ elements.time.textContent = `${Math.floor(elapsed / 60)}:${(elapsed % 60).toString().padStart(2, '0')} / ${Math.floor(total / 60)}:${(total % 60).toString().padStart(2, '0')}`;
+ elements.progressFill.style.width = (progress * 100) + '%';
+ }
+
+ async function pollSimulationResults() {
+ const pollInterval = setInterval(async () => {
+ if (!state.simulationRunning) {
+ clearInterval(pollInterval);
+ return;
+ }
+
+ try {
+ const response = await fetch('/api/simulator/status');
+ if (!response.ok) return;
+
+ const data = await response.json();
+
+ // Update walker positions
+ if (data.walker_positions) {
+ data.walker_positions.forEach(pos => {
+ const walker = state.walkers.find(w => w.id === pos.id);
+ if (walker) {
+ walker.position = pos.position;
+ updateWalkerVisualization(walker);
+ }
+ });
+ }
+
+ // Check if simulation complete
+ if (data.state === 'complete' || data.state === 'stopped') {
+ clearInterval(pollInterval);
+ await fetchSimulationResults();
+ }
+ } catch (err) {
+ console.error('[Simulate] Failed to poll results:', err);
+ }
+ }, 200);
+ }
+
+ async function fetchSimulationResults() {
+ try {
+ const response = await fetch('/api/simulator/results');
+ if (!response.ok) throw new Error('Failed to fetch results');
+
+ const data = await response.json();
+ state.simulationResults = data;
+
+ displayResults(data);
+ stopSimulation();
+
+ console.log('[Simulate] Simulation results:', data);
+ } catch (err) {
+ console.error('[Simulate] Failed to fetch results:', err);
+ }
+ }
+
+ function displayResults(data) {
+ // Show results section
+ elements.resultsSection.style.display = 'block';
+
+ // Display accuracy
+ const accuracy = data.expected_accuracy_m || 0;
+ elements.resultAccuracy.textContent = accuracy < 0.5 ? '< 0.5m (Excellent)' :
+ accuracy < 1.0 ? '< 1.0m (Good)' :
+ accuracy < 1.5 ? '< 1.5m (Fair)' :
+ '> 1.5m (Poor)';
+
+ // Display coverage
+ const coverage = data.coverage_score || 0;
+ elements.resultCoverage.textContent = (coverage * 100).toFixed(0) + '%';
+
+ // Display recommendations
+ if (data.recommendations && data.recommendations.length > 0) {
+ elements.recommendationsSection.style.display = 'block';
+ elements.recommendations.innerHTML = data.recommendations.map(rec => `
+
+ ${rec.priority}
+ ${rec.message}
+
+ `).join('');
+ }
+
+ // Display shopping list
+ if (data.shopping_list) {
+ elements.shoppingSection.style.display = 'block';
+ elements.shoppingList.innerHTML = `
+
+ Minimum nodes:
+ ${data.shopping_list.min_nodes || state.nodes.length}
+
+
+ Recommended nodes:
+ ${data.shopping_list.recommended_nodes || state.nodes.length}
+
+ `;
+ }
+ }
+
+ // ============================================
+ // 3D Visualization
+ // ============================================
+ function updateNodeVisualization(node) {
+ // Get scene from Viz3D
+ const scene = window.Viz3D?.getScene?.();
+ if (!scene) return;
+
+ // Remove existing mesh
+ removeNodeVisualization(node.id);
+
+ // Create node mesh
+ const geometry = new THREE.SphereGeometry(0.15, 16, 16);
+ const material = new THREE.MeshLambertMaterial({
+ color: node.role === 'tx' ? 0xff6b6b : node.role === 'rx' ? 0x4ecdc4 : 0x45b7d1,
+ emissive: node.role === 'tx' ? 0xff6b6b : node.role === 'rx' ? 0x4ecdc4 : 0x45b7d1,
+ emissiveIntensity: 0.3,
+ });
+
+ const mesh = new THREE.Mesh(geometry, material);
+ mesh.position.set(node.position.x, node.position.y, node.position.z);
+ mesh.userData.nodeId = node.id;
+
+ scene.add(mesh);
+ _nodeMeshes.set(node.id, mesh);
+ }
+
+ function removeNodeVisualization(nodeId) {
+ const mesh = _nodeMeshes.get(nodeId);
+ if (mesh) {
+ const scene = window.Viz3D?.getScene?.();
+ if (scene) scene.remove(mesh);
+ mesh.geometry.dispose();
+ mesh.material.dispose();
+ _nodeMeshes.delete(nodeId);
+ }
+ }
+
+ function updateWalkerVisualization(walker) {
+ // Get scene from Viz3D
+ const scene = window.Viz3D?.getScene?.();
+ if (!scene) return;
+
+ // Remove existing mesh
+ removeWalkerVisualization(walker.id);
+
+ // Create walker mesh (capsule for person)
+ const geometry = new THREE.CapsuleGeometry(0.1, 0.5, 4, 8);
+ const material = new THREE.MeshLambertMaterial({
+ color: 0xffa726,
+ transparent: true,
+ opacity: 0.8,
+ });
+
+ const mesh = new THREE.Mesh(geometry, material);
+ mesh.position.set(walker.position.x, walker.position.y, walker.position.z);
+ mesh.userData.walkerId = walker.id;
+
+ scene.add(mesh);
+ _walkerMeshes.set(walker.id, mesh);
+ }
+
+ function removeWalkerVisualization(walkerId) {
+ const mesh = _walkerMeshes.get(walkerId);
+ if (mesh) {
+ const scene = window.Viz3D?.getScene?.();
+ if (scene) scene.remove(mesh);
+ mesh.geometry.dispose();
+ mesh.material.dispose();
+ _walkerMeshes.delete(walkerId);
+ }
+ }
+
+ function clearSimulationMeshes() {
+ _nodeMeshes.forEach((mesh, id) => removeNodeVisualization(id));
+ _walkerMeshes.forEach((mesh, id) => removeWalkerVisualization(id));
+ clearGDOPMesh();
+ }
+
+ // ============================================
+ // Public API
+ // ============================================
+ window.SpaxelSimulator = {
+ init: init,
+ getState: () => state,
+ };
+
+ // Auto-initialize
+ if (document.readyState === 'loading') {
+ document.addEventListener('DOMContentLoaded', init);
+ } else {
+ init();
+ }
+
+ console.log('[Simulate] Simulator module loaded');
+})();
diff --git a/mothership/cmd/mothership/main.go b/mothership/cmd/mothership/main.go
index 714f83f..ea66732 100644
--- a/mothership/cmd/mothership/main.go
+++ b/mothership/cmd/mothership/main.go
@@ -2069,94 +2069,22 @@ func main() {
log.Printf("[INFO] Zones and portals API registered at /api/zones/* and /api/portals/*")
}
- // Phase 6: BLE REST API
- if bleRegistry != nil {
- r.Get("/api/ble/devices", func(w http.ResponseWriter, r *http.Request) {
- devices, err := bleRegistry.GetDevices(false)
- if err != nil {
- http.Error(w, err.Error(), http.StatusInternalServerError)
- return
- }
- writeJSON(w, devices)
- })
- r.Get("/api/ble/devices/{addr}", func(w http.ResponseWriter, r *http.Request) {
- addr := chi.URLParam(r, "addr")
- device, err := bleRegistry.GetDevice(addr)
- if err != nil {
- http.Error(w, err.Error(), http.StatusNotFound)
- return
- }
- writeJSON(w, device)
- })
- r.Post("/api/ble/devices", func(w http.ResponseWriter, r *http.Request) {
- var device ble.DeviceRecord
- if err := json.NewDecoder(r.Body).Decode(&device); err != nil {
- http.Error(w, err.Error(), http.StatusBadRequest)
- return
- }
- if device.Addr == "" {
- http.Error(w, "addr required", http.StatusBadRequest)
- return
- }
- result, err := bleRegistry.PreregisterDevice(device.Addr, device.Name)
- if err != nil {
- http.Error(w, err.Error(), http.StatusInternalServerError)
- return
- }
- writeJSON(w, result)
- })
- r.Put("/api/ble/devices/{addr}", func(w http.ResponseWriter, r *http.Request) {
- addr := chi.URLParam(r, "addr")
- var device ble.DeviceRecord
- if err := json.NewDecoder(r.Body).Decode(&device); err != nil {
- http.Error(w, err.Error(), http.StatusBadRequest)
- return
- }
- updates := map[string]interface{}{}
- if device.Name != "" {
- updates["name"] = device.Name
- }
- if device.Label != "" {
- updates["label"] = device.Label
- }
- if device.DeviceType != "" {
- updates["device_type"] = string(device.DeviceType)
- }
- if device.PersonID != "" {
- updates["person_id"] = device.PersonID
- }
- if len(updates) == 0 {
- writeJSON(w, device)
- return
- }
- if err := bleRegistry.UpdateDevice(addr, updates); err != nil {
- http.Error(w, err.Error(), http.StatusInternalServerError)
- return
- }
- result, err := bleRegistry.GetDevice(addr)
- if err != nil {
- http.Error(w, err.Error(), http.StatusInternalServerError)
- return
- }
- writeJSON(w, result)
- })
- r.Delete("/api/ble/devices/{addr}", func(w http.ResponseWriter, r *http.Request) {
- addr := chi.URLParam(r, "addr")
- if err := bleRegistry.DeleteDevice(addr); err != nil {
- http.Error(w, err.Error(), http.StatusInternalServerError)
- return
- }
- w.WriteHeader(http.StatusNoContent)
- })
- r.Get("/api/ble/matches", func(w http.ResponseWriter, r *http.Request) {
- if identityMatcher == nil {
- writeJSON(w, []*ble.IdentityMatch{})
- return
- }
- matches := identityMatcher.GetAllMatches()
- writeJSON(w, matches)
- })
- }
+ // Phase 6: BLE REST API
+ if bleRegistry != nil {
+ bleHandler := ble.NewHandler(bleRegistry)
+ bleHandler.RegisterRoutes(r)
+ log.Printf("[INFO] BLE REST API registered at /api/ble/* and /api/people/*")
+
+ // BLE identity matches endpoint (not in ble.Handler)
+ r.Get("/api/ble/matches", func(w http.ResponseWriter, r *http.Request) {
+ if identityMatcher == nil {
+ writeJSON(w, []*ble.IdentityMatch{})
+ return
+ }
+ matches := identityMatcher.GetAllMatches()
+ writeJSON(w, matches)
+ })
+ }
// Phase 6: Automation REST API
if automationEngine != nil {
diff --git a/mothership/internal/api/replay.go b/mothership/internal/api/replay.go
index 8b23e68..81e0cce 100644
--- a/mothership/internal/api/replay.go
+++ b/mothership/internal/api/replay.go
@@ -17,10 +17,11 @@ import (
// ReplayHandler manages CSI replay sessions.
type ReplayHandler struct {
- mu sync.RWMutex
- worker *replay.Worker
- sessions map[string]*_replaySession
- nextID int
+ mu sync.RWMutex
+ worker *replay.Worker
+ sessions map[string]*_replaySession
+ nextID int
+ activeSessionID string // Currently active session for dashboard control
}
// _replaySession represents an active replay session (API layer).
@@ -619,3 +620,161 @@ func (h *ReplayHandler) GetReplayPath() string {
func (h *ReplayHandler) GetStoreStats() replay.Stats {
return h.worker.GetStoreStats()
}
+
+// Seek moves the active replay session to the target timestamp.
+// Implements dashboard.ReplayHandler interface.
+func (h *ReplayHandler) Seek(targetMS int64) error {
+ h.mu.Lock()
+ sessionID := h.activeSessionID
+ h.mu.Unlock()
+
+ if sessionID == "" {
+ return fmt.Errorf("no active replay session")
+ }
+
+ return h.worker.Seek(sessionID, targetMS)
+}
+
+// Play starts playback of the active replay session at the specified speed.
+// Implements dashboard.ReplayHandler interface.
+func (h *ReplayHandler) Play(speed float64) error {
+ h.mu.Lock()
+ sessionID := h.activeSessionID
+ h.mu.Unlock()
+
+ if sessionID == "" {
+ return fmt.Errorf("no active replay session")
+ }
+
+ // Convert float speed to int (1x=1, 2x=2, 0.5x=1 for now)
+ speedInt := 1
+ if speed >= 2.0 {
+ speedInt = 2
+ } else if speed >= 5.0 {
+ speedInt = 5
+ }
+
+ // Set speed first
+ if err := h.worker.SetPlaybackSpeed(sessionID, speedInt); err != nil {
+ return err
+ }
+
+ // Then set state to playing
+ return h.worker.SetState(sessionID, "playing")
+}
+
+// Pause pauses playback of the active replay session.
+// Implements dashboard.ReplayHandler interface.
+func (h *ReplayHandler) Pause() error {
+ h.mu.Lock()
+ sessionID := h.activeSessionID
+ h.mu.Unlock()
+
+ if sessionID == "" {
+ return fmt.Errorf("no active replay session")
+ }
+
+ return h.worker.SetState(sessionID, "paused")
+}
+
+// SetParams updates the replay pipeline parameters for the active session.
+// Implements dashboard.ReplayHandler interface.
+func (h *ReplayHandler) SetParams(params *replay.TunableParams) error {
+ h.mu.Lock()
+ sessionID := h.activeSessionID
+ h.mu.Unlock()
+
+ if sessionID == "" {
+ return fmt.Errorf("no active replay session")
+ }
+
+ // Convert TunableParams to map for worker
+ paramMap := make(map[string]interface{})
+ if params.DeltaRMSThreshold != nil {
+ paramMap["delta_rms_threshold"] = *params.DeltaRMSThreshold
+ }
+ if params.TauS != nil {
+ paramMap["tau_s"] = *params.TauS
+ }
+ if params.FresnelDecay != nil {
+ paramMap["fresnel_decay"] = *params.FresnelDecay
+ }
+ if params.FresnelWeightSigma != nil {
+ paramMap["fresnel_weight_sigma"] = *params.FresnelWeightSigma
+ }
+ if params.MinConfidence != nil {
+ paramMap["min_confidence"] = *params.MinConfidence
+ }
+ if params.BreathingSensitivity != nil {
+ paramMap["breathing_sensitivity"] = *params.BreathingSensitivity
+ }
+ if params.NSubcarriers != nil {
+ paramMap["n_subcarriers"] = *params.NSubcarriers
+ }
+
+ return h.worker.UpdateParams(sessionID, paramMap)
+}
+
+// ApplyToLive copies the current replay parameters to the live configuration.
+// Implements dashboard.ReplayHandler interface.
+func (h *ReplayHandler) ApplyToLive() error {
+ h.mu.Lock()
+ sessionID := h.activeSessionID
+ h.mu.Unlock()
+
+ if sessionID == "" {
+ return fmt.Errorf("no active replay session")
+ }
+
+ // Get the current session's parameters
+ session, err := h.worker.GetSession(sessionID)
+ if err != nil {
+ return err
+ }
+
+ // Log the parameters that would be applied to live
+ log.Printf("[INFO] ApplyToLive: Would apply replay parameters to live: %+v", session.Params)
+
+ // TODO: Implement actual parameter persistence to live config
+ // This would involve updating the mothership config file and
+ // notifying the live pipeline to reload its parameters
+
+ return nil
+}
+
+// SetSpeed changes the playback speed of the active replay session.
+// Implements dashboard.ReplayHandler interface.
+func (h *ReplayHandler) SetSpeed(speed float64) error {
+ h.mu.Lock()
+ sessionID := h.activeSessionID
+ h.mu.Unlock()
+
+ if sessionID == "" {
+ return fmt.Errorf("no active replay session")
+ }
+
+ // Convert float speed to int
+ speedInt := 1
+ if speed >= 2.0 {
+ speedInt = 2
+ } else if speed >= 5.0 {
+ speedInt = 5
+ }
+
+ return h.worker.SetPlaybackSpeed(sessionID, speedInt)
+}
+
+// SetActiveSession sets the active replay session for dashboard control.
+func (h *ReplayHandler) SetActiveSession(sessionID string) {
+ h.mu.Lock()
+ defer h.mu.Unlock()
+ h.activeSessionID = sessionID
+ log.Printf("[INFO] Active replay session set to: %s", sessionID)
+}
+
+// GetActiveSession returns the currently active replay session ID.
+func (h *ReplayHandler) GetActiveSession() string {
+ h.mu.RLock()
+ defer h.mu.RUnlock()
+ return h.activeSessionID
+}
diff --git a/mothership/internal/replay/engine.go b/mothership/internal/replay/engine.go
index 48c8467..bf8f63f 100644
--- a/mothership/internal/replay/engine.go
+++ b/mothership/internal/replay/engine.go
@@ -461,6 +461,16 @@ func (e *Engine) runFusion() []BlobUpdate {
return blobs
}
+// splitLinkID splits a link ID in "nodeMAC:peerMAC" format.
+func splitLinkID(linkID string) []string {
+ for i := 0; i < len(linkID); i++ {
+ if linkID[i] == ':' {
+ return []string{linkID[:i], linkID[i+1:]}
+ }
+ }
+ return []string{linkID}
+}
+
// reprocessCurrentPosition re-processes the current position with new parameters.
func (e *Engine) reprocessCurrentPosition() {
e.mu.Lock()
diff --git a/mothership/internal/replay/pipeline.go b/mothership/internal/replay/pipeline.go
index 8835afe..3ffd146 100644
--- a/mothership/internal/replay/pipeline.go
+++ b/mothership/internal/replay/pipeline.go
@@ -137,6 +137,15 @@ func (p *Pipeline) processWithParams(linkID string, parsed *ingestion.ParsedFram
// Re-check motion detection with new threshold
result.MotionDetected = result.SmoothDeltaRMS > *p.params.DeltaRMSThreshold
}
+
+ // Apply minimum confidence filter if set
+ if p.params.MinConfidence != nil && result.AmbientConfidence < *p.params.MinConfidence {
+ // Suppress low-confidence detections
+ result.MotionDetected = false
+ }
+
+ // Note: FresnelWeightSigma and NSubcarriers are applied at the fusion level
+ // BreathingSensitivity is applied in the breathing detection module
}
return result
diff --git a/mothership/internal/replay/session.go b/mothership/internal/replay/session.go
index cb18977..04f6d54 100644
--- a/mothership/internal/replay/session.go
+++ b/mothership/internal/replay/session.go
@@ -50,6 +50,8 @@ type TunableParams struct {
FresnelDecay *float64 `json:"fresnel_decay,omitempty"`
NSubcarriers *int `json:"n_subcarriers,omitempty"`
BreathingSensitivity *float64 `json:"breathing_sensitivity,omitempty"`
+ FresnelWeightSigma *float64 `json:"fresnel_weight_sigma,omitempty"`
+ MinConfidence *float64 `json:"min_confidence,omitempty"`
}
// NewSession creates a new replay session.
diff --git a/mothership/internal/simulator/accuracy.go b/mothership/internal/simulator/accuracy.go
new file mode 100644
index 0000000..c55ef7e
--- /dev/null
+++ b/mothership/internal/simulator/accuracy.go
@@ -0,0 +1,358 @@
+// Package simulator provides accuracy estimation for the pre-deployment simulator.
+package simulator
+
+import (
+ "fmt"
+ "math"
+)
+
+// AccuracyEstimator computes accuracy metrics from simulation results.
+type AccuracyEstimator struct{}
+
+// NewAccuracyEstimator creates a new accuracy estimator.
+func NewAccuracyEstimator() *AccuracyEstimator {
+ return &AccuracyEstimator{}
+}
+
+// AccuracyReport contains accuracy metrics from a simulation run.
+type AccuracyReport struct {
+ MedianError float64 `json:"median_error_m"` // Median position error in meters
+ MeanError float64 `json:"mean_error_m"` // Mean position error in meters
+ MaxError float64 `json:"max_error_m"` // Maximum position error in meters
+ P95Error float64 `json:"p95_error_m"` // 95th percentile error
+ DetectionRate float64 `json:"detection_rate"` // Fraction of walkers detected
+ FalsePositiveRate float64 `json:"false_positive_rate"` // False positives per second
+ RecallAt1m float64 `json:"recall_at_1m"` // Fraction within 1m of true position
+ RecallAt2m float64 `json:"recall_at_2m"` // Fraction within 2m of true position
+ SampleCount int `json:"sample_count"` // Number of walker positions evaluated
+}
+
+// Recommendation is a deployment recommendation.
+type Recommendation struct {
+ Priority string `json:"priority"` // "high", "medium", "low"
+ Message string `json:"message"` // Human-readable recommendation
+ Impact float64 `json:"impact"` // Estimated improvement (0-1)
+ Position *Point `json:"position,omitempty"` // Suggested position (if applicable)
+}
+
+// RecommendationEngine generates deployment recommendations.
+type RecommendationEngine struct{}
+
+// NewRecommendationEngine creates a new recommendation engine.
+func NewRecommendationEngine() *RecommendationEngine {
+ return &RecommendationEngine{}
+}
+
+// Compute evaluates accuracy metrics from walker positions and blob detections.
+func (ae *AccuracyEstimator) Compute(walkers []*SimWalker, blobs []BlobResult) AccuracyReport {
+ if len(walkers) == 0 {
+ return AccuracyReport{}
+ }
+
+ // Collect all true positions and matched blob positions
+ truePositions := make([]Point, 0)
+ detectedPositions := make([]Point, 0)
+ errors := make([]float64, 0)
+
+ for _, walker := range walkers {
+ for _, truePos := range walker.TrueHistory {
+ truePositions = append(truePositions, truePos)
+
+ // Find nearest blob
+ nearestDist := math.Inf(1)
+ for _, blob := range blobs {
+ if blob.WalkerID == walker.ID {
+ dist := blob.Position.Distance(truePos)
+ if dist < nearestDist {
+ nearestDist = dist
+ }
+ }
+ }
+
+ if !math.IsInf(nearestDist, 1) {
+ detectedPositions = append(detectedPositions, truePos)
+ errors = append(errors, nearestDist)
+ }
+ }
+ }
+
+ if len(errors) == 0 {
+ return AccuracyReport{
+ MedianError: math.Inf(1),
+ MeanError: math.Inf(1),
+ MaxError: math.Inf(1),
+ DetectionRate: 0,
+ SampleCount: len(truePositions),
+ }
+ }
+
+ // Compute statistics
+ meanError := 0.0
+ for _, e := range errors {
+ meanError += e
+ }
+ meanError /= float64(len(errors))
+
+ // Median error
+ sortedErrors := make([]float64, len(errors))
+ copy(sortedErrors, errors)
+ for i := 0; i < len(sortedErrors); i++ {
+ for j := i + 1; j < len(sortedErrors); j++ {
+ if sortedErrors[i] > sortedErrors[j] {
+ sortedErrors[i], sortedErrors[j] = sortedErrors[j], sortedErrors[i]
+ }
+ }
+ }
+ medianError := sortedErrors[len(sortedErrors)/2]
+
+ // Max error
+ maxError := sortedErrors[len(sortedErrors)-1]
+
+ // 95th percentile
+ p95Index := int(float64(len(sortedErrors)) * 0.95)
+ if p95Index >= len(sortedErrors) {
+ p95Index = len(sortedErrors) - 1
+ }
+ p95Error := sortedErrors[p95Index]
+
+ // Detection rate
+ detectionRate := float64(len(detectedPositions)) / float64(len(truePositions))
+
+ // Recall at 1m and 2m
+ recall1m := 0.0
+ recall2m := 0.0
+ for _, e := range errors {
+ if e <= 1.0 {
+ recall1m++
+ }
+ if e <= 2.0 {
+ recall2m++
+ }
+ }
+ recall1m /= float64(len(errors))
+ recall2m /= float64(len(errors))
+
+ // False positive rate (blobs without matching walker)
+ falsePositives := 0
+ for _, blob := range blobs {
+ hasMatch := false
+ for _, walker := range walkers {
+ if blob.WalkerID == walker.ID {
+ hasMatch = true
+ break
+ }
+ }
+ if !hasMatch {
+ falsePositives++
+ }
+ }
+ falsePositiveRate := float64(falsePositives) / float64(len(errors))
+
+ return AccuracyReport{
+ MedianError: medianError,
+ MeanError: meanError,
+ MaxError: maxError,
+ P95Error: p95Error,
+ DetectionRate: detectionRate,
+ FalsePositiveRate: falsePositiveRate,
+ RecallAt1m: recall1m,
+ RecallAt2m: recall2m,
+ SampleCount: len(errors),
+ }
+}
+
+// Generate generates recommendations based on space, nodes, GDOP, and coverage.
+func (re *RecommendationEngine) Generate(space *Space, nodes *NodeSet, gdopMap []float64, coverageScore float64) []Recommendation {
+ recs := make([]Recommendation, 0)
+
+ // Check coverage score
+ if coverageScore < 50 {
+ recs = append(recs, Recommendation{
+ Priority: "high",
+ Message: fmt.Sprintf("Coverage is below 50%% (%.0f%%). Consider adding more nodes.", coverageScore),
+ Impact: 0.3,
+ })
+ }
+
+ // Check node count
+ nodeCount := nodes.Count()
+ if nodeCount < 4 {
+ recs = append(recs, Recommendation{
+ Priority: "medium",
+ Message: fmt.Sprintf("Only %d nodes. For best accuracy, use at least 4 nodes.", nodeCount),
+ Impact: 0.2,
+ })
+ }
+
+ // Check height diversity
+ hasLow, hasHigh := false, false
+ for _, node := range nodes.All() {
+ if node.Position.Z < 1.0 {
+ hasLow = true
+ }
+ if node.Position.Z > 2.0 {
+ hasHigh = true
+ }
+ }
+
+ if !hasLow || !hasHigh {
+ recs = append(recs, Recommendation{
+ Priority: "medium",
+ Message: "For better Z-axis accuracy, place nodes at mixed heights (some low, some high).",
+ Impact: 0.15,
+ })
+ }
+
+ // Find worst coverage areas
+ minX, minY, minZ, maxX, maxY, maxZ := space.Bounds()
+ if len(gdopMap) > 0 {
+ // Find cells with worst GDOP (highest values, excluding infinity)
+ maxGDOP := 0.0
+ worstIdx := -1
+
+ for i, gdop := range gdopMap {
+ if !math.IsInf(gdop, 0) && gdop > maxGDOP {
+ maxGDOP = gdop
+ worstIdx = i
+ }
+ }
+
+ if maxGDOP > 8.0 && worstIdx >= 0 {
+ // Compute position from index
+ widthCells := int(math.Ceil((maxX - minX) / 0.2))
+ depthCells := int(math.Ceil((maxY - minY) / 0.2))
+
+ z := worstIdx / (widthCells * depthCells)
+ remainder := worstIdx % (widthCells * depthCells)
+ x := remainder / depthCells
+ y := remainder % depthCells
+
+ posX := minX + float64(x)*0.2 + 0.1
+ posY := minY + float64(y)*0.2 + 0.1
+
+ recs = append(recs, Recommendation{
+ Priority: "high",
+ Message: fmt.Sprintf("Poor coverage detected near (%.1f, %.1f). Consider adding a node nearby.", posX, posY),
+ Impact: 0.25,
+ Position: &Point{X: posX, Y: posY, Z: 2.0},
+ })
+ }
+ }
+
+ // Check for collinear nodes
+ if nodeCount >= 3 {
+ angles := make([]float64, 0, nodeCount)
+ for _, node := range nodes.All() {
+ // Compute angle from center
+ centerX := (minX + maxX) / 2
+ centerY := (minY + maxY) / 2
+ angle := math.Atan2(node.Position.Y-centerY, node.Position.X-centerX)
+ angles = append(angles, angle)
+ }
+
+ // Check if all angles are similar (collinear)
+ angleSpread := 0.0
+ for i := 1; i < len(angles); i++ {
+ diff := math.Abs(angles[i] - angles[0])
+ for diff > math.Pi {
+ diff -= 2 * math.Pi
+ }
+ for diff < -math.Pi {
+ diff += 2 * math.Pi
+ }
+ angleSpread += diff
+ }
+ angleSpread /= float64(len(angles) - 1)
+
+ if angleSpread < 0.3 { // Less than ~17 degrees spread
+ recs = append(recs, Recommendation{
+ Priority: "medium",
+ Message: "Nodes appear to be nearly collinear. Spread them out for better coverage.",
+ Impact: 0.2,
+ })
+ }
+ }
+
+ // Estimate improvement with additional nodes
+ if nodeCount >= 2 && nodeCount < 8 {
+ // Estimate improvement from adding one node
+ estimatedImprovement := 0.1 * float64(8-nodeCount) / 6.0
+ recs = append(recs, Recommendation{
+ Priority: "low",
+ Message: fmt.Sprintf("Adding a node could improve accuracy by ~%.0f%%.", estimatedImprovement*100),
+ Impact: estimatedImprovement,
+ })
+ }
+
+ // If no issues found
+ if len(recs) == 0 {
+ recs = append(recs, Recommendation{
+ Priority: "low",
+ Message: "Coverage looks good! No specific recommendations.",
+ Impact: 0,
+ })
+ }
+
+ return recs
+}
+
+// ShoppingList contains hardware recommendations.
+type ShoppingList struct {
+ MinimumNodes int `json:"minimum_nodes"`
+ RecommendedNodes int `json:"recommended_nodes"`
+ ExpectedAccuracy float64 `json:"expected_accuracy_m"`
+ CoveragePercent float64 `json:"coverage_percent"`
+ HardwareList []string `json:"hardware_list"`
+ AmazonSearchURL string `json:"amazon_search_url"`
+}
+
+// GenerateShoppingListFromResults creates a shopping list from simulation results.
+func GenerateShoppingListFromResults(space *Space, nodes *NodeSet, coverageScore float64, accuracy AccuracyReport) ShoppingList {
+ nodeCount := nodes.Count()
+
+ // Minimum nodes based on space dimensions
+ minX, minY, _, maxX, maxY, _ := space.Bounds()
+ area := (maxX - minX) * (maxY - minY)
+ minNodes := int(math.Ceil(area / 30.0)) // ~30 m² per node for fair coverage
+
+ // Recommended nodes based on desired accuracy
+ recNodes := minNodes
+ if accuracy.MedianError > 1.0 && minNodes < 6 {
+ recNodes = minNodes + 1
+ }
+ if accuracy.MedianError > 0.8 && minNodes < 8 {
+ recNodes = minNodes + 2
+ }
+
+ // Expected accuracy
+ expectedAccuracy := accuracy.MedianError
+ if math.IsInf(expectedAccuracy, 0) {
+ // Estimate from node count
+ if nodeCount >= 6 {
+ expectedAccuracy = 0.5
+ } else if nodeCount >= 4 {
+ expectedAccuracy = 1.0
+ } else {
+ expectedAccuracy = 1.5
+ }
+ }
+
+ // Hardware list
+ hardware := make([]string, 0)
+ hardware = append(hardware, fmt.Sprintf("%d × ESP32-S3 Development Board", recNodes))
+ hardware = append(hardware, fmt.Sprintf("%d × USB-C Power Supply (5V 1A)", recNodes))
+ hardware = append(hardware, fmt.Sprintf("%d × USB-C Cable (1-2m)", recNodes))
+ hardware = append(hardware, fmt.Sprintf("%d × Adhesive Cable Clips for routing", recNodes*4))
+
+ // Amazon search URL (non-affiliate)
+ searchURL := fmt.Sprintf("https://www.amazon.com/s?k=esp32-s3+devkit+usb-c")
+
+ return ShoppingList{
+ MinimumNodes: minNodes,
+ RecommendedNodes: recNodes,
+ ExpectedAccuracy: expectedAccuracy,
+ CoveragePercent: coverageScore,
+ HardwareList: hardware,
+ AmazonSearchURL: searchURL,
+ }
+}
diff --git a/mothership/internal/simulator/engine.go b/mothership/internal/simulator/engine.go
index a0f3389..3a916b0 100644
--- a/mothership/internal/simulator/engine.go
+++ b/mothership/internal/simulator/engine.go
@@ -20,63 +20,41 @@ import (
// Engine is the pre-deployment simulator engine.
type Engine struct {
- mu sync.RWMutex
- space *SpaceDefinition
- virtualNodes []*VirtualNode
- walkers []*EngineWalker
- grid *Grid
- links []*EngineLink
- publishedResults *SimulationResult
- subscribers []chan *SimulationResult
+ mu sync.RWMutex
+ space *Space
+ nodes *NodeSet
+ walkers []*SimWalker
+ grid *Grid
+ links []Link
+ publishedResults *SimulationResult
+ subscribers []chan *SimulationResult
+ propagation *PropagationModel
+ accuracy *AccuracyEstimator
+ recommendations *RecommendationEngine
}
-// SpaceDefinition defines the monitored space.
-type SpaceDefinition struct {
- Width float64 `json:"width"` // meters
- Depth float64 `json:"depth"` // meters
- Height float64 `json:"height"` // meters
- OriginX float64 `json:"origin_x"`
- OriginZ float64 `json:"origin_z"`
-}
-
-// VirtualNode represents a virtual (planned) node position.
-type VirtualNode struct {
- ID string `json:"id"`
- Position [3]float64 `json:"position"` // x, y, z in meters
- Height float64 `json:"height"` // height in meters (same as position[2])
- Virtual bool `json:"virtual"` // true = not yet purchased
-}
-
-// Walker represents a simulated person moving through the space.
-type EngineWalker struct {
- ID string `json:"id"`
- Position [3]float64 `json:"position"` // x, y, z in meters
- Velocity [3]float64 `json:"velocity"` // vx, vy, vz in m/s
- PathType string `json:"path_type"` // "random" or "path"
- PathPoints [][3]float64 `json:"path_points,omitempty"` // for path-following
- CurrentPath int `json:"current_path"` // index in path_points
+// SimWalker represents a simulated person moving through the space.
+type SimWalker struct {
+ ID string `json:"id"`
+ Type WalkerType `json:"type"`
+ Position Point `json:"position"`
+ Velocity Point `json:"velocity"`
+ Path []Point `json:"path,omitempty"` // for path walks
+ PathIndex int `json:"path_index,omitempty"` // current position in path
+ TargetZones []string `json:"target_zones,omitempty"` // for zone walks
+ TrueHistory []Point `json:"true_history,omitempty"` // ground truth positions
}
// Grid is the 3D spatial grid for Fresnel accumulation.
type Grid struct {
- CellSize float64 `json:"cell_size"` // meters
- OriginX float64 `json:"origin_x"` // meters
- OriginZ float64 `json:"origin_z"` // meters
- WidthCells int `json:"width_cells"` // number of cells in X
- DepthCells int `json:"depth_cells"` // number of cells in Z
- HeightCells int `json:"height_cells"` // number of cells in Y (Z axis)
- Data []float64 `json:"data"` // flattened 3D array [z][x][y]
-}
-
-// Link represents a virtual WiFi link between two nodes.
-type EngineLink struct {
- ID string `json:"id"`
- TXNodeID string `json:"tx_node_id"`
- RXNodeID string `json:"rx_node_id"`
- TXPosition [3]float64 `json:"tx_position"`
- RXPosition [3]float64 `json:"rx_position"`
- Length float64 `json:"length"` // meters
- ZoneCache []*ZoneInfo `json:"zone_cache"` // per-cell zone numbers
+ CellSize float64 `json:"cell_size"` // meters
+ OriginX float64 `json:"origin_x"` // meters
+ OriginY float64 `json:"origin_y"` // meters
+ OriginZ float64 `json:"origin_z"` // meters
+ WidthCells int `json:"width_cells"` // number of cells in X
+ DepthCells int `json:"depth_cells"` // number of cells in Y
+ HeightCells int `json:"height_cells"` // number of cells in Z
+ Data []float64 `json:"data"` // flattened 3D array [z][x][y]
}
// ZoneInfo contains Fresnel zone information for a grid cell.
@@ -88,63 +66,71 @@ type ZoneInfo struct {
// SimulationResult contains the results of a simulation run.
type SimulationResult struct {
- Timestamp int64 `json:"timestamp_ms"`
- Blobs []BlobResult `json:"blobs"`
- CoverageScore float64 `json:"coverage_score"` // 0-100
- GDOPMap []float64 `json:"gdop_map"` // flattened grid
- GridDimensions []int `json:"grid_dimensions"` // [width_cells, depth_cells, height_cells]
- Recommendations []string `json:"recommendations"`
+ Timestamp int64 `json:"timestamp_ms"`
+ Blobs []BlobResult `json:"blobs"`
+ CoverageScore float64 `json:"coverage_score"` // 0-100
+ GDOPMap []float64 `json:"gdop_map"` // flattened grid
+ GridDimensions []int `json:"grid_dimensions"` // [width_cells, depth_cells, height_cells]
+ Recommendations []Recommendation `json:"recommendations"`
+ Accuracy AccuracyReport `json:"accuracy"`
+ ShoppingList ShoppingList `json:"shopping_list"`
}
// BlobResult is a simulated detection result.
type BlobResult struct {
- ID int `json:"id"`
- Position [3]float64 `json:"position"`
- Confidence float64 `json:"confidence"`
- Velocity [3]float64 `json:"velocity"`
- WalkerID string `json:"walker_id"`
+ ID int `json:"id"`
+ Position Point `json:"position"`
+ Confidence float64 `json:"confidence"`
+ Velocity Point `json:"velocity"`
+ WalkerID string `json:"walker_id"`
+ TrueError float64 `json:"true_error_m,omitempty"` // distance from true position
}
// NewEngine creates a new simulator engine.
-func NewEngine(space *SpaceDefinition) *Engine {
+func NewEngine(space *Space) *Engine {
return &Engine{
space: space,
- virtualNodes: make([]*VirtualNode, 0),
- walkers: make([]*EngineWalker, 0),
- subscribers: make([]chan *SimulationResult, 0),
+ nodes: NewNodeSet(),
+ walkers: make([]*SimWalker, 0),
+ subscribers: make([]chan *SimulationResult, 0),
+ propagation: NewPropagationModel(space),
+ accuracy: NewAccuracyEstimator(),
+ recommendations: NewRecommendationEngine(),
}
}
// SetSpace updates the space definition.
-func (e *Engine) SetSpace(space *SpaceDefinition) {
+func (e *Engine) SetSpace(space *Space) {
e.mu.Lock()
defer e.mu.Unlock()
e.space = space
+ e.propagation = NewPropagationModel(space)
e.grid = nil // Invalidate grid
}
// AddVirtualNode adds a virtual node at the specified position.
-func (e *Engine) AddVirtualNode(node *VirtualNode) error {
+func (e *Engine) AddVirtualNode(node *Node) error {
e.mu.Lock()
defer e.mu.Unlock()
// Validate position is within space
- if node.Position[0] < e.space.OriginX || node.Position[0] > e.space.OriginX+e.space.Width {
+ minX, minY, minZ, maxX, maxY, maxZ := e.space.Bounds()
+ if node.Position.X < minX || node.Position.X > maxX {
return ErrNodeOutsideSpace
}
- if node.Position[1] < e.space.OriginZ || node.Position[1] > e.space.OriginZ+e.space.Depth {
+ if node.Position.Y < minY || node.Position.Y > maxY {
return ErrNodeOutsideSpace
}
- if node.Position[2] < 0 || node.Position[2] > e.space.Height {
+ if node.Position.Z < minZ || node.Position.Z > maxZ {
return ErrNodeOutsideSpace
}
- e.virtualNodes = append(e.virtualNodes, node)
+ e.nodes.Add(node)
e.links = nil // Invalidate links
e.grid = nil // Invalidate grid
- log.Printf("[SIM] Added virtual node %s at (%.2f, %.2f, %.2f)", node.ID, node.Position[0], node.Position[1], node.Position[2])
+ log.Printf("[SIM] Added virtual node %s at (%.2f, %.2f, %.2f)", node.ID, node.Position.X, node.Position.Y, node.Position.Z)
return nil
}
@@ -154,23 +140,20 @@ func (e *Engine) RemoveVirtualNode(id string) {
e.mu.Lock()
defer e.mu.Unlock()
- for i, node := range e.virtualNodes {
- if node.ID == id {
- e.virtualNodes = append(e.virtualNodes[:i], e.virtualNodes[i+1:]...)
- e.links = nil
- e.grid = nil
- log.Printf("[SIM] Removed virtual node %s", id)
- return
- }
+ if e.nodes.Remove(id) {
+ e.links = nil
+ e.grid = nil
+ log.Printf("[SIM] Removed virtual node %s", id)
}
}
// AddWalker adds a simulated walker.
-func (e *Engine) AddWalker(walker *EngineWalker) {
+func (e *Engine) AddWalker(walker *SimWalker) {
e.mu.Lock()
defer e.mu.Unlock()
e.walkers = append(e.walkers, walker)
+ walker.TrueHistory = make([]Point, 0)
log.Printf("[SIM] Added walker %s", walker.ID)
}
@@ -189,30 +172,20 @@ func (e *Engine) RemoveWalker(id string) {
}
// GetVirtualNodes returns all virtual nodes.
-func (e *Engine) GetVirtualNodes() []*VirtualNode {
+func (e *Engine) GetVirtualNodes() []*Node {
e.mu.RLock()
defer e.mu.RUnlock()
- // Return copies to avoid mutation
- nodes := make([]*VirtualNode, len(e.virtualNodes))
- for i, n := range e.virtualNodes {
- nodeCopy := *n
- nodes[i] = &nodeCopy
- }
- return nodes
+ return e.nodes.All()
}
// GetWalkers returns all walkers.
-func (e *Engine) GetWalkers() []*EngineWalker {
+func (e *Engine) GetWalkers() []*SimWalker {
e.mu.RLock()
defer e.mu.RUnlock()
- // Return copies
- walkers := make([]*EngineWalker, len(e.walkers))
- for i, w := range e.walkers {
- walkerCopy := *w
- walkers[i] = &walkerCopy
- }
+ walkers := make([]*SimWalker, len(e.walkers))
+ copy(walkers, e.walkers)
return walkers
}
@@ -244,7 +217,13 @@ func (e *Engine) RunSimulation() *SimulationResult {
coverageScore := e.computeCoverageScore(gdopMap)
// Generate recommendations
- recommendations := e.generateRecommendations(coverageScore, gdopMap)
+ recommendations := e.recommendations.Generate(e.space, e.nodes, gdopMap, coverageScore)
+
+ // Compute accuracy
+ accuracy := e.accuracy.Compute(e.walkers, blobResults)
+
+ // Generate shopping list
+ shoppingList := GenerateShoppingListFromResults(e.space, e.nodes, coverageScore, accuracy)
result := &SimulationResult{
Timestamp: time.Now().UnixMilli(),
@@ -253,6 +232,8 @@ func (e *Engine) RunSimulation() *SimulationResult {
GDOPMap: gdopMap,
GridDimensions: []int{e.grid.WidthCells, e.grid.DepthCells, e.grid.HeightCells},
Recommendations: recommendations,
+ Accuracy: accuracy,
+ ShoppingList: shoppingList,
}
e.publishedResults = result
@@ -297,14 +278,17 @@ func (e *Engine) Unsubscribe(ch <-chan *SimulationResult) {
func (e *Engine) initializeGrid() {
const cellSize = 0.2 // 20cm cells
- widthCells := int(math.Ceil(e.space.Width / cellSize))
- depthCells := int(math.Ceil(e.space.Depth / cellSize))
- heightCells := int(math.Ceil(e.space.Height / cellSize))
+ minX, minY, minZ, maxX, maxY, maxZ := e.space.Bounds()
+
+ widthCells := int(math.Ceil((maxX - minX) / cellSize))
+ depthCells := int(math.Ceil((maxY - minY) / cellSize))
+ heightCells := int(math.Ceil((maxZ - minZ) / cellSize))
e.grid = &Grid{
CellSize: cellSize,
- OriginX: e.space.OriginX,
- OriginZ: e.space.OriginZ,
+ OriginX: minX,
+ OriginY: minY,
+ OriginZ: minZ,
WidthCells: widthCells,
DepthCells: depthCells,
HeightCells: heightCells,
@@ -316,138 +300,84 @@ func (e *Engine) initializeGrid() {
// generateLinks creates virtual links between all node pairs.
func (e *Engine) generateLinks() {
- e.links = make([]*EngineLink, 0)
-
- // Create links between all pairs of nodes
- for i, tx := range e.virtualNodes {
- for j, rx := range e.virtualNodes {
- if i >= j {
- continue // Skip duplicates and self
- }
-
- link := &Link{
- ID: tx.ID + ":" + rx.ID,
- TXNodeID: tx.ID,
- RXNodeID: rx.ID,
- TXPosition: tx.Position,
- RXPosition: rx.Position,
- }
-
- // Compute link length
- dx := rx.Position[0] - tx.Position[0]
- dy := rx.Position[1] - tx.Position[1]
- dz := rx.Position[2] - tx.Position[2]
- link.Length = math.Sqrt(dx*dx + dy*dy + dz*dz)
-
- // Precompute zone cache for this link
- link.ZoneCache = e.computeZoneCache(link)
-
- e.links = append(e.links, link)
- }
- }
-
+ e.links = GenerateAllLinks(e.nodes)
log.Printf("[SIM] Generated %d links", len(e.links))
}
-// computeZoneCache precomputes Fresnel zone numbers for all grid cells.
-func (e *Engine) computeZoneCache(link *EngineLink) []*ZoneInfo {
- const lambda = 0.123 // WiFi wavelength
- halfLambda := lambda / 2
-
- cache := make([]*ZoneInfo, 0)
-
- for z := 0; z < e.grid.HeightCells; z++ {
- for x := 0; x < e.grid.WidthCells; x++ {
- for y := 0; y < e.grid.DepthCells; y++ {
- // Cell center position
- cx := e.grid.OriginX + float64(x)*e.grid.CellSize + e.grid.CellSize/2
- cy := e.grid.OriginZ + float64(y)*e.grid.CellSize + e.grid.CellSize/2
- cz := float64(z) * e.grid.CellSize + e.grid.CellSize/2
-
- // Path length excess at this cell position
- pathViaCell := math.Sqrt(
- math.Pow(cx-link.TXPosition[0], 2) +
- math.Pow(cy-link.TXPosition[1], 2) +
- math.Pow(cz-link.TXPosition[2], 2))
- pathViaCell += math.Sqrt(
- math.Pow(link.RXPosition[0]-cx, 2) +
- math.Pow(link.RXPosition[1]-cy, 2) +
- math.Pow(link.RXPosition[2]-cz, 2))
- directPath := link.Length
-
- deltaL := pathViaCell - directPath
- zoneNumber := int(math.Ceil(deltaL / halfLambda))
-
- if zoneNumber > 5 {
- continue // Outside zone 5, skip
- }
-
- // Zone decay (default decay_rate = 2.0)
- decay := 1.0 / math.Pow(float64(zoneNumber), 2.0)
-
- cellIndex := z*e.grid.WidthCells*e.grid.DepthCells + x*e.grid.DepthCells + y
- cache = append(cache, &ZoneInfo{
- CellIndex: cellIndex,
- Zone: zoneNumber,
- Decay: decay,
- })
- }
- }
- }
-
- return cache
-}
-
// updateWalkers updates all walker positions.
func (e *Engine) updateWalkers() {
const dt = 0.1 // 100ms time step
+ minX, minY, minZ, maxX, maxY, maxZ := e.space.Bounds()
+
for _, walker := range e.walkers {
- if walker.PathType == "path" && len(walker.PathPoints) > 0 {
+ // Record true position
+ walker.TrueHistory = append(walker.TrueHistory, walker.Position)
+
+ if walker.Type == WalkerTypePath && len(walker.Path) > 0 {
// Follow path
- target := walker.PathPoints[walker.CurrentPath]
- dx := target[0] - walker.Position[0]
- dy := target[1] - walker.Position[1]
- dz := target[2] - walker.Position[2]
+ target := walker.Path[walker.PathIndex]
+ dx := target.X - walker.Position.X
+ dy := target.Y - walker.Position.Y
+ dz := target.Z - walker.Position.Z
dist := math.Sqrt(dx*dx + dy*dy + dz*dz)
- if dist < 0.1 {
+ stepSize := 0.5 / float64(10) // 0.5 m/s at 10 Hz
+
+ if dist <= stepSize {
// Reached waypoint, move to next
- walker.CurrentPath = (walker.CurrentPath + 1) % len(walker.PathPoints)
+ walker.Position = target
+ walker.PathIndex = (walker.PathIndex + 1) % len(walker.Path)
} else {
// Move toward target
- speed := 0.5 // m/s
- walker.Position[0] += (dx / dist) * speed * dt
- walker.Position[1] += (dy / dist) * speed * dt
- walker.Position[2] += (dz / dist) * speed * dt
+ walker.Position.X += (dx / dist) * stepSize
+ walker.Position.Y += (dy / dist) * stepSize
+ walker.Position.Z += (dz / dist) * stepSize
}
} else {
// Random walk
- walker.Position[0] += walker.Velocity[0] * dt
- walker.Position[1] += walker.Velocity[1] * dt
- walker.Position[2] += walker.Velocity[2] * dt
+ walker.Position.X += walker.Velocity.X * dt
+ walker.Position.Y += walker.Velocity.Y * dt
+ walker.Position.Z += walker.Velocity.Z * dt
// Bounce off walls
- if walker.Position[0] < e.space.OriginX || walker.Position[0] > e.space.OriginX+e.space.Width {
- walker.Velocity[0] *= -1
- walker.Position[0] = math.Max(e.space.OriginX, math.Min(e.space.OriginX+e.space.Width, walker.Position[0]))
+ if walker.Position.X < minX {
+ walker.Position.X = minX
+ walker.Velocity.X *= -1
}
- if walker.Position[1] < e.space.OriginZ || walker.Position[1] > e.space.OriginZ+e.space.Depth {
- walker.Velocity[1] *= -1
- walker.Position[1] = math.Max(e.space.OriginZ, math.Min(e.space.OriginZ+e.space.Depth, walker.Position[1]))
+ if walker.Position.X > maxX {
+ walker.Position.X = maxX
+ walker.Velocity.X *= -1
+ }
+ if walker.Position.Y < minY {
+ walker.Position.Y = minY
+ walker.Velocity.Y *= -1
+ }
+ if walker.Position.Y > maxY {
+ walker.Position.Y = maxY
+ walker.Velocity.Y *= -1
+ }
+ if walker.Position.Z < minZ {
+ walker.Position.Z = minZ
+ walker.Velocity.Z *= -1
+ }
+ if walker.Position.Z > maxZ {
+ walker.Position.Z = maxZ
+ walker.Velocity.Z *= -1
}
// Random velocity perturbation
- walker.Velocity[0] += (rand.Float64() - 0.5) * 0.1
- walker.Velocity[1] += (rand.Float64() - 0.5) * 0.1
+ walker.Velocity.X += (rand.Float64() - 0.5) * 0.1
+ walker.Velocity.Y += (rand.Float64() - 0.5) * 0.1
+ walker.Velocity.Z += (rand.Float64() - 0.5) * 0.05
// Clamp velocity
maxSpeed := 0.5
- speed := math.Sqrt(walker.Velocity[0]*walker.Velocity[0] + walker.Velocity[1]*walker.Velocity[1])
+ speed := math.Sqrt(walker.Velocity.X*walker.Velocity.X + walker.Velocity.Y*walker.Velocity.Y)
if speed > maxSpeed {
scale := maxSpeed / speed
- walker.Velocity[0] *= scale
- walker.Velocity[1] *= scale
+ walker.Velocity.X *= scale
+ walker.Velocity.Y *= scale
}
}
}
@@ -464,12 +394,32 @@ func (e *Engine) detectBlobs() []BlobResult {
for _, link := range e.links {
for _, walker := range e.walkers {
// Compute CSI amplitude at walker position
- amplitude := e.computeCSIAtPosition(link, walker.Position)
+ amplitude := e.propagation.AmplitudeAt(link.TX.Position, link.RX.Position, walker.Position)
// Add to grid cells covered by this link
- for _, zoneInfo := range link.ZoneCache {
- contribution := amplitude * zoneInfo.Decay
- e.grid.Data[zoneInfo.CellIndex] += contribution
+ for x := 0; x < e.grid.WidthCells; x++ {
+ for y := 0; y < e.grid.DepthCells; y++ {
+ for z := 0; z < e.grid.HeightCells; z++ {
+ // Cell center position
+ cx := e.grid.OriginX + float64(x)*e.grid.CellSize + e.grid.CellSize/2
+ cy := e.grid.OriginY + float64(y)*e.grid.CellSize + e.grid.CellSize/2
+ cz := e.grid.OriginZ + float64(z)*e.grid.CellSize + e.grid.CellSize/2
+ cellPos := Point{X: cx, Y: cy, Z: cz}
+
+ // Check if in Fresnel zone
+ zone := FresnelZoneNumber(link.TX.Position, link.RX.Position, cellPos)
+ if zone > 5 {
+ continue
+ }
+
+ // Zone decay (default decay_rate = 2.0)
+ decay := 1.0 / math.Pow(float64(zone), 2.0)
+
+ cellIndex := z*e.grid.WidthCells*e.grid.DepthCells + x*e.grid.DepthCells + y
+ contribution := amplitude * decay
+ e.grid.Data[cellIndex] += contribution
+ }
+ }
}
}
}
@@ -492,17 +442,15 @@ func (e *Engine) detectBlobs() []BlobResult {
if e.isLocalMaximum(x, y, z, value) {
// Compute position from cell index
posX := e.grid.OriginX + float64(x)*e.grid.CellSize + e.grid.CellSize/2
- posY := e.grid.OriginZ + float64(y)*e.grid.CellSize + e.grid.CellSize/2
- posZ := float64(z) * e.grid.CellSize + e.grid.CellSize/2
+ posY := e.grid.OriginY + float64(y)*e.grid.CellSize + e.grid.CellSize/2
+ posZ := e.grid.OriginZ + float64(z)*e.grid.CellSize + e.grid.CellSize/2
+ blobPos := Point{X: posX, Y: posY, Z: posZ}
- // Find nearest walker
+ // Find nearest walker and compute true error
nearestWalker := ""
- minDist := 999.0
+ minDist := 9999.0
for _, walker := range e.walkers {
- dx := walker.Position[0] - posX
- dy := walker.Position[1] - posY
- dz := walker.Position[2] - posZ
- dist := math.Sqrt(dx*dx + dy*dy + dz*dz)
+ dist := blobPos.Distance(walker.Position)
if dist < minDist {
minDist = dist
nearestWalker = walker.ID
@@ -511,9 +459,10 @@ func (e *Engine) detectBlobs() []BlobResult {
blobs = append(blobs, BlobResult{
ID: blobID,
- Position: [3]float64{posX, posY, posZ},
+ Position: blobPos,
Confidence: math.Min(1.0, value/5.0), // Normalize confidence
WalkerID: nearestWalker,
+ TrueError: minDist,
})
blobID++
}
@@ -524,33 +473,6 @@ func (e *Engine) detectBlobs() []BlobResult {
return blobs
}
-// computeCSIAtPosition computes simulated CSI amplitude at a position.
-func (e *Engine) computeCSIAtPosition(link *EngineLink, pos [3]float64) float64 {
- // Simplified path loss model
- // PL(d) = PL_0 + 10*n*log10(d/d_0)
- // PL_0 = 40 dB at d_0 = 1m, n = 2.0 (free space)
-
- dx := pos[0] - link.TXPosition[0]
- dy := pos[1] - link.TXPosition[1]
- dz := pos[2] - link.TXPosition[2]
- distFromTX := math.Sqrt(dx*dx + dy*dy + dz*dz)
-
- dx = pos[0] - link.RXPosition[0]
- dy = pos[1] - link.RXPosition[1]
- dz = pos[2] - link.RXPosition[2]
- distFromRX := math.Sqrt(dx*dx + dy*dy + dz*dz)
-
- totalDist := distFromTX + distFromRX
- pathLoss := 40.0 + 20.0*math.Log10(totalDist)
-
- // Convert path loss to linear amplitude
- // Amplitude ~ 10^(-pathLoss/20)
- amplitude := math.Pow(10.0, -pathLoss/20.0)
-
- // Scale to reasonable values
- return amplitude * 1000.0
-}
-
// isLocalMaximum checks if a cell is a local maximum in its 6-neighborhood.
func (e *Engine) isLocalMaximum(x, y, z int, value float64) bool {
// Check 6-connected neighbors
@@ -595,8 +517,8 @@ func (e *Engine) computeGDOPMap() []float64 {
// Cell position
cx := e.grid.OriginX + float64(x)*e.grid.CellSize + e.grid.CellSize/2
- cy := e.grid.OriginZ + float64(y)*e.grid.CellSize + e.grid.CellSize/2
- cz := float64(z) * e.grid.CellSize + e.grid.CellSize/2
+ cy := e.grid.OriginY + float64(y)*e.grid.CellSize + e.grid.CellSize/2
+ cz := e.grid.OriginZ + float64(z)*e.grid.CellSize + e.grid.CellSize/2
gdopMap[cellIndex] = e.computeGDOPAt(cx, cy, cz)
}
@@ -608,32 +530,25 @@ func (e *Engine) computeGDOPMap() []float64 {
// computeGDOPAt computes GDOP at a specific position.
func (e *Engine) computeGDOPAt(x, y, z float64) float64 {
+ point := Point{X: x, Y: y, Z: z}
+
// Collect links that cover this point (within zone 5)
var angles []float64
linkCount := 0
for _, link := range e.links {
// Check if this point is within zone 5
- dx := x - link.TXPosition[0]
- dy := y - link.TXPosition[1]
- dz := z - link.TXPosition[2]
- distFromTX := math.Sqrt(dx*dx + dy*dy + dz*dz)
+ d1 := point.Distance(link.TX.Position)
+ d2 := point.Distance(link.RX.Position)
+ totalDist := d1 + d2
+ deltaL := totalDist - link.TX.Position.Distance(link.RX.Position)
- dx = x - link.RXPosition[0]
- dy = y - link.RXPosition[1]
- dz = z - link.RXPosition[2]
- distFromRX := math.Sqrt(dx*dx + dy*dy + dz*dz)
-
- totalDist := distFromTX + distFromRX
- deltaL := totalDist - link.Length
-
- const halfLambda = 0.0615
- zoneNumber := int(math.Ceil(deltaL / halfLambda))
+ zoneNumber := int(math.Ceil(deltaL / HalfWavelength))
if zoneNumber <= 5 {
linkCount++
// Compute angle to link direction
- angle := math.Atan2(link.RXPosition[1]-link.TXPosition[1], link.RXPosition[0]-link.TXPosition[0])
+ angle := math.Atan2(link.RX.Position.Y-link.TX.Position.Y, link.RX.Position.X-link.TX.Position.X)
angles = append(angles, angle)
}
}
@@ -678,62 +593,11 @@ func (e *Engine) computeCoverageScore(gdopMap []float64) float64 {
return 100.0 * float64(goodCells) / float64(len(gdopMap))
}
-// generateRecommendations generates deployment recommendations.
-func (e *Engine) generateRecommendations(coverageScore float64, gdopMap []float64) []string {
- recs := make([]string, 0)
-
- if coverageScore < 50 {
- recs = append(recs, "Coverage is below 50%. Consider adding more nodes.")
- }
-
- // Find worst coverage areas
- worstX, worstY, worstZ := -1, -1, -1
- maxGDOP := 0.0
-
- for z := 0; z < e.grid.HeightCells; z++ {
- for x := 0; x < e.grid.WidthCells; x++ {
- for y := 0; y < e.grid.DepthCells; y++ {
- idx := z*e.grid.WidthCells*e.grid.DepthCells + x*e.grid.DepthCells + y
- if gdopMap[idx] > maxGDOP {
- maxGDOP = gdopMap[idx]
- worstX, worstY, worstZ = x, y, z
- }
- }
- }
- }
-
- if maxGDOP > 10.0 {
- posX := e.grid.OriginX + float64(worstX)*e.grid.CellSize
- posY := e.grid.OriginZ + float64(worstY)*e.grid.CellSize
- recs = append(recs, fmt.Sprintf("Worst coverage at (%.1f, %.1f). Consider adding a node nearby.", posX, posY))
- }
-
- // Check for node count recommendations
- nodeCount := len(e.virtualNodes)
- if nodeCount < 4 {
- recs = append(recs, fmt.Sprintf("Only %d nodes. For best accuracy, use at least 4 nodes.", nodeCount))
- }
-
- // Check height diversity
- hasLow, hasHigh := false, false
- for _, node := range e.virtualNodes {
- if node.Position[2] < 1.0 {
- hasLow = true
- }
- if node.Position[2] > 2.0 {
- hasHigh = true
- }
- }
-
- if !hasLow || !hasHigh {
- recs = append(recs, "For better Z-axis accuracy, place nodes at mixed heights (some low, some high).")
- }
-
- if len(recs) == 0 {
- recs = append(recs, "Coverage looks good! No specific recommendations.")
- }
-
- return recs
+// GetResults returns the most recent simulation results from the engine.
+func (e *Engine) GetResults() *SimulationResult {
+ e.mu.RLock()
+ defer e.mu.RUnlock()
+ return e.publishedResults
}
// Errors
diff --git a/mothership/internal/simulator/handler.go b/mothership/internal/simulator/handler.go
index 29c5eac..a52180a 100644
--- a/mothership/internal/simulator/handler.go
+++ b/mothership/internal/simulator/handler.go
@@ -37,6 +37,8 @@ func (h *Handler) RegisterRoutes(r chi.Router) {
r.Delete("/api/simulator/walkers/{id}", h.removeWalker)
r.Post("/api/simulator/simulate", h.simulate)
r.Get("/api/simulator/results", h.getResults)
+ r.Post("/api/simulator/gdop", h.computeGDOP)
+ r.Get("/api/simulator/status", h.getStatus)
r.Post("/api/simulator/subscribe", h.subscribe)
}
@@ -45,25 +47,28 @@ func (h *Handler) getSpace(w http.ResponseWriter, r *http.Request) {
h.mu.RLock()
defer h.mu.RUnlock()
- nodes := h.engine.GetVirtualNodes()
- space := h.getSpaceFromNodes(nodes)
-
+ space := h.engine.space
writeJSON(w, space)
}
// setSpace handles PUT /api/simulator/space
func (h *Handler) setSpace(w http.ResponseWriter, r *http.Request) {
- var space SpaceDefinition
+ var space Space
if err := json.NewDecoder(r.Body).Decode(&space); err != nil {
http.Error(w, "Invalid request body", http.StatusBadRequest)
return
}
+ if err := space.Validate(); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+
h.mu.Lock()
h.engine.SetSpace(&space)
h.mu.Unlock()
- log.Printf("[SIM] Space updated: %.1fx%.1fx%.1f m", space.Width, space.Depth, space.Height)
+ log.Printf("[SIM] Space updated: %s", space.ID)
writeJSON(w, map[string]interface{}{
"ok": true,
@@ -78,7 +83,7 @@ func (h *Handler) getNodes(w http.ResponseWriter, r *http.Request) {
// addNode handles POST /api/simulator/nodes
func (h *Handler) addNode(w http.ResponseWriter, r *http.Request) {
- var node VirtualNode
+ var node Node
if err := json.NewDecoder(r.Body).Decode(&node); err != nil {
http.Error(w, "Invalid request body", http.StatusBadRequest)
return
@@ -88,6 +93,10 @@ func (h *Handler) addNode(w http.ResponseWriter, r *http.Request) {
node.ID = fmt.Sprintf("node_%d", time.Now().UnixNano())
}
+ if node.Type == "" {
+ node.Type = NodeTypeVirtual
+ }
+
if err := h.engine.AddVirtualNode(&node); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
@@ -114,7 +123,7 @@ func (h *Handler) getWalkers(w http.ResponseWriter, r *http.Request) {
// addWalker handles POST /api/simulator/walkers
func (h *Handler) addWalker(w http.ResponseWriter, r *http.Request) {
- var walker Walker
+ var walker SimWalker
if err := json.NewDecoder(r.Body).Decode(&walker); err != nil {
http.Error(w, "Invalid request body", http.StatusBadRequest)
return
@@ -124,6 +133,10 @@ func (h *Handler) addWalker(w http.ResponseWriter, r *http.Request) {
walker.ID = fmt.Sprintf("walker_%d", time.Now().UnixNano())
}
+ if walker.Type == "" {
+ walker.Type = WalkerTypeRandom
+ }
+
h.engine.AddWalker(&walker)
writeJSON(w, walker)
@@ -142,6 +155,17 @@ func (h *Handler) removeWalker(w http.ResponseWriter, r *http.Request) {
// simulate handles POST /api/simulator/simulate
// Runs one simulation tick and returns results.
func (h *Handler) simulate(w http.ResponseWriter, r *http.Request) {
+ var req struct {
+ DurationSec int `json:"duration_sec"`
+ TickRateHz int `json:"tick_rate_hz"`
+ }
+
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ // Use defaults if request body is empty
+ req.DurationSec = 30
+ req.TickRateHz = 10
+ }
+
result := h.engine.RunSimulation()
writeJSON(w, result)
}
@@ -157,6 +181,58 @@ func (h *Handler) getResults(w http.ResponseWriter, r *http.Request) {
writeJSON(w, result)
}
+// computeGDOP handles POST /api/simulator/gdop
+func (h *Handler) computeGDOP(w http.ResponseWriter, r *http.Request) {
+ var req struct {
+ Nodes []Node `json:"nodes"`
+ Space *Space `json:"space"`
+ }
+
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ http.Error(w, "Invalid request body", http.StatusBadRequest)
+ return
+ }
+
+ if req.Space == nil {
+ req.Space = DefaultSpace()
+ }
+
+ // Create temporary engine for GDOP computation
+ engine := NewEngine(req.Space)
+ for _, node := range req.Nodes {
+ engine.AddVirtualNode(&node)
+ }
+
+ // Run simulation to get GDOP map
+ result := engine.RunSimulation()
+
+ writeJSON(w, map[string]interface{}{
+ "gdop_map": result.GDOPMap,
+ "grid_dimensions": result.GridDimensions,
+ "coverage_score": result.CoverageScore,
+ })
+}
+
+// getStatus handles GET /api/simulator/status
+func (h *Handler) getStatus(w http.ResponseWriter, r *http.Request) {
+ result := h.engine.GetResults()
+
+ walkerPositions := make([]map[string]interface{}, 0)
+ if result != nil {
+ for _, blob := range result.Blobs {
+ walkerPositions = append(walkerPositions, map[string]interface{}{
+ "id": blob.WalkerID,
+ "position": blob.Position,
+ })
+ }
+ }
+
+ writeJSON(w, map[string]interface{}{
+ "state": "running",
+ "walker_positions": walkerPositions,
+ })
+}
+
// subscribe handles POST /api/simulator/subscribe
// Creates Server-Sent Events stream for simulation updates.
func (h *Handler) subscribe(w http.ResponseWriter, r *http.Request) {
@@ -202,56 +278,6 @@ func (h *Handler) subscribe(w http.ResponseWriter, r *http.Request) {
}
}
-// GetEngine returns the simulator engine for direct access.
-func (h *Handler) GetEngine() *Engine {
- return h.engine
-}
-
-// getSpaceFromNodes derives space bounds from node positions.
-func (h *Handler) getSpaceFromNodes(nodes []*VirtualNode) *SpaceDefinition {
- if len(nodes) == 0 {
- return &SpaceDefinition{
- Width: 10, Depth: 10, Height: 2.5,
- OriginX: 0, OriginZ: 0,
- }
- }
-
- minX, maxX := nodes[0].Position[0], nodes[0].Position[0]
- minY, maxY := nodes[0].Position[1], nodes[0].Position[1]
- minZ, maxZ := nodes[0].Position[2], nodes[0].Position[2]
-
- for _, node := range nodes {
- if node.Position[0] < minX {
- minX = node.Position[0]
- }
- if node.Position[0] > maxX {
- maxX = node.Position[0]
- }
- if node.Position[1] < minY {
- minY = node.Position[1]
- }
- if node.Position[1] > maxY {
- maxY = node.Position[1]
- }
- if node.Position[2] < minZ {
- minZ = node.Position[2]
- }
- if node.Position[2] > maxZ {
- maxZ = node.Position[2]
- }
- }
-
- // Add margin
- margin := 0.5
- return &SpaceDefinition{
- Width: (maxX - minX) + 2*margin,
- Depth: (maxY - minY) + 2*margin,
- Height: maxZ + 0.5, // Floor to ceiling
- OriginX: minX - margin,
- OriginZ: minY - margin,
- }
-}
-
// sendSSEEvent sends an SSE event.
func sendSSEEvent(w http.ResponseWriter, event string, data interface{}) {
jsonData, err := json.Marshal(data)
@@ -276,10 +302,3 @@ func writeJSON(w http.ResponseWriter, v interface{}) {
}
w.Write(data)
}
-
-// GetResults returns the most recent simulation results from the engine.
-func (e *Engine) GetResults() *SimulationResult {
- e.mu.RLock()
- defer e.mu.RUnlock()
- return e.publishedResults
-}
diff --git a/mothership/internal/simulator/session.go b/mothership/internal/simulator/session.go
new file mode 100644
index 0000000..49200c2
--- /dev/null
+++ b/mothership/internal/simulator/session.go
@@ -0,0 +1,412 @@
+// Package simulator provides pre-deployment simulation capabilities.
+//
+// It allows users to model their space, place virtual nodes, and run
+// synthetic walkers to estimate expected accuracy before purchasing hardware.
+package simulator
+
+import (
+ "encoding/json"
+ "fmt"
+ "log"
+ "math"
+ "sync"
+ "time"
+)
+
+// Session represents a simulation session.
+type Session struct {
+ mu sync.RWMutex
+ id string
+ space *Space
+ nodes []*VirtualNode
+ walkers []*Walker
+ params *SimulationParams
+ state SessionState
+ created_at int64
+ updated_at int64
+ ctx chan struct{}
+}
+
+// SessionState is the state of a simulation session.
+type SessionState string
+
+const (
+ StateSetup SessionState = "setup"
+ StateRunning SessionState = "running"
+ StatePaused SessionState = "paused"
+ StateComplete SessionState = "complete"
+)
+
+// Space represents the simulated physical space.
+type Space struct {
+ Width float64 `json:"width"` // meters
+ Depth float64 `json:"depth"` // meters
+ Height float64 `json:"height"` // meters
+ Walls []Wall `json:"walls"`
+}
+
+// Wall represents a wall segment that affects signal propagation.
+type Wall struct {
+ X1 float64 `json:"x1"` // start point (meters)
+ Y1 float64 `json:"y1"`
+ X2 float64 `json:"x2"` // end point (meters)
+ Y2 float64 `json:"y2"`
+ Material string `json:"material"` // "drywall", "brick", "concrete", "glass", "metal"
+}
+
+// Wall attenuation values in dB
+var wallAttenuationDB = map[string]float64{
+ "drywall": 3.0,
+ "brick": 10.0,
+ "concrete": 10.0,
+ "glass": 2.0,
+ "metal": 20.0,
+}
+
+// VirtualNode represents a simulated node.
+type VirtualNode struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Position Vector3 `json:"position"` // x, y, z in meters
+ Role string `json:"role"` // "tx", "rx", "tx_rx"
+}
+
+// Vector3 represents a 3D position.
+type Vector3 struct {
+ X float64 `json:"x"`
+ Y float64 `json:"y"`
+ Z float64 `json:"z"`
+}
+
+// Walker represents a simulated person moving through the space.
+type Walker struct {
+ ID string `json:"id"`
+ Type WalkerType `json:"type"`
+ Position Vector3 `json:"position"`
+ Velocity Vector3 `json:"velocity"`
+ Path []Vector3 `json:"path,omitempty"` // for path walks
+ PathIndex int `json:"path_index,omitempty"` // current position in path
+ TargetZones []string `json:"target_zones,omitempty"` // for zone walks
+}
+
+// WalkerType defines the type of walker movement.
+type WalkerType string
+
+const (
+ WalkerTypeRandom WalkerType = "random"
+ WalkerTypePath WalkerType = "path"
+ WalkerTypeZone WalkerType = "zone"
+)
+
+// SimulationParams holds simulation parameters.
+type SimulationParams struct {
+ TickRateHz int `json:"tick_rate_hz"` // 10 Hz default
+ WalkerSpeed float64 `json:"walker_speed"` // m/s
+ SignalAmplitude float64 `json:"signal_amplitude"` // 0.05
+ FresnelSigma float64 `json:"fresnel_sigma"` // 0.3m
+ NoiseSigma float64 `json:"noise_sigma"` // Gaussian noise std dev
+ DefaultRSSI float64 `json:"default_rssi"` // -30 dBm at 1m
+ WallAttenuationDB float64 `json:"wall_attenuation_db"` // default 4 dB
+}
+
+// DefaultSimulationParams returns the default simulation parameters.
+func DefaultSimulationParams() *SimulationParams {
+ return &SimulationParams{
+ TickRateHz: 10,
+ WalkerSpeed: 1.0,
+ SignalAmplitude: 0.05,
+ FresnelSigma: 0.3,
+ NoiseSigma: 0.01,
+ DefaultRSSI: -30.0,
+ WallAttenuationDB: 4.0,
+ }
+}
+
+// NewSession creates a new simulation session.
+func NewSession(id string, space *Space) *Session {
+ return &Session{
+ id: id,
+ space: space,
+ nodes: []*VirtualNode{},
+ walkers: []*Walker{},
+ params: DefaultSimulationParams(),
+ state: StateSetup,
+ created_at: time.Now().UnixMilli(),
+ updated_at: time.Now().UnixMilli(),
+ ctx: make(chan struct{}),
+ }
+}
+
+// ID returns the session ID.
+func (s *Session) ID() string {
+ return s.id
+}
+
+// State returns the current session state.
+func (s *Session) State() SessionState {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+ return s.state
+}
+
+// AddNode adds a virtual node to the simulation.
+func (s *Session) AddNode(node *VirtualNode) error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ if s.state != StateSetup {
+ return fmt.Errorf("cannot add nodes in state %s", s.state)
+ }
+
+ s.nodes = append(s.nodes, node)
+ s.updated_at = time.Now().UnixMilli()
+ return nil
+}
+
+// RemoveNode removes a virtual node from the simulation.
+func (s *Session) RemoveNode(nodeID string) error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ if s.state != StateSetup {
+ return fmt.Errorf("cannot remove nodes in state %s", s.state)
+ }
+
+ for i, node := range s.nodes {
+ if node.ID == nodeID {
+ s.nodes = append(s.nodes[:i], s.nodes[i+1:]...)
+ s.updated_at = time.Now().UnixMilli()
+ return nil
+ }
+ }
+ return fmt.Errorf("node not found: %s", nodeID)
+}
+
+// AddWalker adds a walker to the simulation.
+func (s *Session) AddWalker(walker *Walker) error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ if s.state != StateSetup {
+ return fmt.Errorf("cannot add walkers in state %s", s.state)
+ }
+
+ s.walkers = append(s.walkers, walker)
+ s.updated_at = time.Now().UnixMilli()
+ return nil
+}
+
+// Start starts the simulation.
+func (s *Session) Start() error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ if s.state != StateSetup && s.state != StatePaused {
+ return fmt.Errorf("cannot start in state %s", s.state)
+ }
+
+ if len(s.nodes) < 2 {
+ return fmt.Errorf("need at least 2 nodes for simulation")
+ }
+
+ if len(s.walkers) == 0 {
+ return fmt.Errorf("need at least 1 walker for simulation")
+ }
+
+ s.state = StateRunning
+ s.updated_at = time.Now().UnixMilli()
+
+ // Start simulation loop in background
+ go s.simulationLoop()
+
+ return nil
+}
+
+// Pause pauses the simulation.
+func (s *Session) Pause() error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ if s.state != StateRunning {
+ return fmt.Errorf("cannot pause in state %s", s.state)
+ }
+
+ s.state = StatePaused
+ s.updated_at = time.Now().UnixMilli()
+ return nil
+}
+
+// Stop stops the simulation.
+func (s *Session) Stop() error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ if s.state != StateRunning && s.state != StatePaused {
+ return fmt.Errorf("cannot stop in state %s", s.state)
+ }
+
+ s.state = StateComplete
+ close(s.ctx)
+ s.updated_at = time.Now().UnixMilli()
+ return nil
+}
+
+// simulationLoop runs the main simulation loop.
+func (s *Session) simulationLoop() {
+ ticker := time.NewTicker(time.Second / time.Duration(s.params.TickRateHz))
+ defer ticker.Stop()
+
+ for {
+ select {
+ case <-ticker.C:
+ s.mu.Lock()
+ if s.state != StateRunning {
+ s.mu.Unlock()
+ continue
+ }
+
+ // Update walker positions
+ for _, walker := range s.walkers {
+ s.updateWalkerPosition(walker)
+ }
+
+ s.updated_at = time.Now().UnixMilli()
+ s.mu.Unlock()
+
+ case <-s.ctx:
+ return
+ }
+ }
+}
+
+// updateWalkerPosition updates a single walker's position based on its type.
+func (s *Session) updateWalkerPosition(walker *Walker) {
+ switch walker.Type {
+ case WalkerTypeRandom:
+ s.updateRandomWalker(walker)
+ case WalkerTypePath:
+ s.updatePathWalker(walker)
+ case WalkerTypeZone:
+ s.updateZoneWalker(walker)
+ }
+}
+
+// updateRandomWalker updates a random walker using Gaussian velocity updates.
+func (s *Session) updateRandomWalker(walker *Walker) {
+ // Apply velocity with small random changes
+ walker.Position.X += walker.Velocity.X / float64(s.params.TickRateHz)
+ walker.Position.Y += walker.Velocity.Y / float64(s.params.TickRateHz)
+
+ // Random velocity changes
+ velocityChange := 0.5 / float64(s.params.TickRateHz)
+ walker.Velocity.X += (randFloat64()*2 - 1) * velocityChange
+ walker.Velocity.Y += (randFloat64()*2 - 1) * velocityChange
+
+ // Clamp velocity to max speed
+ maxSpeed := s.params.WalkerSpeed
+ speed := math.Sqrt(walker.Velocity.X*walker.Velocity.X + walker.Velocity.Y*walker.Velocity.Y)
+ if speed > maxSpeed {
+ scale := maxSpeed / speed
+ walker.Velocity.X *= scale
+ walker.Velocity.Y *= scale
+ }
+
+ // Bounce off walls
+ if walker.Position.X < 0 {
+ walker.Position.X = 0
+ walker.Velocity.X *= -1
+ }
+ if walker.Position.X > s.space.Width {
+ walker.Position.X = s.space.Width
+ walker.Velocity.X *= -1
+ }
+ if walker.Position.Y < 0 {
+ walker.Position.Y = 0
+ walker.Velocity.Y *= -1
+ }
+ if walker.Position.Y > s.space.Depth {
+ walker.Position.Y = s.space.Depth
+ walker.Velocity.Y *= -1
+ }
+}
+
+// updatePathWalker updates a path-following walker.
+func (s *Session) updatePathWalker(walker *Walker) {
+ if len(walker.Path) == 0 {
+ return
+ }
+
+ target := walker.Path[walker.PathIndex]
+ dx := target.X - walker.Position.X
+ dy := target.Y - walker.Position.Y
+ distance := math.Sqrt(dx*dx + dy*dy)
+
+ stepSize := s.params.WalkerSpeed / float64(s.params.TickRateHz)
+
+ if distance <= stepSize {
+ // Reached target, move to next waypoint
+ walker.Position = target
+ walker.PathIndex = (walker.PathIndex + 1) % len(walker.Path)
+ } else {
+ // Move toward target
+ walker.Position.X += (dx / distance) * stepSize
+ walker.Position.Y += (dy / distance) * stepSize
+ }
+}
+
+// updateZoneWalker updates a zone-walking walker.
+func (s *Session) updateZoneWalker(walker *Walker) {
+ // For now, treat zone walkers as random walkers
+ // TODO: Implement zone-based movement
+ s.updateRandomWalker(walker)
+}
+
+// GetSnapshot returns the current simulation state.
+func (s *Session) GetSnapshot() *SessionSnapshot {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+
+ walkerPositions := make([]WalkerPosition, len(s.walkers))
+ for i, w := range s.walkers {
+ walkerPositions[i] = WalkerPosition{
+ ID: w.ID,
+ Position: w.Position,
+ }
+ }
+
+ return &SessionSnapshot{
+ ID: s.id,
+ State: s.state,
+ Space: s.space,
+ NodeCount: len(s.nodes),
+ WalkerPositions: walkerPositions,
+ UpdatedAt: s.updated_at,
+ }
+}
+
+// SessionSnapshot represents a point-in-time snapshot of the simulation.
+type SessionSnapshot struct {
+ ID string `json:"id"`
+ State SessionState `json:"state"`
+ Space *Space `json:"space"`
+ NodeCount int `json:"node_count"`
+ WalkerPositions []WalkerPosition `json:"walker_positions"`
+ UpdatedAt int64 `json:"updated_at"`
+}
+
+// WalkerPosition represents a walker's position at a point in time.
+type WalkerPosition struct {
+ ID string `json:"id"`
+ Position Vector3 `json:"position"`
+}
+
+// randFloat64 returns a random float64 in [0, 1).
+func randFloat64() float64 {
+ return float64(time.Now().UnixNano()%1000) / 1000.0
+}
+
+// ToJSON converts the session to JSON.
+func (s *Session) ToJSON() ([]byte, error) {
+ snapshot := s.GetSnapshot()
+ return json.Marshal(snapshot)
+}