From 6dd89f2adafeff99e90bd9b5491e946ebc208b2b Mon Sep 17 00:00:00 2001 From: rUv Date: Sat, 7 Jun 2025 13:40:52 +0000 Subject: [PATCH] docs: Revamp README and UI documentation; enhance CLI usage instructions and API configuration details --- README.md | 254 ++++++++++++++++++++++++++++++-- ui/README.md | 317 ++++++++++++++++++++++++++++++++++++++++ ui/config/api.config.js | 5 +- ui/start-ui.sh | 39 +++++ 4 files changed, 602 insertions(+), 13 deletions(-) create mode 100644 ui/README.md create mode 100755 ui/start-ui.sh diff --git a/README.md b/README.md index 598a137..5032442 100644 --- a/README.md +++ b/README.md @@ -24,17 +24,60 @@ A cutting-edge WiFi-based human pose estimation system that leverages Channel St ## ๐Ÿ“‹ Table of Contents -1. [System Architecture](#system-architecture) -2. [Installation](#installation) -3. [Quick Start](#quick-start) -4. [Documentation](#documentation) -5. [Hardware Setup](#hardware-setup) -6. [Configuration](#configuration) -7. [Testing](#testing) -8. [Deployment](#deployment) -9. [Performance Metrics](#performance-metrics) -10. [Contributing](#contributing) -11. [License](#license) +1. [๐Ÿš€ Key Features](#-key-features) +2. [๐Ÿ—๏ธ System Architecture](#๏ธ-system-architecture) + - [Core Components](#core-components) +3. [๐Ÿ“ฆ Installation](#-installation) + - [Using pip (Recommended)](#using-pip-recommended) + - [From Source](#from-source) + - [Using Docker](#using-docker) + - [System Requirements](#system-requirements) +4. [๐Ÿš€ Quick Start](#-quick-start) + - [Basic Setup](#1-basic-setup) + - [Start the System](#2-start-the-system) + - [Using the REST API](#3-using-the-rest-api) + - [Real-time Streaming](#4-real-time-streaming) +5. [๐Ÿ–ฅ๏ธ CLI Usage](#๏ธ-cli-usage) + - [Installation](#cli-installation) + - [Basic Commands](#basic-commands) + - [Configuration Commands](#configuration-commands) + - [Monitoring Commands](#monitoring-commands) + - [Examples](#cli-examples) +6. [๐Ÿ“š Documentation](#-documentation) + - [Core Documentation](#-core-documentation) + - [Quick Links](#-quick-links) + - [API Overview](#-api-overview) +7. [๐Ÿ”ง Hardware Setup](#-hardware-setup) + - [Supported Hardware](#supported-hardware) + - [Physical Setup](#physical-setup) + - [Network Configuration](#network-configuration) + - [Environment Calibration](#environment-calibration) +8. [โš™๏ธ Configuration](#๏ธ-configuration) + - [Environment Variables](#environment-variables) + - [Domain-Specific Configurations](#domain-specific-configurations) + - [Advanced Configuration](#advanced-configuration) +9. [๐Ÿงช Testing](#-testing) + - [Running Tests](#running-tests) + - [Test Categories](#test-categories) + - [Mock Testing](#mock-testing) + - [Continuous Integration](#continuous-integration) +10. [๐Ÿš€ Deployment](#-deployment) + - [Production Deployment](#production-deployment) + - [Infrastructure as Code](#infrastructure-as-code) + - [Monitoring and Logging](#monitoring-and-logging) +11. [๐Ÿ“Š Performance Metrics](#-performance-metrics) + - [Benchmark Results](#benchmark-results) + - [Performance Optimization](#performance-optimization) + - [Load Testing](#load-testing) +12. [๐Ÿค Contributing](#-contributing) + - [Development Setup](#development-setup) + - [Code Standards](#code-standards) + - [Contribution Process](#contribution-process) + - [Code Review Checklist](#code-review-checklist) + - [Issue Templates](#issue-templates) +13. [๐Ÿ“„ License](#-license) +14. [๐Ÿ™ Acknowledgments](#-acknowledgments) +15. [๐Ÿ“ž Support](#-support) ## ๐Ÿ—๏ธ System Architecture @@ -199,6 +242,195 @@ async def stream_poses(): asyncio.run(stream_poses()) ``` +## ๐Ÿ–ฅ๏ธ CLI Usage + +WiFi DensePose provides a comprehensive command-line interface for easy system management, configuration, and monitoring. + +### CLI Installation + +The CLI is automatically installed with the package: + +```bash +# Install WiFi DensePose with CLI +pip install wifi-densepose + +# Verify CLI installation +wifi-densepose --version +``` + +### Basic Commands + +#### Start/Stop System +```bash +# Start the WiFi DensePose system +wifi-densepose start + +# Start with custom configuration +wifi-densepose start --config /path/to/config.yaml + +# Start in development mode +wifi-densepose start --dev + +# Stop the system +wifi-densepose stop + +# Restart the system +wifi-densepose restart +``` + +#### System Status +```bash +# Check system status +wifi-densepose status + +# Get detailed health information +wifi-densepose health + +# Show system information +wifi-densepose info +``` + +#### Pose Data Operations +```bash +# Get latest pose data +wifi-densepose pose latest + +# Get pose history +wifi-densepose pose history --hours 24 + +# Stream pose data to console +wifi-densepose pose stream + +# Export pose data +wifi-densepose pose export --format json --output poses.json +``` + +### Configuration Commands + +#### Environment Setup +```bash +# Initialize configuration +wifi-densepose init + +# Create configuration from template +wifi-densepose config create --template healthcare + +# Validate configuration +wifi-densepose config validate + +# Show current configuration +wifi-densepose config show +``` + +#### Hardware Configuration +```bash +# List available WiFi interfaces +wifi-densepose hardware list-interfaces + +# Test hardware connectivity +wifi-densepose hardware test + +# Calibrate environment +wifi-densepose calibrate --duration 10 --environment room_001 + +# Show hardware status +wifi-densepose hardware status +``` + +### Monitoring Commands + +#### Real-time Monitoring +```bash +# Monitor system performance +wifi-densepose monitor + +# Monitor pose detection in real-time +wifi-densepose monitor poses + +# Monitor system logs +wifi-densepose logs --follow + +# Monitor specific component +wifi-densepose monitor --component csi_processor +``` + +#### Analytics and Reports +```bash +# Generate analytics report +wifi-densepose analytics report --period 24h + +# Show fall detection events +wifi-densepose analytics falls --since yesterday + +# Export system metrics +wifi-densepose metrics export --format csv +``` + +### CLI Examples + +#### Complete Setup Workflow +```bash +# 1. Initialize new environment +wifi-densepose init --environment healthcare + +# 2. Configure hardware +wifi-densepose hardware setup --interface wlan0 + +# 3. Calibrate environment +wifi-densepose calibrate --duration 15 + +# 4. Start system +wifi-densepose start + +# 5. Monitor in real-time +wifi-densepose monitor poses +``` + +#### Development Workflow +```bash +# Start in development mode with mock data +wifi-densepose start --dev --mock-hardware + +# Run tests +wifi-densepose test + +# Check code quality +wifi-densepose lint + +# Generate documentation +wifi-densepose docs generate +``` + +#### Production Deployment +```bash +# Deploy to production +wifi-densepose deploy --environment production + +# Check deployment status +wifi-densepose deploy status + +# Scale system +wifi-densepose scale --replicas 3 + +# Update system +wifi-densepose update --version 1.2.0 +``` + +#### Troubleshooting +```bash +# Run system diagnostics +wifi-densepose diagnose + +# Check hardware connectivity +wifi-densepose hardware test --verbose + +# Validate configuration +wifi-densepose config validate --strict + +# Reset to defaults +wifi-densepose reset --confirm +``` + ## ๐Ÿ“š Documentation Comprehensive documentation is available to help you get started and make the most of WiFi-DensePose: diff --git a/ui/README.md b/ui/README.md new file mode 100644 index 0000000..87389ea --- /dev/null +++ b/ui/README.md @@ -0,0 +1,317 @@ +# 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. + +## ๐Ÿ—๏ธ Architecture + +The UI follows a modular architecture with clear separation of concerns: + +``` +ui/ +โ”œโ”€โ”€ app.js # Main application entry point +โ”œโ”€โ”€ index.html # Updated HTML with modular structure +โ”œโ”€โ”€ style.css # Complete CSS with additional styles +โ”œโ”€โ”€ config/ # Configuration modules +โ”‚ โ””โ”€โ”€ api.config.js # API endpoints and configuration +โ”œโ”€โ”€ services/ # Service layer for API communication +โ”‚ โ”œโ”€โ”€ api.service.js # HTTP API client +โ”‚ โ”œโ”€โ”€ websocket.service.js # WebSocket client +โ”‚ โ”œโ”€โ”€ pose.service.js # Pose estimation API wrapper +โ”‚ โ”œโ”€โ”€ health.service.js # Health monitoring API wrapper +โ”‚ โ””โ”€โ”€ stream.service.js # Streaming API wrapper +โ”œโ”€โ”€ components/ # UI components +โ”‚ โ”œโ”€โ”€ TabManager.js # Tab navigation component +โ”‚ โ”œโ”€โ”€ DashboardTab.js # Dashboard component with live data +โ”‚ โ”œโ”€โ”€ HardwareTab.js # Hardware configuration component +โ”‚ โ””โ”€โ”€ LiveDemoTab.js # Live demo with streaming +โ”œโ”€โ”€ utils/ # Utility functions and helpers +โ”‚ โ””โ”€โ”€ mock-server.js # Mock server for testing +โ””โ”€โ”€ tests/ # Comprehensive test suite + โ”œโ”€โ”€ test-runner.html # Test runner UI + โ”œโ”€โ”€ test-runner.js # Test framework and cases + โ””โ”€โ”€ integration-test.html # Integration testing page +``` + +## ๐Ÿš€ Features + +### Real-time Dashboard +- Live system health monitoring +- Real-time pose detection statistics +- Zone occupancy tracking +- System metrics (CPU, memory, disk) +- API status indicators + +### Hardware Configuration +- Interactive antenna array visualization +- Real-time CSI data display +- Configuration panels +- Hardware status monitoring + +### Live Demo +- WebSocket-based real-time streaming +- Signal visualization +- Pose detection visualization +- Interactive controls + +### API Integration +- Complete REST API coverage +- WebSocket streaming support +- Authentication handling +- Error management +- Request/response interceptors + +## ๐Ÿ“‹ API Coverage + +The UI integrates with all WiFi DensePose API endpoints: + +### Health Endpoints +- `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 +- `GET /api/v1/pose/current` - Current pose data +- `POST /api/v1/pose/analyze` - Trigger analysis +- `GET /api/v1/pose/zones/{zone_id}/occupancy` - Zone occupancy +- `GET /api/v1/pose/zones/summary` - All zones summary +- `POST /api/v1/pose/historical` - Historical data +- `GET /api/v1/pose/activities` - Recent activities +- `POST /api/v1/pose/calibrate` - System calibration +- `GET /api/v1/pose/stats` - Statistics + +### Streaming +- `WS /api/v1/stream/pose` - Real-time pose stream +- `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 + +### Test Runner +Open `tests/test-runner.html` to run the complete test suite: + +```bash +# Serve the UI directory on port 3000 (to avoid conflicts with FastAPI on 8000) +cd /workspaces/wifi-densepose/ui +python -m http.server 3000 +# Open http://localhost:3000/tests/test-runner.html +``` + +### Test Categories +- **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 +Use `tests/integration-test.html` for visual integration testing: + +```bash +# Open http://localhost:3000/tests/integration-test.html +``` + +Features: +- 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 + + + + + + +
+ +
+ + + +``` + +### 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 +Edit `config/api.config.js` to modify API settings: + +```javascript +export const API_CONFIG = { + BASE_URL: window.location.origin, + API_VERSION: '/api/v1', + + // Rate limiting + RATE_LIMITS: { + REQUESTS_PER_MINUTE: 60, + BURST_LIMIT: 10 + }, + + // WebSocket configuration + WS_CONFIG: { + RECONNECT_DELAY: 5000, + MAX_RECONNECT_ATTEMPTS: 5, + PING_INTERVAL: 30000 + } +}; +``` + +### Authentication +```javascript +import { apiService } from './services/api.service.js'; + +// Set authentication token +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 +```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 +# or +npx http-server . -p 3000 + +# Open the UI at http://localhost:3000 +# The UI will connect to the FastAPI backend at http://localhost:8000 +``` + +### Production +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 + +1. Follow the modular architecture +2. Add tests for new functionality +3. Update documentation +4. Ensure TypeScript compatibility +5. Test with mock server + +## ๐Ÿ“„ License + +This project is part of the WiFi-DensePose system. See the main project LICENSE file for details. \ No newline at end of file diff --git a/ui/config/api.config.js b/ui/config/api.config.js index 5883431..24b3133 100644 --- a/ui/config/api.config.js +++ b/ui/config/api.config.js @@ -1,7 +1,7 @@ // API Configuration for WiFi-DensePose UI export const API_CONFIG = { - BASE_URL: window.location.origin, + BASE_URL: 'http://localhost:8000', // FastAPI backend port API_VERSION: '/api/v1', WS_PREFIX: 'ws://', WSS_PREFIX: 'wss://', @@ -105,7 +105,8 @@ export function buildWsUrl(endpoint, params = {}) { ? API_CONFIG.WSS_PREFIX : API_CONFIG.WS_PREFIX; - const host = window.location.host; + // Use localhost:8000 for WebSocket connections to match FastAPI backend + const host = 'localhost:8000'; let url = `${protocol}${host}${endpoint}`; // Add query parameters diff --git a/ui/start-ui.sh b/ui/start-ui.sh new file mode 100755 index 0000000..6a513b4 --- /dev/null +++ b/ui/start-ui.sh @@ -0,0 +1,39 @@ +#!/bin/bash + +# WiFi DensePose UI Startup Script +# This script starts the UI on port 3000 to avoid conflicts with the FastAPI backend on port 8000 + +echo "๐Ÿš€ Starting WiFi DensePose UI..." +echo "" +echo "๐Ÿ“‹ Configuration:" +echo " - UI Server: http://localhost:3000" +echo " - Backend API: http://localhost:8000 (make sure it's running)" +echo " - Test Runner: http://localhost:3000/tests/test-runner.html" +echo " - Integration Tests: http://localhost:3000/tests/integration-test.html" +echo "" + +# Check if port 3000 is already in use +if lsof -Pi :3000 -sTCP:LISTEN -t >/dev/null ; then + echo "โš ๏ธ Port 3000 is already in use. Please stop the existing server or use a different port." + echo " You can manually start with: python -m http.server 3001" + exit 1 +fi + +# Check if FastAPI backend is running on port 8000 +if lsof -Pi :8000 -sTCP:LISTEN -t >/dev/null ; then + echo "โœ… FastAPI backend detected on port 8000" +else + echo "โš ๏ธ FastAPI backend not detected on port 8000" + echo " Please start it with: wifi-densepose start" + echo " Or: python -m wifi_densepose.main" + echo "" + echo " The UI will still work with the mock server for testing." +fi + +echo "" +echo "๐ŸŒ Starting HTTP server on port 3000..." +echo " Press Ctrl+C to stop" +echo "" + +# Start the HTTP server +python -m http.server 3000 \ No newline at end of file