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

updates

Browse Source
This commit is contained in:
rUv
2025-06-07 11:44:19 +00:00
parent 43e92c5494
commit c378b705ca
95 changed files with 43677 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

992
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
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).

484
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
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
docs/developer/contributing.md Normal file
View File

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

610
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.

989
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
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
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
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)