dearsky/wifi-densepose
1
0
Fork 0
Code Issues 20 Pull Requests 5 Actions Packages Projects Releases 1 Wiki Activity

feat: Complete Rust port of WiFi-DensePose with modular crates

Browse Source 
Major changes:
- Organized Python v1 implementation into v1/ subdirectory
- Created Rust workspace with 9 modular crates:
  - wifi-densepose-core: Core types, traits, errors
  - wifi-densepose-signal: CSI processing, phase sanitization, FFT
  - wifi-densepose-nn: Neural network inference (ONNX/Candle/tch)
  - wifi-densepose-api: Axum-based REST/WebSocket API
  - wifi-densepose-db: SQLx database layer
  - wifi-densepose-config: Configuration management
  - wifi-densepose-hardware: Hardware abstraction
  - wifi-densepose-wasm: WebAssembly bindings
  - wifi-densepose-cli: Command-line interface

Documentation:
- ADR-001: Workspace structure
- ADR-002: Signal processing library selection
- ADR-003: Neural network inference strategy
- DDD domain model with bounded contexts

Testing:
- 69 tests passing across all crates
- Signal processing: 45 tests
- Neural networks: 21 tests
- Core: 3 doc tests

Performance targets:
- 10x faster CSI processing (~0.5ms vs ~5ms)
- 5x lower memory usage (~100MB vs ~500MB)
- WASM support for browser deployment
This commit is contained in:
Claude
2026-01-13 03:11:16 +00:00
parent 5101504b72
commit 6ed69a3d48
427 changed files with 90993 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

312
v1/docs/api-endpoints-summary.md Normal file
View File

