docs: update UI README with sensing tab, Rust backend, data sources
Reflects current state: Rust sensing server as primary backend, sensing tab with 3D signal field, data source indicators, estimation mode badge, setup guide, Docker deployment with CSI_SOURCE, and updated file tree with all components/services. Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
parent
8166d8d822
commit
9dd61bdbfa
403
ui/README.md
403
ui/README.md
|
|
@ -1,46 +1,73 @@
|
||||||
# WiFi DensePose UI
|
# WiFi DensePose UI
|
||||||
|
|
||||||
A modular, modern web interface for the WiFi DensePose human tracking system. This UI provides real-time monitoring, configuration, and visualization of WiFi-based pose estimation.
|
A modular, modern web interface for the WiFi DensePose human tracking system. Provides real-time monitoring, WiFi sensing visualization, and pose estimation from CSI (Channel State Information).
|
||||||
|
|
||||||
## ๐๏ธ Architecture
|
## Architecture
|
||||||
|
|
||||||
The UI follows a modular architecture with clear separation of concerns:
|
The UI follows a modular architecture with clear separation of concerns:
|
||||||
|
|
||||||
```
|
```
|
||||||
ui/
|
ui/
|
||||||
โโโ app.js # Main application entry point
|
โโโ app.js # Main application entry point
|
||||||
โโโ index.html # Updated HTML with modular structure
|
โโโ index.html # HTML shell with tab structure
|
||||||
โโโ style.css # Complete CSS with additional styles
|
โโโ style.css # Complete CSS design system
|
||||||
โโโ config/ # Configuration modules
|
โโโ config/
|
||||||
โ โโโ api.config.js # API endpoints and configuration
|
โ โโโ api.config.js # API endpoints and configuration
|
||||||
โโโ services/ # Service layer for API communication
|
โโโ services/
|
||||||
โ โโโ api.service.js # HTTP API client
|
โ โโโ api.service.js # HTTP API client
|
||||||
โ โโโ websocket.service.js # WebSocket client
|
โ โโโ websocket.service.js # WebSocket connection manager
|
||||||
โ โโโ pose.service.js # Pose estimation API wrapper
|
โ โโโ websocket-client.js # Low-level WebSocket client
|
||||||
โ โโโ health.service.js # Health monitoring API wrapper
|
โ โโโ pose.service.js # Pose estimation API wrapper
|
||||||
โ โโโ stream.service.js # Streaming API wrapper
|
โ โโโ sensing.service.js # WiFi sensing data service (live + simulation fallback)
|
||||||
โโโ components/ # UI components
|
โ โโโ health.service.js # Health monitoring API wrapper
|
||||||
โ โโโ TabManager.js # Tab navigation component
|
โ โโโ stream.service.js # Streaming API wrapper
|
||||||
โ โโโ DashboardTab.js # Dashboard component with live data
|
โ โโโ data-processor.js # Signal data processing utilities
|
||||||
โ โโโ HardwareTab.js # Hardware configuration component
|
โโโ components/
|
||||||
โ โโโ LiveDemoTab.js # Live demo with streaming
|
โ โโโ TabManager.js # Tab navigation component
|
||||||
โโโ utils/ # Utility functions and helpers
|
โ โโโ DashboardTab.js # Dashboard with live system metrics
|
||||||
โ โโโ mock-server.js # Mock server for testing
|
โ โโโ SensingTab.js # WiFi sensing visualization (3D signal field, metrics)
|
||||||
โโโ tests/ # Comprehensive test suite
|
โ โโโ LiveDemoTab.js # Live pose detection with setup guide
|
||||||
โโโ test-runner.html # Test runner UI
|
โ โโโ HardwareTab.js # Hardware configuration
|
||||||
โโโ test-runner.js # Test framework and cases
|
โ โโโ SettingsPanel.js # Settings panel
|
||||||
โโโ integration-test.html # Integration testing page
|
โ โโโ PoseDetectionCanvas.js # Canvas-based pose skeleton renderer
|
||||||
|
โ โโโ gaussian-splats.js # 3D Gaussian splat signal field renderer (Three.js)
|
||||||
|
โ โโโ body-model.js # 3D body model
|
||||||
|
โ โโโ scene.js # Three.js scene management
|
||||||
|
โ โโโ signal-viz.js # Signal visualization utilities
|
||||||
|
โ โโโ environment.js # Environment/room visualization
|
||||||
|
โ โโโ dashboard-hud.js # Dashboard heads-up display
|
||||||
|
โโโ utils/
|
||||||
|
โ โโโ backend-detector.js # Auto-detect backend availability
|
||||||
|
โ โโโ mock-server.js # Mock server for testing
|
||||||
|
โ โโโ pose-renderer.js # Pose rendering utilities
|
||||||
|
โโโ tests/
|
||||||
|
โโโ test-runner.html # Test runner UI
|
||||||
|
โโโ test-runner.js # Test framework and cases
|
||||||
|
โโโ integration-test.html # Integration testing page
|
||||||
```
|
```
|
||||||
|
|
||||||
## ๐ Features
|
## Features
|
||||||
|
|
||||||
### Smart Backend Detection
|
### WiFi Sensing Tab
|
||||||
- **Automatic Detection**: Automatically detects if your FastAPI backend is running
|
- 3D Gaussian-splat signal field visualization (Three.js)
|
||||||
- **Real Backend Priority**: Always uses the real backend when available
|
- Real-time RSSI, variance, motion band, breathing band metrics
|
||||||
- **Mock Fallback**: Falls back to mock server only when backend is unavailable
|
- Presence/motion classification with confidence scores
|
||||||
- **Testing Mode**: Can force mock mode for testing and development
|
- **Data source banner**: green "LIVE - ESP32", yellow "RECONNECTING...", or red "SIMULATED DATA"
|
||||||
|
- Sparkline RSSI history graph
|
||||||
|
- "About This Data" card explaining CSI capabilities per sensor count
|
||||||
|
|
||||||
### Real-time Dashboard
|
### Live Demo Tab
|
||||||
|
- WebSocket-based real-time pose skeleton rendering
|
||||||
|
- **Estimation Mode badge**: green "Signal-Derived" or blue "Model Inference"
|
||||||
|
- **Setup Guide panel** showing what each ESP32 count provides:
|
||||||
|
- 1 ESP32: presence, breathing, gross motion
|
||||||
|
- 2-3 ESP32s: body localization, motion direction
|
||||||
|
- 4+ ESP32s + trained model: individual limb tracking, full pose
|
||||||
|
- Debug mode with log export
|
||||||
|
- Zone selection and force-reconnect controls
|
||||||
|
- Performance metrics sidebar (frames, uptime, errors)
|
||||||
|
|
||||||
|
### Dashboard
|
||||||
- Live system health monitoring
|
- Live system health monitoring
|
||||||
- Real-time pose detection statistics
|
- Real-time pose detection statistics
|
||||||
- Zone occupancy tracking
|
- Zone occupancy tracking
|
||||||
|
|
@ -53,284 +80,118 @@ ui/
|
||||||
- Configuration panels
|
- Configuration panels
|
||||||
- Hardware status monitoring
|
- Hardware status monitoring
|
||||||
|
|
||||||
### Live Demo
|
## Data Sources
|
||||||
- WebSocket-based real-time streaming
|
|
||||||
- Signal visualization
|
|
||||||
- Pose detection visualization
|
|
||||||
- Interactive controls
|
|
||||||
|
|
||||||
### API Integration
|
The sensing service (`sensing.service.js`) supports three connection states:
|
||||||
- Complete REST API coverage
|
|
||||||
- WebSocket streaming support
|
|
||||||
- Authentication handling
|
|
||||||
- Error management
|
|
||||||
- Request/response interceptors
|
|
||||||
|
|
||||||
## ๐ API Coverage
|
| State | Banner Color | Description |
|
||||||
|
|-------|-------------|-------------|
|
||||||
|
| **LIVE - ESP32** | Green | Connected to the Rust sensing server receiving real CSI data |
|
||||||
|
| **RECONNECTING** | Yellow (pulsing) | WebSocket disconnected, retrying (up to 20 attempts) |
|
||||||
|
| **SIMULATED DATA** | Red | Fallback to client-side simulation after 5+ failed reconnects |
|
||||||
|
|
||||||
The UI integrates with all WiFi DensePose API endpoints:
|
Simulated frames include a `_simulated: true` marker so code can detect synthetic data.
|
||||||
|
|
||||||
### Health Endpoints
|
## Backends
|
||||||
- `GET /health/health` - System health check
|
|
||||||
- `GET /health/ready` - Readiness check
|
|
||||||
- `GET /health/live` - Liveness check
|
|
||||||
- `GET /health/metrics` - System metrics
|
|
||||||
- `GET /health/version` - Version information
|
|
||||||
|
|
||||||
### Pose Estimation
|
### Rust Sensing Server (primary)
|
||||||
- `GET /api/v1/pose/current` - Current pose data
|
The Rust-based `wifi-densepose-sensing-server` serves the UI and provides:
|
||||||
- `POST /api/v1/pose/analyze` - Trigger analysis
|
- `GET /health` โ server health
|
||||||
- `GET /api/v1/pose/zones/{zone_id}/occupancy` - Zone occupancy
|
- `GET /api/v1/sensing/latest` โ latest sensing features
|
||||||
- `GET /api/v1/pose/zones/summary` - All zones summary
|
- `GET /api/v1/vital-signs` โ vital sign estimates (HR/RR)
|
||||||
- `POST /api/v1/pose/historical` - Historical data
|
- `GET /api/v1/model/info` โ RVF model container info
|
||||||
- `GET /api/v1/pose/activities` - Recent activities
|
- `WS /ws/sensing` โ real-time sensing data stream
|
||||||
- `POST /api/v1/pose/calibrate` - System calibration
|
- `WS /api/v1/stream/pose` โ real-time pose keypoint stream
|
||||||
- `GET /api/v1/pose/stats` - Statistics
|
|
||||||
|
|
||||||
### Streaming
|
### Python FastAPI (legacy)
|
||||||
- `WS /api/v1/stream/pose` - Real-time pose stream
|
The original Python backend on port 8000 is still supported. The UI auto-detects which backend is available via `backend-detector.js`.
|
||||||
- `WS /api/v1/stream/events` - Event stream
|
|
||||||
- `GET /api/v1/stream/status` - Stream status
|
|
||||||
- `POST /api/v1/stream/start` - Start streaming
|
|
||||||
- `POST /api/v1/stream/stop` - Stop streaming
|
|
||||||
- `GET /api/v1/stream/clients` - Connected clients
|
|
||||||
- `DELETE /api/v1/stream/clients/{client_id}` - Disconnect client
|
|
||||||
|
|
||||||
## ๐งช Testing
|
## Quick Start
|
||||||
|
|
||||||
### Test Runner
|
|
||||||
Open `tests/test-runner.html` to run the complete test suite:
|
|
||||||
|
|
||||||
|
### With Docker (recommended)
|
||||||
```bash
|
```bash
|
||||||
# Serve the UI directory on port 3000 (to avoid conflicts with FastAPI on 8000)
|
cd docker/
|
||||||
cd /workspaces/wifi-densepose/ui
|
|
||||||
|
# Default: auto-detects ESP32 on UDP 5005, falls back to simulation
|
||||||
|
docker-compose up
|
||||||
|
|
||||||
|
# Force real ESP32 data
|
||||||
|
CSI_SOURCE=esp32 docker-compose up
|
||||||
|
|
||||||
|
# Force simulation (no hardware needed)
|
||||||
|
CSI_SOURCE=simulated docker-compose up
|
||||||
|
```
|
||||||
|
Open http://localhost:3000/ui/index.html
|
||||||
|
|
||||||
|
### With local Rust binary
|
||||||
|
```bash
|
||||||
|
cd rust-port/wifi-densepose-rs
|
||||||
|
cargo build -p wifi-densepose-sensing-server --no-default-features
|
||||||
|
|
||||||
|
# Run with simulated data
|
||||||
|
../../target/debug/sensing-server --source simulated --tick-ms 100 --ui-path ../../ui --http-port 3000
|
||||||
|
|
||||||
|
# Run with real ESP32
|
||||||
|
../../target/debug/sensing-server --source esp32 --tick-ms 100 --ui-path ../../ui --http-port 3000
|
||||||
|
```
|
||||||
|
Open http://localhost:3000/ui/index.html
|
||||||
|
|
||||||
|
### With Python HTTP server (legacy)
|
||||||
|
```bash
|
||||||
|
# Start FastAPI backend on port 8000
|
||||||
|
wifi-densepose start
|
||||||
|
|
||||||
|
# Serve the UI on port 3000
|
||||||
|
cd ui/
|
||||||
python -m http.server 3000
|
python -m http.server 3000
|
||||||
# Open http://localhost:3000/tests/test-runner.html
|
|
||||||
```
|
```
|
||||||
|
Open http://localhost:3000
|
||||||
|
|
||||||
### Test Categories
|
## Pose Estimation Modes
|
||||||
- **API Configuration Tests** - Configuration and URL building
|
|
||||||
- **API Service Tests** - HTTP client functionality
|
|
||||||
- **WebSocket Service Tests** - WebSocket connection management
|
|
||||||
- **Pose Service Tests** - Pose estimation API wrapper
|
|
||||||
- **Health Service Tests** - Health monitoring functionality
|
|
||||||
- **UI Component Tests** - Component behavior and interaction
|
|
||||||
- **Integration Tests** - End-to-end functionality
|
|
||||||
|
|
||||||
### Integration Testing
|
| Mode | Badge | Requirements | Accuracy |
|
||||||
Use `tests/integration-test.html` for visual integration testing:
|
|------|-------|-------------|----------|
|
||||||
|
| **Signal-Derived** | Green | 1+ ESP32, no model needed | Presence, breathing, gross motion |
|
||||||
|
| **Model Inference** | Blue | 4+ ESP32s + trained `.rvf` model | Full 17-keypoint COCO pose |
|
||||||
|
|
||||||
|
To use model inference, start the server with a trained model:
|
||||||
```bash
|
```bash
|
||||||
# Open http://localhost:3000/tests/integration-test.html
|
sensing-server --source esp32 --model path/to/model.rvf --ui-path ./ui
|
||||||
```
|
```
|
||||||
|
|
||||||
Features:
|
## Configuration
|
||||||
- Mock server with realistic API responses
|
|
||||||
- Visual testing of all components
|
|
||||||
- Real-time data simulation
|
|
||||||
- Error scenario testing
|
|
||||||
- WebSocket stream testing
|
|
||||||
|
|
||||||
## ๐ ๏ธ Usage
|
|
||||||
|
|
||||||
### Basic Setup
|
|
||||||
```html
|
|
||||||
<!DOCTYPE html>
|
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<link rel="stylesheet" href="style.css">
|
|
||||||
</head>
|
|
||||||
<body>
|
|
||||||
<div class="container">
|
|
||||||
<!-- Your content -->
|
|
||||||
</div>
|
|
||||||
<script type="module" src="app.js"></script>
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Using Services
|
|
||||||
```javascript
|
|
||||||
import { poseService } from './services/pose.service.js';
|
|
||||||
import { healthService } from './services/health.service.js';
|
|
||||||
|
|
||||||
// Get current pose data
|
|
||||||
const poseData = await poseService.getCurrentPose();
|
|
||||||
|
|
||||||
// Subscribe to health updates
|
|
||||||
healthService.subscribeToHealth(health => {
|
|
||||||
console.log('Health status:', health.status);
|
|
||||||
});
|
|
||||||
|
|
||||||
// Start pose streaming
|
|
||||||
poseService.startPoseStream({
|
|
||||||
minConfidence: 0.7,
|
|
||||||
maxFps: 30
|
|
||||||
});
|
|
||||||
|
|
||||||
poseService.subscribeToPoseUpdates(update => {
|
|
||||||
if (update.type === 'pose_update') {
|
|
||||||
console.log('New pose data:', update.data);
|
|
||||||
}
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Using Components
|
|
||||||
```javascript
|
|
||||||
import { TabManager } from './components/TabManager.js';
|
|
||||||
import { DashboardTab } from './components/DashboardTab.js';
|
|
||||||
|
|
||||||
// Initialize tab manager
|
|
||||||
const container = document.querySelector('.container');
|
|
||||||
const tabManager = new TabManager(container);
|
|
||||||
tabManager.init();
|
|
||||||
|
|
||||||
// Initialize dashboard
|
|
||||||
const dashboardContainer = document.getElementById('dashboard');
|
|
||||||
const dashboard = new DashboardTab(dashboardContainer);
|
|
||||||
await dashboard.init();
|
|
||||||
```
|
|
||||||
|
|
||||||
## ๐ง Configuration
|
|
||||||
|
|
||||||
### API Configuration
|
### API Configuration
|
||||||
Edit `config/api.config.js` to modify API settings:
|
Edit `config/api.config.js`:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
export const API_CONFIG = {
|
export const API_CONFIG = {
|
||||||
BASE_URL: window.location.origin,
|
BASE_URL: window.location.origin,
|
||||||
API_VERSION: '/api/v1',
|
API_VERSION: '/api/v1',
|
||||||
|
|
||||||
// Rate limiting
|
|
||||||
RATE_LIMITS: {
|
|
||||||
REQUESTS_PER_MINUTE: 60,
|
|
||||||
BURST_LIMIT: 10
|
|
||||||
},
|
|
||||||
|
|
||||||
// WebSocket configuration
|
|
||||||
WS_CONFIG: {
|
WS_CONFIG: {
|
||||||
RECONNECT_DELAY: 5000,
|
RECONNECT_DELAY: 5000,
|
||||||
MAX_RECONNECT_ATTEMPTS: 5,
|
MAX_RECONNECT_ATTEMPTS: 20,
|
||||||
PING_INTERVAL: 30000
|
PING_INTERVAL: 30000
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
### Authentication
|
## Testing
|
||||||
```javascript
|
|
||||||
import { apiService } from './services/api.service.js';
|
|
||||||
|
|
||||||
// Set authentication token
|
Open `tests/test-runner.html` to run the test suite:
|
||||||
apiService.setAuthToken('your-jwt-token');
|
|
||||||
|
|
||||||
// Add request interceptor for auth
|
|
||||||
apiService.addRequestInterceptor((url, options) => {
|
|
||||||
// Modify request before sending
|
|
||||||
return { url, options };
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## ๐จ Styling
|
|
||||||
|
|
||||||
The UI uses a comprehensive CSS design system with:
|
|
||||||
|
|
||||||
- CSS Custom Properties for theming
|
|
||||||
- Dark/light mode support
|
|
||||||
- Responsive design
|
|
||||||
- Component-based styling
|
|
||||||
- Smooth animations and transitions
|
|
||||||
|
|
||||||
### Key CSS Variables
|
|
||||||
```css
|
|
||||||
:root {
|
|
||||||
--color-primary: rgba(33, 128, 141, 1);
|
|
||||||
--color-background: rgba(252, 252, 249, 1);
|
|
||||||
--color-surface: rgba(255, 255, 253, 1);
|
|
||||||
--color-text: rgba(19, 52, 59, 1);
|
|
||||||
--space-16: 16px;
|
|
||||||
--radius-lg: 12px;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## ๐ Monitoring & Debugging
|
|
||||||
|
|
||||||
### Health Monitoring
|
|
||||||
```javascript
|
|
||||||
import { healthService } from './services/health.service.js';
|
|
||||||
|
|
||||||
// Start automatic health checks
|
|
||||||
healthService.startHealthMonitoring(30000); // Every 30 seconds
|
|
||||||
|
|
||||||
// Check if system is healthy
|
|
||||||
const isHealthy = healthService.isSystemHealthy();
|
|
||||||
|
|
||||||
// Get specific component status
|
|
||||||
const apiStatus = healthService.getComponentStatus('api');
|
|
||||||
```
|
|
||||||
|
|
||||||
### Error Handling
|
|
||||||
```javascript
|
|
||||||
// Global error handling
|
|
||||||
window.addEventListener('error', (event) => {
|
|
||||||
console.error('Global error:', event.error);
|
|
||||||
});
|
|
||||||
|
|
||||||
// API error handling
|
|
||||||
apiService.addResponseInterceptor(async (response, url) => {
|
|
||||||
if (!response.ok) {
|
|
||||||
console.error(`API error: ${response.status} for ${url}`);
|
|
||||||
}
|
|
||||||
return response;
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## ๐ Deployment
|
|
||||||
|
|
||||||
### Development
|
|
||||||
|
|
||||||
**Option 1: Use the startup script**
|
|
||||||
```bash
|
```bash
|
||||||
cd /workspaces/wifi-densepose/ui
|
cd ui/
|
||||||
./start-ui.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
**Option 2: Manual setup**
|
|
||||||
```bash
|
|
||||||
# First, start your FastAPI backend (runs on port 8000)
|
|
||||||
wifi-densepose start
|
|
||||||
# or from the main project directory:
|
|
||||||
python -m wifi_densepose.main
|
|
||||||
|
|
||||||
# Then, start the UI server on a different port to avoid conflicts
|
|
||||||
cd /workspaces/wifi-densepose/ui
|
|
||||||
python -m http.server 3000
|
python -m http.server 3000
|
||||||
# or
|
# Open http://localhost:3000/tests/test-runner.html
|
||||||
npx http-server . -p 3000
|
|
||||||
|
|
||||||
# Open the UI at http://localhost:3000
|
|
||||||
# The UI will automatically detect and connect to your backend
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Backend Detection Behavior
|
Test categories: API configuration, API service, WebSocket, pose service, health service, UI components, integration.
|
||||||
- **Real Backend Available**: UI connects to `http://localhost:8000` and shows โ
"Connected to real backend"
|
|
||||||
- **Backend Unavailable**: UI automatically uses mock server and shows โ ๏ธ "Mock server active - testing mode"
|
|
||||||
- **Force Mock Mode**: Set `API_CONFIG.MOCK_SERVER.ENABLED = true` for testing
|
|
||||||
|
|
||||||
### Production
|
## Styling
|
||||||
1. Configure `API_CONFIG.BASE_URL` for your backend
|
|
||||||
2. Set up HTTPS for WebSocket connections
|
|
||||||
3. Configure authentication if required
|
|
||||||
4. Optimize assets (minify CSS/JS)
|
|
||||||
5. Set up monitoring and logging
|
|
||||||
|
|
||||||
## ๐ค Contributing
|
Uses a CSS design system with custom properties, dark/light mode, responsive layout, and component-based styling. Key variables in `:root` of `style.css`.
|
||||||
|
|
||||||
1. Follow the modular architecture
|
## License
|
||||||
2. Add tests for new functionality
|
|
||||||
3. Update documentation
|
|
||||||
4. Ensure TypeScript compatibility
|
|
||||||
5. Test with mock server
|
|
||||||
|
|
||||||
## ๐ License
|
Part of the WiFi-DensePose system. See the main project LICENSE file.
|
||||||
|
|
||||||
This project is part of the WiFi-DensePose system. See the main project LICENSE file for details.
|
|
||||||
|
|
|
||||||
Loadingโฆ
Reference in New Issue