@@ -0,0 +1,312 @@
# WiFi-DensePose API Endpoints Summary
## Overview
The WiFi-DensePose API provides RESTful endpoints and WebSocket connections for real-time human pose estimation using WiFi CSI (Channel State Information) data. The API is built with FastAPI and supports both synchronous REST operations and real-time streaming via WebSockets.
## Base URL
- **Development**: `http://localhost:8000`
- **API Prefix**: `/api/v1`
- **Documentation**: `http://localhost:8000/docs`
## Authentication
Authentication is configurable via environment variables:
- When `ENABLE_AUTHENTICATION=true`, protected endpoints require JWT tokens
- Tokens can be passed via:
- Authorization header: `Bearer <token>`
- Query parameter: `?token=<token>`
- Cookie: `access_token`
## Rate Limiting
Rate limiting is configurable and when enabled (`ENABLE_RATE_LIMITING=true`):
- Anonymous: 100 requests/hour
- Authenticated: 1000 requests/hour
- Admin: 10000 requests/hour
## Endpoints
### 1. Health & Status
#### GET `/health/health`
System health check with component status and metrics.
**Response Example:**
```json
{
"status": "healthy",
"timestamp": "2025-06-09T16:00:00Z",
"uptime_seconds": 3600.0,
"components": {
"hardware": {...},
"pose": {...},
"stream": {...}
},
"system_metrics": {
"cpu": {"percent": 24.1, "count": 2},
"memory": {"total_gb": 7.75, "available_gb": 3.73},
"disk": {"total_gb": 31.33, "free_gb": 7.09}
}
}
```
#### GET `/health/ready`
Readiness check for load balancers.
#### GET `/health/live`
Simple liveness check.
#### GET `/health/metrics` 🔒
Detailed system metrics (requires auth).
### 2. Pose Estimation
#### GET `/api/v1/pose/current`
Get current pose estimation from WiFi signals.
**Query Parameters:**
- `zone_ids`: List of zone IDs to analyze
- `confidence_threshold`: Minimum confidence (0.0-1.0)
- `max_persons`: Maximum persons to detect
- `include_keypoints`: Include keypoint data (default: true)
- `include_segmentation`: Include DensePose segmentation (default: false)
**Response Example:**
```json
{
"timestamp": "2025-06-09T16:00:00Z",
"frame_id": "frame_123456",
"persons": [
{
"person_id": "0",
"confidence": 0.95,
"bounding_box": {"x": 0.1, "y": 0.2, "width": 0.3, "height": 0.6},
"keypoints": [...],
"zone_id": "zone_1",
"activity": "standing"
}
],
"zone_summary": {"zone_1": 1, "zone_2": 0},
"processing_time_ms": 45.2
}
```
#### POST `/api/v1/pose/analyze` 🔒
Analyze pose data with custom parameters (requires auth).
#### GET `/api/v1/pose/zones/{zone_id}/occupancy`
Get occupancy for a specific zone.
#### GET `/api/v1/pose/zones/summary`
Get occupancy summary for all zones.
#### GET `/api/v1/pose/activities`
Get recently detected activities.
**Query Parameters:**
- `zone_id`: Filter by zone
- `limit`: Maximum results (1-100)
#### POST `/api/v1/pose/historical` 🔒
Query historical pose data (requires auth).
**Request Body:**
```json
{
"start_time": "2025-06-09T15:00:00Z",
"end_time": "2025-06-09T16:00:00Z",
"zone_ids": ["zone_1"],
"aggregation_interval": 300,
"include_raw_data": false
}
```
#### GET `/api/v1/pose/stats`
Get pose estimation statistics.
**Query Parameters:**
- `hours`: Hours of data to analyze (1-168)
### 3. Calibration
#### POST `/api/v1/pose/calibrate` 🔒
Start system calibration (requires auth).
#### GET `/api/v1/pose/calibration/status` 🔒
Get calibration status (requires auth).
### 4. Streaming
#### GET `/api/v1/stream/status`
Get streaming service status.
#### POST `/api/v1/stream/start` 🔒
Start streaming service (requires auth).
#### POST `/api/v1/stream/stop` 🔒
Stop streaming service (requires auth).
#### GET `/api/v1/stream/clients` 🔒
List connected WebSocket clients (requires auth).
#### DELETE `/api/v1/stream/clients/{client_id}` 🔒
Disconnect specific client (requires auth).
#### POST `/api/v1/stream/broadcast` 🔒
Broadcast message to clients (requires auth).
### 5. WebSocket Endpoints
#### WS `/api/v1/stream/pose`
Real-time pose data streaming.
**Query Parameters:**
- `zone_ids`: Comma-separated zone IDs
- `min_confidence`: Minimum confidence (0.0-1.0)
- `max_fps`: Maximum frames per second (1-60)
- `token`: Auth token (if authentication enabled)
**Message Types:**
- `connection_established`: Initial connection confirmation
- `pose_update`: Pose data updates
- `error`: Error messages
- `ping`/`pong`: Keep-alive
#### WS `/api/v1/stream/events`
Real-time event streaming.
**Query Parameters:**
- `event_types`: Comma-separated event types
- `zone_ids`: Comma-separated zone IDs
- `token`: Auth token (if authentication enabled)
### 6. API Information
#### GET `/`
Root endpoint with API information.
#### GET `/api/v1/info`
Detailed API configuration.
#### GET `/api/v1/status`
Current API and service status.
#### GET `/api/v1/metrics`
API performance metrics (if enabled).
### 7. Development Endpoints
These endpoints are only available when `ENABLE_TEST_ENDPOINTS=true`:
#### GET `/api/v1/dev/config`
Get current configuration (development only).
#### POST `/api/v1/dev/reset`
Reset services (development only).
## Error Handling
All errors follow a consistent format:
```json
{
"error": {
"code": 400,
"message": "Error description",
"type": "error_type"
}
}
```
Error types:
- `http_error`: HTTP-related errors
- `validation_error`: Request validation errors
- `authentication_error`: Authentication failures
- `rate_limit_exceeded`: Rate limit violations
- `internal_error`: Server errors
## WebSocket Protocol
### Connection Flow
1. **Connect**: `ws://host/api/v1/stream/pose?params`
2. **Receive**: Connection confirmation message
3. **Send/Receive**: Bidirectional communication
4. **Disconnect**: Clean connection closure
### Message Format
All WebSocket messages use JSON format:
```json
{
"type": "message_type",
"timestamp": "ISO-8601 timestamp",
"data": {...}
}
```
### Client Messages
- `{"type": "ping"}`: Keep-alive ping
- `{"type": "update_config", "config": {...}}`: Update stream config
- `{"type": "get_status"}`: Request status
- `{"type": "disconnect"}`: Clean disconnect
### Server Messages
- `{"type": "connection_established", ...}`: Connection confirmed
- `{"type": "pose_update", ...}`: Pose data update
- `{"type": "event", ...}`: Event notification
- `{"type": "pong"}`: Ping response
- `{"type": "error", "message": "..."}`: Error message
## CORS Configuration
CORS is enabled with configurable origins:
- Development: Allow all origins (`*`)
- Production: Restrict to specific domains
## Security Headers
The API includes security headers:
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`
- `Referrer-Policy: strict-origin-when-cross-origin`
- `Content-Security-Policy: ...`
## Performance Considerations
1. **Batch Requests**: Use zone summaries instead of individual zone queries
2. **WebSocket Streaming**: Adjust `max_fps` to reduce bandwidth
3. **Historical Data**: Use appropriate `aggregation_interval`
4. **Caching**: Results are cached when Redis is enabled
## Testing
Use the provided test scripts:
- `scripts/test_api_endpoints.py`: Comprehensive endpoint testing
- `scripts/test_websocket_streaming.py`: WebSocket functionality testing
## Production Deployment
For production:
1. Set `ENVIRONMENT=production`
2. Enable authentication and rate limiting
3. Configure proper database (PostgreSQL)
4. Enable Redis for caching
5. Use HTTPS with valid certificates
6. Restrict CORS origins
7. Disable debug mode and test endpoints
8. Configure monitoring and logging
## API Versioning
The API uses URL versioning:
- Current version: `v1`
- Base path: `/api/v1`
Future versions will be available at `/api/v2`, etc.

309
v1/docs/api-test-results.md Normal file
View File

@@ -0,0 +1,309 @@
# WiFi-DensePose API Test Results
## Test Summary
**Date**: June 9, 2025
**Environment**: Development
**Server**: http://localhost:8000
**Total Tests**: 26
**Passed**: 18
**Failed**: 8
**Success Rate**: 69.2%
## Test Configuration
### Environment Settings
- **Authentication**: Disabled
- **Rate Limiting**: Disabled
- **Mock Hardware**: Enabled
- **Mock Pose Data**: Enabled
- **WebSockets**: Enabled
- **Real-time Processing**: Enabled
### Key Configuration Parameters
```env
ENVIRONMENT=development
DEBUG=true
ENABLE_AUTHENTICATION=false
ENABLE_RATE_LIMITING=false
MOCK_HARDWARE=true
MOCK_POSE_DATA=true
ENABLE_WEBSOCKETS=true
ENABLE_REAL_TIME_PROCESSING=true
```
## Endpoint Test Results
### 1. Health Check Endpoints ✅
#### `/health/health` - System Health Check
- **Status**: ✅ PASSED
- **Response Time**: ~1015ms
- **Response**: Complete system health including hardware, pose, and stream services
- **Notes**: Shows CPU, memory, disk, and network metrics
#### `/health/ready` - Readiness Check
- **Status**: ✅ PASSED
- **Response Time**: ~1.6ms
- **Response**: System readiness status with individual service checks
### 2. Pose Detection Endpoints 🔧
#### `/api/v1/pose/current` - Current Pose Estimation
- **Status**: ✅ PASSED
- **Response Time**: ~1.2ms
- **Response**: Current pose data with mock poses
- **Notes**: Working with mock data in development mode
#### `/api/v1/pose/zones/{zone_id}/occupancy` - Zone Occupancy
- **Status**: ✅ PASSED
- **Response Time**: ~1.2ms
- **Response**: Zone-specific occupancy data
#### `/api/v1/pose/zones/summary` - All Zones Summary
- **Status**: ✅ PASSED
- **Response Time**: ~1.2ms
- **Response**: Summary of all zones with total persons count
#### `/api/v1/pose/activities` - Recent Activities
- **Status**: ✅ PASSED
- **Response Time**: ~1.4ms
- **Response**: List of recently detected activities
#### `/api/v1/pose/stats` - Pose Statistics
- **Status**: ✅ PASSED
- **Response Time**: ~1.1ms
- **Response**: Statistical data for specified time period
### 3. Protected Endpoints (Authentication Required) 🔒
These endpoints require authentication, which is disabled in development:
#### `/api/v1/pose/analyze` - Pose Analysis
- **Status**: ❌ FAILED (401 Unauthorized)
- **Note**: Requires authentication token
#### `/api/v1/pose/historical` - Historical Data
- **Status**: ❌ FAILED (401 Unauthorized)
- **Note**: Requires authentication token
#### `/api/v1/pose/calibrate` - Start Calibration
- **Status**: ❌ FAILED (401 Unauthorized)
- **Note**: Requires authentication token
#### `/api/v1/pose/calibration/status` - Calibration Status
- **Status**: ❌ FAILED (401 Unauthorized)
- **Note**: Requires authentication token
### 4. Streaming Endpoints 📡
#### `/api/v1/stream/status` - Stream Status
- **Status**: ✅ PASSED
- **Response Time**: ~1.0ms
- **Response**: Current streaming status and connected clients
#### `/api/v1/stream/start` - Start Streaming
- **Status**: ❌ FAILED (401 Unauthorized)
- **Note**: Requires authentication token
#### `/api/v1/stream/stop` - Stop Streaming
- **Status**: ❌ FAILED (401 Unauthorized)
- **Note**: Requires authentication token
### 5. WebSocket Endpoints 🌐
#### `/api/v1/stream/pose` - Pose WebSocket
- **Status**: ✅ PASSED
- **Connection Time**: ~15.1ms
- **Features**: Real-time pose data streaming
- **Parameters**: zone_ids, min_confidence, max_fps, token (optional)
#### `/api/v1/stream/events` - Events WebSocket
- **Status**: ✅ PASSED
- **Connection Time**: ~2.9ms
- **Features**: Real-time event streaming
- **Parameters**: event_types, zone_ids, token (optional)
### 6. Documentation Endpoints 📚
#### `/docs` - API Documentation
- **Status**: ✅ PASSED
- **Response Time**: ~1.0ms
- **Features**: Interactive Swagger UI documentation
#### `/openapi.json` - OpenAPI Schema
- **Status**: ✅ PASSED
- **Response Time**: ~14.6ms
- **Features**: Complete OpenAPI 3.0 specification
### 7. API Information Endpoints ℹ️
#### `/` - Root Endpoint
- **Status**: ✅ PASSED
- **Response Time**: ~0.9ms
- **Response**: API name, version, environment, and feature flags
#### `/api/v1/info` - API Information
- **Status**: ✅ PASSED
- **Response Time**: ~0.8ms
- **Response**: Detailed API configuration and limits
#### `/api/v1/status` - API Status
- **Status**: ✅ PASSED
- **Response Time**: ~1.0ms
- **Response**: Current API and service statuses
### 8. Error Handling ⚠️
#### `/nonexistent` - 404 Error
- **Status**: ✅ PASSED
- **Response Time**: ~1.4ms
- **Response**: Proper 404 error with formatted error response
## Authentication Status
Authentication is currently **DISABLED** in development mode. The following endpoints require authentication when enabled:
1. **POST** `/api/v1/pose/analyze` - Analyze pose data with custom parameters
2. **POST** `/api/v1/pose/historical` - Query historical pose data
3. **POST** `/api/v1/pose/calibrate` - Start system calibration
4. **GET** `/api/v1/pose/calibration/status` - Get calibration status
5. **POST** `/api/v1/stream/start` - Start streaming service
6. **POST** `/api/v1/stream/stop` - Stop streaming service
7. **GET** `/api/v1/stream/clients` - List connected clients
8. **DELETE** `/api/v1/stream/clients/{client_id}` - Disconnect specific client
9. **POST** `/api/v1/stream/broadcast` - Broadcast message to clients
## Rate Limiting Status
Rate limiting is currently **DISABLED** in development mode. When enabled:
- Anonymous users: 100 requests/hour
- Authenticated users: 1000 requests/hour
- Admin users: 10000 requests/hour
Path-specific limits:
- `/api/v1/pose/current`: 60 requests/minute
- `/api/v1/pose/analyze`: 10 requests/minute
- `/api/v1/pose/calibrate`: 1 request/5 minutes
- `/api/v1/stream/start`: 5 requests/minute
- `/api/v1/stream/stop`: 5 requests/minute
## Error Response Format
All error responses follow a consistent format:
```json
{
"error": {
"code": 404,
"message": "Endpoint not found",
"type": "http_error"
}
}
```
Validation errors include additional details:
```json
{
"error": {
"code": 422,
"message": "Validation error",
"type": "validation_error",
"details": [...]
}
}
```
## WebSocket Message Format
### Connection Establishment
```json
{
"type": "connection_established",
"client_id": "unique-client-id",
"timestamp": "2025-06-09T16:00:00.000Z",
"config": {
"zone_ids": ["zone_1"],
"min_confidence": 0.5,
"max_fps": 30
}
}
```
### Pose Data Stream
```json
{
"type": "pose_update",
"timestamp": "2025-06-09T16:00:00.000Z",
"frame_id": "frame-123",
"persons": [...],
"zone_summary": {...}
}
```
### Error Messages
```json
{
"type": "error",
"message": "Error description"
}
```
## Performance Metrics
- **Average Response Time**: ~2.5ms (excluding health check)
- **Health Check Time**: ~1015ms (includes system metrics collection)
- **WebSocket Connection Time**: ~9ms average
- **OpenAPI Schema Generation**: ~14.6ms
## Known Issues
1. **CSI Processing**: Initial implementation had method name mismatch (`add_data` vs `add_to_history`)
2. **Phase Sanitizer**: Required configuration parameters were missing
3. **Stream Service**: Missing `shutdown` method implementation
4. **WebSocket Paths**: Documentation showed incorrect paths (`/ws/pose` instead of `/api/v1/stream/pose`)
## Recommendations
### For Development
1. Keep authentication and rate limiting disabled for easier testing
2. Use mock data for hardware and pose estimation
3. Enable all documentation endpoints
4. Use verbose logging for debugging
### For Production
1. **Enable Authentication**: Set `ENABLE_AUTHENTICATION=true`
2. **Enable Rate Limiting**: Set `ENABLE_RATE_LIMITING=true`
3. **Disable Mock Data**: Set `MOCK_HARDWARE=false` and `MOCK_POSE_DATA=false`
4. **Secure Endpoints**: Disable documentation endpoints in production
5. **Configure CORS**: Restrict `CORS_ORIGINS` to specific domains
6. **Set Secret Key**: Use a strong, unique `SECRET_KEY`
7. **Database**: Use PostgreSQL instead of SQLite
8. **Redis**: Enable Redis for caching and rate limiting
9. **HTTPS**: Use HTTPS in production with proper certificates
10. **Monitoring**: Enable metrics and health monitoring
## Test Script Usage
To run the API tests:
```bash
python scripts/test_api_endpoints.py
```
Test results are saved to: `scripts/api_test_results_[timestamp].json`
## Conclusion
The WiFi-DensePose API is functioning correctly in development mode with:
- ✅ All public endpoints working
- ✅ WebSocket connections established successfully
- ✅ Proper error handling and response formats
- ✅ Mock data generation for testing
- ❌ Protected endpoints correctly requiring authentication (when enabled)
The system is ready for development and testing. For production deployment, follow the recommendations above to enable security features and use real hardware/model implementations.

992
v1/docs/api/rest-endpoints.md Normal file
View File

@@ -0,0 +1,992 @@
# REST API Endpoints
## Overview
The WiFi-DensePose REST API provides comprehensive access to pose estimation data, system configuration, and analytics. This document details all available endpoints, request/response formats, authentication requirements, and usage examples.
## Table of Contents
1. [API Overview](#api-overview)
2. [Authentication](#authentication)
3. [Common Response Formats](#common-response-formats)
4. [Error Handling](#error-handling)
5. [Pose Estimation Endpoints](#pose-estimation-endpoints)
6. [System Management Endpoints](#system-management-endpoints)
7. [Configuration Endpoints](#configuration-endpoints)
8. [Analytics Endpoints](#analytics-endpoints)
9. [Health and Status Endpoints](#health-and-status-endpoints)
10. [Rate Limiting](#rate-limiting)
## API Overview
### Base URL
```
Production: https://api.wifi-densepose.com/api/v1
Staging: https://staging-api.wifi-densepose.com/api/v1
Development: http://localhost:8000/api/v1
```
### API Versioning
The API uses URL path versioning. The current version is `v1`. Future versions will be available at `/api/v2`, etc.
### Content Types
- **Request Content-Type**: `application/json`
- **Response Content-Type**: `application/json`
- **File Upload**: `multipart/form-data`
### HTTP Methods
- **GET**: Retrieve data
- **POST**: Create new resources
- **PUT**: Update existing resources (full replacement)
- **PATCH**: Partial updates
- **DELETE**: Remove resources
## Authentication
### JWT Token Authentication
Most endpoints require JWT token authentication. Include the token in the Authorization header:
```http
Authorization: Bearer <jwt_token>
```
### API Key Authentication
For service-to-service communication, use API key authentication:
```http
X-API-Key: <api_key>
```
### Getting an Access Token
```http
POST /api/v1/auth/token
Content-Type: application/json
{
"username": "your_username",
"password": "your_password"
}
```
**Response:**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 86400,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
## Common Response Formats
### Success Response
```json
{
"success": true,
"data": {
// Response data
},
"timestamp": "2025-01-07T10:30:00Z",
"request_id": "req_123456789"
}
```
### Error Response
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"field": "confidence_threshold",
"reason": "Value must be between 0 and 1"
}
},
"timestamp": "2025-01-07T10:30:00Z",
"request_id": "req_123456789"
}
```
### Pagination
```json
{
"success": true,
"data": [
// Array of items
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 1250,
"total_pages": 25,
"has_next": true,
"has_prev": false
}
}
```
## Error Handling
### HTTP Status Codes
- **200 OK**: Request successful
- **201 Created**: Resource created successfully
- **400 Bad Request**: Invalid request parameters
- **401 Unauthorized**: Authentication required
- **403 Forbidden**: Insufficient permissions
- **404 Not Found**: Resource not found
- **422 Unprocessable Entity**: Validation error
- **429 Too Many Requests**: Rate limit exceeded
- **500 Internal Server Error**: Server error
### Error Codes
| Code | Description |
|------|-------------|
| `VALIDATION_ERROR` | Request validation failed |
| `AUTHENTICATION_ERROR` | Authentication failed |
| `AUTHORIZATION_ERROR` | Insufficient permissions |
| `RESOURCE_NOT_FOUND` | Requested resource not found |
| `RATE_LIMIT_EXCEEDED` | Too many requests |
| `SYSTEM_ERROR` | Internal system error |
| `HARDWARE_ERROR` | Hardware communication error |
| `MODEL_ERROR` | Neural network model error |
## Pose Estimation Endpoints
### Get Latest Pose Data
Retrieve the most recent pose estimation results.
```http
GET /api/v1/pose/latest
Authorization: Bearer <token>
```
**Query Parameters:**
- `environment_id` (optional): Filter by environment ID
- `min_confidence` (optional): Minimum confidence threshold (0.0-1.0)
- `include_keypoints` (optional): Include detailed keypoint data (default: true)
**Response:**
```json
{
"success": true,
"data": {
"timestamp": "2025-01-07T10:30:00.123Z",
"frame_id": 12345,
"environment_id": "room_001",
"processing_time_ms": 45.2,
"persons": [
{
"person_id": 1,
"track_id": 7,
"confidence": 0.87,
"bounding_box": {
"x": 120,
"y": 80,
"width": 180,
"height": 320
},
"keypoints": [
{
"name": "nose",
"x": 210,
"y": 95,
"confidence": 0.92,
"visible": true
},
{
"name": "left_eye",
"x": 205,
"y": 90,
"confidence": 0.89,
"visible": true
}
// ... additional keypoints
],
"dense_pose": {
"iuv_image": "base64_encoded_image_data",
"confidence_map": "base64_encoded_confidence_data"
}
}
],
"metadata": {
"model_version": "v1.2.0",
"processing_mode": "real_time",
"csi_quality": 0.85
}
}
}
```
### Get Historical Pose Data
Retrieve pose estimation data for a specific time range.
```http
GET /api/v1/pose/history
Authorization: Bearer <token>
```
**Query Parameters:**
- `start_time` (required): Start timestamp (ISO 8601)
- `end_time` (required): End timestamp (ISO 8601)
- `environment_id` (optional): Filter by environment ID
- `person_id` (optional): Filter by person ID
- `track_id` (optional): Filter by track ID
- `min_confidence` (optional): Minimum confidence threshold
- `page` (optional): Page number (default: 1)
- `per_page` (optional): Items per page (default: 50, max: 1000)
**Response:**
```json
{
"success": true,
"data": [
{
"timestamp": "2025-01-07T10:30:00.123Z",
"frame_id": 12345,
"person_id": 1,
"track_id": 7,
"confidence": 0.87,
"bounding_box": {
"x": 120,
"y": 80,
"width": 180,
"height": 320
},
"keypoints": [
// Keypoint data
]
}
// ... additional pose data
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 1250,
"total_pages": 25,
"has_next": true,
"has_prev": false
}
}
```
### Get Person Tracking Data
Retrieve tracking information for a specific person or track.
```http
GET /api/v1/pose/tracking/{track_id}
Authorization: Bearer <token>
```
**Path Parameters:**
- `track_id` (required): Track identifier
**Query Parameters:**
- `start_time` (optional): Start timestamp
- `end_time` (optional): End timestamp
- `include_trajectory` (optional): Include movement trajectory (default: false)
**Response:**
```json
{
"success": true,
"data": {
"track_id": 7,
"person_id": 1,
"first_seen": "2025-01-07T10:25:00Z",
"last_seen": "2025-01-07T10:35:00Z",
"duration_seconds": 600,
"total_frames": 18000,
"average_confidence": 0.84,
"status": "active",
"trajectory": [
{
"timestamp": "2025-01-07T10:25:00Z",
"center_x": 210,
"center_y": 240,
"confidence": 0.87
}
// ... trajectory points
],
"statistics": {
"movement_distance": 15.7,
"average_speed": 0.026,
"time_stationary": 420,
"time_moving": 180
}
}
}
```
### Submit CSI Data for Processing
Submit raw CSI data for pose estimation processing.
```http
POST /api/v1/pose/process
Authorization: Bearer <token>
Content-Type: application/json
{
"csi_data": {
"timestamp": "2025-01-07T10:30:00.123Z",
"antenna_data": [
[
{"real": 1.23, "imag": -0.45},
{"real": 0.87, "imag": 1.12}
// ... subcarrier data
]
// ... antenna data
],
"metadata": {
"router_id": "router_001",
"sampling_rate": 30,
"signal_strength": -45
}
},
"processing_options": {
"confidence_threshold": 0.5,
"max_persons": 10,
"enable_tracking": true,
"return_dense_pose": false
}
}
```
**Response:**
```json
{
"success": true,
"data": {
"processing_id": "proc_123456",
"status": "completed",
"processing_time_ms": 67.3,
"poses": [
// Pose estimation results
]
}
}
```
## System Management Endpoints
### Start System
Start the pose estimation system with specified configuration.
```http
POST /api/v1/system/start
Authorization: Bearer <token>
Content-Type: application/json
{
"configuration": {
"domain": "healthcare",
"environment_id": "room_001",
"detection_settings": {
"confidence_threshold": 0.7,
"max_persons": 5,
"enable_tracking": true
},
"hardware_settings": {
"csi_sampling_rate": 30,
"buffer_size": 1000
}
}
}
```
**Response:**
```json
{
"success": true,
"data": {
"status": "starting",
"session_id": "session_123456",
"estimated_startup_time": 15,
"configuration_applied": {
// Applied configuration
}
}
}
```
### Stop System
Stop the pose estimation system.
```http
POST /api/v1/system/stop
Authorization: Bearer <token>
```
**Response:**
```json
{
"success": true,
"data": {
"status": "stopping",
"session_id": "session_123456",
"shutdown_initiated": "2025-01-07T10:30:00Z"
}
}
```
### Get System Status
Get current system status and performance metrics.
```http
GET /api/v1/system/status
Authorization: Bearer <token>
```
**Response:**
```json
{
"success": true,
"data": {
"status": "running",
"session_id": "session_123456",
"uptime_seconds": 3600,
"started_at": "2025-01-07T09:30:00Z",
"performance": {
"frames_processed": 108000,
"average_fps": 29.8,
"average_latency_ms": 45.2,
"cpu_usage": 65.4,
"memory_usage": 78.2,
"gpu_usage": 82.1
},
"components": {
"csi_processor": {
"status": "healthy",
"last_heartbeat": "2025-01-07T10:29:55Z"
},
"neural_network": {
"status": "healthy",
"model_loaded": true,
"inference_queue_size": 3
},
"tracker": {
"status": "healthy",
"active_tracks": 2
},
"database": {
"status": "healthy",
"connection_pool": "8/20"
}
}
}
}
```
### Restart System
Restart the pose estimation system.
```http
POST /api/v1/system/restart
Authorization: Bearer <token>
```
**Response:**
```json
{
"success": true,
"data": {
"status": "restarting",
"previous_session_id": "session_123456",
"new_session_id": "session_789012",
"estimated_restart_time": 30
}
}
```
## Configuration Endpoints
### Get Current Configuration
Retrieve the current system configuration.
```http
GET /api/v1/config
Authorization: Bearer <token>
```
**Response:**
```json
{
"success": true,
"data": {
"domain": "healthcare",
"environment_id": "room_001",
"detection": {
"confidence_threshold": 0.7,
"max_persons": 5,
"enable_tracking": true,
"tracking_max_age": 30,
"tracking_min_hits": 3
},
"neural_network": {
"model_version": "v1.2.0",
"batch_size": 32,
"enable_gpu": true,
"inference_timeout": 1000
},
"hardware": {
"csi_sampling_rate": 30,
"buffer_size": 1000,
"antenna_count": 3,
"subcarrier_count": 56
},
"analytics": {
"enable_fall_detection": true,
"enable_activity_recognition": true,
"alert_thresholds": {
"fall_confidence": 0.8,
"inactivity_timeout": 300
}
},
"privacy": {
"data_retention_days": 30,
"anonymize_data": true,
"enable_encryption": true
}
}
}
```
### Update Configuration
Update system configuration (requires system restart for some changes).
```http
PUT /api/v1/config
Authorization: Bearer <token>
Content-Type: application/json
{
"detection": {
"confidence_threshold": 0.8,
"max_persons": 3
},
"analytics": {
"enable_fall_detection": true,
"alert_thresholds": {
"fall_confidence": 0.9
}
}
}
```
**Response:**
```json
{
"success": true,
"data": {
"updated_fields": [
"detection.confidence_threshold",
"detection.max_persons",
"analytics.alert_thresholds.fall_confidence"
],
"requires_restart": false,
"applied_at": "2025-01-07T10:30:00Z",
"configuration": {
// Updated configuration
}
}
}
```
### Get Configuration Schema
Get the configuration schema with validation rules and descriptions.
```http
GET /api/v1/config/schema
Authorization: Bearer <token>
```
**Response:**
```json
{
"success": true,
"data": {
"schema": {
"type": "object",
"properties": {
"detection": {
"type": "object",
"properties": {
"confidence_threshold": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Minimum confidence for pose detection"
}
}
}
}
},
"defaults": {
// Default configuration values
}
}
}
```
## Analytics Endpoints
### Get Analytics Summary
Get analytics summary for a specified time period.
```http
GET /api/v1/analytics/summary
Authorization: Bearer <token>
```
**Query Parameters:**
- `start_time` (required): Start timestamp
- `end_time` (required): End timestamp
- `environment_id` (optional): Filter by environment
- `granularity` (optional): Data granularity (hour, day, week)
**Response:**
```json
{
"success": true,
"data": {
"time_period": {
"start": "2025-01-07T00:00:00Z",
"end": "2025-01-07T23:59:59Z",
"duration_hours": 24
},
"detection_stats": {
"total_detections": 15420,
"unique_persons": 47,
"average_confidence": 0.84,
"peak_occupancy": 8,
"peak_occupancy_time": "2025-01-07T14:30:00Z"
},
"activity_stats": {
"total_movement_events": 1250,
"fall_detections": 2,
"alert_count": 5,
"average_activity_level": 0.67
},
"system_stats": {
"uptime_percentage": 99.8,
"average_processing_time": 45.2,
"frames_processed": 2592000,
"error_count": 12
},
"hourly_breakdown": [
{
"hour": "2025-01-07T00:00:00Z",
"detections": 420,
"unique_persons": 2,
"average_confidence": 0.82
}
// ... hourly data
]
}
}
```
### Get Activity Events
Retrieve detected activity events (falls, alerts, etc.).
```http
GET /api/v1/analytics/events
Authorization: Bearer <token>
```
**Query Parameters:**
- `start_time` (optional): Start timestamp
- `end_time` (optional): End timestamp
- `event_type` (optional): Filter by event type (fall, alert, activity)
- `severity` (optional): Filter by severity (low, medium, high)
- `environment_id` (optional): Filter by environment
**Response:**
```json
{
"success": true,
"data": [
{
"event_id": "event_123456",
"type": "fall_detection",
"severity": "high",
"timestamp": "2025-01-07T14:25:30Z",
"environment_id": "room_001",
"person_id": 3,
"track_id": 15,
"confidence": 0.92,
"location": {
"x": 210,
"y": 180
},
"metadata": {
"fall_duration": 2.3,
"impact_severity": 0.85,
"recovery_detected": false
},
"actions_taken": [
"alert_sent",
"notification_dispatched"
]
}
// ... additional events
]
}
```
### Get Occupancy Data
Get occupancy statistics and trends.
```http
GET /api/v1/analytics/occupancy
Authorization: Bearer <token>
```
**Query Parameters:**
- `start_time` (required): Start timestamp
- `end_time` (required): End timestamp
- `environment_id` (optional): Filter by environment
- `interval` (optional): Data interval (5min, 15min, 1hour)
**Response:**
```json
{
"success": true,
"data": {
"summary": {
"average_occupancy": 3.2,
"peak_occupancy": 8,
"peak_time": "2025-01-07T14:30:00Z",
"total_person_hours": 76.8
},
"time_series": [
{
"timestamp": "2025-01-07T00:00:00Z",
"occupancy": 2,
"confidence": 0.89
},
{
"timestamp": "2025-01-07T00:15:00Z",
"occupancy": 1,
"confidence": 0.92
}
// ... time series data
],
"distribution": {
"0_persons": 15.2,
"1_person": 42.8,
"2_persons": 28.5,
"3_persons": 10.1,
"4_plus_persons": 3.4
}
}
}
```
## Health and Status Endpoints
### Health Check
Basic health check endpoint for load balancers and monitoring.
```http
GET /api/v1/health
```
**Response:**
```json
{
"status": "healthy",
"timestamp": "2025-01-07T10:30:00Z",
"version": "1.2.0",
"uptime": 3600
}
```
### Detailed Health Check
Comprehensive health check with component status.
```http
GET /api/v1/health/detailed
Authorization: Bearer <token>
```
**Response:**
```json
{
"success": true,
"data": {
"overall_status": "healthy",
"timestamp": "2025-01-07T10:30:00Z",
"version": "1.2.0",
"uptime": 3600,
"components": {
"api": {
"status": "healthy",
"response_time_ms": 12.3,
"requests_per_second": 45.2
},
"database": {
"status": "healthy",
"connection_pool": "8/20",
"query_time_ms": 5.7
},
"redis": {
"status": "healthy",
"memory_usage": "45%",
"connected_clients": 12
},
"neural_network": {
"status": "healthy",
"model_loaded": true,
"gpu_memory_usage": "78%",
"inference_queue": 2
},
"csi_processor": {
"status": "healthy",
"data_rate": 30.1,
"buffer_usage": "23%"
}
},
"metrics": {
"cpu_usage": 65.4,
"memory_usage": 78.2,
"disk_usage": 45.8,
"network_io": {
"bytes_in": 1024000,
"bytes_out": 2048000
}
}
}
}
```
### System Metrics
Get detailed system performance metrics.
```http
GET /api/v1/metrics
Authorization: Bearer <token>
```
**Query Parameters:**
- `start_time` (optional): Start timestamp for historical metrics
- `end_time` (optional): End timestamp for historical metrics
- `metric_type` (optional): Filter by metric type
**Response:**
```json
{
"success": true,
"data": {
"current": {
"timestamp": "2025-01-07T10:30:00Z",
"performance": {
"frames_per_second": 29.8,
"average_latency_ms": 45.2,
"processing_queue_size": 3,
"error_rate": 0.001
},
"resources": {
"cpu_usage": 65.4,
"memory_usage": 78.2,
"gpu_usage": 82.1,
"disk_io": {
"read_mb_per_sec": 12.5,
"write_mb_per_sec": 8.3
}
},
"business": {
"active_persons": 3,
"detections_per_minute": 89.5,
"tracking_accuracy": 0.94
}
},
"historical": [
{
"timestamp": "2025-01-07T10:25:00Z",
"frames_per_second": 30.1,
"average_latency_ms": 43.8,
"cpu_usage": 62.1
}
// ... historical data points
]
}
}
```
## Rate Limiting
### Rate Limit Headers
All API responses include rate limiting headers:
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704686400
X-RateLimit-Window: 3600
```
### Rate Limits by Endpoint Category
| Category | Limit | Window |
|----------|-------|--------|
| Authentication | 10 requests | 1 minute |
| Pose Data (GET) | 1000 requests | 1 hour |
| Pose Processing (POST) | 100 requests | 1 hour |
| Configuration | 50 requests | 1 hour |
| Analytics | 500 requests | 1 hour |
| Health Checks | 10000 requests | 1 hour |
### Rate Limit Exceeded Response
```json
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 45 seconds.",
"details": {
"limit": 1000,
"window": 3600,
"reset_at": "2025-01-07T11:00:00Z"
}
}
}
```
---
This REST API documentation provides comprehensive coverage of all available endpoints. For real-time data streaming, see the [WebSocket API documentation](websocket-api.md). For authentication details, see the [Authentication documentation](authentication.md).
For code examples in multiple languages, see the [API Examples documentation](examples.md).

998
v1/docs/api/websocket-api.md Normal file
View File

@@ -0,0 +1,998 @@
# WebSocket API Documentation
## Overview
The WiFi-DensePose WebSocket API provides real-time streaming of pose estimation data, system events, and analytics. This enables applications to receive live updates without polling REST endpoints, making it ideal for real-time monitoring dashboards and interactive applications.
## Table of Contents
1. [Connection Setup](#connection-setup)
2. [Authentication](#authentication)
3. [Message Format](#message-format)
4. [Event Types](#event-types)
5. [Subscription Management](#subscription-management)
6. [Real-time Pose Streaming](#real-time-pose-streaming)
7. [System Events](#system-events)
8. [Analytics Streaming](#analytics-streaming)
9. [Error Handling](#error-handling)
10. [Connection Management](#connection-management)
11. [Rate Limiting](#rate-limiting)
12. [Code Examples](#code-examples)
## Connection Setup
### WebSocket Endpoint
```
Production: wss://api.wifi-densepose.com/ws/v1
Staging: wss://staging-api.wifi-densepose.com/ws/v1
Development: ws://localhost:8000/ws/v1
```
### Connection URL Parameters
```
wss://api.wifi-densepose.com/ws/v1?token=<jwt_token>&client_id=<client_id>
```
**Parameters:**
- `token` (required): JWT authentication token
- `client_id` (optional): Unique client identifier for connection tracking
- `compression` (optional): Enable compression (gzip, deflate)
### Connection Headers
```http
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: wifi-densepose-v1
Authorization: Bearer <jwt_token>
```
## Authentication
### JWT Token Authentication
Include the JWT token in the connection URL or as a header:
```javascript
// URL parameter method
const ws = new WebSocket('wss://api.wifi-densepose.com/ws/v1?token=your_jwt_token');
// Header method (if supported by client)
const ws = new WebSocket('wss://api.wifi-densepose.com/ws/v1', [], {
headers: {
'Authorization': 'Bearer your_jwt_token'
}
});
```
### Token Refresh
When a token expires, the server will send a `token_expired` event. Clients should refresh their token and reconnect:
```json
{
"type": "token_expired",
"timestamp": "2025-01-07T10:30:00Z",
"message": "JWT token has expired. Please refresh and reconnect."
}
```
## Message Format
### Standard Message Structure
All WebSocket messages follow this JSON structure:
```json
{
"type": "message_type",
"timestamp": "2025-01-07T10:30:00.123Z",
"data": {
// Message-specific data
},
"metadata": {
"client_id": "client_123",
"sequence": 12345,
"compression": "gzip"
}
}
```
### Message Types
| Type | Direction | Description |
|------|-----------|-------------|
| `subscribe` | Client → Server | Subscribe to event streams |
| `unsubscribe` | Client → Server | Unsubscribe from event streams |
| `pose_data` | Server → Client | Real-time pose estimation data |
| `system_event` | Server → Client | System status and events |
| `analytics_update` | Server → Client | Analytics and metrics updates |
| `error` | Server → Client | Error notifications |
| `heartbeat` | Bidirectional | Connection keep-alive |
| `ack` | Server → Client | Acknowledgment of client messages |
## Event Types
### Pose Data Events
#### Real-time Pose Detection
```json
{
"type": "pose_data",
"timestamp": "2025-01-07T10:30:00.123Z",
"data": {
"frame_id": 12345,
"environment_id": "room_001",
"processing_time_ms": 45.2,
"persons": [
{
"person_id": 1,
"track_id": 7,
"confidence": 0.87,
"bounding_box": {
"x": 120,
"y": 80,
"width": 180,
"height": 320
},
"keypoints": [
{
"name": "nose",
"x": 210,
"y": 95,
"confidence": 0.92,
"visible": true
}
// ... additional keypoints
],
"activity": {
"type": "walking",
"confidence": 0.78,
"velocity": {
"x": 0.5,
"y": 0.2
}
}
}
],
"metadata": {
"model_version": "v1.2.0",
"csi_quality": 0.85,
"frame_rate": 29.8
}
}
}
```
#### Person Tracking Updates
```json
{
"type": "tracking_update",
"timestamp": "2025-01-07T10:30:00.123Z",
"data": {
"track_id": 7,
"person_id": 1,
"event": "track_started",
"position": {
"x": 210,
"y": 240
},
"confidence": 0.87,
"metadata": {
"first_detection": "2025-01-07T10:29:45Z",
"track_quality": 0.92
}
}
}
```
### System Events
#### System Status Changes
```json
{
"type": "system_event",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"event": "system_started",
"status": "running",
"session_id": "session_123456",
"configuration": {
"domain": "healthcare",
"environment_id": "room_001"
},
"components": {
"neural_network": "healthy",
"csi_processor": "healthy",
"tracker": "healthy"
}
}
}
```
#### Hardware Events
```json
{
"type": "hardware_event",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"event": "router_disconnected",
"router_id": "router_001",
"severity": "warning",
"message": "Router connection lost. Attempting reconnection...",
"metadata": {
"last_seen": "2025-01-07T10:29:30Z",
"reconnect_attempts": 1
}
}
}
```
### Analytics Events
#### Activity Detection
```json
{
"type": "activity_event",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"event_type": "fall_detected",
"severity": "high",
"person_id": 3,
"track_id": 15,
"confidence": 0.92,
"location": {
"x": 210,
"y": 180
},
"details": {
"fall_duration": 2.3,
"impact_severity": 0.85,
"recovery_detected": false
},
"actions": [
"alert_triggered",
"notification_sent"
]
}
}
```
#### Occupancy Updates
```json
{
"type": "occupancy_update",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"environment_id": "room_001",
"current_occupancy": 3,
"previous_occupancy": 2,
"change_type": "person_entered",
"confidence": 0.89,
"persons": [
{
"person_id": 1,
"track_id": 7,
"status": "active"
},
{
"person_id": 2,
"track_id": 8,
"status": "active"
},
{
"person_id": 4,
"track_id": 12,
"status": "new"
}
]
}
}
```
## Subscription Management
### Subscribe to Events
Send a subscription message to start receiving specific event types:
```json
{
"type": "subscribe",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"subscriptions": [
{
"event_type": "pose_data",
"filters": {
"environment_id": "room_001",
"min_confidence": 0.7,
"include_keypoints": true,
"include_dense_pose": false
},
"throttle": {
"max_fps": 10,
"buffer_size": 5
}
},
{
"event_type": "system_event",
"filters": {
"severity": ["warning", "error", "critical"]
}
},
{
"event_type": "activity_event",
"filters": {
"event_types": ["fall_detected", "alert_triggered"]
}
}
]
}
}
```
### Subscription Acknowledgment
Server responds with subscription confirmation:
```json
{
"type": "ack",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"message_type": "subscribe",
"status": "success",
"active_subscriptions": [
{
"subscription_id": "sub_123",
"event_type": "pose_data",
"status": "active"
},
{
"subscription_id": "sub_124",
"event_type": "system_event",
"status": "active"
}
]
}
}
```
### Unsubscribe from Events
```json
{
"type": "unsubscribe",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"subscription_ids": ["sub_123", "sub_124"]
}
}
```
### Update Subscription Filters
```json
{
"type": "update_subscription",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"subscription_id": "sub_123",
"filters": {
"min_confidence": 0.8,
"max_fps": 15
}
}
}
```
## Real-time Pose Streaming
### High-Frequency Pose Data
For applications requiring high-frequency updates:
```json
{
"type": "subscribe",
"data": {
"subscriptions": [
{
"event_type": "pose_data",
"filters": {
"environment_id": "room_001",
"min_confidence": 0.5,
"include_keypoints": true,
"include_dense_pose": true,
"include_velocity": true
},
"throttle": {
"max_fps": 30,
"buffer_size": 1,
"compression": "gzip"
},
"quality": "high"
}
]
}
}
```
### Pose Data with Trajectory
```json
{
"type": "pose_data_trajectory",
"timestamp": "2025-01-07T10:30:00.123Z",
"data": {
"track_id": 7,
"person_id": 1,
"trajectory": [
{
"timestamp": "2025-01-07T10:29:58.123Z",
"position": {"x": 200, "y": 230},
"confidence": 0.89
},
{
"timestamp": "2025-01-07T10:29:59.123Z",
"position": {"x": 205, "y": 235},
"confidence": 0.91
},
{
"timestamp": "2025-01-07T10:30:00.123Z",
"position": {"x": 210, "y": 240},
"confidence": 0.87
}
],
"prediction": {
"next_position": {"x": 215, "y": 245},
"confidence": 0.73,
"time_horizon": 1.0
}
}
}
```
## System Events
### Performance Monitoring
```json
{
"type": "performance_update",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"metrics": {
"frames_per_second": 29.8,
"average_latency_ms": 45.2,
"processing_queue_size": 3,
"cpu_usage": 65.4,
"memory_usage": 78.2,
"gpu_usage": 82.1
},
"alerts": [
{
"type": "high_latency",
"severity": "warning",
"value": 67.3,
"threshold": 50.0
}
]
}
}
```
### Configuration Changes
```json
{
"type": "config_update",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"changed_fields": [
"detection.confidence_threshold",
"analytics.enable_fall_detection"
],
"new_values": {
"detection.confidence_threshold": 0.8,
"analytics.enable_fall_detection": true
},
"applied_by": "admin_user",
"requires_restart": false
}
}
```
## Analytics Streaming
### Real-time Analytics
```json
{
"type": "analytics_stream",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"window": "1_minute",
"metrics": {
"occupancy": {
"current": 3,
"average": 2.7,
"peak": 5
},
"activity": {
"movement_events": 15,
"stationary_time": 45.2,
"activity_level": 0.67
},
"detection": {
"total_detections": 1800,
"average_confidence": 0.84,
"tracking_accuracy": 0.92
}
},
"trends": {
"occupancy_trend": "increasing",
"activity_trend": "stable",
"confidence_trend": "improving"
}
}
}
```
## Error Handling
### Connection Errors
```json
{
"type": "error",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"error_code": "CONNECTION_ERROR",
"message": "WebSocket connection lost",
"details": {
"reason": "network_timeout",
"retry_after": 5,
"max_retries": 3
}
}
}
```
### Subscription Errors
```json
{
"type": "error",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"error_code": "SUBSCRIPTION_ERROR",
"message": "Invalid subscription filter",
"details": {
"subscription_id": "sub_123",
"field": "min_confidence",
"reason": "Value must be between 0 and 1"
}
}
}
```
### Rate Limit Errors
```json
{
"type": "error",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"error_code": "RATE_LIMIT_EXCEEDED",
"message": "Message rate limit exceeded",
"details": {
"current_rate": 150,
"limit": 100,
"window": "1_minute",
"retry_after": 30
}
}
}
```
## Connection Management
### Heartbeat
Both client and server should send periodic heartbeat messages:
```json
{
"type": "heartbeat",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"client_id": "client_123",
"uptime": 3600,
"last_message": "2025-01-07T10:29:55Z"
}
}
```
### Connection Status
```json
{
"type": "connection_status",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"status": "connected",
"client_id": "client_123",
"session_id": "session_789",
"connected_since": "2025-01-07T09:30:00Z",
"active_subscriptions": 3,
"message_count": 1250
}
}
```
### Graceful Disconnect
```json
{
"type": "disconnect",
"timestamp": "2025-01-07T10:30:00Z",
"data": {
"reason": "client_requested",
"message": "Graceful disconnect initiated by client"
}
}
```
## Rate Limiting
### Message Rate Limits
| Message Type | Limit | Window |
|--------------|-------|--------|
| Subscribe/Unsubscribe | 10 messages | 1 minute |
| Heartbeat | 1 message | 30 seconds |
| General Commands | 60 messages | 1 minute |
### Data Rate Limits
| Subscription Type | Max Rate | Buffer Size |
|-------------------|----------|-------------|
| Pose Data (Low Quality) | 10 FPS | 5 frames |
| Pose Data (High Quality) | 30 FPS | 1 frame |
| System Events | 100 events/min | 10 events |
| Analytics | 60 updates/min | 5 updates |
## Code Examples
### JavaScript Client
```javascript
class WiFiDensePoseWebSocket {
constructor(token, options = {}) {
this.token = token;
this.options = {
url: 'wss://api.wifi-densepose.com/ws/v1',
reconnectInterval: 5000,
maxReconnectAttempts: 5,
...options
};
this.ws = null;
this.reconnectAttempts = 0;
this.subscriptions = new Map();
}
connect() {
const url = `${this.options.url}?token=${this.token}`;
this.ws = new WebSocket(url);
this.ws.onopen = () => {
console.log('Connected to WiFi-DensePose WebSocket');
this.reconnectAttempts = 0;
this.startHeartbeat();
};
this.ws.onmessage = (event) => {
const message = JSON.parse(event.data);
this.handleMessage(message);
};
this.ws.onclose = (event) => {
console.log('WebSocket connection closed:', event.code);
this.stopHeartbeat();
this.attemptReconnect();
};
this.ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
}
subscribeToPoseData(environmentId, options = {}) {
const subscription = {
event_type: 'pose_data',
filters: {
environment_id: environmentId,
min_confidence: options.minConfidence || 0.7,
include_keypoints: options.includeKeypoints !== false,
include_dense_pose: options.includeDensePose || false
},
throttle: {
max_fps: options.maxFps || 10,
buffer_size: options.bufferSize || 5
}
};
this.send({
type: 'subscribe',
timestamp: new Date().toISOString(),
data: {
subscriptions: [subscription]
}
});
}
subscribeToSystemEvents() {
this.send({
type: 'subscribe',
timestamp: new Date().toISOString(),
data: {
subscriptions: [{
event_type: 'system_event',
filters: {
severity: ['warning', 'error', 'critical']
}
}]
}
});
}
handleMessage(message) {
switch (message.type) {
case 'pose_data':
this.onPoseData(message.data);
break;
case 'system_event':
this.onSystemEvent(message.data);
break;
case 'activity_event':
this.onActivityEvent(message.data);
break;
case 'error':
this.onError(message.data);
break;
case 'ack':
this.onAcknowledgment(message.data);
break;
}
}
onPoseData(data) {
// Handle pose data
console.log('Received pose data:', data);
}
onSystemEvent(data) {
// Handle system events
console.log('System event:', data);
}
onActivityEvent(data) {
// Handle activity events
console.log('Activity event:', data);
}
onError(data) {
console.error('WebSocket error:', data);
}
send(message) {
if (this.ws && this.ws.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify(message));
}
}
startHeartbeat() {
this.heartbeatInterval = setInterval(() => {
this.send({
type: 'heartbeat',
timestamp: new Date().toISOString(),
data: {
client_id: this.options.clientId,
uptime: Date.now() - this.connectTime
}
});
}, 30000);
}
stopHeartbeat() {
if (this.heartbeatInterval) {
clearInterval(this.heartbeatInterval);
}
}
attemptReconnect() {
if (this.reconnectAttempts < this.options.maxReconnectAttempts) {
this.reconnectAttempts++;
console.log(`Attempting to reconnect (${this.reconnectAttempts}/${this.options.maxReconnectAttempts})`);
setTimeout(() => {
this.connect();
}, this.options.reconnectInterval);
}
}
disconnect() {
this.stopHeartbeat();
if (this.ws) {
this.ws.close();
}
}
}
// Usage example
const client = new WiFiDensePoseWebSocket('your_jwt_token', {
clientId: 'dashboard_client_001'
});
client.onPoseData = (data) => {
// Update UI with pose data
updatePoseVisualization(data);
};
client.onActivityEvent = (data) => {
if (data.event_type === 'fall_detected') {
showFallAlert(data);
}
};
client.connect();
client.subscribeToPoseData('room_001', {
minConfidence: 0.8,
maxFps: 15,
includeKeypoints: true
});
```
### Python Client
```python
import asyncio
import websockets
import json
from datetime import datetime
class WiFiDensePoseWebSocket:
def __init__(self, token, url='wss://api.wifi-densepose.com/ws/v1'):
self.token = token
self.url = f"{url}?token={token}"
self.websocket = None
self.subscriptions = {}
async def connect(self):
"""Connect to the WebSocket server."""
try:
self.websocket = await websockets.connect(self.url)
print("Connected to WiFi-DensePose WebSocket")
# Start heartbeat task
asyncio.create_task(self.heartbeat())
# Listen for messages
await self.listen()
except Exception as e:
print(f"Connection error: {e}")
async def listen(self):
"""Listen for incoming messages."""
try:
async for message in self.websocket:
data = json.loads(message)
await self.handle_message(data)
except websockets.exceptions.ConnectionClosed:
print("WebSocket connection closed")
except Exception as e:
print(f"Error listening for messages: {e}")
async def handle_message(self, message):
"""Handle incoming messages."""
message_type = message.get('type')
data = message.get('data', {})
if message_type == 'pose_data':
await self.on_pose_data(data)
elif message_type == 'system_event':
await self.on_system_event(data)
elif message_type == 'activity_event':
await self.on_activity_event(data)
elif message_type == 'error':
await self.on_error(data)
async def subscribe_to_pose_data(self, environment_id, **options):
"""Subscribe to pose data stream."""
subscription = {
'event_type': 'pose_data',
'filters': {
'environment_id': environment_id,
'min_confidence': options.get('min_confidence', 0.7),
'include_keypoints': options.get('include_keypoints', True),
'include_dense_pose': options.get('include_dense_pose', False)
},
'throttle': {
'max_fps': options.get('max_fps', 10),
'buffer_size': options.get('buffer_size', 5)
}
}
await self.send({
'type': 'subscribe',
'timestamp': datetime.utcnow().isoformat() + 'Z',
'data': {
'subscriptions': [subscription]
}
})
async def send(self, message):
"""Send a message to the server."""
if self.websocket:
await self.websocket.send(json.dumps(message))
async def heartbeat(self):
"""Send periodic heartbeat messages."""
while True:
try:
await self.send({
'type': 'heartbeat',
'timestamp': datetime.utcnow().isoformat() + 'Z',
'data': {
'client_id': 'python_client'
}
})
await asyncio.sleep(30)
except Exception as e:
print(f"Heartbeat error: {e}")
break
async def on_pose_data(self, data):
"""Handle pose data."""
print(f"Received pose data: {len(data.get('persons', []))} persons detected")
async def on_system_event(self, data):
"""Handle system events."""
print(f"System event: {data.get('event')} - {data.get('message', '')}")
async def on_activity_event(self, data):
"""Handle activity events."""
if data.get('event_type') == 'fall_detected':
print(f"FALL DETECTED: Person {data.get('person_id')} at {data.get('location')}")
async def on_error(self, data):
"""Handle errors."""
print(f"WebSocket error: {data.get('message')}")
# Usage example
async def main():
client = WiFiDensePoseWebSocket('your_jwt_token')
# Connect and subscribe
await client.connect()
await client.subscribe_to_pose_data('room_001', min_confidence=0.8)
if __name__ == "__main__":
asyncio.run(main())
```
---
This WebSocket API documentation provides comprehensive coverage of real-time communication capabilities. For authentication details, see the [Authentication documentation](authentication.md). For REST API endpoints, see the [REST Endpoints documentation](rest-endpoints.md).

931
v1/docs/api_reference.md Normal file
View File

@@ -0,0 +1,931 @@
# WiFi-DensePose API Reference
## Table of Contents
1. [Overview](#overview)
2. [Authentication](#authentication)
3. [Base URL and Versioning](#base-url-and-versioning)
4. [Request/Response Format](#requestresponse-format)
5. [Error Handling](#error-handling)
6. [Rate Limiting](#rate-limiting)
7. [Pose Estimation API](#pose-estimation-api)
8. [System Management API](#system-management-api)
9. [Health Check API](#health-check-api)
10. [WebSocket API](#websocket-api)
11. [Data Models](#data-models)
12. [SDK Examples](#sdk-examples)
## Overview
The WiFi-DensePose API provides comprehensive access to WiFi-based human pose estimation capabilities. The API follows REST principles and supports both synchronous HTTP requests and real-time WebSocket connections.
### Key Features
- **RESTful Design**: Standard HTTP methods and status codes
- **Real-time Streaming**: WebSocket support for live pose data
- **Authentication**: JWT-based authentication with role-based access
- **Rate Limiting**: Configurable rate limits to prevent abuse
- **Comprehensive Documentation**: OpenAPI/Swagger documentation
- **Error Handling**: Detailed error responses with actionable messages
### API Capabilities
- Real-time pose estimation from WiFi CSI data
- Historical pose data retrieval and analysis
- System health monitoring and diagnostics
- Multi-zone occupancy tracking
- Activity recognition and analytics
- System configuration and calibration
## Authentication
### JWT Authentication
The API uses JSON Web Tokens (JWT) for authentication. Include the token in the `Authorization` header:
```http
Authorization: Bearer <your-jwt-token>
```
### Obtaining a Token
```bash
# Login to get JWT token
curl -X POST http://localhost:8000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "your-username",
"password": "your-password"
}'
```
**Response:**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 86400
}
```
### Token Refresh
```bash
# Refresh expired token
curl -X POST http://localhost:8000/api/v1/auth/refresh \
-H "Authorization: Bearer <your-refresh-token>"
```
### Public Endpoints
Some endpoints are publicly accessible without authentication:
- `GET /api/v1/health/*` - Health check endpoints
- `GET /api/v1/version` - Version information
- `GET /docs` - API documentation
## Base URL and Versioning
### Base URL
```
http://localhost:8000/api/v1
```
### API Versioning
The API uses URL path versioning. Current version is `v1`.
### Content Types
- **Request**: `application/json`
- **Response**: `application/json`
- **WebSocket**: `application/json` messages
## Request/Response Format
### Standard Response Format
```json
{
"data": {},
"timestamp": "2025-01-07T10:00:00Z",
"status": "success"
}
```
### Error Response Format
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"field": "confidence_threshold",
"issue": "Value must be between 0.0 and 1.0"
}
},
"timestamp": "2025-01-07T10:00:00Z",
"status": "error"
}
```
## Error Handling
### HTTP Status Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 409 | Conflict |
| 422 | Validation Error |
| 429 | Rate Limited |
| 500 | Internal Server Error |
| 503 | Service Unavailable |
### Error Codes
| Code | Description |
|------|-------------|
| `VALIDATION_ERROR` | Request validation failed |
| `AUTHENTICATION_ERROR` | Authentication failed |
| `AUTHORIZATION_ERROR` | Insufficient permissions |
| `RESOURCE_NOT_FOUND` | Requested resource not found |
| `RATE_LIMIT_EXCEEDED` | Rate limit exceeded |
| `HARDWARE_ERROR` | Hardware communication error |
| `PROCESSING_ERROR` | Pose processing error |
| `CALIBRATION_ERROR` | System calibration error |
## Rate Limiting
### Default Limits
- **Authenticated users**: 1000 requests per hour
- **Anonymous users**: 100 requests per hour
- **WebSocket connections**: 10 concurrent per user
### Rate Limit Headers
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1641556800
```
### Rate Limit Response
```json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 60 seconds."
}
}
```
## Pose Estimation API
### Get Current Pose Estimation
Get real-time pose estimation from WiFi signals.
```http
GET /api/v1/pose/current
```
**Query Parameters:**
- `zone_ids` (array, optional): Specific zones to analyze
- `confidence_threshold` (float, optional): Minimum confidence (0.0-1.0)
- `max_persons` (integer, optional): Maximum persons to detect (1-50)
- `include_keypoints` (boolean, optional): Include keypoint data (default: true)
- `include_segmentation` (boolean, optional): Include segmentation masks (default: false)
**Example Request:**
```bash
curl "http://localhost:8000/api/v1/pose/current?confidence_threshold=0.7&max_persons=5" \
-H "Authorization: Bearer <token>"
```
**Response:**
```json
{
"timestamp": "2025-01-07T10:00:00Z",
"frame_id": "frame_12345",
"persons": [
{
"person_id": "person_001",
"confidence": 0.85,
"bounding_box": {
"x": 100,
"y": 150,
"width": 80,
"height": 180
},
"keypoints": [
{
"name": "nose",
"x": 140,
"y": 160,
"confidence": 0.9
}
],
"zone_id": "zone_001",
"activity": "standing",
"timestamp": "2025-01-07T10:00:00Z"
}
],
"zone_summary": {
"zone_001": 1,
"zone_002": 0
},
"processing_time_ms": 45.2
}
```
### Analyze Pose Data
Trigger pose analysis with custom parameters.
```http
POST /api/v1/pose/analyze
```
**Request Body:**
```json
{
"zone_ids": ["zone_001", "zone_002"],
"confidence_threshold": 0.8,
"max_persons": 10,
"include_keypoints": true,
"include_segmentation": false
}
```
**Response:** Same format as current pose estimation.
### Get Zone Occupancy
Get current occupancy for a specific zone.
```http
GET /api/v1/pose/zones/{zone_id}/occupancy
```
**Path Parameters:**
- `zone_id` (string): Zone identifier
**Example Request:**
```bash
curl "http://localhost:8000/api/v1/pose/zones/zone_001/occupancy" \
-H "Authorization: Bearer <token>"
```
**Response:**
```json
{
"zone_id": "zone_001",
"current_occupancy": 3,
"max_occupancy": 10,
"persons": [
{
"person_id": "person_001",
"confidence": 0.85,
"activity": "standing"
}
],
"timestamp": "2025-01-07T10:00:00Z"
}
```
### Get Zones Summary
Get occupancy summary for all zones.
```http
GET /api/v1/pose/zones/summary
```
**Response:**
```json
{
"timestamp": "2025-01-07T10:00:00Z",
"total_persons": 5,
"zones": {
"zone_001": {
"occupancy": 3,
"max_occupancy": 10,
"status": "normal"
},
"zone_002": {
"occupancy": 2,
"max_occupancy": 8,
"status": "normal"
}
},
"active_zones": 2
}
```
### Get Historical Data
Retrieve historical pose estimation data.
```http
POST /api/v1/pose/historical
```
**Request Body:**
```json
{
"start_time": "2025-01-07T00:00:00Z",
"end_time": "2025-01-07T23:59:59Z",
"zone_ids": ["zone_001"],
"aggregation_interval": 300,
"include_raw_data": false
}
```
**Response:**
```json
{
"query": {
"start_time": "2025-01-07T00:00:00Z",
"end_time": "2025-01-07T23:59:59Z",
"zone_ids": ["zone_001"],
"aggregation_interval": 300
},
"data": [
{
"timestamp": "2025-01-07T00:00:00Z",
"average_occupancy": 2.5,
"max_occupancy": 5,
"total_detections": 150
}
],
"total_records": 288
}
```
### Get Detected Activities
Get recently detected activities.
```http
GET /api/v1/pose/activities
```
**Query Parameters:**
- `zone_id` (string, optional): Filter by zone
- `limit` (integer, optional): Maximum activities (1-100, default: 10)
**Response:**
```json
{
"activities": [
{
"activity": "walking",
"person_id": "person_001",
"zone_id": "zone_001",
"confidence": 0.9,
"timestamp": "2025-01-07T10:00:00Z",
"duration_seconds": 15.5
}
],
"total_count": 1,
"zone_id": "zone_001"
}
```
### Calibrate System
Start system calibration process.
```http
POST /api/v1/pose/calibrate
```
**Response:**
```json
{
"calibration_id": "cal_12345",
"status": "started",
"estimated_duration_minutes": 5,
"message": "Calibration process started"
}
```
### Get Calibration Status
Check calibration progress.
```http
GET /api/v1/pose/calibration/status
```
**Response:**
```json
{
"is_calibrating": true,
"calibration_id": "cal_12345",
"progress_percent": 60,
"current_step": "phase_sanitization",
"estimated_remaining_minutes": 2,
"last_calibration": "2025-01-06T15:30:00Z"
}
```
### Get Pose Statistics
Get pose estimation statistics.
```http
GET /api/v1/pose/stats
```
**Query Parameters:**
- `hours` (integer, optional): Hours of data to analyze (1-168, default: 24)
**Response:**
```json
{
"period": {
"start_time": "2025-01-06T10:00:00Z",
"end_time": "2025-01-07T10:00:00Z",
"hours": 24
},
"statistics": {
"total_detections": 1500,
"average_confidence": 0.82,
"unique_persons": 25,
"average_processing_time_ms": 47.3,
"zones": {
"zone_001": {
"detections": 800,
"average_occupancy": 3.2
}
}
}
}
```
## System Management API
### System Status
Get current system status.
```http
GET /api/v1/system/status
```
**Response:**
```json
{
"status": "running",
"uptime_seconds": 86400,
"services": {
"hardware": "healthy",
"pose_estimation": "healthy",
"streaming": "healthy"
},
"configuration": {
"domain": "healthcare",
"max_persons": 10,
"confidence_threshold": 0.7
},
"timestamp": "2025-01-07T10:00:00Z"
}
```
### Start System
Start the pose estimation system.
```http
POST /api/v1/system/start
```
**Request Body:**
```json
{
"configuration": {
"domain": "healthcare",
"environment_id": "room_001",
"calibration_required": true
}
}
```
### Stop System
Stop the pose estimation system.
```http
POST /api/v1/system/stop
```
### Restart System
Restart the system with new configuration.
```http
POST /api/v1/system/restart
```
### Get Configuration
Get current system configuration.
```http
GET /api/v1/config
```
### Update Configuration
Update system configuration.
```http
PUT /api/v1/config
```
**Request Body:**
```json
{
"detection": {
"confidence_threshold": 0.8,
"max_persons": 8
},
"analytics": {
"enable_fall_detection": true
}
}
```
## Health Check API
### Comprehensive Health Check
Get detailed system health information.
```http
GET /api/v1/health
```
**Response:**
```json
{
"status": "healthy",
"timestamp": "2025-01-07T10:00:00Z",
"uptime_seconds": 86400,
"components": {
"hardware": {
"name": "Hardware Service",
"status": "healthy",
"message": "All routers connected",
"last_check": "2025-01-07T10:00:00Z",
"uptime_seconds": 86400,
"metrics": {
"connected_routers": 3,
"csi_data_rate": 30.5
}
},
"pose": {
"name": "Pose Service",
"status": "healthy",
"message": "Processing normally",
"last_check": "2025-01-07T10:00:00Z",
"metrics": {
"processing_rate": 29.8,
"average_latency_ms": 45.2
}
}
},
"system_metrics": {
"cpu": {
"percent": 65.2,
"count": 8
},
"memory": {
"total_gb": 16.0,
"available_gb": 8.5,
"percent": 46.9
},
"disk": {
"total_gb": 500.0,
"free_gb": 350.0,
"percent": 30.0
}
}
}
```
### Readiness Check
Check if system is ready to serve requests.
```http
GET /api/v1/ready
```
**Response:**
```json
{
"ready": true,
"timestamp": "2025-01-07T10:00:00Z",
"checks": {
"hardware_ready": true,
"pose_ready": true,
"stream_ready": true,
"memory_available": true,
"disk_space_available": true
},
"message": "System is ready"
}
```
### Liveness Check
Simple liveness check for load balancers.
```http
GET /api/v1/live
```
**Response:**
```json
{
"status": "alive",
"timestamp": "2025-01-07T10:00:00Z"
}
```
### System Metrics
Get detailed system metrics.
```http
GET /api/v1/metrics
```
### Version Information
Get application version information.
```http
GET /api/v1/version
```
**Response:**
```json
{
"name": "WiFi-DensePose API",
"version": "1.0.0",
"environment": "production",
"debug": false,
"timestamp": "2025-01-07T10:00:00Z"
}
```
## WebSocket API
### Connection
Connect to WebSocket endpoint:
```javascript
const ws = new WebSocket('ws://localhost:8000/ws/pose/stream');
```
### Authentication
Send authentication message after connection:
```javascript
ws.send(JSON.stringify({
type: 'auth',
token: 'your-jwt-token'
}));
```
### Subscribe to Pose Updates
```javascript
ws.send(JSON.stringify({
type: 'subscribe',
channel: 'pose_updates',
filters: {
zone_ids: ['zone_001'],
min_confidence: 0.7
}
}));
```
### Pose Data Message
```json
{
"type": "pose_data",
"channel": "pose_updates",
"data": {
"timestamp": "2025-01-07T10:00:00Z",
"frame_id": "frame_12345",
"persons": [
{
"person_id": "person_001",
"confidence": 0.85,
"bounding_box": {
"x": 100,
"y": 150,
"width": 80,
"height": 180
},
"zone_id": "zone_001"
}
]
}
}
```
### System Events
Subscribe to system events:
```javascript
ws.send(JSON.stringify({
type: 'subscribe',
channel: 'system_events'
}));
```
### Event Message
```json
{
"type": "system_event",
"channel": "system_events",
"data": {
"event_type": "fall_detected",
"person_id": "person_001",
"zone_id": "zone_001",
"confidence": 0.95,
"timestamp": "2025-01-07T10:00:00Z"
}
}
```
## Data Models
### PersonPose
```json
{
"person_id": "string",
"confidence": 0.85,
"bounding_box": {
"x": 100,
"y": 150,
"width": 80,
"height": 180
},
"keypoints": [
{
"name": "nose",
"x": 140,
"y": 160,
"confidence": 0.9,
"visible": true
}
],
"segmentation": {
"mask": "base64-encoded-mask",
"body_parts": ["torso", "left_arm", "right_arm"]
},
"zone_id": "zone_001",
"activity": "standing",
"timestamp": "2025-01-07T10:00:00Z"
}
```
### Keypoint Names
Standard keypoint names following COCO format:
- `nose`, `left_eye`, `right_eye`, `left_ear`, `right_ear`
- `left_shoulder`, `right_shoulder`, `left_elbow`, `right_elbow`
- `left_wrist`, `right_wrist`, `left_hip`, `right_hip`
- `left_knee`, `right_knee`, `left_ankle`, `right_ankle`
### Activity Types
Supported activity classifications:
- `standing`, `sitting`, `walking`, `running`, `lying_down`
- `falling`, `jumping`, `bending`, `reaching`, `waving`
### Zone Configuration
```json
{
"zone_id": "zone_001",
"name": "Living Room",
"coordinates": {
"x": 0,
"y": 0,
"width": 500,
"height": 300
},
"max_occupancy": 10,
"alerts_enabled": true,
"privacy_level": "high"
}
```
## SDK Examples
### Python SDK
```python
from wifi_densepose import WiFiDensePoseClient
# Initialize client
client = WiFiDensePoseClient(
base_url="http://localhost:8000",
api_key="your-api-key"
)
# Get current poses
poses = client.get_current_poses(
confidence_threshold=0.7,
max_persons=5
)
# Get historical data
history = client.get_historical_data(
start_time="2025-01-07T00:00:00Z",
end_time="2025-01-07T23:59:59Z",
zone_ids=["zone_001"]
)
# Subscribe to real-time updates
def pose_callback(poses):
print(f"Received {len(poses)} poses")
client.subscribe_to_poses(callback=pose_callback)
```
### JavaScript SDK
```javascript
import { WiFiDensePoseClient } from 'wifi-densepose-js';
// Initialize client
const client = new WiFiDensePoseClient({
baseUrl: 'http://localhost:8000',
apiKey: 'your-api-key'
});
// Get current poses
const poses = await client.getCurrentPoses({
confidenceThreshold: 0.7,
maxPersons: 5
});
// Subscribe to WebSocket updates
client.subscribeToPoses({
onData: (poses) => {
console.log(`Received ${poses.length} poses`);
},
onError: (error) => {
console.error('WebSocket error:', error);
}
});
```
### cURL Examples
```bash
# Get current poses
curl -X GET "http://localhost:8000/api/v1/pose/current?confidence_threshold=0.7" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json"
# Start system
curl -X POST "http://localhost:8000/api/v1/system/start" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"configuration": {
"domain": "healthcare",
"environment_id": "room_001"
}
}'
# Get zone occupancy
curl -X GET "http://localhost:8000/api/v1/pose/zones/zone_001/occupancy" \
-H "Authorization: Bearer <token>"
```
---
For more information, see:
- [User Guide](user_guide.md)
- [Deployment Guide](deployment.md)
- [Troubleshooting Guide](troubleshooting.md)
- [Interactive API Documentation](http://localhost:8000/docs)

1103
v1/docs/deployment.md Normal file
View File

File diff suppressed because it is too large Load Diff

484
v1/docs/deployment/README.md Normal file
View File

@@ -0,0 +1,484 @@
# WiFi-DensePose DevOps & Deployment Guide
This guide provides comprehensive instructions for deploying and managing the WiFi-DensePose application infrastructure using modern DevOps practices.
## 🏗️ Architecture Overview
The WiFi-DensePose deployment architecture includes:
- **Container Orchestration**: Kubernetes with auto-scaling capabilities
- **Infrastructure as Code**: Terraform for AWS resource provisioning
- **CI/CD Pipelines**: GitHub Actions and GitLab CI support
- **Monitoring**: Prometheus, Grafana, and comprehensive alerting
- **Logging**: Centralized log aggregation with Fluentd and Elasticsearch
- **Security**: Automated security scanning and compliance checks
## 📋 Prerequisites
### Required Tools
Ensure the following tools are installed on your system:
```bash
# AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
# kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
# Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
# Terraform
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
# Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
### AWS Configuration
Configure AWS credentials with appropriate permissions:
```bash
aws configure
# Enter your AWS Access Key ID, Secret Access Key, and default region
```
Required AWS permissions:
- EC2 (VPC, Subnets, Security Groups, Load Balancers)
- EKS (Cluster management)
- ECR (Container registry)
- IAM (Roles and policies)
- S3 (State storage and log backup)
- CloudWatch (Monitoring and logging)
## 🚀 Quick Start
### 1. Clone and Setup
```bash
git clone <repository-url>
cd wifi-densepose
```
### 2. Configure Environment
```bash
# Set environment variables
export ENVIRONMENT=production
export AWS_REGION=us-west-2
export PROJECT_NAME=wifi-densepose
```
### 3. Deploy Everything
```bash
# Deploy complete infrastructure and application
./deploy.sh all
```
### 4. Verify Deployment
```bash
# Check application status
kubectl get pods -n wifi-densepose
# Access Grafana dashboard
kubectl port-forward svc/grafana 3000:80 -n monitoring
# Open http://localhost:3000 (admin/admin)
# Access application
kubectl get ingress -n wifi-densepose
```
## 📁 Directory Structure
```
├── deploy.sh # Main deployment script
├── Dockerfile # Application container image
├── docker-compose.yml # Local development setup
├── docker-compose.prod.yml # Production deployment
├── .dockerignore # Docker build context optimization
├── .github/workflows/ # GitHub Actions CI/CD
│ ├── ci.yml # Continuous Integration
│ ├── cd.yml # Continuous Deployment
│ └── security-scan.yml # Security scanning
├── .gitlab-ci.yml # GitLab CI configuration
├── k8s/ # Kubernetes manifests
│ ├── namespace.yaml # Namespace definition
│ ├── deployment.yaml # Application deployment
│ ├── service.yaml # Service configuration
│ ├── ingress.yaml # Ingress rules
│ ├── configmap.yaml # Configuration management
│ ├── secrets.yaml # Secret management template
│ └── hpa.yaml # Horizontal Pod Autoscaler
├── terraform/ # Infrastructure as Code
│ ├── main.tf # Main infrastructure definition
│ ├── variables.tf # Configuration variables
│ └── outputs.tf # Output values
├── ansible/ # Server configuration
│ └── playbook.yml # Ansible playbook
├── monitoring/ # Monitoring configuration
│ ├── prometheus-config.yml # Prometheus configuration
│ ├── grafana-dashboard.json # Grafana dashboard
│ └── alerting-rules.yml # Alert rules
└── logging/ # Logging configuration
└── fluentd-config.yml # Fluentd configuration
```
## 🔧 Deployment Options
### Individual Component Deployment
```bash
# Deploy only infrastructure
./deploy.sh infrastructure
# Deploy only Kubernetes resources
./deploy.sh kubernetes
# Deploy only monitoring stack
./deploy.sh monitoring
# Build and push Docker images
./deploy.sh images
# Run health checks
./deploy.sh health
# Setup CI/CD
./deploy.sh cicd
```
### Environment-Specific Deployment
```bash
# Development environment
ENVIRONMENT=development ./deploy.sh all
# Staging environment
ENVIRONMENT=staging ./deploy.sh all
# Production environment
ENVIRONMENT=production ./deploy.sh all
```
## 🐳 Docker Configuration
### Local Development
```bash
# Start local development environment
docker-compose up -d
# View logs
docker-compose logs -f
# Stop environment
docker-compose down
```
### Production Build
```bash
# Build production image
docker build -f Dockerfile -t wifi-densepose:latest .
# Multi-stage build for optimization
docker build --target production -t wifi-densepose:prod .
```
## ☸️ Kubernetes Management
### Common Operations
```bash
# View application logs
kubectl logs -f deployment/wifi-densepose -n wifi-densepose
# Scale application
kubectl scale deployment wifi-densepose --replicas=5 -n wifi-densepose
# Update application
kubectl set image deployment/wifi-densepose wifi-densepose=new-image:tag -n wifi-densepose
# Rollback deployment
kubectl rollout undo deployment/wifi-densepose -n wifi-densepose
# View resource usage
kubectl top pods -n wifi-densepose
kubectl top nodes
```
### Configuration Management
```bash
# Update ConfigMap
kubectl create configmap wifi-densepose-config \
--from-file=config/ \
--dry-run=client -o yaml | kubectl apply -f -
# Update Secrets
kubectl create secret generic wifi-densepose-secrets \
--from-literal=database-password=secret \
--dry-run=client -o yaml | kubectl apply -f -
```
## 📊 Monitoring & Observability
### Prometheus Metrics
Access Prometheus at: `http://localhost:9090` (via port-forward)
Key metrics to monitor:
- `http_requests_total` - HTTP request count
- `http_request_duration_seconds` - Request latency
- `wifi_densepose_data_processed_total` - Data processing metrics
- `wifi_densepose_model_inference_duration_seconds` - ML model performance
### Grafana Dashboards
Access Grafana at: `http://localhost:3000` (admin/admin)
Pre-configured dashboards:
- Application Overview
- Infrastructure Metrics
- Database Performance
- Kubernetes Cluster Status
- Security Alerts
### Log Analysis
```bash
# View application logs
kubectl logs -f -l app=wifi-densepose -n wifi-densepose
# Search logs in Elasticsearch
curl -X GET "elasticsearch:9200/wifi-densepose-*/_search" \
-H 'Content-Type: application/json' \
-d '{"query": {"match": {"level": "error"}}}'
```
## 🔒 Security Best Practices
### Implemented Security Measures
1. **Container Security**
- Non-root user execution
- Minimal base images
- Regular vulnerability scanning
- Resource limits and quotas
2. **Kubernetes Security**
- Network policies
- Pod security policies
- RBAC configuration
- Secret management
3. **Infrastructure Security**
- VPC with private subnets
- Security groups with minimal access
- IAM roles with least privilege
- Encrypted storage and transit
4. **CI/CD Security**
- Automated security scanning
- Dependency vulnerability checks
- Container image scanning
- Secret scanning
### Security Scanning
```bash
# Run security scan
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
aquasec/trivy image wifi-densepose:latest
# Kubernetes security scan
kubectl run --rm -i --tty kube-bench --image=aquasec/kube-bench:latest \
--restart=Never -- --version 1.20
```
## 🔄 CI/CD Pipelines
### GitHub Actions
Workflows are triggered on:
- **CI Pipeline** (`ci.yml`): Pull requests and pushes to main
- **CD Pipeline** (`cd.yml`): Tags and main branch pushes
- **Security Scan** (`security-scan.yml`): Daily scheduled runs
### GitLab CI
Configure GitLab CI variables:
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `KUBE_CONFIG`
- `ECR_REPOSITORY`
## 🏗️ Infrastructure as Code
### Terraform Configuration
```bash
# Initialize Terraform
cd terraform
terraform init
# Plan deployment
terraform plan -var="environment=production"
# Apply changes
terraform apply
# Destroy infrastructure
terraform destroy
```
### Ansible Configuration
```bash
# Run Ansible playbook
ansible-playbook -i inventory ansible/playbook.yml
```
## 🚨 Troubleshooting
### Common Issues
1. **Pod Startup Issues**
```bash
kubectl describe pod <pod-name> -n wifi-densepose
kubectl logs <pod-name> -n wifi-densepose
```
2. **Service Discovery Issues**
```bash
kubectl get endpoints -n wifi-densepose
kubectl get services -n wifi-densepose
```
3. **Ingress Issues**
```bash
kubectl describe ingress wifi-densepose-ingress -n wifi-densepose
kubectl get events -n wifi-densepose
```
4. **Resource Issues**
```bash
kubectl top pods -n wifi-densepose
kubectl describe nodes
```
### Health Checks
```bash
# Application health
curl http://<ingress-url>/health
# Database connectivity
kubectl exec -it <pod-name> -n wifi-densepose -- pg_isready
# Redis connectivity
kubectl exec -it <pod-name> -n wifi-densepose -- redis-cli ping
```
## 📈 Scaling & Performance
### Horizontal Pod Autoscaler
```bash
# View HPA status
kubectl get hpa -n wifi-densepose
# Update HPA configuration
kubectl patch hpa wifi-densepose-hpa -n wifi-densepose -p '{"spec":{"maxReplicas":10}}'
```
### Cluster Autoscaler
```bash
# View cluster autoscaler logs
kubectl logs -f deployment/cluster-autoscaler -n kube-system
```
### Performance Tuning
1. **Resource Requests/Limits**
- CPU: Request 100m, Limit 500m
- Memory: Request 256Mi, Limit 512Mi
2. **Database Optimization**
- Connection pooling
- Query optimization
- Index management
3. **Caching Strategy**
- Redis for session storage
- Application-level caching
- CDN for static assets
## 🔄 Backup & Recovery
### Database Backup
```bash
# Create database backup
kubectl exec -it postgres-pod -n wifi-densepose -- \
pg_dump -U postgres wifi_densepose > backup.sql
# Restore database
kubectl exec -i postgres-pod -n wifi-densepose -- \
psql -U postgres wifi_densepose < backup.sql
```
### Configuration Backup
```bash
# Backup Kubernetes resources
kubectl get all -n wifi-densepose -o yaml > k8s-backup.yaml
# Backup ConfigMaps and Secrets
kubectl get configmaps,secrets -n wifi-densepose -o yaml > config-backup.yaml
```
## 📞 Support & Maintenance
### Regular Maintenance Tasks
1. **Weekly**
- Review monitoring alerts
- Check resource utilization
- Update dependencies
2. **Monthly**
- Security patch updates
- Performance optimization
- Backup verification
3. **Quarterly**
- Disaster recovery testing
- Security audit
- Capacity planning
### Contact Information
- **DevOps Team**: devops@wifi-densepose.com
- **On-Call**: +1-555-0123
- **Documentation**: https://docs.wifi-densepose.com
- **Status Page**: https://status.wifi-densepose.com
## 📚 Additional Resources
- [Kubernetes Documentation](https://kubernetes.io/docs/)
- [Terraform AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
- [Prometheus Monitoring](https://prometheus.io/docs/)
- [Grafana Dashboards](https://grafana.com/docs/)
- [AWS EKS Best Practices](https://aws.github.io/aws-eks-best-practices/)

848
v1/docs/developer/architecture-overview.md Normal file
View File

@@ -0,0 +1,848 @@
# Architecture Overview
## Overview
The WiFi-DensePose system is a distributed, microservices-based architecture that transforms WiFi Channel State Information (CSI) into real-time human pose estimation. This document provides a comprehensive overview of the system architecture, component interactions, and design principles.
## Table of Contents
1. [System Architecture](#system-architecture)
2. [Core Components](#core-components)
3. [Data Flow](#data-flow)
4. [Processing Pipeline](#processing-pipeline)
5. [API Architecture](#api-architecture)
6. [Storage Architecture](#storage-architecture)
7. [Security Architecture](#security-architecture)
8. [Deployment Architecture](#deployment-architecture)
9. [Scalability and Performance](#scalability-and-performance)
10. [Design Principles](#design-principles)
## System Architecture
### High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ WiFi-DensePose System │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Client Apps │ │ Web Dashboard │ │ Mobile Apps │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ API Gateway │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ REST API │ │ WebSocket API │ │ MQTT Broker │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Processing Layer │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Pose Estimation │ │ Tracking │ │ Analytics │ │
│ │ Service │ │ Service │ │ Service │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Data Layer │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ CSI Processor │ │ Data Pipeline │ │ Model Manager │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Hardware Layer │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ WiFi Routers │ │ Processing Unit │ │ GPU Cluster │ │
│ │ (CSI Data) │ │ (CPU/Memory) │ │ (Neural Net) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### Component Interaction Diagram
```
┌─────────────┐ CSI Data ┌─────────────┐ Features ┌─────────────┐
│ Router │ ──────────────▶│ CSI │ ──────────────▶│ Feature │
│ Network │ │ Processor │ │ Extractor │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ Poses ┌─────────────┐ Inference ┌─────────────┐
│ Client │ ◀──────────────│ Pose │ ◀──────────────│ Neural │
│ Applications│ │ Tracker │ │ Network │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────┐ Events ┌─────────────┐ Models ┌─────────────┐
│ Alert │ ◀──────────────│ Analytics │ ◀──────────────│ Model │
│ System │ │ Engine │ │ Manager │
└─────────────┘ └─────────────┘ └─────────────┘
```
## Core Components
### 1. CSI Data Processor
**Purpose**: Receives and processes raw Channel State Information from WiFi routers.
**Key Features**:
- Real-time CSI data ingestion from multiple routers
- Signal preprocessing and noise reduction
- Phase sanitization and amplitude normalization
- Multi-antenna data fusion
**Implementation**: [`src/hardware/csi_processor.py`](../../src/hardware/csi_processor.py)
```python
class CSIProcessor:
"""Processes raw CSI data from WiFi routers."""
def __init__(self, config: CSIConfig):
self.routers = self._initialize_routers(config.routers)
self.buffer = CircularBuffer(config.buffer_size)
self.preprocessor = CSIPreprocessor()
async def process_stream(self) -> AsyncGenerator[CSIData, None]:
"""Process continuous CSI data stream."""
async for raw_data in self._receive_csi_data():
processed_data = self.preprocessor.process(raw_data)
yield processed_data
```
### 2. Neural Network Service
**Purpose**: Performs pose estimation using deep learning models.
**Key Features**:
- DensePose model inference
- Batch processing optimization
- GPU acceleration support
- Model versioning and hot-swapping
**Implementation**: [`src/neural_network/inference.py`](../../src/neural_network/inference.py)
```python
class PoseEstimationService:
"""Neural network service for pose estimation."""
def __init__(self, model_config: ModelConfig):
self.model = self._load_model(model_config.model_path)
self.device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
self.batch_processor = BatchProcessor(model_config.batch_size)
async def estimate_poses(self, csi_features: CSIFeatures) -> List[PoseEstimation]:
"""Estimate human poses from CSI features."""
with torch.no_grad():
predictions = self.model(csi_features.to(self.device))
return self._postprocess_predictions(predictions)
```
### 3. Tracking Service
**Purpose**: Maintains temporal consistency and person identity across frames.
**Key Features**:
- Multi-object tracking with Kalman filters
- Person re-identification
- Track lifecycle management
- Trajectory smoothing
**Implementation**: [`src/tracking/tracker.py`](../../src/tracking/tracker.py)
```python
class PersonTracker:
"""Tracks multiple persons across time."""
def __init__(self, tracking_config: TrackingConfig):
self.tracks = {}
self.track_id_counter = 0
self.kalman_filter = KalmanFilter()
self.reid_model = ReIDModel()
def update(self, detections: List[PoseDetection]) -> List[TrackedPose]:
"""Update tracks with new detections."""
matched_tracks, unmatched_detections = self._associate_detections(detections)
self._update_matched_tracks(matched_tracks)
self._create_new_tracks(unmatched_detections)
return self._get_active_tracks()
```
### 4. API Gateway
**Purpose**: Provides unified access to system functionality through REST and WebSocket APIs.
**Key Features**:
- Authentication and authorization
- Rate limiting and throttling
- Request routing and load balancing
- API versioning
**Implementation**: [`src/api/main.py`](../../src/api/main.py)
```python
from fastapi import FastAPI, Depends
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(
title="WiFi-DensePose API",
version="1.0.0",
description="Privacy-preserving human pose estimation using WiFi signals"
)
# Middleware
app.add_middleware(CORSMiddleware, **get_cors_config())
app.add_middleware(RateLimitMiddleware)
app.add_middleware(AuthenticationMiddleware)
# Routers
app.include_router(pose_router, prefix="/api/v1/pose")
app.include_router(system_router, prefix="/api/v1/system")
app.include_router(analytics_router, prefix="/api/v1/analytics")
```
### 5. Analytics Engine
**Purpose**: Processes pose data to generate insights and trigger alerts.
**Key Features**:
- Real-time event detection (falls, intrusions)
- Statistical analysis and reporting
- Domain-specific analytics (healthcare, retail, security)
- Machine learning-based pattern recognition
**Implementation**: [`src/analytics/engine.py`](../../src/analytics/engine.py)
```python
class AnalyticsEngine:
"""Processes pose data for insights and alerts."""
def __init__(self, domain_config: DomainConfig):
self.domain = domain_config.domain
self.event_detectors = self._load_event_detectors(domain_config)
self.alert_manager = AlertManager(domain_config.alerts)
async def process_poses(self, poses: List[TrackedPose]) -> AnalyticsResult:
"""Process poses and generate analytics."""
events = []
for detector in self.event_detectors:
detected_events = await detector.detect(poses)
events.extend(detected_events)
await self.alert_manager.process_events(events)
return AnalyticsResult(events=events, metrics=self._calculate_metrics(poses))
```
## Data Flow
### Real-Time Processing Pipeline
```
1. CSI Data Acquisition
┌─────────────┐
│ Router 1 │ ──┐
└─────────────┘ │
┌─────────────┐ │ ┌─────────────┐
│ Router 2 │ ──┼───▶│ CSI Buffer │
└─────────────┘ │ └─────────────┘
┌─────────────┐ │ │
│ Router N │ ──┘ ▼
└─────────────┘ ┌─────────────┐
│ Preprocessor│
└─────────────┘
│
2. Feature Extraction ▼
┌─────────────┐ ┌─────────────┐
│ Phase │ ◀─────│ Feature │
│ Sanitizer │ │ Extractor │
└─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Amplitude │ │ Frequency │
│ Processor │ │ Analyzer │
└─────────────┘ └─────────────┘
│ │
└──────┬──────────────┘
▼
3. Neural Network Inference
┌─────────────┐
│ DensePose │
│ Model │
└─────────────┘
│
▼
┌─────────────┐
│ Pose │
│ Decoder │
└─────────────┘
│
4. Tracking and Analytics ▼
┌─────────────┐ ┌─────────────┐
│ Person │ ◀─────│ Raw Pose │
│ Tracker │ │ Detections │
└─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ Analytics │
│ Engine │
└─────────────┘
│
5. Output and Storage ▼
┌─────────────┐ ┌─────────────┐
│ WebSocket │ ◀─────│ Tracked │
│ Streams │ │ Poses │
└─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Client │ │ Database │
│ Applications│ │ Storage │
└─────────────┘ └─────────────┘
```
### Data Models
#### CSI Data Structure
```python
@dataclass
class CSIData:
"""Channel State Information data structure."""
timestamp: datetime
router_id: str
antenna_pairs: List[AntennaPair]
subcarriers: List[SubcarrierData]
metadata: CSIMetadata
@dataclass
class SubcarrierData:
"""Individual subcarrier information."""
frequency: float
amplitude: complex
phase: float
snr: float
```
#### Pose Data Structure
```python
@dataclass
class PoseEstimation:
"""Human pose estimation result."""
person_id: Optional[int]
confidence: float
bounding_box: BoundingBox
keypoints: List[Keypoint]
dense_pose: Optional[DensePoseResult]
timestamp: datetime
@dataclass
class TrackedPose:
"""Tracked pose with temporal information."""
track_id: int
pose: PoseEstimation
velocity: Vector2D
track_age: int
track_confidence: float
```
## Processing Pipeline
### 1. CSI Preprocessing
```python
class CSIPreprocessor:
"""Preprocesses raw CSI data for neural network input."""
def __init__(self, config: PreprocessingConfig):
self.phase_sanitizer = PhaseSanitizer()
self.amplitude_normalizer = AmplitudeNormalizer()
self.noise_filter = NoiseFilter(config.filter_params)
def process(self, raw_csi: RawCSIData) -> ProcessedCSIData:
"""Process raw CSI data."""
# Phase unwrapping and sanitization
sanitized_phase = self.phase_sanitizer.sanitize(raw_csi.phase)
# Amplitude normalization
normalized_amplitude = self.amplitude_normalizer.normalize(raw_csi.amplitude)
# Noise filtering
filtered_data = self.noise_filter.filter(sanitized_phase, normalized_amplitude)
return ProcessedCSIData(
phase=filtered_data.phase,
amplitude=filtered_data.amplitude,
timestamp=raw_csi.timestamp,
metadata=raw_csi.metadata
)
```
### 2. Feature Extraction
```python
class FeatureExtractor:
"""Extracts features from processed CSI data."""
def __init__(self, config: FeatureConfig):
self.window_size = config.window_size
self.feature_types = config.feature_types
self.pca_reducer = PCAReducer(config.pca_components)
def extract_features(self, csi_data: ProcessedCSIData) -> CSIFeatures:
"""Extract features for neural network input."""
features = {}
if 'amplitude' in self.feature_types:
features['amplitude'] = self._extract_amplitude_features(csi_data)
if 'phase' in self.feature_types:
features['phase'] = self._extract_phase_features(csi_data)
if 'doppler' in self.feature_types:
features['doppler'] = self._extract_doppler_features(csi_data)
# Dimensionality reduction
reduced_features = self.pca_reducer.transform(features)
return CSIFeatures(
features=reduced_features,
timestamp=csi_data.timestamp,
feature_types=self.feature_types
)
```
### 3. Neural Network Architecture
```python
class DensePoseNet(nn.Module):
"""DensePose neural network for WiFi-based pose estimation."""
def __init__(self, config: ModelConfig):
super().__init__()
self.backbone = self._build_backbone(config.backbone)
self.feature_pyramid = FeaturePyramidNetwork(config.fpn)
self.pose_head = PoseEstimationHead(config.pose_head)
self.dense_pose_head = DensePoseHead(config.dense_pose_head)
def forward(self, csi_features: torch.Tensor) -> Dict[str, torch.Tensor]:
"""Forward pass through the network."""
# Feature extraction
backbone_features = self.backbone(csi_features)
pyramid_features = self.feature_pyramid(backbone_features)
# Pose estimation
pose_predictions = self.pose_head(pyramid_features)
dense_pose_predictions = self.dense_pose_head(pyramid_features)
return {
'poses': pose_predictions,
'dense_poses': dense_pose_predictions
}
```
## API Architecture
### REST API Design
The REST API follows RESTful principles with clear resource hierarchies:
```
/api/v1/
├── auth/
│ ├── token # POST: Get authentication token
│ └── verify # POST: Verify token validity
├── system/
│ ├── status # GET: System health status
│ ├── start # POST: Start pose estimation
│ ├── stop # POST: Stop pose estimation
│ └── diagnostics # GET: System diagnostics
├── pose/
│ ├── latest # GET: Latest pose data
│ ├── history # GET: Historical pose data
│ └── query # POST: Complex pose queries
├── config/
│ └── [resource] # GET/PUT: Configuration management
└── analytics/
├── healthcare # GET: Healthcare analytics
├── retail # GET: Retail analytics
└── security # GET: Security analytics
```
### WebSocket API Design
```python
class WebSocketManager:
"""Manages WebSocket connections and subscriptions."""
def __init__(self):
self.connections: Dict[str, WebSocket] = {}
self.subscriptions: Dict[str, Set[str]] = {}
async def handle_connection(self, websocket: WebSocket, client_id: str):
"""Handle new WebSocket connection."""
await websocket.accept()
self.connections[client_id] = websocket
try:
async for message in websocket.iter_text():
await self._handle_message(client_id, json.loads(message))
except WebSocketDisconnect:
self._cleanup_connection(client_id)
async def broadcast_pose_update(self, pose_data: TrackedPose):
"""Broadcast pose updates to subscribed clients."""
message = {
'type': 'pose_update',
'data': pose_data.to_dict(),
'timestamp': datetime.utcnow().isoformat()
}
for client_id in self.subscriptions.get('pose_updates', set()):
if client_id in self.connections:
await self.connections[client_id].send_text(json.dumps(message))
```
## Storage Architecture
### Database Design
#### Time-Series Data (PostgreSQL + TimescaleDB)
```sql
-- Pose data table with time-series optimization
CREATE TABLE pose_data (
id BIGSERIAL PRIMARY KEY,
timestamp TIMESTAMPTZ NOT NULL,
frame_id BIGINT NOT NULL,
person_id INTEGER,
track_id INTEGER,
confidence REAL NOT NULL,
bounding_box JSONB NOT NULL,
keypoints JSONB NOT NULL,
dense_pose JSONB,
metadata JSONB,
environment_id VARCHAR(50) NOT NULL
);
-- Convert to hypertable for time-series optimization
SELECT create_hypertable('pose_data', 'timestamp');
-- Create indexes for common queries
CREATE INDEX idx_pose_data_timestamp ON pose_data (timestamp DESC);
CREATE INDEX idx_pose_data_person_id ON pose_data (person_id, timestamp DESC);
CREATE INDEX idx_pose_data_environment ON pose_data (environment_id, timestamp DESC);
```
#### Configuration Storage (PostgreSQL)
```sql
-- System configuration
CREATE TABLE system_config (
id SERIAL PRIMARY KEY,
domain VARCHAR(50) NOT NULL,
environment_id VARCHAR(50) NOT NULL,
config_data JSONB NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(domain, environment_id)
);
-- Model metadata
CREATE TABLE model_metadata (
id SERIAL PRIMARY KEY,
model_name VARCHAR(100) NOT NULL,
model_version VARCHAR(20) NOT NULL,
model_path TEXT NOT NULL,
config JSONB NOT NULL,
performance_metrics JSONB,
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(model_name, model_version)
);
```
### Caching Strategy (Redis)
```python
class CacheManager:
"""Manages Redis caching for frequently accessed data."""
def __init__(self, redis_client: Redis):
self.redis = redis_client
self.default_ttl = 300 # 5 minutes
async def cache_pose_data(self, pose_data: TrackedPose, ttl: int = None):
"""Cache pose data with automatic expiration."""
key = f"pose:latest:{pose_data.track_id}"
value = json.dumps(pose_data.to_dict(), default=str)
await self.redis.setex(key, ttl or self.default_ttl, value)
async def get_cached_poses(self, track_ids: List[int]) -> List[TrackedPose]:
"""Retrieve cached pose data for multiple tracks."""
keys = [f"pose:latest:{track_id}" for track_id in track_ids]
cached_data = await self.redis.mget(keys)
poses = []
for data in cached_data:
if data:
pose_dict = json.loads(data)
poses.append(TrackedPose.from_dict(pose_dict))
return poses
```
## Security Architecture
### Authentication and Authorization
```python
class SecurityManager:
"""Handles authentication and authorization."""
def __init__(self, config: SecurityConfig):
self.jwt_secret = config.jwt_secret
self.jwt_algorithm = config.jwt_algorithm
self.token_expiry = config.token_expiry
def create_access_token(self, user_data: dict) -> str:
"""Create JWT access token."""
payload = {
'sub': user_data['username'],
'exp': datetime.utcnow() + timedelta(hours=self.token_expiry),
'iat': datetime.utcnow(),
'permissions': user_data.get('permissions', [])
}
return jwt.encode(payload, self.jwt_secret, algorithm=self.jwt_algorithm)
def verify_token(self, token: str) -> dict:
"""Verify and decode JWT token."""
try:
payload = jwt.decode(token, self.jwt_secret, algorithms=[self.jwt_algorithm])
return payload
except jwt.ExpiredSignatureError:
raise HTTPException(status_code=401, detail="Token expired")
except jwt.InvalidTokenError:
raise HTTPException(status_code=401, detail="Invalid token")
```
### Data Privacy
```python
class PrivacyManager:
"""Manages data privacy and anonymization."""
def __init__(self, config: PrivacyConfig):
self.anonymization_enabled = config.anonymization_enabled
self.data_retention_days = config.data_retention_days
self.encryption_key = config.encryption_key
def anonymize_pose_data(self, pose_data: TrackedPose) -> TrackedPose:
"""Anonymize pose data for privacy protection."""
if not self.anonymization_enabled:
return pose_data
# Remove or hash identifying information
anonymized_data = pose_data.copy()
anonymized_data.track_id = self._hash_track_id(pose_data.track_id)
# Apply differential privacy to keypoints
anonymized_data.pose.keypoints = self._add_noise_to_keypoints(
pose_data.pose.keypoints
)
return anonymized_data
```
## Deployment Architecture
### Container Architecture
```yaml
# docker-compose.yml
version: '3.8'
services:
wifi-densepose-api:
build: .
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql://user:pass@postgres:5432/wifi_densepose
- REDIS_URL=redis://redis:6379/0
depends_on:
- postgres
- redis
- neural-network
volumes:
- ./data:/app/data
- ./models:/app/models
neural-network:
build: ./neural_network
runtime: nvidia
environment:
- CUDA_VISIBLE_DEVICES=0
volumes:
- ./models:/app/models
postgres:
image: timescale/timescaledb:latest-pg14
environment:
- POSTGRES_DB=wifi_densepose
- POSTGRES_USER=user
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
volumes:
postgres_data:
redis_data:
```
### Kubernetes Deployment
```yaml
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: wifi-densepose-api
spec:
replicas: 3
selector:
matchLabels:
app: wifi-densepose-api
template:
metadata:
labels:
app: wifi-densepose-api
spec:
containers:
- name: api
image: wifi-densepose:latest
ports:
- containerPort: 8000
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: database-secret
key: url
resources:
requests:
memory: "2Gi"
cpu: "1000m"
limits:
memory: "4Gi"
cpu: "2000m"
```
## Scalability and Performance
### Horizontal Scaling
```python
class LoadBalancer:
"""Distributes processing load across multiple instances."""
def __init__(self, config: LoadBalancerConfig):
self.processing_nodes = config.processing_nodes
self.load_balancing_strategy = config.strategy
self.health_checker = HealthChecker()
async def distribute_csi_data(self, csi_data: CSIData) -> str:
"""Distribute CSI data to available processing nodes."""
available_nodes = await self.health_checker.get_healthy_nodes()
if self.load_balancing_strategy == 'round_robin':
node = self._round_robin_selection(available_nodes)
elif self.load_balancing_strategy == 'least_loaded':
node = await self._least_loaded_selection(available_nodes)
else:
node = random.choice(available_nodes)
await self._send_to_node(node, csi_data)
return node.id
```
### Performance Optimization
```python
class PerformanceOptimizer:
"""Optimizes system performance based on runtime metrics."""
def __init__(self, config: OptimizationConfig):
self.metrics_collector = MetricsCollector()
self.auto_scaling_enabled = config.auto_scaling_enabled
self.optimization_interval = config.optimization_interval
async def optimize_processing_pipeline(self):
"""Optimize processing pipeline based on current metrics."""
metrics = await self.metrics_collector.get_current_metrics()
# Adjust batch size based on GPU utilization
if metrics.gpu_utilization < 0.7:
await self._increase_batch_size()
elif metrics.gpu_utilization > 0.9:
await self._decrease_batch_size()
# Scale processing nodes based on queue length
if metrics.processing_queue_length > 100:
await self._scale_up_processing_nodes()
elif metrics.processing_queue_length < 10:
await self._scale_down_processing_nodes()
```
## Design Principles
### 1. Modularity and Separation of Concerns
- Each component has a single, well-defined responsibility
- Clear interfaces between components
- Pluggable architecture for easy component replacement
### 2. Scalability
- Horizontal scaling support through microservices
- Stateless service design where possible
- Efficient resource utilization and load balancing
### 3. Reliability and Fault Tolerance
- Graceful degradation under failure conditions
- Circuit breaker patterns for external dependencies
- Comprehensive error handling and recovery mechanisms
### 4. Performance
- Optimized data structures and algorithms
- Efficient memory management and garbage collection
- GPU acceleration for compute-intensive operations
### 5. Security and Privacy
- Defense in depth security model
- Data encryption at rest and in transit
- Privacy-preserving data processing techniques
### 6. Observability
- Comprehensive logging and monitoring
- Distributed tracing for request flow analysis
- Performance metrics and alerting
### 7. Maintainability
- Clean code principles and consistent coding standards
- Comprehensive documentation and API specifications
- Automated testing and continuous integration
---
This architecture overview provides the foundation for understanding the WiFi-DensePose system. For implementation details, see:
- [API Architecture](../api/rest-endpoints.md)
- [Neural Network Architecture](../../plans/phase2-architecture/neural-network-architecture.md)
- [Hardware Integration](../../plans/phase2-architecture/hardware-integration.md)
- [Deployment Guide](deployment-guide.md)

1056
v1/docs/developer/contributing.md Normal file
View File

File diff suppressed because it is too large Load Diff

1637
v1/docs/developer/deployment-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

1774
v1/docs/developer/testing-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

507
v1/docs/implementation-plan.md Normal file
View File

@@ -0,0 +1,507 @@
# WiFi-DensePose Full Implementation Plan
## Executive Summary
This document outlines a comprehensive plan to fully implement WiFi-based pose detection functionality in the WiFi-DensePose system. Based on the system review, while the architecture and infrastructure are professionally implemented, the core WiFi CSI processing and machine learning components require complete implementation.
## Current System Assessment
### ✅ Existing Infrastructure (90%+ Complete)
- **API Framework**: FastAPI with REST endpoints and WebSocket streaming
- **Database Layer**: SQLAlchemy models, migrations, PostgreSQL/SQLite support
- **Configuration Management**: Environment variables, settings, logging
- **Service Architecture**: Orchestration, health checks, metrics collection
- **Deployment Infrastructure**: Docker, Kubernetes, monitoring configurations
### ❌ Missing Core Functionality (0-40% Complete)
- **WiFi CSI Data Collection**: Hardware interface implementation
- **Signal Processing Pipeline**: Real-time CSI processing algorithms
- **Machine Learning Models**: Trained DensePose models and inference
- **Domain Adaptation**: CSI-to-visual feature translation
- **Real-time Processing**: Integration of all components
## Implementation Strategy
### Phase-Based Approach
The implementation will follow a 4-phase approach to minimize risk and ensure systematic progress:
1. **Phase 1: Hardware Foundation** (4-6 weeks)
2. **Phase 2: Signal Processing Pipeline** (6-8 weeks)
3. **Phase 3: Machine Learning Integration** (8-12 weeks)
4. **Phase 4: Optimization & Production** (4-6 weeks)
## Hardware Requirements Analysis
### Supported CSI Hardware Platforms
Based on 2024 research, the following hardware platforms support CSI extraction:
#### Primary Recommendation: ESP32 Series
- **ESP32/ESP32-S2/ESP32-C3/ESP32-S3/ESP32-C6**: All support CSI extraction
- **Advantages**:
- Dual-core 240MHz CPU with AI instruction sets
- Neural network support for edge processing
- BLE support for device scanning
- Low cost and widely available
- Active community and documentation
#### Secondary Options:
- **NXP 88w8987 Module**: SDIO 3.0 interface, requires SDK 2.15+
- **Atheros-based Routers**: With modified OpenWRT firmware
- **Intel WiFi Cards**: With CSI tool support (Linux driver modifications)
#### Commercial Router Integration:
- **TP-Link WR842ND**: With special OpenWRT firmware containing recvCSI/sendData functions
- **Custom Router Deployment**: Modified firmware for CSI data extraction
## Detailed Implementation Plan
### Phase 1: Hardware Foundation (4-6 weeks)
#### Week 1-2: Hardware Setup and CSI Extraction
**Objective**: Establish reliable CSI data collection from WiFi hardware
**Tasks**:
1. **Hardware Procurement and Setup**
- Deploy ESP32 development boards as CSI receivers
- Configure routers with CSI-enabled firmware
- Set up test environment with controlled RF conditions
2. **CSI Data Collection Implementation**
- Implement `src/hardware/csi_extractor.py`:
- ESP32 CSI data parsing (amplitude, phase, subcarrier data)
- Router communication protocols (SSH, SNMP, custom APIs)
- Real-time data streaming over WiFi/Ethernet
- Replace mock data generation with actual CSI parsing
- Implement CSI data validation and error handling
3. **Router Interface Development**
- Complete `src/hardware/router_interface.py`:
- SSH connection management for router control
- CSI data request/response protocols
- Router health monitoring and status reporting
- Implement `src/core/router_interface.py`:
- Real CSI data collection replacing mock implementation
- Multi-router support for spatial diversity
- Data synchronization across multiple sources
**Deliverables**:
- Functional CSI data extraction from ESP32 devices
- Router communication interface with actual hardware
- Real-time CSI data streaming to processing pipeline
- Hardware configuration documentation
#### Week 3-4: Signal Processing Foundation
**Objective**: Implement basic CSI preprocessing and validation
**Tasks**:
1. **CSI Data Preprocessing**
- Enhance `src/core/phase_sanitizer.py`:
- Advanced phase unwrapping algorithms
- Phase noise filtering specific to WiFi CSI
- Temporal phase consistency correction
2. **Signal Quality Assessment**
- Implement CSI signal quality metrics
- Signal-to-noise ratio estimation
- Subcarrier validity checking
- Environmental noise characterization
3. **Data Validation Pipeline**
- CSI data integrity checks
- Temporal consistency validation
- Multi-antenna correlation analysis
- Real-time data quality monitoring
**Deliverables**:
- Clean, validated CSI data streams
- Signal quality assessment metrics
- Preprocessing pipeline for ML consumption
- Data quality monitoring dashboard
### Phase 2: Signal Processing Pipeline (6-8 weeks)
#### Week 5-8: Advanced Signal Processing
**Objective**: Develop sophisticated CSI processing for human detection
**Tasks**:
1. **Human Detection Algorithms**
- Implement `src/core/csi_processor.py`:
- Doppler shift analysis for motion detection
- Amplitude variation patterns for human presence
- Multi-path analysis for spatial localization
- Temporal filtering for noise reduction
2. **Feature Extraction**
- CSI amplitude and phase feature extraction
- Statistical features (mean, variance, correlation)
- Frequency domain analysis (FFT, spectrograms)
- Spatial correlation between antenna pairs
3. **Environmental Calibration**
- Background noise characterization
- Static environment profiling
- Dynamic calibration for environmental changes
- Multi-zone detection algorithms
**Deliverables**:
- Real-time human detection from CSI data
- Feature extraction pipeline for ML models
- Environmental calibration system
- Performance metrics and validation
#### Week 9-12: Real-time Processing Integration
**Objective**: Integrate signal processing with existing system architecture
**Tasks**:
1. **Service Integration**
- Update `src/services/pose_service.py`:
- Remove mock data generation
- Integrate real CSI processing pipeline
- Implement real-time pose estimation workflow
2. **Streaming Pipeline**
- Real-time CSI data streaming architecture
- Buffer management for temporal processing
- Low-latency processing optimizations
- Data synchronization across multiple sensors
3. **Performance Optimization**
- Multi-threading for parallel processing
- GPU acceleration where applicable
- Memory optimization for real-time constraints
- Latency optimization for interactive applications
**Deliverables**:
- Integrated real-time processing pipeline
- Optimized performance for production deployment
- Real-time CSI-to-pose data flow
- System performance benchmarks
### Phase 3: Machine Learning Integration (8-12 weeks)
#### Week 13-16: Model Training Infrastructure
**Objective**: Develop training pipeline for WiFi-to-pose domain adaptation
**Tasks**:
1. **Data Collection and Annotation**
- Synchronized CSI and video data collection
- Human pose annotation using computer vision
- Multi-person scenario data collection
- Diverse environment data gathering
2. **Domain Adaptation Framework**
- Complete `src/models/modality_translation.py`:
- Load pre-trained visual DensePose models
- Implement CSI-to-visual feature mapping
- Domain adversarial training setup
- Transfer learning optimization
3. **Training Pipeline**
- Model training scripts and configuration
- Data preprocessing for training
- Loss function design for domain adaptation
- Training monitoring and validation
**Deliverables**:
- Annotated CSI-pose dataset
- Domain adaptation training framework
- Initial trained models for testing
- Training pipeline documentation
#### Week 17-20: DensePose Integration
**Objective**: Integrate trained models with inference pipeline
**Tasks**:
1. **Model Loading and Inference**
- Complete `src/models/densepose_head.py`:
- Load trained DensePose models
- GPU acceleration for inference
- Batch processing optimization
- Real-time inference pipeline
2. **Pose Estimation Pipeline**
- CSI → Visual features → Pose estimation workflow
- Temporal smoothing for consistent poses
- Multi-person pose tracking
- Confidence scoring and validation
3. **Output Processing**
- Pose keypoint extraction and formatting
- Coordinate system transformation
- Output validation and filtering
- API integration for real-time streaming
**Deliverables**:
- Functional pose estimation from CSI data
- Real-time inference pipeline
- Validated pose estimation accuracy
- API integration for pose streaming
#### Week 21-24: Model Optimization and Validation
**Objective**: Optimize models for production deployment
**Tasks**:
1. **Model Optimization**
- Model quantization for edge deployment
- Architecture optimization for latency
- Memory usage optimization
- Model ensembling for improved accuracy
2. **Validation and Testing**
- Comprehensive accuracy testing
- Cross-environment validation
- Multi-person scenario testing
- Long-term stability testing
3. **Performance Benchmarking**
- Latency benchmarking
- Accuracy metrics vs. visual methods
- Resource usage profiling
- Scalability testing
**Deliverables**:
- Production-ready models
- Comprehensive validation results
- Performance benchmarks
- Deployment optimization guide
### Phase 4: Optimization & Production (4-6 weeks)
#### Week 25-26: System Integration and Testing
**Objective**: Complete end-to-end system integration
**Tasks**:
1. **Full System Integration**
- Integration testing of all components
- End-to-end workflow validation
- Error handling and recovery testing
- System reliability testing
2. **API Completion**
- Remove all mock implementations
- Complete authentication system
- Real-time streaming optimization
- API documentation updates
3. **Database Integration**
- Pose data persistence implementation
- Historical data analysis features
- Data retention and archival policies
- Performance optimization
**Deliverables**:
- Fully integrated system
- Complete API implementation
- Database integration for pose storage
- System reliability validation
#### Week 27-28: Production Deployment and Monitoring
**Objective**: Prepare system for production deployment
**Tasks**:
1. **Production Optimization**
- Docker container optimization
- Kubernetes deployment refinement
- Monitoring and alerting setup
- Backup and disaster recovery
2. **Documentation and Training**
- Deployment guide updates
- User manual completion
- API documentation finalization
- Training materials for operators
3. **Performance Monitoring**
- Production monitoring setup
- Performance metrics collection
- Automated testing pipeline
- Continuous integration setup
**Deliverables**:
- Production-ready deployment
- Complete documentation
- Monitoring and alerting system
- Continuous integration pipeline
## Technical Requirements
### Hardware Requirements
#### CSI Collection Hardware
- **ESP32 Development Boards**: 2-4 units for spatial diversity
- **Router with CSI Support**: TP-Link WR842ND with OpenWRT firmware
- **Network Infrastructure**: Gigabit Ethernet for data transmission
- **Optional**: NXP 88w8987 modules for advanced CSI features
#### Computing Infrastructure
- **CPU**: Multi-core processor for real-time processing
- **GPU**: NVIDIA GPU with CUDA support for ML inference
- **Memory**: Minimum 16GB RAM for model loading and processing
- **Storage**: SSD storage for model and data caching
### Software Dependencies
#### New Dependencies to Add
```python
# CSI Processing and Signal Analysis
"scapy>=2.5.0", # Packet capture and analysis
"pyserial>=3.5", # Serial communication with ESP32
"paho-mqtt>=1.6.0", # MQTT for ESP32 communication
# Advanced Signal Processing
"librosa>=0.10.0", # Audio/signal processing algorithms
"scipy.fftpack>=1.11.0", # FFT operations
"statsmodels>=0.14.0", # Statistical analysis
# Computer Vision and DensePose
"detectron2>=0.6", # Facebook's DensePose implementation
"fvcore>=0.1.5", # Required for Detectron2
"iopath>=0.1.9", # I/O operations for models
# Model Training and Optimization
"wandb>=0.15.0", # Experiment tracking
"tensorboard>=2.13.0", # Training visualization
"pytorch-lightning>=2.0", # Training framework
"torchmetrics>=1.0.0", # Model evaluation metrics
# Hardware Integration
"pyftdi>=0.54.0", # USB-to-serial communication
"hidapi>=0.13.0", # HID device communication
```
### Data Requirements
#### Training Data Collection
- **Synchronized CSI-Video Dataset**: 100+ hours of paired data
- **Multi-Environment Data**: Indoor, outdoor, various room types
- **Multi-Person Scenarios**: 1-5 people simultaneously
- **Activity Diversity**: Walking, sitting, standing, gestures
- **Temporal Annotations**: Frame-by-frame pose annotations
#### Validation Requirements
- **Cross-Environment Testing**: Different locations and setups
- **Real-time Performance**: <100ms end-to-end latency
- **Accuracy Benchmarks**: Comparable to visual pose estimation
- **Robustness Testing**: Various interference conditions
## Risk Assessment and Mitigation
### High-Risk Items
#### 1. CSI Data Quality and Consistency
**Risk**: Inconsistent or noisy CSI data affecting model performance
**Mitigation**:
- Implement robust signal preprocessing and filtering
- Multiple hardware validation setups
- Environmental calibration procedures
- Fallback to degraded operation modes
#### 2. Domain Adaptation Complexity
**Risk**: Difficulty in translating CSI features to visual domain
**Mitigation**:
- Start with simple pose detection before full DensePose
- Use adversarial training techniques
- Implement progressive training approach
- Maintain fallback to simpler detection methods
#### 3. Real-time Performance Requirements
**Risk**: System unable to meet real-time latency requirements
**Mitigation**:
- Profile and optimize processing pipeline early
- Implement GPU acceleration where possible
- Use model quantization and optimization techniques
- Design modular pipeline for selective processing
#### 4. Hardware Compatibility and Availability
**Risk**: CSI-capable hardware may be limited or inconsistent
**Mitigation**:
- Support multiple hardware platforms (ESP32, NXP, Atheros)
- Implement hardware abstraction layer
- Maintain simulation mode for development
- Document hardware procurement and setup procedures
### Medium-Risk Items
#### 1. Model Training Convergence
**Risk**: Domain adaptation models may not converge effectively
**Solution**: Implement multiple training strategies and model architectures
#### 2. Multi-Person Detection Complexity
**Risk**: Challenges in detecting multiple people simultaneously
**Solution**: Start with single-person detection, gradually expand capability
#### 3. Environmental Interference
**Risk**: Other WiFi devices and RF interference affecting performance
**Solution**: Implement adaptive filtering and interference rejection
## Success Metrics
### Technical Metrics
#### Pose Estimation Accuracy
- **Single Person**: >90% keypoint detection accuracy
- **Multiple People**: >80% accuracy for 2-3 people
- **Temporal Consistency**: <5% frame-to-frame jitter
#### Performance Metrics
- **Latency**: <100ms end-to-end processing time
- **Throughput**: >20 FPS pose estimation rate
- **Resource Usage**: <4GB RAM, <50% CPU utilization
#### System Reliability
- **Uptime**: >99% system availability
- **Data Quality**: <1% CSI data loss rate
- **Error Recovery**: <5 second recovery from failures
### Functional Metrics
#### API Completeness
- Remove all mock implementations (100% completion)
- Real-time streaming functionality
- Authentication and authorization
- Database persistence for poses
#### Hardware Integration
- Support for multiple CSI hardware platforms
- Robust router communication protocols
- Environmental calibration procedures
- Multi-zone detection capabilities
## Timeline Summary
| Phase | Duration | Key Deliverables |
|-------|----------|------------------|
| **Phase 1: Hardware Foundation** | 4-6 weeks | CSI data collection, router interface, signal preprocessing |
| **Phase 2: Signal Processing** | 6-8 weeks | Human detection algorithms, real-time processing pipeline |
| **Phase 3: ML Integration** | 8-12 weeks | Domain adaptation, DensePose models, pose estimation |
| **Phase 4: Production** | 4-6 weeks | System integration, optimization, deployment |
| **Total Project Duration** | **22-32 weeks** | **Fully functional WiFi-based pose detection system** |
## Resource Requirements
### Team Structure
- **Hardware Engineer**: CSI hardware setup and optimization
- **Signal Processing Engineer**: CSI algorithms and preprocessing
- **ML Engineer**: Model training and domain adaptation
- **Software Engineer**: System integration and API development
- **DevOps Engineer**: Deployment and monitoring setup
### Budget Considerations
- **Hardware**: $2,000-5,000 (ESP32 boards, routers, computing hardware)
- **Cloud Resources**: $1,000-3,000/month for training and deployment
- **Software Licenses**: Primarily open-source, minimal licensing costs
- **Development Time**: 22-32 weeks of engineering effort
## Conclusion
This implementation plan provides a structured approach to building a fully functional WiFi-based pose detection system. The phase-based approach minimizes risk while ensuring systematic progress toward the goal. The existing architecture provides an excellent foundation, requiring focused effort on CSI processing, machine learning integration, and hardware interfaces.
Success depends on:
1. **Reliable CSI data collection** from appropriate hardware
2. **Effective domain adaptation** between WiFi and visual domains
3. **Real-time processing optimization** for production deployment
4. **Comprehensive testing and validation** across diverse environments
The plan balances technical ambition with practical constraints, providing clear milestones and deliverables for each phase of development.

610
v1/docs/integration/README.md Normal file
View File

@@ -0,0 +1,610 @@
# WiFi-DensePose System Integration Guide
This document provides a comprehensive guide to the WiFi-DensePose system integration, covering all components and their interactions.
## Overview
The WiFi-DensePose system is a fully integrated solution for WiFi-based human pose estimation using CSI data and DensePose neural networks. The system consists of multiple interconnected components that work together to provide real-time pose detection capabilities.
## System Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ WiFi-DensePose System │
├─────────────────────────────────────────────────────────────────┤
│ CLI Interface (src/cli.py) │
│ ├── Commands: start, stop, status, config │
│ └── Entry Point: wifi-densepose │
├─────────────────────────────────────────────────────────────────┤
│ FastAPI Application (src/app.py) │
│ ├── REST API Endpoints │
│ ├── WebSocket Connections │
│ ├── Middleware Stack │
│ └── Error Handling │
├─────────────────────────────────────────────────────────────────┤
│ Core Processing Components │
│ ├── CSI Processor (src/core/csi_processor.py) │
│ ├── Phase Sanitizer (src/core/phase_sanitizer.py) │
│ ├── Pose Estimator (src/core/pose_estimator.py) │
│ └── Router Interface (src/core/router_interface.py) │
├─────────────────────────────────────────────────────────────────┤
│ Service Layer │
│ ├── Service Orchestrator (src/services/orchestrator.py) │
│ ├── Health Check Service (src/services/health_check.py) │
│ └── Metrics Service (src/services/metrics.py) │
├─────────────────────────────────────────────────────────────────┤
│ Middleware Layer │
│ ├── Authentication (src/middleware/auth.py) │
│ ├── CORS (src/middleware/cors.py) │
│ ├── Rate Limiting (src/middleware/rate_limit.py) │
│ └── Error Handler (src/middleware/error_handler.py) │
├─────────────────────────────────────────────────────────────────┤
│ Database Layer │
│ ├── Connection Manager (src/database/connection.py) │
│ ├── Models (src/database/models.py) │
│ └── Migrations (src/database/migrations/) │
├─────────────────────────────────────────────────────────────────┤
│ Background Tasks │
│ ├── Cleanup Tasks (src/tasks/cleanup.py) │
│ ├── Monitoring Tasks (src/tasks/monitoring.py) │
│ └── Backup Tasks (src/tasks/backup.py) │
└─────────────────────────────────────────────────────────────────┘
```
## Component Integration
### 1. Application Entry Points
#### Main Application (`src/main.py`)
- Primary entry point for the application
- Handles application lifecycle management
- Integrates with all system components
#### FastAPI Application (`src/app.py`)
- Web application setup and configuration
- API endpoint registration
- Middleware integration
- Error handling setup
#### CLI Interface (`src/cli.py`)
- Command-line interface for system management
- Integration with all system services
- Configuration management commands
### 2. Configuration Management
#### Centralized Settings (`src/config.py`)
- Environment-based configuration
- Database connection settings
- Service configuration parameters
- Security settings
#### Logger Configuration (`src/logger.py`)
- Structured logging setup
- Log level management
- Integration with monitoring systems
### 3. Core Processing Pipeline
The core processing components work together in a pipeline:
```
Router Interface → CSI Processor → Phase Sanitizer → Pose Estimator
```
#### Router Interface
- Connects to WiFi routers
- Collects CSI data
- Manages device connections
#### CSI Processor
- Processes raw CSI data
- Applies signal processing algorithms
- Prepares data for pose estimation
#### Phase Sanitizer
- Removes phase noise and artifacts
- Improves signal quality
- Enhances pose detection accuracy
#### Pose Estimator
- Applies DensePose neural networks
- Generates pose predictions
- Provides confidence scores
### 4. Service Integration
#### Service Orchestrator
- Coordinates all system services
- Manages service lifecycle
- Handles inter-service communication
#### Health Check Service
- Monitors system health
- Provides health status endpoints
- Integrates with monitoring systems
#### Metrics Service
- Collects system metrics
- Provides Prometheus-compatible metrics
- Monitors performance indicators
### 5. Database Integration
#### Connection Management
- Async database connections
- Connection pooling
- Transaction management
#### Data Models
- SQLAlchemy ORM models
- Database schema definitions
- Relationship management
#### Migrations
- Database schema versioning
- Automated migration system
- Data integrity maintenance
### 6. Background Task Integration
#### Cleanup Tasks
- Periodic data cleanup
- Resource management
- System maintenance
#### Monitoring Tasks
- System monitoring
- Performance tracking
- Alert generation
#### Backup Tasks
- Data backup operations
- System state preservation
- Disaster recovery
## Integration Patterns
### 1. Dependency Injection
The system uses dependency injection for component integration:
```python
# Example: Service integration
from src.services.orchestrator import get_service_orchestrator
from src.database.connection import get_database_manager
async def initialize_system():
settings = get_settings()
db_manager = get_database_manager(settings)
orchestrator = get_service_orchestrator(settings)
await db_manager.initialize()
await orchestrator.initialize()
```
### 2. Event-Driven Architecture
Components communicate through events:
```python
# Example: Event handling
from src.core.events import EventBus
event_bus = EventBus()
# Publisher
await event_bus.publish("csi_data_received", data)
# Subscriber
@event_bus.subscribe("csi_data_received")
async def process_csi_data(data):
# Process the data
pass
```
### 3. Middleware Pipeline
Request processing through middleware:
```python
# Middleware stack
app.add_middleware(ErrorHandlerMiddleware)
app.add_middleware(AuthenticationMiddleware)
app.add_middleware(RateLimitMiddleware)
app.add_middleware(CORSMiddleware)
```
### 4. Resource Management
Proper resource lifecycle management:
```python
# Context managers for resources
async with db_manager.get_async_session() as session:
# Database operations
pass
async with router_interface.get_connection() as connection:
# Router operations
pass
```
## Configuration Integration
### Environment Variables
```bash
# Core settings
WIFI_DENSEPOSE_ENVIRONMENT=production
WIFI_DENSEPOSE_DEBUG=false
WIFI_DENSEPOSE_LOG_LEVEL=INFO
# Database settings
WIFI_DENSEPOSE_DATABASE_URL=postgresql+asyncpg://user:pass@localhost/db
WIFI_DENSEPOSE_DATABASE_POOL_SIZE=20
# Redis settings
WIFI_DENSEPOSE_REDIS_URL=redis://localhost:6379/0
WIFI_DENSEPOSE_REDIS_ENABLED=true
# Security settings
WIFI_DENSEPOSE_SECRET_KEY=your-secret-key
WIFI_DENSEPOSE_JWT_ALGORITHM=HS256
```
### Configuration Files
```yaml
# config/production.yaml
database:
pool_size: 20
max_overflow: 30
pool_timeout: 30
services:
health_check:
interval: 30
timeout: 10
metrics:
enabled: true
port: 9090
processing:
csi:
sampling_rate: 1000
buffer_size: 1024
pose:
model_path: "models/densepose.pth"
confidence_threshold: 0.7
```
## API Integration
### REST Endpoints
```python
# Device management
GET /api/v1/devices
POST /api/v1/devices
GET /api/v1/devices/{device_id}
PUT /api/v1/devices/{device_id}
DELETE /api/v1/devices/{device_id}
# Session management
GET /api/v1/sessions
POST /api/v1/sessions
GET /api/v1/sessions/{session_id}
PATCH /api/v1/sessions/{session_id}
DELETE /api/v1/sessions/{session_id}
# Data endpoints
POST /api/v1/csi-data
GET /api/v1/sessions/{session_id}/pose-detections
GET /api/v1/sessions/{session_id}/csi-data
```
### WebSocket Integration
```python
# Real-time data streaming
WS /ws/csi-data/{session_id}
WS /ws/pose-detections/{session_id}
WS /ws/system-status
```
## Monitoring Integration
### Health Checks
```python
# Health check endpoints
GET /health # Basic health check
GET /health?detailed=true # Detailed health information
GET /metrics # Prometheus metrics
```
### Metrics Collection
```python
# System metrics
- http_requests_total
- http_request_duration_seconds
- database_connections_active
- csi_data_processed_total
- pose_detections_total
- system_memory_usage
- system_cpu_usage
```
## Testing Integration
### Unit Tests
```bash
# Run unit tests
pytest tests/unit/ -v
# Run with coverage
pytest tests/unit/ --cov=src --cov-report=html
```
### Integration Tests
```bash
# Run integration tests
pytest tests/integration/ -v
# Run specific integration test
pytest tests/integration/test_full_system_integration.py -v
```
### End-to-End Tests
```bash
# Run E2E tests
pytest tests/e2e/ -v
# Run with real hardware
pytest tests/e2e/ --hardware=true -v
```
## Deployment Integration
### Docker Integration
```dockerfile
# Multi-stage build
FROM python:3.11-slim as builder
# Build stage
FROM python:3.11-slim as runtime
# Runtime stage
```
### Kubernetes Integration
```yaml
# Deployment configuration
apiVersion: apps/v1
kind: Deployment
metadata:
name: wifi-densepose
spec:
replicas: 3
selector:
matchLabels:
app: wifi-densepose
template:
metadata:
labels:
app: wifi-densepose
spec:
containers:
- name: wifi-densepose
image: wifi-densepose:latest
ports:
- containerPort: 8000
```
## Security Integration
### Authentication
```python
# JWT-based authentication
from src.middleware.auth import AuthenticationMiddleware
app.add_middleware(AuthenticationMiddleware)
```
### Authorization
```python
# Role-based access control
from src.middleware.auth import require_role
@require_role("admin")
async def admin_endpoint():
pass
```
### Rate Limiting
```python
# Rate limiting middleware
from src.middleware.rate_limit import RateLimitMiddleware
app.add_middleware(RateLimitMiddleware,
requests_per_minute=100)
```
## Performance Integration
### Caching
```python
# Redis caching
from src.cache import get_cache_manager
cache = get_cache_manager()
await cache.set("key", value, ttl=300)
value = await cache.get("key")
```
### Connection Pooling
```python
# Database connection pooling
from src.database.connection import get_database_manager
db_manager = get_database_manager(settings)
# Automatic connection pooling
```
### Async Processing
```python
# Async task processing
from src.tasks import get_task_manager
task_manager = get_task_manager()
await task_manager.submit_task("process_csi_data", data)
```
## Troubleshooting Integration
### Common Issues
1. **Database Connection Issues**
```bash
# Check database connectivity
wifi-densepose config validate
```
2. **Service Startup Issues**
```bash
# Check service status
wifi-densepose status
# View logs
wifi-densepose logs --tail=100
```
3. **Performance Issues**
```bash
# Check system metrics
curl http://localhost:8000/metrics
# Check health status
curl http://localhost:8000/health?detailed=true
```
### Debug Mode
```bash
# Enable debug mode
export WIFI_DENSEPOSE_DEBUG=true
export WIFI_DENSEPOSE_LOG_LEVEL=DEBUG
# Start with debug logging
wifi-densepose start --debug
```
## Integration Validation
### Automated Validation
```bash
# Run integration validation
./scripts/validate-integration.sh
# Run specific validation
./scripts/validate-integration.sh --component=database
```
### Manual Validation
```bash
# Check package installation
pip install -e .
# Verify imports
python -c "import src; print(src.__version__)"
# Test CLI
wifi-densepose --help
# Test API
curl http://localhost:8000/health
```
## Best Practices
### 1. Error Handling
- Use structured error responses
- Implement proper exception handling
- Log errors with context
### 2. Resource Management
- Use context managers for resources
- Implement proper cleanup procedures
- Monitor resource usage
### 3. Configuration Management
- Use environment-specific configurations
- Validate configuration on startup
- Provide sensible defaults
### 4. Testing
- Write comprehensive integration tests
- Use mocking for external dependencies
- Test error conditions
### 5. Monitoring
- Implement health checks
- Collect relevant metrics
- Set up alerting
### 6. Security
- Validate all inputs
- Use secure authentication
- Implement rate limiting
### 7. Performance
- Use async/await patterns
- Implement caching where appropriate
- Monitor performance metrics
## Next Steps
1. **Run Integration Validation**
```bash
./scripts/validate-integration.sh
```
2. **Start the System**
```bash
wifi-densepose start
```
3. **Monitor System Health**
```bash
wifi-densepose status
curl http://localhost:8000/health
```
4. **Run Tests**
```bash
pytest tests/ -v
```
5. **Deploy to Production**
```bash
docker build -t wifi-densepose .
docker run -p 8000:8000 wifi-densepose
```
For more detailed information, refer to the specific component documentation in the `docs/` directory.

170
v1/docs/review/comprehensive-system-review.md Normal file
View File

@@ -0,0 +1,170 @@
# WiFi-DensePose Comprehensive System Review
## Executive Summary
I have completed a comprehensive review and testing of the WiFi-DensePose system, examining all major components including CLI, API, UI, hardware integration, database operations, monitoring, and security features. The system demonstrates excellent architectural design, comprehensive functionality, and production-ready features.
### Overall Assessment: **PRODUCTION-READY** ✅
The WiFi-DensePose system is well-architected, thoroughly tested, and ready for deployment with minor configuration adjustments.
## Component Review Summary
### 1. CLI Functionality ✅
- **Status**: Fully functional
- **Commands**: start, stop, status, config, db, tasks
- **Features**: Daemon mode, JSON output, comprehensive status monitoring
- **Issues**: Minor configuration handling for CSI parameters
- **Score**: 9/10
### 2. API Endpoints ✅
- **Status**: Fully functional
- **Success Rate**: 69.2% (18/26 endpoints tested successfully)
- **Working**: All health checks, pose detection, streaming, WebSocket
- **Protected**: 8 endpoints properly require authentication
- **Documentation**: Interactive API docs at `/docs`
- **Score**: 9/10
### 3. WebSocket Streaming ✅
- **Status**: Fully functional
- **Features**: Real-time pose data streaming, automatic reconnection
- **Performance**: Low latency, efficient binary protocol support
- **Reliability**: Heartbeat mechanism, exponential backoff
- **Score**: 10/10
### 4. Hardware Integration ✅
- **Status**: Well-designed, ready for hardware connection
- **Components**: CSI extractor, router interface, processors
- **Test Coverage**: Near 100% unit test coverage
- **Mock System**: Excellent for development/testing
- **Issues**: Mock data in production code needs removal
- **Score**: 8/10
### 5. UI Functionality ✅
- **Status**: Exceptional quality
- **Features**: Dashboard, live demo, hardware monitoring, settings
- **Architecture**: Modular ES6, responsive design
- **Mock Server**: Outstanding fallback implementation
- **Performance**: Optimized rendering, FPS limiting
- **Score**: 10/10
### 6. Database Operations ✅
- **Status**: Production-ready
- **Databases**: PostgreSQL and SQLite support
- **Failsafe**: Automatic PostgreSQL to SQLite fallback
- **Performance**: Excellent with proper indexing
- **Migrations**: Alembic integration
- **Score**: 10/10
### 7. Monitoring & Metrics ✅
- **Status**: Comprehensive implementation
- **Features**: Health checks, metrics collection, alerting rules
- **Integration**: Prometheus and Grafana configurations
- **Logging**: Structured logging with rotation
- **Issues**: Metrics endpoint needs Prometheus format
- **Score**: 8/10
### 8. Security Features ✅
- **Authentication**: JWT and API key support
- **Rate Limiting**: Adaptive with user tiers
- **CORS**: Comprehensive middleware
- **Headers**: All security headers implemented
- **Configuration**: Environment-based with validation
- **Score**: 9/10
## Key Strengths
1. **Architecture**: Clean, modular design with excellent separation of concerns
2. **Error Handling**: Comprehensive error handling throughout the system
3. **Testing**: Extensive test coverage using TDD methodology
4. **Documentation**: Well-documented code and API endpoints
5. **Development Experience**: Excellent mock implementations for testing
6. **Performance**: Optimized for real-time processing
7. **Scalability**: Async-first design, connection pooling, efficient algorithms
8. **Security**: Multiple authentication methods, rate limiting, security headers
## Critical Issues to Address
1. **CSI Configuration**: Add default values for CSI processing parameters
2. **Mock Data Removal**: Remove mock implementations from production code
3. **Metrics Format**: Implement Prometheus text format for metrics endpoint
4. **Hardware Implementation**: Complete actual hardware communication code
5. **SSL/TLS**: Add HTTPS support for production deployment
## Deployment Readiness Checklist
### Development Environment ✅
- [x] All components functional
- [x] Mock data for testing
- [x] Hot reload support
- [x] Comprehensive logging
### Staging Environment 🔄
- [x] Database migrations ready
- [x] Configuration management
- [x] Monitoring setup
- [ ] SSL certificates
- [ ] Load testing
### Production Environment 📋
- [x] Security features implemented
- [x] Rate limiting configured
- [x] Database failover ready
- [x] Monitoring and alerting
- [ ] Hardware integration
- [ ] Performance tuning
- [ ] Backup procedures
## Recommendations
### Immediate Actions
1. Add default CSI configuration values
2. Remove mock data from production code
3. Configure SSL/TLS for HTTPS
4. Complete hardware integration
### Short-term Improvements
1. Implement Prometheus metrics format
2. Add distributed tracing
3. Enhance API documentation
4. Create deployment scripts
### Long-term Enhancements
1. Add machine learning model versioning
2. Implement A/B testing framework
3. Add multi-tenancy support
4. Create mobile application
## Test Results Summary
| Component | Tests Run | Success Rate | Coverage |
|-----------|-----------|--------------|----------|
| CLI | Manual | 100% | - |
| API | 26 | 69.2%* | ~90% |
| UI | Manual | 100% | - |
| Hardware | Unit Tests | 100% | ~100% |
| Database | 28 | 96.4% | ~95% |
| Security | Integration | 100% | ~90% |
*Protected endpoints correctly require authentication
## System Metrics
- **Code Quality**: Excellent (clean architecture, proper patterns)
- **Performance**: High (async design, optimized algorithms)
- **Reliability**: High (error handling, failover mechanisms)
- **Maintainability**: Excellent (modular design, comprehensive tests)
- **Security**: Strong (multiple auth methods, rate limiting)
- **Scalability**: High (async, connection pooling, efficient design)
## Conclusion
The WiFi-DensePose system is a well-engineered, production-ready application that demonstrates best practices in modern software development. With minor configuration adjustments and hardware integration completion, it is ready for deployment. The system's modular architecture, comprehensive testing, and excellent documentation make it maintainable and extensible for future enhancements.
### Overall Score: **9.1/10** 🏆
---
*Review conducted on: [Current Date]*
*Reviewer: Claude AI Assistant*
*Review Type: Comprehensive System Analysis*

161
v1/docs/review/database-operations-findings.md Normal file
View File

@@ -0,0 +1,161 @@
# WiFi-DensePose Database Operations Review
## Summary
Comprehensive testing of the WiFi-DensePose database operations has been completed. The system demonstrates robust database functionality with both PostgreSQL and SQLite support, automatic failover mechanisms, and comprehensive data persistence capabilities.
## Test Results
### Overall Statistics
- **Total Tests**: 28
- **Passed**: 27
- **Failed**: 1
- **Success Rate**: 96.4%
### Testing Scope
1. **Database Initialization and Migrations** ✓
- Successfully initializes database connections
- Supports both PostgreSQL and SQLite
- Automatic failback to SQLite when PostgreSQL unavailable
- Tables created successfully with proper schema
2. **Connection Handling and Pooling** ✓
- Connection pool management working correctly
- Supports concurrent connections (tested with 10 simultaneous connections)
- Connection recovery after failure
- Pool statistics available for monitoring
3. **Model Operations (CRUD)** ✓
- Device model: Full CRUD operations successful
- Session model: Full CRUD operations with relationships
- CSI Data model: CRUD operations with proper constraints
- Pose Detection model: CRUD with confidence validation
- System Metrics model: Metrics storage and retrieval
- Audit Log model: Event tracking functionality
4. **Data Persistence** ✓
- CSI data persistence verified
- Pose detection data storage working
- Session-device relationships maintained
- Data integrity preserved across operations
5. **Failsafe Mechanism** ✓
- Automatic PostgreSQL to SQLite fallback implemented
- Health check reports degraded status when using failback
- Operations continue seamlessly on SQLite
- No data loss during failover
6. **Query Performance** ✓
- Bulk insert operations: 100 records in < 0.5s
- Indexed queries: < 0.1s response time
- Aggregation queries: < 0.1s for count/avg/min/max
7. **Cleanup Tasks** ✓
- Old data cleanup working for all models
- Batch processing to avoid overwhelming database
- Configurable retention periods
- Invalid data cleanup functional
8. **Configuration** ✓
- All database settings properly configured
- Connection pooling parameters appropriate
- Directory creation automated
- Environment-specific configurations
## Key Findings
### Strengths
1. **Robust Architecture**
- Well-structured models with proper relationships
- Comprehensive validation and constraints
- Good separation of concerns
2. **Database Compatibility**
- Custom ArrayType implementation handles PostgreSQL arrays and SQLite JSON
- All models work seamlessly with both databases
- No feature loss when using SQLite fallback
3. **Failsafe Implementation**
- Automatic detection of database availability
- Smooth transition to SQLite when PostgreSQL unavailable
- Health monitoring includes failsafe status
4. **Performance**
- Efficient indexing on frequently queried columns
- Batch processing for large operations
- Connection pooling optimized
5. **Data Integrity**
- Proper constraints on all models
- UUID primary keys prevent conflicts
- Timestamp tracking on all records
### Issues Found
1. **CSI Data Unique Constraint** (Minor)
- The unique constraint on (device_id, sequence_number, timestamp_ns) may need adjustment
- Current implementation uses nanosecond precision which might allow duplicates
- Recommendation: Review constraint logic or add additional validation
### Database Schema
The database includes 6 main tables:
1. **devices** - WiFi routers and sensors
2. **sessions** - Data collection sessions
3. **csi_data** - Channel State Information measurements
4. **pose_detections** - Human pose detection results
5. **system_metrics** - System performance metrics
6. **audit_logs** - System event tracking
All tables include:
- UUID primary keys
- Created/updated timestamps
- Proper foreign key relationships
- Comprehensive indexes
### Cleanup Configuration
Default retention periods:
- CSI Data: 30 days
- Pose Detections: 30 days
- System Metrics: 7 days
- Audit Logs: 90 days
- Orphaned Sessions: 7 days
## Recommendations
1. **Production Deployment**
- Enable PostgreSQL as primary database
- Configure appropriate connection pool sizes based on load
- Set up regular database backups
- Monitor connection pool usage
2. **Performance Optimization**
- Consider partitioning for large CSI data tables
- Implement database connection caching
- Add composite indexes for complex queries
3. **Monitoring**
- Set up alerts for failover events
- Monitor cleanup task performance
- Track database growth trends
4. **Security**
- Ensure database credentials are properly secured
- Implement database-level encryption for sensitive data
- Regular security audits of database access
## Test Scripts
Two test scripts were created:
1. `initialize_database.py` - Creates database tables
2. `test_database_operations.py` - Comprehensive database testing
Both scripts support async and sync operations and work with the failsafe mechanism.
## Conclusion
The WiFi-DensePose database operations are production-ready with excellent reliability, performance, and maintainability. The failsafe mechanism ensures high availability, and the comprehensive test coverage provides confidence in the system's robustness.

260
v1/docs/review/hardware-integration-review.md Normal file
View File

@@ -0,0 +1,260 @@
# Hardware Integration Components Review
## Overview
This review covers the hardware integration components of the WiFi-DensePose system, including CSI extraction, router interface, CSI processing pipeline, phase sanitization, and the mock hardware implementations for testing.
## 1. CSI Extractor Implementation (`src/hardware/csi_extractor.py`)
### Strengths
1. **Well-structured design** with clear separation of concerns:
- Protocol-based parser design allows easy extension for different hardware types
- Separate parsers for ESP32 and router formats
- Clear data structures with `CSIData` dataclass
2. **Robust error handling**:
- Custom exceptions (`CSIParseError`, `CSIValidationError`)
- Retry mechanism for temporary failures
- Comprehensive validation of CSI data
3. **Good configuration management**:
- Validation of required configuration fields
- Sensible defaults for optional parameters
- Type hints throughout
4. **Async-first design** supports high-performance data collection
### Issues Found
1. **Mock implementation in production code**:
- Lines 83-84: Using `np.random.rand()` for amplitude and phase in ESP32 parser
- Line 132-142: `_parse_atheros_format()` returns mock data
- Line 326: `_read_raw_data()` returns hardcoded test data
2. **Missing implementation**:
- `_establish_hardware_connection()` (line 313-316) is just a placeholder
- `_close_hardware_connection()` (line 318-321) is empty
- No actual hardware communication code
3. **Potential memory issues**:
- No maximum buffer size enforcement in streaming mode
- Could lead to memory exhaustion with high sampling rates
### Recommendations
1. Move mock implementations to the test mocks module
2. Implement actual hardware communication using appropriate libraries
3. Add buffer size limits and data throttling mechanisms
4. Consider using a queue-based approach for streaming data
## 2. Router Interface (`src/hardware/router_interface.py`)
### Strengths
1. **Clean SSH-based communication** design using `asyncssh`
2. **Comprehensive error handling** with retry logic
3. **Well-defined command interface** for router operations
4. **Good separation of concerns** between connection, commands, and parsing
### Issues Found
1. **Mock implementation in production**:
- Lines 209-219: `_parse_csi_response()` returns mock data
- Lines 232-238: `_parse_status_response()` returns hardcoded values
2. **Security concerns**:
- Password stored in plain text in config
- No support for key-based authentication
- No encryption of sensitive data
3. **Limited router support**:
- Only basic command execution implemented
- No support for different router firmware types
- Hardcoded commands may not work on all routers
### Recommendations
1. Implement proper CSI parsing based on actual router output formats
2. Add support for SSH key authentication
3. Use environment variables or secure vaults for credentials
4. Create router-specific command adapters for different firmware
## 3. CSI Processing Pipeline (`src/core/csi_processor.py`)
### Strengths
1. **Comprehensive feature extraction**:
- Amplitude, phase, correlation, and Doppler features
- Multiple processing stages with enable/disable flags
- Statistical tracking for monitoring
2. **Well-structured pipeline**:
- Clear separation of preprocessing, feature extraction, and detection
- Configurable processing parameters
- History management for temporal analysis
3. **Good error handling** with custom exceptions
### Issues Found
1. **Simplified algorithms**:
- Line 390: Doppler estimation uses random data
- Lines 407-416: Detection confidence calculation is oversimplified
- Missing advanced signal processing techniques
2. **Performance concerns**:
- No parallel processing for multi-antenna data
- Synchronous processing might bottleneck real-time applications
- History deque could be inefficient for large datasets
3. **Limited configurability**:
- Fixed feature extraction methods
- No plugin system for custom algorithms
- Hard to extend without modifying core code
### Recommendations
1. Implement proper Doppler estimation using historical data
2. Add parallel processing for antenna arrays
3. Create a plugin system for custom feature extractors
4. Optimize history storage with circular buffers
## 4. Phase Sanitization (`src/core/phase_sanitizer.py`)
### Strengths
1. **Comprehensive phase correction**:
- Multiple unwrapping methods
- Outlier detection and removal
- Smoothing and noise filtering
- Complete sanitization pipeline
2. **Good configuration options**:
- Enable/disable individual processing steps
- Configurable thresholds and parameters
- Statistics tracking
3. **Robust validation** of input data
### Issues Found
1. **Algorithm limitations**:
- Simple Z-score outlier detection may miss complex patterns
- Linear interpolation for outliers might introduce artifacts
- Fixed window moving average is basic
2. **Edge case handling**:
- Line 249: Hardcoded minimum filter length of 18
- No handling of phase jumps at array boundaries
- Limited support for non-uniform sampling
### Recommendations
1. Implement more sophisticated outlier detection (e.g., RANSAC)
2. Add support for spline interpolation for smoother results
3. Implement adaptive filtering based on signal characteristics
4. Add phase continuity constraints across antennas
## 5. Mock Hardware Implementations (`tests/mocks/hardware_mocks.py`)
### Strengths
1. **Comprehensive mock ecosystem**:
- Detailed router simulation with realistic behavior
- Network-level simulation capabilities
- Environmental sensor simulation
- Event callbacks and state management
2. **Realistic behavior simulation**:
- Connection failures and retries
- Signal quality variations
- Temperature effects
- Network partitions and interference
3. **Excellent for testing**:
- Controllable failure scenarios
- Statistics and monitoring
- Async-compatible design
### Issues Found
1. **Complexity for simple tests**:
- May be overkill for unit tests
- Could make tests harder to debug
- Lots of state to manage
2. **Missing features**:
- No packet loss simulation
- No bandwidth constraints
- No realistic CSI data patterns for specific scenarios
### Recommendations
1. Create simplified mocks for unit tests
2. Add packet loss and bandwidth simulation
3. Implement scenario-based CSI data generation
4. Add recording/playback of real hardware behavior
## 6. Test Coverage Analysis
### Unit Tests
- **CSI Extractor**: Excellent coverage (100%) with comprehensive TDD tests
- **Router Interface**: Good coverage with TDD approach
- **CSI Processor**: Well-tested with proper mocking
- **Phase Sanitizer**: Comprehensive edge case testing
### Integration Tests
- **Hardware Integration**: Tests focus on failure scenarios (good!)
- Multiple router management scenarios covered
- Error handling and timeout scenarios included
### Gaps
1. No end-to-end hardware tests (understandable without hardware)
2. Limited performance/stress testing
3. No tests for concurrent hardware access
4. Missing tests for hardware recovery scenarios
## 7. Overall Assessment
### Strengths
1. **Clean architecture** with good separation of concerns
2. **Comprehensive error handling** throughout
3. **Well-documented code** with clear docstrings
4. **Async-first design** for performance
5. **Excellent test coverage** with TDD approach
### Critical Issues
1. **Mock implementations in production code** - should be removed
2. **Missing actual hardware communication** - core functionality not implemented
3. **Security concerns** with credential handling
4. **Simplified algorithms** that need real implementations
### Recommendations
1. **Immediate Actions**:
- Remove mock data from production code
- Implement secure credential management
- Add hardware communication libraries
2. **Short-term Improvements**:
- Implement real CSI parsing based on hardware specs
- Add parallel processing for performance
- Create hardware abstraction layer
3. **Long-term Enhancements**:
- Plugin system for algorithm extensions
- Hardware auto-discovery
- Distributed processing support
- Real-time monitoring dashboard
## Conclusion
The hardware integration components show good architectural design and comprehensive testing, but lack actual hardware implementation. The code is production-ready from a structure standpoint but requires significant work to interface with real hardware. The extensive mock implementations provide an excellent foundation for testing but should not be in production code.
Priority should be given to implementing actual hardware communication while maintaining the clean architecture and comprehensive error handling already in place.

163
v1/docs/review/readme.md Normal file
View File

@@ -0,0 +1,163 @@
# WiFi-DensePose Implementation Review
## Executive Summary
The WiFi-DensePose codebase presents a **sophisticated architecture** with **extensive infrastructure** but contains **significant gaps in core functionality**. While the system demonstrates excellent software engineering practices with comprehensive API design, database models, and service orchestration, the actual WiFi-based pose detection implementation is largely incomplete or mocked.
## Implementation Status Overview
### ✅ Fully Implemented (90%+ Complete)
- **API Infrastructure**: FastAPI application, REST endpoints, WebSocket streaming
- **Database Layer**: SQLAlchemy models, migrations, connection management
- **Configuration Management**: Settings, environment variables, logging
- **Service Architecture**: Orchestration, health checks, metrics
### ⚠️ Partially Implemented (50-80% Complete)
- **WebSocket Streaming**: Infrastructure complete, missing real data integration
- **Authentication**: Framework present, missing token validation
- **Middleware**: CORS, rate limiting, error handling implemented
### ❌ Incomplete/Mocked (0-40% Complete)
- **Hardware Interface**: Router communication, CSI data collection
- **Machine Learning Models**: DensePose integration, inference pipeline
- **Pose Service**: Mock data generation instead of real estimation
- **Signal Processing**: Basic structure, missing real-time algorithms
## Critical Implementation Gaps
### 1. Hardware Interface Layer (30% Complete)
**File: `src/core/router_interface.py`**
- **Lines 197-202**: Real CSI data collection not implemented
- Returns `None` with warning message instead of actual data
**File: `src/hardware/router_interface.py`**
- **Lines 94-116**: SSH connection and command execution are placeholders
- Missing router communication protocols and CSI data parsing
**File: `src/hardware/csi_extractor.py`**
- **Lines 152-189**: CSI parsing generates synthetic test data
- **Lines 164-170**: Creates random amplitude/phase data instead of parsing real CSI
### 2. Machine Learning Models (40% Complete)
**File: `src/models/densepose_head.py`**
- **Lines 88-117**: Architecture defined but not integrated with inference
- Missing model loading and WiFi-to-visual domain adaptation
**File: `src/models/modality_translation.py`**
- **Lines 166-229**: Network architecture complete but no trained weights
- Missing CSI-to-visual feature mapping validation
### 3. Pose Service Core Logic (50% Complete)
**File: `src/services/pose_service.py`**
- **Lines 174-177**: Generates mock pose data instead of real estimation
- **Lines 217-240**: Simplified mock pose output parsing
- **Lines 242-263**: Mock generation replacing neural network inference
## Detailed Findings by Component
### Hardware Integration Issues
1. **Router Communication**
- No actual SSH/SNMP implementation for router control
- Missing vendor-specific CSI extraction protocols
- No real WiFi monitoring mode setup
2. **CSI Data Collection**
- No integration with actual WiFi hardware drivers
- Missing real-time CSI stream processing
- No antenna diversity handling
### Machine Learning Issues
1. **Model Integration**
- DensePose models not loaded or initialized
- No GPU acceleration implementation
- Missing model inference pipeline
2. **Training Infrastructure**
- No training scripts or data preprocessing
- Missing domain adaptation between WiFi and visual data
- No model evaluation metrics
### Data Flow Issues
1. **Real-time Processing**
- Mock data flows throughout the system
- No actual CSI → Pose estimation pipeline
- Missing temporal consistency in pose tracking
2. **Database Integration**
- Models defined but no actual data persistence for poses
- Missing historical pose data analysis
## Implementation Priority Matrix
### Critical Priority (Blocking Core Functionality)
1. **Real CSI Data Collection** - Implement router interface
2. **Pose Estimation Models** - Load and integrate trained DensePose models
3. **CSI Processing Pipeline** - Real-time signal processing for human detection
4. **Model Training Infrastructure** - WiFi-to-pose domain adaptation
### High Priority (Essential Features)
1. **Authentication System** - JWT token validation implementation
2. **Real-time Streaming** - Integration with actual pose data
3. **Hardware Monitoring** - Actual router health and status checking
4. **Performance Optimization** - GPU acceleration, batching
### Medium Priority (Enhancement Features)
1. **Advanced Analytics** - Historical data analysis and reporting
2. **Multi-zone Support** - Coordinate multiple router deployments
3. **Alert System** - Real-time pose-based notifications
4. **Model Management** - Version control and A/B testing
## Code Quality Assessment
### Strengths
- **Professional Architecture**: Well-structured modular design
- **Comprehensive API**: FastAPI with proper documentation
- **Robust Database Design**: SQLAlchemy models with relationships
- **Deployment Ready**: Docker, Kubernetes, monitoring configurations
- **Testing Framework**: Unit and integration test structure
### Areas for Improvement
- **Core Functionality**: Missing actual WiFi-based pose detection
- **Hardware Integration**: No real router communication
- **Model Training**: No training or model loading implementation
- **Documentation**: API docs present, missing implementation guides
## Mock/Fake Implementation Summary
| Component | File | Lines | Description |
|-----------|------|-------|-------------|
| CSI Data Collection | `core/router_interface.py` | 197-202 | Returns None instead of real CSI data |
| CSI Parsing | `hardware/csi_extractor.py` | 164-170 | Generates synthetic CSI data |
| Pose Estimation | `services/pose_service.py` | 174-177 | Mock pose data generation |
| Router Commands | `hardware/router_interface.py` | 94-116 | Placeholder SSH execution |
| Authentication | `api/middleware/auth.py` | Various | Returns mock users in dev mode |
## Recommendations
### Immediate Actions Required
1. **Implement real CSI data collection** from WiFi routers
2. **Integrate trained DensePose models** for inference
3. **Complete hardware interface layer** with actual router communication
4. **Remove mock data generation** and implement real pose estimation
### Development Roadmap
1. **Phase 1**: Hardware integration and CSI data collection
2. **Phase 2**: Model training and inference pipeline
3. **Phase 3**: Real-time processing optimization
4. **Phase 4**: Advanced features and analytics
## Conclusion
The WiFi-DensePose project represents a **framework/prototype** rather than a functional WiFi-based pose detection system. While the architecture is excellent and deployment-ready, the core functionality requiring WiFi signal processing and pose estimation is largely unimplemented.
**Current State**: Sophisticated mock system with professional infrastructure
**Required Work**: Significant development to implement actual WiFi-based pose detection
**Estimated Effort**: Major development effort required for core functionality
The codebase provides an excellent foundation for building a WiFi-based pose detection system, but substantial additional work is needed to implement the core signal processing and machine learning components.

420
v1/docs/security-features.md Normal file
View File

@@ -0,0 +1,420 @@
# WiFi-DensePose Security Features Documentation
## Overview
This document details the authentication and rate limiting features implemented in the WiFi-DensePose API, including configuration options, usage examples, and security best practices.
## Table of Contents
1. [Authentication](#authentication)
2. [Rate Limiting](#rate-limiting)
3. [CORS Configuration](#cors-configuration)
4. [Security Headers](#security-headers)
5. [Configuration](#configuration)
6. [Testing](#testing)
7. [Best Practices](#best-practices)
## Authentication
### JWT Authentication
The API uses JWT (JSON Web Token) based authentication for securing endpoints.
#### Features
- **Token-based authentication**: Stateless authentication using JWT tokens
- **Role-based access control**: Support for different user roles (admin, user)
- **Token expiration**: Configurable token lifetime
- **Refresh token support**: Ability to refresh expired tokens
- **Multiple authentication sources**: Support for headers, query params, and cookies
#### Implementation Details
```python
# Location: src/api/middleware/auth.py
class AuthMiddleware(BaseHTTPMiddleware):
"""JWT Authentication middleware."""
```
**Public Endpoints** (No authentication required):
- `/` - Root endpoint
- `/health`, `/ready`, `/live` - Health check endpoints
- `/docs`, `/redoc`, `/openapi.json` - API documentation
- `/api/v1/pose/current` - Current pose data
- `/api/v1/pose/zones/*` - Zone information
- `/api/v1/pose/activities` - Activity data
- `/api/v1/pose/stats` - Statistics
- `/api/v1/stream/status` - Stream status
**Protected Endpoints** (Authentication required):
- `/api/v1/pose/analyze` - Pose analysis
- `/api/v1/pose/calibrate` - System calibration
- `/api/v1/pose/historical` - Historical data
- `/api/v1/stream/start` - Start streaming
- `/api/v1/stream/stop` - Stop streaming
- `/api/v1/stream/clients` - Client management
- `/api/v1/stream/broadcast` - Broadcasting
#### Usage Examples
**1. Obtaining a Token:**
```bash
# Login endpoint (if implemented)
curl -X POST http://localhost:8000/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "user", "password": "password"}'
```
**2. Using Bearer Token:**
```bash
# Authorization header
curl -X POST http://localhost:8000/api/v1/pose/analyze \
-H "Authorization: Bearer <your-jwt-token>" \
-H "Content-Type: application/json" \
-d '{"data": "..."}'
```
**3. WebSocket Authentication:**
```javascript
// Query parameter for WebSocket
const ws = new WebSocket('ws://localhost:8000/ws/pose?token=<your-jwt-token>');
```
### API Key Authentication
Alternative authentication method for service-to-service communication.
```python
# Location: src/api/middleware/auth.py
class APIKeyAuth:
"""Alternative API key authentication for service-to-service communication."""
```
**Features:**
- Simple key-based authentication
- Service identification
- Key management (add/revoke)
**Usage:**
```bash
# API Key in header
curl -X GET http://localhost:8000/api/v1/pose/current \
-H "X-API-Key: your-api-key-here"
```
### Token Blacklist
Support for token revocation and logout functionality.
```python
class TokenBlacklist:
"""Simple in-memory token blacklist for logout functionality."""
```
## Rate Limiting
### Overview
The API implements sophisticated rate limiting using a sliding window algorithm with support for different user tiers.
#### Features
- **Sliding window algorithm**: Accurate request counting
- **Token bucket algorithm**: Alternative rate limiting method
- **User-based limits**: Different limits for anonymous/authenticated/admin users
- **Path-specific limits**: Custom limits for specific endpoints
- **Adaptive rate limiting**: Adjust limits based on system load
- **Temporary blocking**: Block clients after excessive violations
#### Implementation Details
```python
# Location: src/api/middleware/rate_limit.py
class RateLimitMiddleware(BaseHTTPMiddleware):
"""Rate limiting middleware with sliding window algorithm."""
```
**Default Rate Limits:**
- Anonymous users: 100 requests/hour (configurable)
- Authenticated users: 1000 requests/hour (configurable)
- Admin users: 10000 requests/hour
**Path-Specific Limits:**
- `/api/v1/pose/current`: 60 requests/minute
- `/api/v1/pose/analyze`: 10 requests/minute
- `/api/v1/pose/calibrate`: 1 request/5 minutes
- `/api/v1/stream/start`: 5 requests/minute
- `/api/v1/stream/stop`: 5 requests/minute
#### Response Headers
Rate limit information is included in response headers:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Window: 3600
X-RateLimit-Reset: 1641234567
```
When rate limit is exceeded:
```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: Exceeded
X-RateLimit-Remaining: 0
```
### Adaptive Rate Limiting
The system can adjust rate limits based on system load:
```python
class AdaptiveRateLimit:
"""Adaptive rate limiting based on system load."""
```
**Load-based adjustments:**
- High load (>80%): Reduce limits by 50%
- Medium load (>60%): Reduce limits by 30%
- Low load (<30%): Increase limits by 20%
## CORS Configuration
### Overview
Cross-Origin Resource Sharing (CORS) configuration for browser-based clients.
#### Features
- **Configurable origins**: Whitelist specific origins
- **Wildcard support**: Allow all origins in development
- **Preflight handling**: Proper OPTIONS request handling
- **Credential support**: Allow cookies and auth headers
- **Custom headers**: Expose rate limit and other headers
#### Configuration
```python
# Development configuration
cors_config = {
"allow_origins": ["*"],
"allow_credentials": True,
"allow_methods": ["*"],
"allow_headers": ["*"]
}
# Production configuration
cors_config = {
"allow_origins": ["https://app.example.com", "https://admin.example.com"],
"allow_credentials": True,
"allow_methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
"allow_headers": ["Authorization", "Content-Type"]
}
```
## Security Headers
The API includes various security headers for enhanced protection:
```python
class SecurityHeaders:
"""Security headers for API responses."""
```
**Headers included:**
- `X-Content-Type-Options: nosniff` - Prevent MIME sniffing
- `X-Frame-Options: DENY` - Prevent clickjacking
- `X-XSS-Protection: 1; mode=block` - Enable XSS protection
- `Referrer-Policy: strict-origin-when-cross-origin` - Control referrer
- `Content-Security-Policy` - Control resource loading
## Configuration
### Environment Variables
```bash
# Authentication
ENABLE_AUTHENTICATION=true
SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=24
# Rate Limiting
ENABLE_RATE_LIMITING=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_AUTHENTICATED_REQUESTS=1000
RATE_LIMIT_WINDOW=3600
# CORS
CORS_ENABLED=true
CORS_ORIGINS=["https://app.example.com"]
CORS_ALLOW_CREDENTIALS=true
# Security
ALLOWED_HOSTS=["api.example.com", "localhost"]
```
### Settings Class
```python
# src/config/settings.py
class Settings(BaseSettings):
# Authentication settings
enable_authentication: bool = Field(default=True)
secret_key: str = Field(...)
jwt_algorithm: str = Field(default="HS256")
jwt_expire_hours: int = Field(default=24)
# Rate limiting settings
enable_rate_limiting: bool = Field(default=True)
rate_limit_requests: int = Field(default=100)
rate_limit_authenticated_requests: int = Field(default=1000)
rate_limit_window: int = Field(default=3600)
# CORS settings
cors_enabled: bool = Field(default=True)
cors_origins: List[str] = Field(default=["*"])
cors_allow_credentials: bool = Field(default=True)
```
## Testing
### Test Script
A comprehensive test script is provided to verify security features:
```bash
# Run the test script
python test_auth_rate_limit.py
```
The test script covers:
- Public endpoint access
- Protected endpoint authentication
- JWT token validation
- Rate limiting behavior
- CORS headers
- Security headers
- Feature flag verification
### Manual Testing
**1. Test Authentication:**
```bash
# Without token (should fail)
curl -X POST http://localhost:8000/api/v1/pose/analyze
# With token (should succeed)
curl -X POST http://localhost:8000/api/v1/pose/analyze \
-H "Authorization: Bearer <token>"
```
**2. Test Rate Limiting:**
```bash
# Send multiple requests quickly
for i in {1..150}; do
curl -s -o /dev/null -w "%{http_code}\n" \
http://localhost:8000/api/v1/pose/current
done
```
**3. Test CORS:**
```bash
# Preflight request
curl -X OPTIONS http://localhost:8000/api/v1/pose/current \
-H "Origin: https://example.com" \
-H "Access-Control-Request-Method: GET" \
-H "Access-Control-Request-Headers: Authorization"
```
## Best Practices
### Security Recommendations
1. **Production Configuration:**
- Always use strong secret keys
- Disable debug mode
- Restrict CORS origins
- Use HTTPS only
- Enable all security headers
2. **Token Management:**
- Implement token refresh mechanism
- Use short-lived tokens
- Implement logout/blacklist functionality
- Store tokens securely on client
3. **Rate Limiting:**
- Set appropriate limits for your use case
- Monitor and adjust based on usage
- Implement different tiers for users
- Use Redis for distributed systems
4. **API Keys:**
- Use for service-to-service communication
- Rotate keys regularly
- Monitor key usage
- Implement key scoping
### Monitoring
1. **Authentication Events:**
- Log failed authentication attempts
- Monitor suspicious patterns
- Alert on repeated failures
2. **Rate Limit Violations:**
- Track clients hitting limits
- Identify potential abuse
- Adjust limits as needed
3. **Security Headers:**
- Verify headers in responses
- Test with security tools
- Regular security audits
### Troubleshooting
**Common Issues:**
1. **401 Unauthorized:**
- Check token format
- Verify token expiration
- Ensure correct secret key
2. **429 Too Many Requests:**
- Check rate limit configuration
- Verify client identification
- Look for Retry-After header
3. **CORS Errors:**
- Verify allowed origins
- Check preflight responses
- Ensure credentials setting matches
## Disabling Security Features
For development or testing, security features can be disabled:
```bash
# Disable authentication
ENABLE_AUTHENTICATION=false
# Disable rate limiting
ENABLE_RATE_LIMITING=false
# Allow all CORS origins
CORS_ORIGINS=["*"]
```
**Warning:** Never disable security features in production!
## Future Enhancements
1. **OAuth2/OpenID Connect Support**
2. **API Key Scoping and Permissions**
3. **IP-based Rate Limiting**
4. **Geographic Restrictions**
5. **Request Signing**
6. **Mutual TLS Authentication**

1058
v1/docs/troubleshooting.md Normal file
View File

File diff suppressed because it is too large Load Diff

989
v1/docs/user-guide/api-reference.md Normal file
View File

@@ -0,0 +1,989 @@
# API Reference
## Overview
The WiFi-DensePose API provides comprehensive access to pose estimation data, system control, and configuration management through RESTful endpoints and real-time WebSocket connections.
## Table of Contents
1. [Authentication](#authentication)
2. [Base URL and Versioning](#base-url-and-versioning)
3. [Pose Data Endpoints](#pose-data-endpoints)
4. [System Control Endpoints](#system-control-endpoints)
5. [Configuration Endpoints](#configuration-endpoints)
6. [Analytics Endpoints](#analytics-endpoints)
7. [WebSocket API](#websocket-api)
8. [Error Handling](#error-handling)
9. [Rate Limiting](#rate-limiting)
10. [Code Examples](#code-examples)
## Authentication
### Bearer Token Authentication
All API endpoints require authentication using JWT Bearer tokens:
```http
Authorization: Bearer <your-jwt-token>
```
### Obtaining a Token
```bash
# Get authentication token
curl -X POST http://localhost:8000/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"username": "your-username",
"password": "your-password"
}'
```
**Response:**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 86400
}
```
### API Key Authentication
For service-to-service communication:
```http
X-API-Key: <your-api-key>
```
## Base URL and Versioning
- **Base URL**: `http://localhost:8000/api/v1`
- **Current Version**: v1
- **Content-Type**: `application/json`
## Pose Data Endpoints
### Get Latest Pose Data
Retrieve the most recent pose estimation results.
**Endpoint:** `GET /pose/latest`
**Headers:**
```http
Authorization: Bearer <token>
```
**Response:**
```json
{
"timestamp": "2025-01-07T04:46:32.123Z",
"frame_id": 12345,
"processing_time_ms": 45,
"persons": [
{
"id": 1,
"confidence": 0.87,
"bounding_box": {
"x": 120,
"y": 80,
"width": 200,
"height": 400
},
"keypoints": [
{
"name": "nose",
"x": 220,
"y": 100,
"confidence": 0.95,
"visible": true
},
{
"name": "left_shoulder",
"x": 200,
"y": 150,
"confidence": 0.89,
"visible": true
}
],
"dense_pose": {
"body_parts": [
{
"part_id": 1,
"part_name": "torso",
"uv_coordinates": [[0.5, 0.3], [0.6, 0.4]],
"confidence": 0.89
}
]
},
"tracking_info": {
"track_id": "track_001",
"track_age": 150,
"velocity": {"x": 0.1, "y": 0.05}
}
}
],
"metadata": {
"environment_id": "room_001",
"router_count": 3,
"signal_quality": 0.82,
"processing_pipeline": "standard"
}
}
```
**Status Codes:**
- `200 OK`: Success
- `404 Not Found`: No pose data available
- `401 Unauthorized`: Authentication required
- `503 Service Unavailable`: System not initialized
### Get Historical Pose Data
Retrieve historical pose data with filtering options.
**Endpoint:** `GET /pose/history`
**Query Parameters:**
- `start_time` (optional): ISO 8601 timestamp for range start
- `end_time` (optional): ISO 8601 timestamp for range end
- `limit` (optional): Maximum number of records (default: 100, max: 1000)
- `person_id` (optional): Filter by specific person ID
- `confidence_threshold` (optional): Minimum confidence score (0.0-1.0)
**Example:**
```bash
curl "http://localhost:8000/api/v1/pose/history?start_time=2025-01-07T00:00:00Z&limit=50&confidence_threshold=0.7" \
-H "Authorization: Bearer <token>"
```
**Response:**
```json
{
"poses": [
{
"timestamp": "2025-01-07T04:46:32.123Z",
"persons": [...],
"metadata": {...}
}
],
"pagination": {
"total_count": 1500,
"returned_count": 50,
"has_more": true,
"next_cursor": "eyJpZCI6MTIzNDV9"
}
}
```
### Query Pose Data
Execute complex queries on pose data with aggregation support.
**Endpoint:** `POST /pose/query`
**Request Body:**
```json
{
"query": {
"time_range": {
"start": "2025-01-07T00:00:00Z",
"end": "2025-01-07T23:59:59Z"
},
"filters": {
"person_count": {"min": 1, "max": 5},
"confidence": {"min": 0.7},
"activity": ["walking", "standing"]
},
"aggregation": {
"type": "hourly_summary",
"metrics": ["person_count", "avg_confidence"]
}
}
}
```
**Response:**
```json
{
"results": [
{
"timestamp": "2025-01-07T10:00:00Z",
"person_count": 3,
"avg_confidence": 0.85,
"activities": {
"walking": 0.6,
"standing": 0.4
}
}
],
"query_metadata": {
"execution_time_ms": 150,
"total_records_scanned": 10000,
"cache_hit": false
}
}
```
## System Control Endpoints
### Get System Status
Get comprehensive system health and status information.
**Endpoint:** `GET /system/status`
**Response:**
```json
{
"status": "running",
"uptime_seconds": 86400,
"version": "1.0.0",
"components": {
"csi_receiver": {
"status": "active",
"data_rate_hz": 25.3,
"packet_loss_rate": 0.02,
"last_packet_time": "2025-01-07T04:46:32Z"
},
"neural_network": {
"status": "active",
"model_loaded": true,
"inference_time_ms": 45,
"gpu_utilization": 0.65
},
"tracking": {
"status": "active",
"active_tracks": 2,
"track_quality": 0.89
}
},
"hardware": {
"cpu_usage": 0.45,
"memory_usage": 0.62,
"gpu_memory_usage": 0.78,
"disk_usage": 0.23
},
"network": {
"connected_routers": 3,
"signal_strength": -45,
"interference_level": 0.15
}
}
```
### Start System
Start the pose estimation system with configuration options.
**Endpoint:** `POST /system/start`
**Request Body:**
```json
{
"configuration": {
"domain": "healthcare",
"environment_id": "room_001",
"calibration_required": true
}
}
```
**Response:**
```json
{
"status": "starting",
"estimated_ready_time": "2025-01-07T04:47:00Z",
"initialization_steps": [
{
"step": "hardware_initialization",
"status": "in_progress",
"progress": 0.3
},
{
"step": "model_loading",
"status": "pending",
"progress": 0.0
}
]
}
```
### Stop System
Gracefully stop the pose estimation system.
**Endpoint:** `POST /system/stop`
**Request Body:**
```json
{
"force": false,
"save_state": true
}
```
**Response:**
```json
{
"status": "stopping",
"estimated_stop_time": "2025-01-07T04:47:30Z",
"shutdown_steps": [
{
"step": "data_pipeline_stop",
"status": "completed",
"progress": 1.0
},
{
"step": "model_unloading",
"status": "in_progress",
"progress": 0.7
}
]
}
```
## Configuration Endpoints
### Get Configuration
Retrieve current system configuration.
**Endpoint:** `GET /config`
**Response:**
```json
{
"domain": "healthcare",
"environment": {
"id": "room_001",
"name": "Patient Room 1",
"calibration_timestamp": "2025-01-07T04:00:00Z"
},
"detection": {
"confidence_threshold": 0.7,
"max_persons": 5,
"tracking_enabled": true
},
"alerts": {
"fall_detection": {
"enabled": true,
"sensitivity": 0.8,
"notification_delay_seconds": 5
},
"inactivity_detection": {
"enabled": true,
"threshold_minutes": 30
}
},
"streaming": {
"restream_enabled": false,
"websocket_enabled": true,
"mqtt_enabled": true
}
}
```
### Update Configuration
Update system configuration with partial updates supported.
**Endpoint:** `PUT /config`
**Request Body:**
```json
{
"detection": {
"confidence_threshold": 0.75,
"max_persons": 3
},
"alerts": {
"fall_detection": {
"sensitivity": 0.9
}
}
}
```
**Response:**
```json
{
"status": "updated",
"changes_applied": [
"detection.confidence_threshold",
"detection.max_persons",
"alerts.fall_detection.sensitivity"
],
"restart_required": false,
"validation_warnings": []
}
```
## Analytics Endpoints
### Healthcare Analytics
Get healthcare-specific analytics and insights.
**Endpoint:** `GET /analytics/healthcare`
**Query Parameters:**
- `period`: Time period (hour, day, week, month)
- `metrics`: Comma-separated list of metrics
**Example:**
```bash
curl "http://localhost:8000/api/v1/analytics/healthcare?period=day&metrics=fall_events,activity_summary" \
-H "Authorization: Bearer <token>"
```
**Response:**
```json
{
"period": "day",
"date": "2025-01-07",
"metrics": {
"fall_events": {
"count": 2,
"events": [
{
"timestamp": "2025-01-07T14:30:15Z",
"person_id": 1,
"severity": "moderate",
"response_time_seconds": 45,
"location": {"x": 150, "y": 200}
}
]
},
"activity_summary": {
"walking_minutes": 120,
"sitting_minutes": 480,
"lying_minutes": 360,
"standing_minutes": 180
},
"mobility_score": 0.75,
"sleep_quality": {
"total_sleep_hours": 7.5,
"sleep_efficiency": 0.89,
"restlessness_events": 3
}
}
}
```
### Retail Analytics
Get retail-specific analytics and customer insights.
**Endpoint:** `GET /analytics/retail`
**Response:**
```json
{
"period": "day",
"date": "2025-01-07",
"metrics": {
"traffic": {
"total_visitors": 245,
"unique_visitors": 198,
"peak_hour": "14:00",
"peak_count": 15,
"average_dwell_time_minutes": 12.5
},
"zones": [
{
"zone_id": "entrance",
"zone_name": "Store Entrance",
"visitor_count": 245,
"avg_dwell_time_minutes": 2.1,
"conversion_rate": 0.85
},
{
"zone_id": "electronics",
"zone_name": "Electronics Section",
"visitor_count": 89,
"avg_dwell_time_minutes": 8.7,
"conversion_rate": 0.34
}
],
"conversion_funnel": {
"entrance": 245,
"product_interaction": 156,
"checkout_area": 89,
"purchase": 67
},
"heat_map": {
"high_traffic_areas": [
{"zone": "entrance", "intensity": 0.95},
{"zone": "checkout", "intensity": 0.78}
]
}
}
}
```
### Security Analytics
Get security-specific analytics and threat assessments.
**Endpoint:** `GET /analytics/security`
**Response:**
```json
{
"period": "day",
"date": "2025-01-07",
"metrics": {
"intrusion_events": {
"count": 1,
"events": [
{
"timestamp": "2025-01-07T02:15:30Z",
"zone": "restricted_area",
"person_count": 1,
"threat_level": "medium",
"response_time_seconds": 120
}
]
},
"perimeter_monitoring": {
"total_detections": 45,
"authorized_entries": 42,
"unauthorized_attempts": 3,
"false_positives": 0
},
"crowd_analysis": {
"max_occupancy": 12,
"average_occupancy": 3.2,
"crowd_formation_events": 0
}
}
}
```
## WebSocket API
### Connection
Connect to the WebSocket endpoint for real-time data streaming.
**Endpoint:** `ws://localhost:8000/ws/pose`
**Authentication:** Include token as query parameter or in headers:
```javascript
const ws = new WebSocket('ws://localhost:8000/ws/pose?token=<your-jwt-token>');
```
### Connection Establishment
**Server Message:**
```json
{
"type": "connection_established",
"client_id": "client_12345",
"server_time": "2025-01-07T04:46:32Z",
"supported_protocols": ["pose_v1", "alerts_v1"]
}
```
### Subscription Management
**Subscribe to Pose Updates:**
```json
{
"type": "subscribe",
"channel": "pose_updates",
"filters": {
"min_confidence": 0.7,
"person_ids": [1, 2, 3],
"include_keypoints": true,
"include_dense_pose": false
}
}
```
**Subscription Confirmation:**
```json
{
"type": "subscription_confirmed",
"channel": "pose_updates",
"subscription_id": "sub_67890",
"filters_applied": {
"min_confidence": 0.7,
"person_ids": [1, 2, 3]
}
}
```
### Real-Time Data Streaming
**Pose Update Message:**
```json
{
"type": "pose_update",
"subscription_id": "sub_67890",
"timestamp": "2025-01-07T04:46:32.123Z",
"data": {
"frame_id": 12345,
"persons": [...],
"metadata": {...}
}
}
```
**System Status Update:**
```json
{
"type": "system_status",
"timestamp": "2025-01-07T04:46:32Z",
"status": {
"processing_fps": 25.3,
"active_persons": 2,
"system_health": "good",
"gpu_utilization": 0.65
}
}
```
### Alert Streaming
**Subscribe to Alerts:**
```json
{
"type": "subscribe",
"channel": "alerts",
"filters": {
"alert_types": ["fall_detection", "intrusion"],
"severity": ["high", "critical"]
}
}
```
**Alert Message:**
```json
{
"type": "alert",
"alert_id": "alert_12345",
"timestamp": "2025-01-07T04:46:32Z",
"alert_type": "fall_detection",
"severity": "high",
"data": {
"person_id": 1,
"location": {"x": 220, "y": 180},
"confidence": 0.92,
"video_clip_url": "/clips/fall_12345.mp4"
},
"actions_required": ["medical_response", "notification"]
}
```
## Error Handling
### Standard Error Response Format
```json
{
"error": {
"code": "POSE_DATA_NOT_FOUND",
"message": "No pose data available for the specified time range",
"details": {
"requested_range": {
"start": "2025-01-07T00:00:00Z",
"end": "2025-01-07T01:00:00Z"
},
"available_range": {
"start": "2025-01-07T02:00:00Z",
"end": "2025-01-07T04:46:32Z"
}
},
"timestamp": "2025-01-07T04:46:32Z",
"request_id": "req_12345"
}
}
```
### HTTP Status Codes
#### Success Codes
- `200 OK`: Request successful
- `201 Created`: Resource created successfully
- `202 Accepted`: Request accepted for processing
- `204 No Content`: Request successful, no content returned
#### Client Error Codes
- `400 Bad Request`: Invalid request format or parameters
- `401 Unauthorized`: Authentication required or invalid
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: Resource not found
- `409 Conflict`: Resource conflict (e.g., system already running)
- `422 Unprocessable Entity`: Validation errors
- `429 Too Many Requests`: Rate limit exceeded
#### Server Error Codes
- `500 Internal Server Error`: Unexpected server error
- `502 Bad Gateway`: Upstream service error
- `503 Service Unavailable`: System not ready or overloaded
- `504 Gateway Timeout`: Request timeout
### Validation Error Response
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": {
"field_errors": [
{
"field": "confidence_threshold",
"message": "Value must be between 0.0 and 1.0",
"received_value": 1.5
},
{
"field": "max_persons",
"message": "Value must be a positive integer",
"received_value": -1
}
]
},
"timestamp": "2025-01-07T04:46:32Z",
"request_id": "req_12346"
}
}
```
## Rate Limiting
### Rate Limit Headers
All responses include rate limiting information:
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704686400
X-RateLimit-Window: 3600
```
### Rate Limits by Endpoint Type
- **REST API**: 1000 requests per hour per API key
- **WebSocket**: 100 connections per IP address
- **Streaming**: 10 concurrent streams per account
- **Webhook**: 10,000 events per hour per endpoint
### Rate Limit Exceeded Response
```json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again later.",
"details": {
"limit": 1000,
"window_seconds": 3600,
"reset_time": "2025-01-07T05:46:32Z"
},
"timestamp": "2025-01-07T04:46:32Z",
"request_id": "req_12347"
}
}
```
## Code Examples
### Python Example
```python
import requests
import json
from datetime import datetime, timedelta
class WiFiDensePoseClient:
def __init__(self, base_url, token):
self.base_url = base_url
self.headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
def get_latest_pose(self):
"""Get the latest pose data."""
response = requests.get(
f'{self.base_url}/pose/latest',
headers=self.headers
)
response.raise_for_status()
return response.json()
def get_historical_poses(self, start_time=None, end_time=None, limit=100):
"""Get historical pose data."""
params = {'limit': limit}
if start_time:
params['start_time'] = start_time.isoformat()
if end_time:
params['end_time'] = end_time.isoformat()
response = requests.get(
f'{self.base_url}/pose/history',
headers=self.headers,
params=params
)
response.raise_for_status()
return response.json()
def start_system(self, domain='general', environment_id='default'):
"""Start the pose estimation system."""
data = {
'configuration': {
'domain': domain,
'environment_id': environment_id,
'calibration_required': True
}
}
response = requests.post(
f'{self.base_url}/system/start',
headers=self.headers,
json=data
)
response.raise_for_status()
return response.json()
# Usage example
client = WiFiDensePoseClient('http://localhost:8000/api/v1', 'your-token')
# Get latest pose data
latest = client.get_latest_pose()
print(f"Found {len(latest['persons'])} persons")
# Get historical data for the last hour
end_time = datetime.now()
start_time = end_time - timedelta(hours=1)
history = client.get_historical_poses(start_time, end_time)
print(f"Retrieved {len(history['poses'])} historical records")
```
### JavaScript Example
```javascript
class WiFiDensePoseClient {
constructor(baseUrl, token) {
this.baseUrl = baseUrl;
this.headers = {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
};
}
async getLatestPose() {
const response = await fetch(`${this.baseUrl}/pose/latest`, {
headers: this.headers
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
}
async updateConfiguration(config) {
const response = await fetch(`${this.baseUrl}/config`, {
method: 'PUT',
headers: this.headers,
body: JSON.stringify(config)
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
}
connectWebSocket() {
const ws = new WebSocket(`ws://localhost:8000/ws/pose?token=${this.token}`);
ws.onopen = () => {
console.log('WebSocket connected');
// Subscribe to pose updates
ws.send(JSON.stringify({
type: 'subscribe',
channel: 'pose_updates',
filters: {
min_confidence: 0.7
}
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received:', data);
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
return ws;
}
}
// Usage example
const client = new WiFiDensePoseClient('http://localhost:8000/api/v1', 'your-token');
// Get latest pose data
client.getLatestPose()
.then(data => console.log('Latest pose:', data))
.catch(error => console.error('Error:', error));
// Connect to WebSocket for real-time updates
const ws = client.connectWebSocket();
```
### cURL Examples
```bash
# Get authentication token
curl -X POST http://localhost:8000/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "password"}'
# Get latest pose data
curl http://localhost:8000/api/v1/pose/latest \
-H "Authorization: Bearer <token>"
# Start system
curl -X POST http://localhost:8000/api/v1/system/start \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"configuration": {
"domain": "healthcare",
"environment_id": "room_001"
}
}'
# Update configuration
curl -X PUT http://localhost:8000/api/v1/config \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"detection": {
"confidence_threshold": 0.8
}
}'
# Get healthcare analytics
curl "http://localhost:8000/api/v1/analytics/healthcare?period=day" \
-H "Authorization: Bearer <token>"
```
---
For more detailed information, see:
- [Getting Started Guide](getting-started.md)
- [Configuration Guide](configuration.md)
- [WebSocket API Documentation](../api/websocket-api.md)
- [Authentication Guide](../api/authentication.md)

722
v1/docs/user-guide/configuration.md Normal file
View File

@@ -0,0 +1,722 @@
# Configuration Guide
## Overview
This guide covers comprehensive configuration options for the WiFi-DensePose system, including domain-specific settings, hardware configuration, performance tuning, and security settings.
## Table of Contents
1. [Configuration Files](#configuration-files)
2. [Environment Variables](#environment-variables)
3. [Domain-Specific Configuration](#domain-specific-configuration)
4. [Hardware Configuration](#hardware-configuration)
5. [Performance Tuning](#performance-tuning)
6. [Security Configuration](#security-configuration)
7. [Integration Settings](#integration-settings)
8. [Monitoring and Logging](#monitoring-and-logging)
9. [Advanced Configuration](#advanced-configuration)
## Configuration Files
### Primary Configuration File
The system uses environment variables and configuration files for settings management:
```bash
# Main configuration file
.env
# Domain-specific configurations
config/domains/healthcare.yaml
config/domains/retail.yaml
config/domains/security.yaml
# Hardware configurations
config/hardware/routers.yaml
config/hardware/processing.yaml
```
### Configuration Hierarchy
Configuration is loaded in the following order (later values override earlier ones):
1. Default values in [`src/config/settings.py`](../../src/config/settings.py)
2. Environment-specific configuration files
3. `.env` file
4. Environment variables
5. Command-line arguments
## Environment Variables
### Application Settings
```bash
# Basic application settings
APP_NAME="WiFi-DensePose API"
VERSION="1.0.0"
ENVIRONMENT="development" # development, staging, production
DEBUG=false
# Server configuration
HOST="0.0.0.0"
PORT=8000
RELOAD=false
WORKERS=1
```
### Security Settings
```bash
# JWT Configuration
SECRET_KEY="your-super-secret-key-change-in-production"
JWT_ALGORITHM="HS256"
JWT_EXPIRE_HOURS=24
# CORS and Host Settings
ALLOWED_HOSTS="localhost,127.0.0.1,your-domain.com"
CORS_ORIGINS="http://localhost:3000,https://your-frontend.com"
# Rate Limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_AUTHENTICATED_REQUESTS=1000
RATE_LIMIT_WINDOW=3600 # seconds
```
### Database Configuration
```bash
# Database Settings
DATABASE_URL="postgresql://user:password@localhost:5432/wifi_densepose"
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20
# Redis Configuration
REDIS_URL="redis://localhost:6379/0"
REDIS_PASSWORD=""
REDIS_DB=0
```
### Hardware Settings
```bash
# WiFi Interface
WIFI_INTERFACE="wlan0"
CSI_BUFFER_SIZE=1000
HARDWARE_POLLING_INTERVAL=0.1
# Development/Testing
MOCK_HARDWARE=false
MOCK_POSE_DATA=false
```
### Pose Estimation Settings
```bash
# Model Configuration
POSE_MODEL_PATH="./models/densepose_model.pth"
POSE_CONFIDENCE_THRESHOLD=0.5
POSE_PROCESSING_BATCH_SIZE=32
POSE_MAX_PERSONS=10
# Streaming Settings
STREAM_FPS=30
STREAM_BUFFER_SIZE=100
WEBSOCKET_PING_INTERVAL=60
WEBSOCKET_TIMEOUT=300
```
### Storage Settings
```bash
# Storage Paths
DATA_STORAGE_PATH="./data"
MODEL_STORAGE_PATH="./models"
TEMP_STORAGE_PATH="./temp"
MAX_STORAGE_SIZE_GB=100
```
### Feature Flags
```bash
# Feature Toggles
ENABLE_AUTHENTICATION=true
ENABLE_RATE_LIMITING=true
ENABLE_WEBSOCKETS=true
ENABLE_HISTORICAL_DATA=true
ENABLE_REAL_TIME_PROCESSING=true
ENABLE_TEST_ENDPOINTS=false
```
## Domain-Specific Configuration
### Healthcare Domain
Healthcare deployments require enhanced privacy and accuracy settings:
```yaml
# config/domains/healthcare.yaml
domain: healthcare
description: "Healthcare monitoring and patient safety"
detection:
confidence_threshold: 0.8
max_persons: 3
tracking_enabled: true
privacy_mode: true
alerts:
fall_detection:
enabled: true
sensitivity: 0.9
notification_delay_seconds: 5
emergency_contacts:
- "nurse-station@hospital.com"
- "+1-555-0123"
inactivity_detection:
enabled: true
threshold_minutes: 30
alert_levels: ["warning", "critical"]
vital_signs_monitoring:
enabled: true
heart_rate_estimation: true
breathing_pattern_analysis: true
privacy:
data_retention_days: 30
anonymization_enabled: true
audit_logging: true
hipaa_compliance: true
notifications:
webhook_urls:
- "https://hospital-system.com/api/alerts"
mqtt_topics:
- "hospital/room/{room_id}/alerts"
email_alerts: true
```
### Retail Domain
Retail deployments focus on customer analytics and traffic patterns:
```yaml
# config/domains/retail.yaml
domain: retail
description: "Retail analytics and customer insights"
detection:
confidence_threshold: 0.7
max_persons: 15
tracking_enabled: true
zone_detection: true
analytics:
traffic_counting:
enabled: true
entrance_zones: ["entrance", "exit"]
dwell_time_tracking: true
heat_mapping:
enabled: true
zone_definitions:
- name: "entrance"
coordinates: [[0, 0], [100, 50]]
- name: "electronics"
coordinates: [[100, 0], [200, 100]]
- name: "checkout"
coordinates: [[200, 0], [300, 50]]
conversion_tracking:
enabled: true
interaction_threshold_seconds: 10
purchase_correlation: true
privacy:
data_retention_days: 90
anonymization_enabled: true
gdpr_compliance: true
reporting:
daily_reports: true
weekly_summaries: true
real_time_dashboard: true
```
### Security Domain
Security deployments prioritize intrusion detection and perimeter monitoring:
```yaml
# config/domains/security.yaml
domain: security
description: "Security monitoring and intrusion detection"
detection:
confidence_threshold: 0.9
max_persons: 10
tracking_enabled: true
motion_sensitivity: 0.95
security:
intrusion_detection:
enabled: true
restricted_zones:
- name: "secure_area"
coordinates: [[50, 50], [150, 150]]
alert_immediately: true
- name: "perimeter"
coordinates: [[0, 0], [300, 300]]
alert_delay_seconds: 10
unauthorized_access:
enabled: true
authorized_persons: [] # Empty for general detection
time_restrictions:
- days: ["monday", "tuesday", "wednesday", "thursday", "friday"]
hours: ["09:00", "17:00"]
threat_assessment:
enabled: true
aggressive_behavior_detection: true
crowd_formation_detection: true
alerts:
immediate_notification: true
escalation_levels:
- level: 1
delay_seconds: 0
contacts: ["security@company.com"]
- level: 2
delay_seconds: 30
contacts: ["security@company.com", "manager@company.com"]
- level: 3
delay_seconds: 60
contacts: ["security@company.com", "manager@company.com", "emergency@company.com"]
integration:
security_system_api: "https://security-system.com/api"
camera_system_integration: true
access_control_integration: true
```
## Hardware Configuration
### Router Configuration
```yaml
# config/hardware/routers.yaml
routers:
- id: "router_001"
type: "atheros"
model: "TP-Link Archer C7"
ip_address: "192.168.1.1"
mac_address: "aa:bb:cc:dd:ee:01"
location:
room: "living_room"
coordinates: [0, 0, 2.5] # x, y, z in meters
csi_config:
sampling_rate: 30 # Hz
antenna_count: 3
subcarrier_count: 56
data_port: 5500
- id: "router_002"
type: "atheros"
model: "Netgear Nighthawk"
ip_address: "192.168.1.2"
mac_address: "aa:bb:cc:dd:ee:02"
location:
room: "living_room"
coordinates: [5, 0, 2.5]
csi_config:
sampling_rate: 30
antenna_count: 3
subcarrier_count: 56
data_port: 5501
network:
csi_data_interface: "eth0"
buffer_size: 1000
timeout_seconds: 5
retry_attempts: 3
```
### Processing Hardware Configuration
```yaml
# config/hardware/processing.yaml
processing:
cpu:
cores: 8
threads_per_core: 2
optimization: "performance" # performance, balanced, power_save
memory:
total_gb: 16
allocation:
csi_processing: 4
neural_network: 8
api_services: 2
system_overhead: 2
gpu:
enabled: true
device_id: 0
memory_gb: 8
cuda_version: "11.8"
optimization:
batch_size: 32
mixed_precision: true
tensor_cores: true
storage:
data_drive:
path: "/data"
type: "ssd"
size_gb: 500
model_drive:
path: "/models"
type: "ssd"
size_gb: 100
temp_drive:
path: "/tmp"
type: "ram"
size_gb: 8
```
## Performance Tuning
### Processing Pipeline Optimization
```bash
# Neural Network Settings
POSE_PROCESSING_BATCH_SIZE=32 # Adjust based on GPU memory
POSE_CONFIDENCE_THRESHOLD=0.7 # Higher = fewer false positives
POSE_MAX_PERSONS=5 # Limit for performance
# Streaming Optimization
STREAM_FPS=30 # Reduce for lower bandwidth
STREAM_BUFFER_SIZE=100 # Increase for smoother streaming
WEBSOCKET_PING_INTERVAL=60 # Connection keep-alive
# Database Optimization
DATABASE_POOL_SIZE=20 # Increase for high concurrency
DATABASE_MAX_OVERFLOW=40 # Additional connections when needed
# Caching Settings
REDIS_URL="redis://localhost:6379/0"
CACHE_TTL_SECONDS=300 # Cache expiration time
```
### Resource Allocation
```yaml
# docker-compose.override.yml
version: '3.8'
services:
wifi-densepose-api:
deploy:
resources:
limits:
cpus: '4.0'
memory: 8G
reservations:
cpus: '2.0'
memory: 4G
environment:
- WORKERS=4
- POSE_PROCESSING_BATCH_SIZE=64
neural-network:
deploy:
resources:
limits:
cpus: '2.0'
memory: 6G
reservations:
cpus: '1.0'
memory: 4G
runtime: nvidia
environment:
- CUDA_VISIBLE_DEVICES=0
```
### Performance Monitoring
```bash
# Enable performance monitoring
PERFORMANCE_MONITORING=true
METRICS_ENABLED=true
HEALTH_CHECK_INTERVAL=30
# Logging for performance analysis
LOG_LEVEL="INFO"
LOG_PERFORMANCE_METRICS=true
LOG_SLOW_QUERIES=true
SLOW_QUERY_THRESHOLD_MS=1000
```
## Security Configuration
### Authentication and Authorization
```bash
# JWT Configuration
SECRET_KEY="$(openssl rand -base64 32)" # Generate secure key
JWT_ALGORITHM="HS256"
JWT_EXPIRE_HOURS=8 # Shorter expiration for production
# API Key Configuration
API_KEY_LENGTH=32
API_KEY_EXPIRY_DAYS=90
API_KEY_ROTATION_ENABLED=true
```
### Network Security
```bash
# HTTPS Configuration
ENABLE_HTTPS=true
SSL_CERT_PATH="/etc/ssl/certs/wifi-densepose.crt"
SSL_KEY_PATH="/etc/ssl/private/wifi-densepose.key"
# Firewall Settings
ALLOWED_IPS="192.168.1.0/24,10.0.0.0/8"
BLOCKED_IPS=""
RATE_LIMIT_ENABLED=true
```
### Data Protection
```bash
# Encryption Settings
DATABASE_ENCRYPTION=true
DATA_AT_REST_ENCRYPTION=true
BACKUP_ENCRYPTION=true
# Privacy Settings
ANONYMIZATION_ENABLED=true
DATA_RETENTION_DAYS=30
AUDIT_LOGGING=true
GDPR_COMPLIANCE=true
```
## Integration Settings
### MQTT Configuration
```bash
# MQTT Broker Settings
MQTT_BROKER_HOST="localhost"
MQTT_BROKER_PORT=1883
MQTT_USERNAME="wifi_densepose"
MQTT_PASSWORD="secure_password"
MQTT_TLS_ENABLED=true
# Topic Configuration
MQTT_TOPIC_PREFIX="wifi-densepose"
MQTT_QOS_LEVEL=1
MQTT_RETAIN_MESSAGES=false
```
### Webhook Configuration
```bash
# Webhook Settings
WEBHOOK_TIMEOUT_SECONDS=30
WEBHOOK_RETRY_ATTEMPTS=3
WEBHOOK_RETRY_DELAY_SECONDS=5
# Security
WEBHOOK_SIGNATURE_ENABLED=true
WEBHOOK_SECRET_KEY="webhook_secret_key"
```
### External API Integration
```bash
# Restream Integration
RESTREAM_API_KEY="your_restream_api_key"
RESTREAM_ENABLED=false
RESTREAM_PLATFORMS="youtube,twitch"
# Third-party APIs
EXTERNAL_API_TIMEOUT=30
EXTERNAL_API_RETRY_ATTEMPTS=3
```
## Monitoring and Logging
### Logging Configuration
```bash
# Log Levels
LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
# Log Files
LOG_FILE="/var/log/wifi-densepose/app.log"
LOG_MAX_SIZE=10485760 # 10MB
LOG_BACKUP_COUNT=5
# Structured Logging
LOG_JSON_FORMAT=true
LOG_CORRELATION_ID=true
```
### Metrics and Monitoring
```bash
# Prometheus Metrics
METRICS_ENABLED=true
METRICS_PORT=9090
METRICS_PATH="/metrics"
# Health Checks
HEALTH_CHECK_INTERVAL=30
HEALTH_CHECK_TIMEOUT=10
DEEP_HEALTH_CHECKS=true
# Performance Monitoring
PERFORMANCE_MONITORING=true
SLOW_QUERY_LOGGING=true
RESOURCE_MONITORING=true
```
## Advanced Configuration
### Custom Model Configuration
```yaml
# config/models/custom_model.yaml
model:
name: "custom_densepose_v2"
path: "./models/custom_densepose_v2.pth"
type: "pytorch"
preprocessing:
input_size: [256, 256]
normalization:
mean: [0.485, 0.456, 0.406]
std: [0.229, 0.224, 0.225]
inference:
batch_size: 32
device: "cuda:0"
precision: "fp16" # fp32, fp16, int8
postprocessing:
confidence_threshold: 0.7
nms_threshold: 0.5
max_detections: 10
```
### Environment-Specific Overrides
```bash
# config/environments/production.env
ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=WARNING
WORKERS=8
POSE_PROCESSING_BATCH_SIZE=64
ENABLE_TEST_ENDPOINTS=false
MOCK_HARDWARE=false
```
```bash
# config/environments/development.env
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=DEBUG
WORKERS=1
RELOAD=true
MOCK_HARDWARE=true
ENABLE_TEST_ENDPOINTS=true
```
### Configuration Validation
The system automatically validates configuration on startup:
```bash
# Run configuration validation
python -m src.config.validate
# Check specific configuration
python -c "
from src.config.settings import get_settings, validate_settings
settings = get_settings()
issues = validate_settings(settings)
if issues:
print('Configuration issues:')
for issue in issues:
print(f' - {issue}')
else:
print('Configuration is valid')
"
```
### Dynamic Configuration Updates
Some settings can be updated without restarting the system:
```bash
# Update detection settings
curl -X PUT http://localhost:8000/api/v1/config \
-H "Content-Type: application/json" \
-d '{
"detection": {
"confidence_threshold": 0.8,
"max_persons": 3
}
}'
# Update alert settings
curl -X PUT http://localhost:8000/api/v1/config \
-H "Content-Type: application/json" \
-d '{
"alerts": {
"fall_detection": {
"sensitivity": 0.9
}
}
}'
```
## Configuration Best Practices
### Security Best Practices
1. **Use Strong Secret Keys**: Generate cryptographically secure keys
2. **Restrict CORS Origins**: Don't use wildcards in production
3. **Enable Rate Limiting**: Protect against abuse
4. **Use HTTPS**: Encrypt all communications
5. **Regular Key Rotation**: Rotate API keys and JWT secrets
### Performance Best Practices
1. **Right-size Resources**: Allocate appropriate CPU/memory
2. **Use GPU Acceleration**: Enable CUDA for neural network processing
3. **Optimize Batch Sizes**: Balance throughput and latency
4. **Configure Caching**: Use Redis for frequently accessed data
5. **Monitor Resource Usage**: Set up alerts for resource exhaustion
### Operational Best Practices
1. **Environment Separation**: Use different configs for dev/staging/prod
2. **Configuration Validation**: Validate settings before deployment
3. **Backup Configurations**: Version control all configuration files
4. **Document Changes**: Maintain change logs for configuration updates
5. **Test Configuration**: Validate configuration in staging environment
---
For more specific configuration examples, see:
- [Hardware Setup Guide](../hardware/router-setup.md)
- [API Reference](api-reference.md)
- [Deployment Guide](../developer/deployment-guide.md)

501
v1/docs/user-guide/getting-started.md Normal file
View File

@@ -0,0 +1,501 @@
# Getting Started with WiFi-DensePose
## Overview
WiFi-DensePose is a revolutionary privacy-preserving human pose estimation system that transforms commodity WiFi infrastructure into a powerful human sensing platform. This guide will help you install, configure, and start using the system.
## Table of Contents
1. [System Requirements](#system-requirements)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Basic Configuration](#basic-configuration)
5. [First Pose Detection](#first-pose-detection)
6. [Troubleshooting](#troubleshooting)
7. [Next Steps](#next-steps)
## System Requirements
### Hardware Requirements
#### WiFi Router Requirements
- **Compatible Hardware**: Atheros-based routers (TP-Link Archer series, Netgear Nighthawk), Intel 5300 NIC-based systems, or ASUS RT-AC68U series
- **Antenna Configuration**: Minimum 3×3 MIMO antenna configuration
- **Frequency Bands**: 2.4GHz and 5GHz support
- **Firmware**: OpenWRT firmware compatibility with CSI extraction patches
#### Processing Hardware
- **CPU**: Multi-core processor (4+ cores recommended)
- **RAM**: 8GB minimum, 16GB recommended
- **Storage**: 50GB available space
- **Network**: Gigabit Ethernet for CSI data streams
- **GPU** (Optional): NVIDIA GPU with CUDA capability and 4GB+ memory for real-time processing
### Software Requirements
#### Operating System
- **Primary**: Linux (Ubuntu 20.04+, CentOS 8+)
- **Secondary**: Windows 10/11 with WSL2
- **Container**: Docker support for deployment
#### Runtime Dependencies
- Python 3.8+
- PyTorch (GPU-accelerated recommended)
- OpenCV
- FFmpeg
- FastAPI
## Installation
### Method 1: Docker Installation (Recommended)
#### Prerequisites
```bash
# Install Docker and Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
#### Download and Setup
```bash
# Clone the repository
git clone https://github.com/your-org/wifi-densepose.git
cd wifi-densepose
# Copy environment configuration
cp .env.example .env
# Edit configuration (see Configuration section)
nano .env
# Start the system
docker-compose up -d
```
### Method 2: Native Installation
#### Install System Dependencies
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y python3.9 python3.9-pip python3.9-venv
sudo apt install -y build-essential cmake
sudo apt install -y libopencv-dev ffmpeg
# CentOS/RHEL
sudo yum update
sudo yum install -y python39 python39-pip
sudo yum groupinstall -y "Development Tools"
sudo yum install -y opencv-devel ffmpeg
```
#### Install Python Dependencies
```bash
# Create virtual environment
python3.9 -m venv venv
source venv/bin/activate
# Install requirements
pip install -r requirements.txt
# Install PyTorch with CUDA support (if GPU available)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```
#### Install WiFi-DensePose
```bash
# Install in development mode
pip install -e .
# Or install from PyPI (when available)
pip install wifi-densepose
```
## Quick Start
### 1. Environment Configuration
Create and configure your environment file:
```bash
# Copy the example configuration
cp .env.example .env
```
Edit the `.env` file with your settings:
```bash
# Application settings
APP_NAME="WiFi-DensePose API"
VERSION="1.0.0"
ENVIRONMENT="development"
DEBUG=true
# Server settings
HOST="0.0.0.0"
PORT=8000
# Security settings (CHANGE IN PRODUCTION!)
SECRET_KEY="your-secret-key-here"
JWT_EXPIRE_HOURS=24
# Hardware settings
WIFI_INTERFACE="wlan0"
CSI_BUFFER_SIZE=1000
MOCK_HARDWARE=true # Set to false when using real hardware
# Pose estimation settings
POSE_CONFIDENCE_THRESHOLD=0.5
POSE_MAX_PERSONS=5
# Storage settings
DATA_STORAGE_PATH="./data"
MODEL_STORAGE_PATH="./models"
```
### 2. Start the System
#### Using Docker
```bash
# Start all services
docker-compose up -d
# Check service status
docker-compose ps
# View logs
docker-compose logs -f
```
#### Using Native Installation
```bash
# Activate virtual environment
source venv/bin/activate
# Start the API server
python -m src.api.main
# Or use uvicorn directly
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload
```
### 3. Verify Installation
Check that the system is running:
```bash
# Check API health
curl http://localhost:8000/health
# Expected response:
# {"status": "healthy", "timestamp": "2025-01-07T10:00:00Z"}
```
Access the web interface:
- **API Documentation**: http://localhost:8000/docs
- **Alternative Docs**: http://localhost:8000/redoc
- **Health Check**: http://localhost:8000/health
## Basic Configuration
### Domain Configuration
WiFi-DensePose supports different domain-specific configurations:
#### Healthcare Domain
```bash
# Set healthcare-specific settings
export DOMAIN="healthcare"
export POSE_CONFIDENCE_THRESHOLD=0.8
export ENABLE_FALL_DETECTION=true
export ALERT_SENSITIVITY=0.9
```
#### Retail Domain
```bash
# Set retail-specific settings
export DOMAIN="retail"
export POSE_CONFIDENCE_THRESHOLD=0.7
export ENABLE_TRAFFIC_ANALYTICS=true
export ZONE_TRACKING=true
```
#### Security Domain
```bash
# Set security-specific settings
export DOMAIN="security"
export POSE_CONFIDENCE_THRESHOLD=0.9
export ENABLE_INTRUSION_DETECTION=true
export ALERT_IMMEDIATE=true
```
### Router Configuration
#### Configure WiFi Routers for CSI Extraction
1. **Flash OpenWRT Firmware**:
```bash
# Download OpenWRT firmware for your router model
wget https://downloads.openwrt.org/releases/22.03.0/targets/...
# Flash firmware (router-specific process)
# Follow your router's flashing instructions
```
2. **Install CSI Extraction Patches**:
```bash
# SSH into router
ssh root@192.168.1.1
# Install CSI tools
opkg update
opkg install csi-tools
# Configure CSI extraction
echo "csi_enable=1" >> /etc/config/wireless
echo "csi_rate=30" >> /etc/config/wireless
```
3. **Configure Network Settings**:
```bash
# Set router to monitor mode
iwconfig wlan0 mode monitor
# Start CSI data streaming
csi_tool -i wlan0 -d 192.168.1.100 -p 5500
```
### Database Configuration
#### SQLite (Development)
```bash
# Default SQLite database (no additional configuration needed)
DATABASE_URL="sqlite:///./data/wifi_densepose.db"
```
#### PostgreSQL (Production)
```bash
# Install PostgreSQL with TimescaleDB extension
sudo apt install postgresql-14 postgresql-14-timescaledb
# Configure database
DATABASE_URL="postgresql://user:password@localhost:5432/wifi_densepose"
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20
```
#### Redis (Caching)
```bash
# Install Redis
sudo apt install redis-server
# Configure Redis
REDIS_URL="redis://localhost:6379/0"
REDIS_PASSWORD="" # Set password for production
```
## First Pose Detection
### 1. Start the System
```bash
# Using Docker
docker-compose up -d
# Using native installation
python -m src.api.main
```
### 2. Initialize Hardware
```bash
# Check system status
curl http://localhost:8000/api/v1/system/status
# Start pose estimation system
curl -X POST http://localhost:8000/api/v1/system/start \
-H "Content-Type: application/json" \
-d '{
"configuration": {
"domain": "general",
"environment_id": "room_001",
"calibration_required": true
}
}'
```
### 3. Get Pose Data
#### REST API
```bash
# Get latest pose data
curl http://localhost:8000/api/v1/pose/latest
# Get historical data
curl "http://localhost:8000/api/v1/pose/history?limit=10"
```
#### WebSocket Streaming
```javascript
// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8000/ws/pose');
// Subscribe to pose updates
ws.onopen = function() {
ws.send(JSON.stringify({
type: 'subscribe',
channel: 'pose_updates',
filters: {
min_confidence: 0.7
}
}));
};
// Handle pose data
ws.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log('Pose data:', data);
};
```
### 4. View Results
Access the web dashboard:
- **Main Dashboard**: http://localhost:8000/dashboard
- **Real-time View**: http://localhost:8000/dashboard/live
- **Analytics**: http://localhost:8000/dashboard/analytics
## Troubleshooting
### Common Issues
#### 1. System Won't Start
```bash
# Check logs
docker-compose logs
# Common solutions:
# - Verify port 8000 is available
# - Check environment variables
# - Ensure sufficient disk space
```
#### 2. No Pose Data
```bash
# Check hardware status
curl http://localhost:8000/api/v1/system/status
# Verify router connectivity
ping 192.168.1.1
# Check CSI data reception
netstat -an | grep 5500
```
#### 3. Poor Detection Accuracy
```bash
# Adjust confidence threshold
curl -X PUT http://localhost:8000/api/v1/config \
-H "Content-Type: application/json" \
-d '{"detection": {"confidence_threshold": 0.6}}'
# Recalibrate environment
curl -X POST http://localhost:8000/api/v1/system/calibrate
```
#### 4. High CPU/Memory Usage
```bash
# Check resource usage
docker stats
# Optimize settings
export POSE_PROCESSING_BATCH_SIZE=16
export STREAM_FPS=15
```
### Getting Help
#### Log Analysis
```bash
# View application logs
docker-compose logs wifi-densepose-api
# View system logs
journalctl -u wifi-densepose
# Enable debug logging
export LOG_LEVEL="DEBUG"
```
#### Health Checks
```bash
# Comprehensive system check
curl http://localhost:8000/api/v1/system/status
# Component-specific checks
curl http://localhost:8000/api/v1/hardware/status
curl http://localhost:8000/api/v1/processing/status
```
#### Support Resources
- **Documentation**: [docs/](../README.md)
- **API Reference**: [api-reference.md](api-reference.md)
- **Troubleshooting Guide**: [troubleshooting.md](troubleshooting.md)
- **GitHub Issues**: https://github.com/your-org/wifi-densepose/issues
## Next Steps
### 1. Configure for Your Domain
- Review [configuration.md](configuration.md) for domain-specific settings
- Set up alerts and notifications
- Configure external integrations
### 2. Integrate with Your Applications
- Review [API Reference](api-reference.md)
- Set up webhooks for events
- Configure MQTT for IoT integration
### 3. Deploy to Production
- Review [deployment guide](../developer/deployment-guide.md)
- Set up monitoring and alerting
- Configure backup and recovery
### 4. Optimize Performance
- Tune processing parameters
- Set up GPU acceleration
- Configure load balancing
## Security Considerations
### Development Environment
- Use strong secret keys
- Enable authentication
- Restrict network access
### Production Environment
- Use HTTPS/TLS encryption
- Configure firewall rules
- Set up audit logging
- Regular security updates
## Performance Tips
### Hardware Optimization
- Use SSD storage for better I/O performance
- Ensure adequate cooling for continuous operation
- Use dedicated network interface for CSI data
### Software Optimization
- Enable GPU acceleration when available
- Tune batch sizes for your hardware
- Configure appropriate worker processes
- Use Redis for caching frequently accessed data
---
**Congratulations!** You now have WiFi-DensePose up and running. Continue with the [Configuration Guide](configuration.md) to customize the system for your specific needs.

948
v1/docs/user-guide/troubleshooting.md Normal file
View File

@@ -0,0 +1,948 @@
# Troubleshooting Guide
## Overview
This guide provides solutions to common issues encountered when using the WiFi-DensePose system, including installation problems, hardware connectivity issues, performance optimization, and error resolution.
## Table of Contents
1. [Quick Diagnostics](#quick-diagnostics)
2. [Installation Issues](#installation-issues)
3. [Hardware Problems](#hardware-problems)
4. [Performance Issues](#performance-issues)
5. [API and Connectivity Issues](#api-and-connectivity-issues)
6. [Data Quality Issues](#data-quality-issues)
7. [System Errors](#system-errors)
8. [Domain-Specific Issues](#domain-specific-issues)
9. [Advanced Troubleshooting](#advanced-troubleshooting)
10. [Getting Support](#getting-support)
## Quick Diagnostics
### System Health Check
Run a comprehensive system health check to identify issues:
```bash
# Check system status
curl http://localhost:8000/api/v1/system/status
# Run built-in diagnostics
curl http://localhost:8000/api/v1/system/diagnostics
# Check component health
curl http://localhost:8000/api/v1/health
```
### Log Analysis
Check system logs for error patterns:
```bash
# View recent logs
docker-compose logs --tail=100 wifi-densepose-api
# Search for errors
docker-compose logs | grep -i error
# Check specific component logs
docker-compose logs neural-network
docker-compose logs csi-processor
```
### Resource Monitoring
Monitor system resources:
```bash
# Check Docker container resources
docker stats
# Check system resources
htop
nvidia-smi # For GPU monitoring
# Check disk space
df -h
```
## Installation Issues
### Docker Installation Problems
#### Issue: Docker Compose Fails to Start
**Symptoms:**
- Services fail to start
- Port conflicts
- Permission errors
**Solutions:**
1. **Check Port Availability:**
```bash
# Check if port 8000 is in use
netstat -tulpn | grep :8000
lsof -i :8000
# Kill process using the port
sudo kill -9 <PID>
```
2. **Fix Permission Issues:**
```bash
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
# Fix file permissions
sudo chown -R $USER:$USER .
```
3. **Update Docker Compose:**
```bash
# Update Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
#### Issue: Out of Disk Space
**Symptoms:**
- Build failures
- Container crashes
- Database errors
**Solutions:**
1. **Clean Docker Resources:**
```bash
# Remove unused containers, networks, images
docker system prune -a
# Remove unused volumes
docker volume prune
# Check disk usage
docker system df
```
2. **Configure Storage Location:**
```bash
# Edit docker-compose.yml to use external storage
volumes:
- /external/storage/data:/app/data
- /external/storage/models:/app/models
```
### Native Installation Problems
#### Issue: Python Dependencies Fail to Install
**Symptoms:**
- pip install errors
- Compilation failures
- Missing system libraries
**Solutions:**
1. **Install System Dependencies:**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y build-essential cmake python3-dev
sudo apt install -y libopencv-dev libffi-dev libssl-dev
# CentOS/RHEL
sudo yum groupinstall -y "Development Tools"
sudo yum install -y python3-devel opencv-devel
```
2. **Use Virtual Environment:**
```bash
# Create clean virtual environment
python3 -m venv venv_clean
source venv_clean/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
```
3. **Install PyTorch Separately:**
```bash
# Install PyTorch with specific CUDA version
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# Or CPU-only version
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
```
#### Issue: CUDA/GPU Setup Problems
**Symptoms:**
- GPU not detected
- CUDA version mismatch
- Out of GPU memory
**Solutions:**
1. **Verify CUDA Installation:**
```bash
# Check CUDA version
nvcc --version
nvidia-smi
# Check PyTorch CUDA support
python -c "import torch; print(torch.cuda.is_available())"
```
2. **Install Correct CUDA Version:**
```bash
# Install CUDA 11.8 (example)
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run
```
3. **Configure GPU Memory:**
```bash
# Set GPU memory limit
export CUDA_VISIBLE_DEVICES=0
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
```
## Hardware Problems
### Router Connectivity Issues
#### Issue: Cannot Connect to Router
**Symptoms:**
- No CSI data received
- Connection timeouts
- Authentication failures
**Solutions:**
1. **Verify Network Connectivity:**
```bash
# Ping router
ping 192.168.1.1
# Check SSH access
ssh root@192.168.1.1
# Test CSI port
telnet 192.168.1.1 5500
```
2. **Check Router Configuration:**
```bash
# SSH into router and check CSI tools
ssh root@192.168.1.1
csi_tool --status
# Restart CSI service
/etc/init.d/csi restart
```
3. **Verify Firewall Settings:**
```bash
# Check iptables rules
iptables -L
# Allow CSI port
iptables -A INPUT -p tcp --dport 5500 -j ACCEPT
```
#### Issue: Poor CSI Data Quality
**Symptoms:**
- High packet loss
- Inconsistent data rates
- Signal interference
**Solutions:**
1. **Optimize Router Placement:**
```bash
# Check signal strength
iwconfig wlan0
# Analyze interference
iwlist wlan0 scan | grep -E "(ESSID|Frequency|Quality)"
```
2. **Adjust CSI Parameters:**
```bash
# Reduce sampling rate
echo "csi_rate=20" >> /etc/config/wireless
# Change channel
echo "channel=6" >> /etc/config/wireless
uci commit wireless
wifi reload
```
3. **Monitor Data Quality:**
```bash
# Check CSI data statistics
curl http://localhost:8000/api/v1/hardware/csi/stats
# View real-time quality metrics
curl http://localhost:8000/api/v1/hardware/status
```
### Hardware Resource Issues
#### Issue: High CPU Usage
**Symptoms:**
- System slowdown
- Processing delays
- High temperature
**Solutions:**
1. **Optimize Processing Settings:**
```bash
# Reduce batch size
export POSE_PROCESSING_BATCH_SIZE=16
# Lower frame rate
export STREAM_FPS=15
# Disable unnecessary features
export ENABLE_HISTORICAL_DATA=false
```
2. **Scale Resources:**
```bash
# Increase worker processes
export WORKERS=4
# Use process affinity
taskset -c 0-3 python -m src.api.main
```
#### Issue: GPU Memory Errors
**Symptoms:**
- CUDA out of memory errors
- Model loading failures
- Inference crashes
**Solutions:**
1. **Optimize GPU Usage:**
```bash
# Reduce batch size
export POSE_PROCESSING_BATCH_SIZE=8
# Enable mixed precision
export ENABLE_MIXED_PRECISION=true
# Clear GPU cache
python -c "import torch; torch.cuda.empty_cache()"
```
2. **Monitor GPU Memory:**
```bash
# Watch GPU memory usage
watch -n 1 nvidia-smi
# Check memory allocation
python -c "
import torch
print(f'Allocated: {torch.cuda.memory_allocated()/1024**3:.2f} GB')
print(f'Cached: {torch.cuda.memory_reserved()/1024**3:.2f} GB')
"
```
## Performance Issues
### Slow Pose Detection
#### Issue: Low Processing Frame Rate
**Symptoms:**
- FPS below expected rate
- High latency
- Delayed responses
**Solutions:**
1. **Optimize Neural Network:**
```bash
# Use TensorRT optimization
export ENABLE_TENSORRT=true
# Enable model quantization
export MODEL_QUANTIZATION=int8
# Use smaller model variant
export POSE_MODEL_PATH="./models/densepose_mobile.pth"
```
2. **Tune Processing Pipeline:**
```bash
# Increase batch size (if GPU memory allows)
export POSE_PROCESSING_BATCH_SIZE=64
# Reduce input resolution
export INPUT_RESOLUTION=256
# Skip frames for real-time processing
export FRAME_SKIP_RATIO=2
```
3. **Parallel Processing:**
```bash
# Enable multi-threading
export OMP_NUM_THREADS=4
export MKL_NUM_THREADS=4
# Use multiple GPU devices
export CUDA_VISIBLE_DEVICES=0,1
```
### Memory Issues
#### Issue: High Memory Usage
**Symptoms:**
- System running out of RAM
- Swap usage increasing
- OOM killer activated
**Solutions:**
1. **Optimize Memory Usage:**
```bash
# Reduce buffer sizes
export CSI_BUFFER_SIZE=500
export STREAM_BUFFER_SIZE=50
# Limit historical data retention
export DATA_RETENTION_HOURS=24
# Enable memory mapping for large files
export USE_MEMORY_MAPPING=true
```
2. **Configure Swap:**
```bash
# Add swap space
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```
## API and Connectivity Issues
### Authentication Problems
#### Issue: JWT Token Errors
**Symptoms:**
- 401 Unauthorized responses
- Token expired errors
- Invalid signature errors
**Solutions:**
1. **Verify Token Configuration:**
```bash
# Check secret key
echo $SECRET_KEY
# Verify token expiration
curl -X POST http://localhost:8000/api/v1/auth/verify \
-H "Authorization: Bearer <token>"
```
2. **Regenerate Tokens:**
```bash
# Get new token
curl -X POST http://localhost:8000/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "password"}'
```
3. **Check System Time:**
```bash
# Ensure system time is correct
timedatectl status
sudo ntpdate -s time.nist.gov
```
### WebSocket Connection Issues
#### Issue: WebSocket Disconnections
**Symptoms:**
- Frequent disconnections
- Connection timeouts
- No real-time data
**Solutions:**
1. **Adjust WebSocket Settings:**
```bash
# Increase timeout values
export WEBSOCKET_TIMEOUT=600
export WEBSOCKET_PING_INTERVAL=30
# Enable keep-alive
export WEBSOCKET_KEEPALIVE=true
```
2. **Check Network Configuration:**
```bash
# Test WebSocket connection
wscat -c ws://localhost:8000/ws/pose
# Check proxy settings
curl -I http://localhost:8000/ws/pose
```
### Rate Limiting Issues
#### Issue: Rate Limit Exceeded
**Symptoms:**
- 429 Too Many Requests errors
- API calls being rejected
- Slow response times
**Solutions:**
1. **Adjust Rate Limits:**
```bash
# Increase rate limits
export RATE_LIMIT_REQUESTS=1000
export RATE_LIMIT_WINDOW=3600
# Disable rate limiting for development
export ENABLE_RATE_LIMITING=false
```
2. **Implement Request Batching:**
```python
# Batch multiple requests
def batch_requests(requests, batch_size=10):
for i in range(0, len(requests), batch_size):
batch = requests[i:i+batch_size]
# Process batch
time.sleep(1) # Rate limiting delay
```
## Data Quality Issues
### Poor Detection Accuracy
#### Issue: Low Confidence Scores
**Symptoms:**
- Many false positives
- Missing detections
- Inconsistent tracking
**Solutions:**
1. **Adjust Detection Thresholds:**
```bash
# Increase confidence threshold
curl -X PUT http://localhost:8000/api/v1/config \
-H "Content-Type: application/json" \
-d '{"detection": {"confidence_threshold": 0.8}}'
```
2. **Improve Environment Setup:**
```bash
# Recalibrate system
curl -X POST http://localhost:8000/api/v1/system/calibrate
# Check for interference
curl http://localhost:8000/api/v1/hardware/interference
```
3. **Optimize Model Parameters:**
```bash
# Use domain-specific model
export POSE_MODEL_PATH="./models/healthcare_optimized.pth"
# Enable post-processing filters
export ENABLE_TEMPORAL_SMOOTHING=true
export ENABLE_OUTLIER_FILTERING=true
```
### Tracking Issues
#### Issue: Person ID Switching
**Symptoms:**
- IDs change frequently
- Lost tracks
- Duplicate persons
**Solutions:**
1. **Tune Tracking Parameters:**
```bash
# Adjust tracking thresholds
curl -X PUT http://localhost:8000/api/v1/config \
-H "Content-Type: application/json" \
-d '{
"tracking": {
"max_age": 30,
"min_hits": 3,
"iou_threshold": 0.3
}
}'
```
2. **Improve Detection Consistency:**
```bash
# Enable temporal smoothing
export ENABLE_TEMPORAL_SMOOTHING=true
# Use appearance features
export USE_APPEARANCE_FEATURES=true
```
## System Errors
### Database Issues
#### Issue: Database Connection Errors
**Symptoms:**
- Connection refused errors
- Timeout errors
- Data not persisting
**Solutions:**
1. **Check Database Status:**
```bash
# PostgreSQL
sudo systemctl status postgresql
sudo -u postgres psql -c "SELECT version();"
# SQLite
ls -la ./data/wifi_densepose.db
sqlite3 ./data/wifi_densepose.db ".tables"
```
2. **Fix Connection Issues:**
```bash
# Reset database connection
export DATABASE_URL="postgresql://user:password@localhost:5432/wifi_densepose"
# Restart database service
sudo systemctl restart postgresql
```
3. **Database Migration:**
```bash
# Run database migrations
python -m src.database.migrate
# Reset database (WARNING: Data loss)
python -m src.database.reset --confirm
```
### Service Crashes
#### Issue: API Service Crashes
**Symptoms:**
- Service stops unexpectedly
- No response from API
- Error 502/503 responses
**Solutions:**
1. **Check Service Logs:**
```bash
# View crash logs
journalctl -u wifi-densepose -f
# Check for segmentation faults
dmesg | grep -i "segfault"
```
2. **Restart Services:**
```bash
# Restart with Docker
docker-compose restart wifi-densepose-api
# Restart native service
sudo systemctl restart wifi-densepose
```
3. **Debug Memory Issues:**
```bash
# Run with memory debugging
valgrind --tool=memcheck python -m src.api.main
# Check for memory leaks
python -m tracemalloc
```
## Domain-Specific Issues
### Healthcare Domain Issues
#### Issue: Fall Detection False Alarms
**Symptoms:**
- Too many fall alerts
- Normal activities triggering alerts
- Delayed detection
**Solutions:**
1. **Adjust Sensitivity:**
```bash
curl -X PUT http://localhost:8000/api/v1/config \
-H "Content-Type: application/json" \
-d '{
"alerts": {
"fall_detection": {
"sensitivity": 0.7,
"notification_delay_seconds": 10
}
}
}'
```
2. **Improve Training Data:**
```bash
# Collect domain-specific training data
python -m src.training.collect_healthcare_data
# Retrain model with healthcare data
python -m src.training.train_healthcare_model
```
### Retail Domain Issues
#### Issue: Inaccurate Traffic Counting
**Symptoms:**
- Wrong visitor counts
- Missing entries/exits
- Double counting
**Solutions:**
1. **Calibrate Zone Detection:**
```bash
# Define entrance/exit zones
curl -X PUT http://localhost:8000/api/v1/config \
-H "Content-Type: application/json" \
-d '{
"zones": {
"entrance": {
"coordinates": [[0, 0], [100, 50]],
"type": "entrance"
}
}
}'
```
2. **Optimize Tracking:**
```bash
# Enable zone-based tracking
export ENABLE_ZONE_TRACKING=true
# Adjust dwell time thresholds
export MIN_DWELL_TIME_SECONDS=5
```
## Advanced Troubleshooting
### Performance Profiling
#### CPU Profiling
```bash
# Profile Python code
python -m cProfile -o profile.stats -m src.api.main
# Analyze profile
python -c "
import pstats
p = pstats.Stats('profile.stats')
p.sort_stats('cumulative').print_stats(20)
"
```
#### GPU Profiling
```bash
# Profile CUDA kernels
nvprof python -m src.neural_network.inference
# Use PyTorch profiler
python -c "
import torch
with torch.profiler.profile() as prof:
# Your code here
pass
print(prof.key_averages().table())
"
```
### Network Debugging
#### Packet Capture
```bash
# Capture CSI packets
sudo tcpdump -i eth0 port 5500 -w csi_capture.pcap
# Analyze with Wireshark
wireshark csi_capture.pcap
```
#### Network Latency Testing
```bash
# Test network latency
ping -c 100 192.168.1.1 | tail -1
# Test bandwidth
iperf3 -c 192.168.1.1 -t 60
```
### System Monitoring
#### Real-time Monitoring
```bash
# Monitor system resources
htop
iotop
nethogs
# Monitor GPU
nvidia-smi -l 1
# Monitor Docker containers
docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
```
#### Log Aggregation
```bash
# Centralized logging with ELK stack
docker run -d --name elasticsearch elasticsearch:7.17.0
docker run -d --name kibana kibana:7.17.0
# Configure log shipping
echo 'LOGGING_DRIVER=syslog' >> .env
echo 'SYSLOG_ADDRESS=tcp://localhost:514' >> .env
```
## Getting Support
### Collecting Diagnostic Information
Before contacting support, collect the following information:
```bash
# System information
uname -a
cat /etc/os-release
docker --version
python --version
# Application logs
docker-compose logs --tail=1000 > logs.txt
# Configuration
cat .env > config.txt
curl http://localhost:8000/api/v1/system/status > status.json
# Hardware information
lscpu
free -h
nvidia-smi > gpu_info.txt
```
### Support Channels
1. **Documentation**: Check the comprehensive documentation first
2. **GitHub Issues**: Report bugs and feature requests
3. **Community Forum**: Ask questions and share solutions
4. **Enterprise Support**: For commercial deployments
### Creating Effective Bug Reports
Include the following information:
1. **Environment Details**:
- Operating system and version
- Hardware specifications
- Docker/Python versions
2. **Steps to Reproduce**:
- Exact commands or API calls
- Configuration settings
- Input data characteristics
3. **Expected vs Actual Behavior**:
- What you expected to happen
- What actually happened
- Error messages and logs
4. **Additional Context**:
- Screenshots or videos
- Configuration files
- System logs
### Emergency Procedures
For critical production issues:
1. **Immediate Actions**:
```bash
# Stop the system safely
curl -X POST http://localhost:8000/api/v1/system/stop
# Backup current data
cp -r ./data ./data_backup_$(date +%Y%m%d_%H%M%S)
# Restart with minimal configuration
export MOCK_HARDWARE=true
docker-compose up -d
```
2. **Rollback Procedures**:
```bash
# Rollback to previous version
git checkout <previous-tag>
docker-compose down
docker-compose up -d
# Restore data backup
rm -rf ./data
cp -r ./data_backup_<timestamp> ./data
```
3. **Contact Information**:
- Emergency support: support@wifi-densepose.com
- Phone: +1-555-SUPPORT
- Slack: #wifi-densepose-emergency
---
**Remember**: Most issues can be resolved by checking logs, verifying configuration, and ensuring proper hardware setup. When in doubt, start with the basic diagnostics and work your way through the troubleshooting steps systematically.
For additional help, see:
- [Configuration Guide](configuration.md)
- [API Reference](api-reference.md)
- [Hardware Setup Guide](../hardware/router-setup.md)
- [Deployment Guide](../developer/deployment-guide.md)

770
v1/docs/user_guide.md Normal file
View File

@@ -0,0 +1,770 @@
# WiFi-DensePose User Guide
## Table of Contents
1. [Overview](#overview)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Configuration](#configuration)
5. [Basic Usage](#basic-usage)
6. [Advanced Features](#advanced-features)
7. [Examples](#examples)
8. [Best Practices](#best-practices)
## Overview
WiFi-DensePose is a revolutionary privacy-preserving human pose estimation system that leverages Channel State Information (CSI) data from standard WiFi infrastructure. Unlike traditional camera-based systems, WiFi-DensePose provides real-time pose detection while maintaining complete privacy.
### Key Features
- **Privacy-First Design**: No cameras or visual data required
- **Real-Time Processing**: Sub-50ms latency with 30 FPS pose estimation
- **Multi-Person Tracking**: Simultaneous tracking of up to 10 individuals
- **Domain-Specific Optimization**: Tailored for healthcare, fitness, retail, and security
- **Enterprise-Ready**: Production-grade API with authentication and monitoring
- **Hardware Agnostic**: Works with standard WiFi routers and access points
### System Architecture
```
WiFi Routers → CSI Data → Signal Processing → Neural Network → Pose Estimation
↓ ↓ ↓ ↓ ↓
Hardware Data Collection Phase Cleaning DensePose Person Tracking
Interface & Buffering & Filtering Model & Analytics
```
## Installation
### Prerequisites
- **Python**: 3.9 or higher
- **Operating System**: Linux (Ubuntu 18.04+), macOS (10.15+), Windows 10+
- **Memory**: Minimum 4GB RAM, Recommended 8GB+
- **Storage**: 2GB free space for models and data
- **Network**: WiFi interface with CSI capability
### Method 1: Install from PyPI (Recommended)
```bash
# Install the latest stable version
pip install wifi-densepose
# Install with optional dependencies
pip install wifi-densepose[gpu,monitoring,deployment]
# Verify installation
wifi-densepose --version
```
### Method 2: Install from Source
```bash
# Clone the repository
git clone https://github.com/ruvnet/wifi-densepose.git
cd wifi-densepose
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install in development mode
pip install -e .
```
### Method 3: Docker Installation
```bash
# Pull the latest image
docker pull ruvnet/wifi-densepose:latest
# Run with default configuration
docker run -p 8000:8000 ruvnet/wifi-densepose:latest
# Run with custom configuration
docker run -p 8000:8000 -v $(pwd)/config:/app/config ruvnet/wifi-densepose:latest
```
### Verify Installation
```bash
# Check system information
python -c "import wifi_densepose; wifi_densepose.print_system_info()"
# Test API server
wifi-densepose start --test-mode
# Check health endpoint
curl http://localhost:8000/api/v1/health
```
## Quick Start
### 1. Basic Setup
```bash
# Create configuration file
wifi-densepose init
# Edit configuration (optional)
nano .env
# Start the system
wifi-densepose start
```
### 2. Python API Usage
```python
from wifi_densepose import WiFiDensePose
# Initialize with default configuration
system = WiFiDensePose()
# Start pose estimation
system.start()
# Get latest pose data
poses = system.get_latest_poses()
print(f"Detected {len(poses)} persons")
# Stop the system
system.stop()
```
### 3. REST API Usage
```bash
# Start the API server
wifi-densepose start --api
# Get latest poses
curl http://localhost:8000/api/v1/pose/latest
# Get system status
curl http://localhost:8000/api/v1/system/status
```
### 4. WebSocket Streaming
```python
import asyncio
import websockets
import json
async def stream_poses():
uri = "ws://localhost:8000/ws/pose/stream"
async with websockets.connect(uri) as websocket:
while True:
data = await websocket.recv()
poses = json.loads(data)
print(f"Received: {len(poses['persons'])} persons")
asyncio.run(stream_poses())
```
## Configuration
### Environment Variables
Create a `.env` file in your project directory:
```bash
# Application Settings
APP_NAME=WiFi-DensePose API
VERSION=1.0.0
ENVIRONMENT=production
DEBUG=false
# Server Settings
HOST=0.0.0.0
PORT=8000
WORKERS=4
# Security Settings
SECRET_KEY=your-secure-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=24
# Hardware Settings
WIFI_INTERFACE=wlan0
CSI_BUFFER_SIZE=1000
HARDWARE_POLLING_INTERVAL=0.1
# Pose Estimation Settings
POSE_CONFIDENCE_THRESHOLD=0.7
POSE_PROCESSING_BATCH_SIZE=32
POSE_MAX_PERSONS=10
# Feature Flags
ENABLE_AUTHENTICATION=true
ENABLE_RATE_LIMITING=true
ENABLE_WEBSOCKETS=true
ENABLE_REAL_TIME_PROCESSING=true
```
### Domain-Specific Configuration
#### Healthcare Configuration
```python
from wifi_densepose.config import Settings
config = Settings(
domain="healthcare",
detection={
"confidence_threshold": 0.8,
"max_persons": 5,
"enable_tracking": True
},
analytics={
"enable_fall_detection": True,
"enable_activity_recognition": True,
"alert_thresholds": {
"fall_confidence": 0.9,
"inactivity_timeout": 300
}
},
privacy={
"data_retention_days": 30,
"anonymize_data": True,
"enable_encryption": True
}
)
```
#### Fitness Configuration
```python
config = Settings(
domain="fitness",
detection={
"confidence_threshold": 0.6,
"max_persons": 20,
"enable_tracking": True
},
analytics={
"enable_activity_recognition": True,
"enable_form_analysis": True,
"metrics": ["rep_count", "form_score", "intensity"]
}
)
```
#### Retail Configuration
```python
config = Settings(
domain="retail",
detection={
"confidence_threshold": 0.7,
"max_persons": 50,
"enable_tracking": True
},
analytics={
"enable_traffic_analytics": True,
"enable_zone_tracking": True,
"heatmap_generation": True
}
)
```
## Basic Usage
### Starting the System
#### Command Line Interface
```bash
# Start with default configuration
wifi-densepose start
# Start with custom configuration
wifi-densepose start --config /path/to/config.yaml
# Start in development mode
wifi-densepose start --dev --reload
# Start with specific domain
wifi-densepose start --domain healthcare
# Start API server only
wifi-densepose start --api-only
```
#### Python API
```python
from wifi_densepose import WiFiDensePose
from wifi_densepose.config import Settings
# Initialize with custom settings
settings = Settings(
pose_confidence_threshold=0.8,
max_persons=5,
enable_gpu=True
)
system = WiFiDensePose(settings=settings)
# Start the system
system.start()
# Check if system is running
if system.is_running():
print("System is active")
# Get system status
status = system.get_status()
print(f"Status: {status}")
```
### Getting Pose Data
#### Latest Poses
```python
# Get the most recent pose data
poses = system.get_latest_poses()
for person in poses:
print(f"Person {person.id}:")
print(f" Confidence: {person.confidence}")
print(f" Keypoints: {len(person.keypoints)}")
print(f" Bounding box: {person.bbox}")
```
#### Historical Data
```python
from datetime import datetime, timedelta
# Get poses from the last hour
end_time = datetime.now()
start_time = end_time - timedelta(hours=1)
history = system.get_pose_history(
start_time=start_time,
end_time=end_time,
min_confidence=0.7
)
print(f"Found {len(history)} pose records")
```
#### Real-Time Streaming
```python
def pose_callback(poses):
"""Callback function for real-time pose updates"""
print(f"Received {len(poses)} poses at {datetime.now()}")
for person in poses:
if person.confidence > 0.8:
print(f"High-confidence detection: Person {person.id}")
# Subscribe to real-time updates
system.subscribe_to_poses(callback=pose_callback)
# Unsubscribe when done
system.unsubscribe_from_poses()
```
### System Control
#### Starting and Stopping
```python
# Start the pose estimation system
system.start()
# Pause processing (keeps connections alive)
system.pause()
# Resume processing
system.resume()
# Stop the system
system.stop()
# Restart with new configuration
system.restart(new_settings)
```
#### Configuration Updates
```python
# Update configuration at runtime
new_config = {
"detection": {
"confidence_threshold": 0.8,
"max_persons": 8
}
}
system.update_config(new_config)
# Get current configuration
current_config = system.get_config()
print(current_config)
```
## Advanced Features
### Multi-Environment Support
```python
# Configure multiple environments
environments = {
"room_001": {
"calibration_file": "/path/to/room_001_cal.json",
"router_ips": ["192.168.1.1", "192.168.1.2"]
},
"room_002": {
"calibration_file": "/path/to/room_002_cal.json",
"router_ips": ["192.168.2.1", "192.168.2.2"]
}
}
# Switch between environments
system.set_environment("room_001")
poses_room1 = system.get_latest_poses()
system.set_environment("room_002")
poses_room2 = system.get_latest_poses()
```
### Custom Analytics
```python
from wifi_densepose.analytics import AnalyticsEngine
# Initialize analytics engine
analytics = AnalyticsEngine(system)
# Enable fall detection
analytics.enable_fall_detection(
sensitivity=0.9,
callback=lambda event: print(f"Fall detected: {event}")
)
# Enable activity recognition
analytics.enable_activity_recognition(
activities=["sitting", "standing", "walking", "running"],
callback=lambda activity: print(f"Activity: {activity}")
)
# Custom analytics function
def custom_analytics(poses):
"""Custom analytics function"""
person_count = len(poses)
avg_confidence = sum(p.confidence for p in poses) / person_count if person_count > 0 else 0
return {
"person_count": person_count,
"average_confidence": avg_confidence,
"timestamp": datetime.now().isoformat()
}
analytics.add_custom_function(custom_analytics)
```
### Hardware Integration
```python
from wifi_densepose.hardware import RouterManager
# Configure router connections
router_manager = RouterManager()
# Add routers
router_manager.add_router(
ip="192.168.1.1",
username="admin",
password="password",
router_type="asus_ac68u"
)
# Check router status
status = router_manager.get_router_status("192.168.1.1")
print(f"Router status: {status}")
# Configure CSI extraction
router_manager.configure_csi_extraction(
router_ip="192.168.1.1",
extraction_rate=30,
target_ip="192.168.1.100",
target_port=5500
)
```
## Examples
### Example 1: Healthcare Monitoring
```python
from wifi_densepose import WiFiDensePose
from wifi_densepose.analytics import FallDetector
import logging
# Configure for healthcare
system = WiFiDensePose(domain="healthcare")
# Set up fall detection
fall_detector = FallDetector(
sensitivity=0.95,
alert_callback=lambda event: send_alert(event)
)
def send_alert(fall_event):
"""Send alert to healthcare staff"""
logging.critical(f"FALL DETECTED: {fall_event}")
# Send notification to staff
# notify_healthcare_staff(fall_event)
# Start monitoring
system.start()
system.add_analytics_module(fall_detector)
print("Healthcare monitoring active...")
```
### Example 2: Fitness Tracking
```python
from wifi_densepose import WiFiDensePose
from wifi_densepose.analytics import ActivityTracker
# Configure for fitness
system = WiFiDensePose(domain="fitness")
# Set up activity tracking
activity_tracker = ActivityTracker(
activities=["squats", "pushups", "jumping_jacks"],
rep_counting=True
)
def workout_callback(activity_data):
"""Handle workout data"""
print(f"Exercise: {activity_data['exercise']}")
print(f"Reps: {activity_data['rep_count']}")
print(f"Form score: {activity_data['form_score']}")
activity_tracker.set_callback(workout_callback)
# Start fitness tracking
system.start()
system.add_analytics_module(activity_tracker)
print("Fitness tracking active...")
```
### Example 3: Retail Analytics
```python
from wifi_densepose import WiFiDensePose
from wifi_densepose.analytics import TrafficAnalyzer
# Configure for retail
system = WiFiDensePose(domain="retail")
# Set up traffic analysis
traffic_analyzer = TrafficAnalyzer(
zones={
"entrance": {"x": 0, "y": 0, "width": 100, "height": 50},
"checkout": {"x": 200, "y": 150, "width": 100, "height": 50},
"electronics": {"x": 50, "y": 100, "width": 150, "height": 100}
}
)
def traffic_callback(traffic_data):
"""Handle traffic analytics"""
print(f"Zone occupancy: {traffic_data['zone_occupancy']}")
print(f"Traffic flow: {traffic_data['flow_patterns']}")
print(f"Dwell times: {traffic_data['dwell_times']}")
traffic_analyzer.set_callback(traffic_callback)
# Start retail analytics
system.start()
system.add_analytics_module(traffic_analyzer)
print("Retail analytics active...")
```
### Example 4: Security Monitoring
```python
from wifi_densepose import WiFiDensePose
from wifi_densepose.analytics import IntrusionDetector
# Configure for security
system = WiFiDensePose(domain="security")
# Set up intrusion detection
intrusion_detector = IntrusionDetector(
restricted_zones=[
{"x": 100, "y": 100, "width": 50, "height": 50, "name": "server_room"},
{"x": 200, "y": 50, "width": 75, "height": 75, "name": "executive_office"}
],
alert_threshold=0.9
)
def security_alert(intrusion_event):
"""Handle security alerts"""
logging.warning(f"INTRUSION DETECTED: {intrusion_event}")
# Trigger security response
# activate_security_protocol(intrusion_event)
intrusion_detector.set_alert_callback(security_alert)
# Start security monitoring
system.start()
system.add_analytics_module(intrusion_detector)
print("Security monitoring active...")
```
## Best Practices
### Performance Optimization
1. **Hardware Configuration**
```python
# Enable GPU acceleration when available
settings = Settings(
enable_gpu=True,
batch_size=64,
mixed_precision=True
)
```
2. **Memory Management**
```python
# Configure appropriate buffer sizes
settings = Settings(
csi_buffer_size=1000,
pose_history_limit=10000,
cleanup_interval=3600 # 1 hour
)
```
3. **Network Optimization**
```python
# Optimize network settings
settings = Settings(
hardware_polling_interval=0.05, # 50ms
network_timeout=5.0,
max_concurrent_connections=100
)
```
### Security Best Practices
1. **Authentication**
```python
# Enable authentication in production
settings = Settings(
enable_authentication=True,
jwt_secret_key="your-secure-secret-key",
jwt_expire_hours=24
)
```
2. **Rate Limiting**
```python
# Configure rate limiting
settings = Settings(
enable_rate_limiting=True,
rate_limit_requests=100,
rate_limit_window=60 # per minute
)
```
3. **Data Privacy**
```python
# Enable privacy features
settings = Settings(
anonymize_data=True,
data_retention_days=30,
enable_encryption=True
)
```
### Monitoring and Logging
1. **Structured Logging**
```python
import logging
from wifi_densepose.logger import setup_logging
# Configure structured logging
setup_logging(
level=logging.INFO,
format="json",
output_file="/var/log/wifi-densepose.log"
)
```
2. **Metrics Collection**
```python
from wifi_densepose.monitoring import MetricsCollector
# Enable metrics collection
metrics = MetricsCollector()
metrics.enable_prometheus_export(port=9090)
```
3. **Health Monitoring**
```python
# Set up health checks
system.enable_health_monitoring(
check_interval=30, # seconds
alert_on_failure=True
)
```
### Error Handling
1. **Graceful Degradation**
```python
try:
system.start()
except HardwareNotAvailableError:
# Fall back to mock mode
system.start(mock_mode=True)
logging.warning("Running in mock mode - no hardware detected")
```
2. **Retry Logic**
```python
from wifi_densepose.utils import retry_on_failure
@retry_on_failure(max_attempts=3, delay=5.0)
def connect_to_router():
return router_manager.connect("192.168.1.1")
```
3. **Circuit Breaker Pattern**
```python
from wifi_densepose.resilience import CircuitBreaker
# Protect against failing services
circuit_breaker = CircuitBreaker(
failure_threshold=5,
recovery_timeout=60
)
@circuit_breaker
def process_csi_data(data):
return csi_processor.process(data)
```
---
For more detailed information, see:
- [API Reference Guide](api_reference.md)
- [Deployment Guide](deployment.md)
- [Troubleshooting Guide](troubleshooting.md)