feat: Complete Rust port of WiFi-DensePose with modular crates
Major changes: - Organized Python v1 implementation into v1/ subdirectory - Created Rust workspace with 9 modular crates: - wifi-densepose-core: Core types, traits, errors - wifi-densepose-signal: CSI processing, phase sanitization, FFT - wifi-densepose-nn: Neural network inference (ONNX/Candle/tch) - wifi-densepose-api: Axum-based REST/WebSocket API - wifi-densepose-db: SQLx database layer - wifi-densepose-config: Configuration management - wifi-densepose-hardware: Hardware abstraction - wifi-densepose-wasm: WebAssembly bindings - wifi-densepose-cli: Command-line interface Documentation: - ADR-001: Workspace structure - ADR-002: Signal processing library selection - ADR-003: Neural network inference strategy - DDD domain model with bounded contexts Testing: - 69 tests passing across all crates - Signal processing: 45 tests - Neural networks: 21 tests - Core: 3 doc tests Performance targets: - 10x faster CSI processing (~0.5ms vs ~5ms) - 5x lower memory usage (~100MB vs ~500MB) - WASM support for browser deployment
This commit is contained in:
Claude
989
v1/docs/user-guide/api-reference.md
Normal file
989
v1/docs/user-guide/api-reference.md
Normal file
@@ -0,0 +1,989 @@
|
||||
# API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The WiFi-DensePose API provides comprehensive access to pose estimation data, system control, and configuration management through RESTful endpoints and real-time WebSocket connections.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Authentication](#authentication)
|
||||
2. [Base URL and Versioning](#base-url-and-versioning)
|
||||
3. [Pose Data Endpoints](#pose-data-endpoints)
|
||||
4. [System Control Endpoints](#system-control-endpoints)
|
||||
5. [Configuration Endpoints](#configuration-endpoints)
|
||||
6. [Analytics Endpoints](#analytics-endpoints)
|
||||
7. [WebSocket API](#websocket-api)
|
||||
8. [Error Handling](#error-handling)
|
||||
9. [Rate Limiting](#rate-limiting)
|
||||
10. [Code Examples](#code-examples)
|
||||
|
||||
## Authentication
|
||||
|
||||
### Bearer Token Authentication
|
||||
|
||||
All API endpoints require authentication using JWT Bearer tokens:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <your-jwt-token>
|
||||
```
|
||||
|
||||
### Obtaining a Token
|
||||
|
||||
```bash
|
||||
# Get authentication token
|
||||
curl -X POST http://localhost:8000/api/v1/auth/token \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "your-username",
|
||||
"password": "your-password"
|
||||
}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 86400
|
||||
}
|
||||
```
|
||||
|
||||
### API Key Authentication
|
||||
|
||||
For service-to-service communication:
|
||||
|
||||
```http
|
||||
X-API-Key: <your-api-key>
|
||||
```
|
||||
|
||||
## Base URL and Versioning
|
||||
|
||||
- **Base URL**: `http://localhost:8000/api/v1`
|
||||
- **Current Version**: v1
|
||||
- **Content-Type**: `application/json`
|
||||
|
||||
## Pose Data Endpoints
|
||||
|
||||
### Get Latest Pose Data
|
||||
|
||||
Retrieve the most recent pose estimation results.
|
||||
|
||||
**Endpoint:** `GET /pose/latest`
|
||||
|
||||
**Headers:**
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-01-07T04:46:32.123Z",
|
||||
"frame_id": 12345,
|
||||
"processing_time_ms": 45,
|
||||
"persons": [
|
||||
{
|
||||
"id": 1,
|
||||
"confidence": 0.87,
|
||||
"bounding_box": {
|
||||
"x": 120,
|
||||
"y": 80,
|
||||
"width": 200,
|
||||
"height": 400
|
||||
},
|
||||
"keypoints": [
|
||||
{
|
||||
"name": "nose",
|
||||
"x": 220,
|
||||
"y": 100,
|
||||
"confidence": 0.95,
|
||||
"visible": true
|
||||
},
|
||||
{
|
||||
"name": "left_shoulder",
|
||||
"x": 200,
|
||||
"y": 150,
|
||||
"confidence": 0.89,
|
||||
"visible": true
|
||||
}
|
||||
],
|
||||
"dense_pose": {
|
||||
"body_parts": [
|
||||
{
|
||||
"part_id": 1,
|
||||
"part_name": "torso",
|
||||
"uv_coordinates": [[0.5, 0.3], [0.6, 0.4]],
|
||||
"confidence": 0.89
|
||||
}
|
||||
]
|
||||
},
|
||||
"tracking_info": {
|
||||
"track_id": "track_001",
|
||||
"track_age": 150,
|
||||
"velocity": {"x": 0.1, "y": 0.05}
|
||||
}
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"environment_id": "room_001",
|
||||
"router_count": 3,
|
||||
"signal_quality": 0.82,
|
||||
"processing_pipeline": "standard"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes:**
|
||||
- `200 OK`: Success
|
||||
- `404 Not Found`: No pose data available
|
||||
- `401 Unauthorized`: Authentication required
|
||||
- `503 Service Unavailable`: System not initialized
|
||||
|
||||
### Get Historical Pose Data
|
||||
|
||||
Retrieve historical pose data with filtering options.
|
||||
|
||||
**Endpoint:** `GET /pose/history`
|
||||
|
||||
**Query Parameters:**
|
||||
- `start_time` (optional): ISO 8601 timestamp for range start
|
||||
- `end_time` (optional): ISO 8601 timestamp for range end
|
||||
- `limit` (optional): Maximum number of records (default: 100, max: 1000)
|
||||
- `person_id` (optional): Filter by specific person ID
|
||||
- `confidence_threshold` (optional): Minimum confidence score (0.0-1.0)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/pose/history?start_time=2025-01-07T00:00:00Z&limit=50&confidence_threshold=0.7" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"poses": [
|
||||
{
|
||||
"timestamp": "2025-01-07T04:46:32.123Z",
|
||||
"persons": [...],
|
||||
"metadata": {...}
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total_count": 1500,
|
||||
"returned_count": 50,
|
||||
"has_more": true,
|
||||
"next_cursor": "eyJpZCI6MTIzNDV9"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Query Pose Data
|
||||
|
||||
Execute complex queries on pose data with aggregation support.
|
||||
|
||||
**Endpoint:** `POST /pose/query`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"query": {
|
||||
"time_range": {
|
||||
"start": "2025-01-07T00:00:00Z",
|
||||
"end": "2025-01-07T23:59:59Z"
|
||||
},
|
||||
"filters": {
|
||||
"person_count": {"min": 1, "max": 5},
|
||||
"confidence": {"min": 0.7},
|
||||
"activity": ["walking", "standing"]
|
||||
},
|
||||
"aggregation": {
|
||||
"type": "hourly_summary",
|
||||
"metrics": ["person_count", "avg_confidence"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"timestamp": "2025-01-07T10:00:00Z",
|
||||
"person_count": 3,
|
||||
"avg_confidence": 0.85,
|
||||
"activities": {
|
||||
"walking": 0.6,
|
||||
"standing": 0.4
|
||||
}
|
||||
}
|
||||
],
|
||||
"query_metadata": {
|
||||
"execution_time_ms": 150,
|
||||
"total_records_scanned": 10000,
|
||||
"cache_hit": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## System Control Endpoints
|
||||
|
||||
### Get System Status
|
||||
|
||||
Get comprehensive system health and status information.
|
||||
|
||||
**Endpoint:** `GET /system/status`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"uptime_seconds": 86400,
|
||||
"version": "1.0.0",
|
||||
"components": {
|
||||
"csi_receiver": {
|
||||
"status": "active",
|
||||
"data_rate_hz": 25.3,
|
||||
"packet_loss_rate": 0.02,
|
||||
"last_packet_time": "2025-01-07T04:46:32Z"
|
||||
},
|
||||
"neural_network": {
|
||||
"status": "active",
|
||||
"model_loaded": true,
|
||||
"inference_time_ms": 45,
|
||||
"gpu_utilization": 0.65
|
||||
},
|
||||
"tracking": {
|
||||
"status": "active",
|
||||
"active_tracks": 2,
|
||||
"track_quality": 0.89
|
||||
}
|
||||
},
|
||||
"hardware": {
|
||||
"cpu_usage": 0.45,
|
||||
"memory_usage": 0.62,
|
||||
"gpu_memory_usage": 0.78,
|
||||
"disk_usage": 0.23
|
||||
},
|
||||
"network": {
|
||||
"connected_routers": 3,
|
||||
"signal_strength": -45,
|
||||
"interference_level": 0.15
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Start System
|
||||
|
||||
Start the pose estimation system with configuration options.
|
||||
|
||||
**Endpoint:** `POST /system/start`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"configuration": {
|
||||
"domain": "healthcare",
|
||||
"environment_id": "room_001",
|
||||
"calibration_required": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "starting",
|
||||
"estimated_ready_time": "2025-01-07T04:47:00Z",
|
||||
"initialization_steps": [
|
||||
{
|
||||
"step": "hardware_initialization",
|
||||
"status": "in_progress",
|
||||
"progress": 0.3
|
||||
},
|
||||
{
|
||||
"step": "model_loading",
|
||||
"status": "pending",
|
||||
"progress": 0.0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Stop System
|
||||
|
||||
Gracefully stop the pose estimation system.
|
||||
|
||||
**Endpoint:** `POST /system/stop`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"force": false,
|
||||
"save_state": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "stopping",
|
||||
"estimated_stop_time": "2025-01-07T04:47:30Z",
|
||||
"shutdown_steps": [
|
||||
{
|
||||
"step": "data_pipeline_stop",
|
||||
"status": "completed",
|
||||
"progress": 1.0
|
||||
},
|
||||
{
|
||||
"step": "model_unloading",
|
||||
"status": "in_progress",
|
||||
"progress": 0.7
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Endpoints
|
||||
|
||||
### Get Configuration
|
||||
|
||||
Retrieve current system configuration.
|
||||
|
||||
**Endpoint:** `GET /config`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"domain": "healthcare",
|
||||
"environment": {
|
||||
"id": "room_001",
|
||||
"name": "Patient Room 1",
|
||||
"calibration_timestamp": "2025-01-07T04:00:00Z"
|
||||
},
|
||||
"detection": {
|
||||
"confidence_threshold": 0.7,
|
||||
"max_persons": 5,
|
||||
"tracking_enabled": true
|
||||
},
|
||||
"alerts": {
|
||||
"fall_detection": {
|
||||
"enabled": true,
|
||||
"sensitivity": 0.8,
|
||||
"notification_delay_seconds": 5
|
||||
},
|
||||
"inactivity_detection": {
|
||||
"enabled": true,
|
||||
"threshold_minutes": 30
|
||||
}
|
||||
},
|
||||
"streaming": {
|
||||
"restream_enabled": false,
|
||||
"websocket_enabled": true,
|
||||
"mqtt_enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Update Configuration
|
||||
|
||||
Update system configuration with partial updates supported.
|
||||
|
||||
**Endpoint:** `PUT /config`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"detection": {
|
||||
"confidence_threshold": 0.75,
|
||||
"max_persons": 3
|
||||
},
|
||||
"alerts": {
|
||||
"fall_detection": {
|
||||
"sensitivity": 0.9
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "updated",
|
||||
"changes_applied": [
|
||||
"detection.confidence_threshold",
|
||||
"detection.max_persons",
|
||||
"alerts.fall_detection.sensitivity"
|
||||
],
|
||||
"restart_required": false,
|
||||
"validation_warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
## Analytics Endpoints
|
||||
|
||||
### Healthcare Analytics
|
||||
|
||||
Get healthcare-specific analytics and insights.
|
||||
|
||||
**Endpoint:** `GET /analytics/healthcare`
|
||||
|
||||
**Query Parameters:**
|
||||
- `period`: Time period (hour, day, week, month)
|
||||
- `metrics`: Comma-separated list of metrics
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/analytics/healthcare?period=day&metrics=fall_events,activity_summary" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"period": "day",
|
||||
"date": "2025-01-07",
|
||||
"metrics": {
|
||||
"fall_events": {
|
||||
"count": 2,
|
||||
"events": [
|
||||
{
|
||||
"timestamp": "2025-01-07T14:30:15Z",
|
||||
"person_id": 1,
|
||||
"severity": "moderate",
|
||||
"response_time_seconds": 45,
|
||||
"location": {"x": 150, "y": 200}
|
||||
}
|
||||
]
|
||||
},
|
||||
"activity_summary": {
|
||||
"walking_minutes": 120,
|
||||
"sitting_minutes": 480,
|
||||
"lying_minutes": 360,
|
||||
"standing_minutes": 180
|
||||
},
|
||||
"mobility_score": 0.75,
|
||||
"sleep_quality": {
|
||||
"total_sleep_hours": 7.5,
|
||||
"sleep_efficiency": 0.89,
|
||||
"restlessness_events": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Retail Analytics
|
||||
|
||||
Get retail-specific analytics and customer insights.
|
||||
|
||||
**Endpoint:** `GET /analytics/retail`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"period": "day",
|
||||
"date": "2025-01-07",
|
||||
"metrics": {
|
||||
"traffic": {
|
||||
"total_visitors": 245,
|
||||
"unique_visitors": 198,
|
||||
"peak_hour": "14:00",
|
||||
"peak_count": 15,
|
||||
"average_dwell_time_minutes": 12.5
|
||||
},
|
||||
"zones": [
|
||||
{
|
||||
"zone_id": "entrance",
|
||||
"zone_name": "Store Entrance",
|
||||
"visitor_count": 245,
|
||||
"avg_dwell_time_minutes": 2.1,
|
||||
"conversion_rate": 0.85
|
||||
},
|
||||
{
|
||||
"zone_id": "electronics",
|
||||
"zone_name": "Electronics Section",
|
||||
"visitor_count": 89,
|
||||
"avg_dwell_time_minutes": 8.7,
|
||||
"conversion_rate": 0.34
|
||||
}
|
||||
],
|
||||
"conversion_funnel": {
|
||||
"entrance": 245,
|
||||
"product_interaction": 156,
|
||||
"checkout_area": 89,
|
||||
"purchase": 67
|
||||
},
|
||||
"heat_map": {
|
||||
"high_traffic_areas": [
|
||||
{"zone": "entrance", "intensity": 0.95},
|
||||
{"zone": "checkout", "intensity": 0.78}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Security Analytics
|
||||
|
||||
Get security-specific analytics and threat assessments.
|
||||
|
||||
**Endpoint:** `GET /analytics/security`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"period": "day",
|
||||
"date": "2025-01-07",
|
||||
"metrics": {
|
||||
"intrusion_events": {
|
||||
"count": 1,
|
||||
"events": [
|
||||
{
|
||||
"timestamp": "2025-01-07T02:15:30Z",
|
||||
"zone": "restricted_area",
|
||||
"person_count": 1,
|
||||
"threat_level": "medium",
|
||||
"response_time_seconds": 120
|
||||
}
|
||||
]
|
||||
},
|
||||
"perimeter_monitoring": {
|
||||
"total_detections": 45,
|
||||
"authorized_entries": 42,
|
||||
"unauthorized_attempts": 3,
|
||||
"false_positives": 0
|
||||
},
|
||||
"crowd_analysis": {
|
||||
"max_occupancy": 12,
|
||||
"average_occupancy": 3.2,
|
||||
"crowd_formation_events": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## WebSocket API
|
||||
|
||||
### Connection
|
||||
|
||||
Connect to the WebSocket endpoint for real-time data streaming.
|
||||
|
||||
**Endpoint:** `ws://localhost:8000/ws/pose`
|
||||
|
||||
**Authentication:** Include token as query parameter or in headers:
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:8000/ws/pose?token=<your-jwt-token>');
|
||||
```
|
||||
|
||||
### Connection Establishment
|
||||
|
||||
**Server Message:**
|
||||
```json
|
||||
{
|
||||
"type": "connection_established",
|
||||
"client_id": "client_12345",
|
||||
"server_time": "2025-01-07T04:46:32Z",
|
||||
"supported_protocols": ["pose_v1", "alerts_v1"]
|
||||
}
|
||||
```
|
||||
|
||||
### Subscription Management
|
||||
|
||||
**Subscribe to Pose Updates:**
|
||||
```json
|
||||
{
|
||||
"type": "subscribe",
|
||||
"channel": "pose_updates",
|
||||
"filters": {
|
||||
"min_confidence": 0.7,
|
||||
"person_ids": [1, 2, 3],
|
||||
"include_keypoints": true,
|
||||
"include_dense_pose": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Subscription Confirmation:**
|
||||
```json
|
||||
{
|
||||
"type": "subscription_confirmed",
|
||||
"channel": "pose_updates",
|
||||
"subscription_id": "sub_67890",
|
||||
"filters_applied": {
|
||||
"min_confidence": 0.7,
|
||||
"person_ids": [1, 2, 3]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Real-Time Data Streaming
|
||||
|
||||
**Pose Update Message:**
|
||||
```json
|
||||
{
|
||||
"type": "pose_update",
|
||||
"subscription_id": "sub_67890",
|
||||
"timestamp": "2025-01-07T04:46:32.123Z",
|
||||
"data": {
|
||||
"frame_id": 12345,
|
||||
"persons": [...],
|
||||
"metadata": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**System Status Update:**
|
||||
```json
|
||||
{
|
||||
"type": "system_status",
|
||||
"timestamp": "2025-01-07T04:46:32Z",
|
||||
"status": {
|
||||
"processing_fps": 25.3,
|
||||
"active_persons": 2,
|
||||
"system_health": "good",
|
||||
"gpu_utilization": 0.65
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Alert Streaming
|
||||
|
||||
**Subscribe to Alerts:**
|
||||
```json
|
||||
{
|
||||
"type": "subscribe",
|
||||
"channel": "alerts",
|
||||
"filters": {
|
||||
"alert_types": ["fall_detection", "intrusion"],
|
||||
"severity": ["high", "critical"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Alert Message:**
|
||||
```json
|
||||
{
|
||||
"type": "alert",
|
||||
"alert_id": "alert_12345",
|
||||
"timestamp": "2025-01-07T04:46:32Z",
|
||||
"alert_type": "fall_detection",
|
||||
"severity": "high",
|
||||
"data": {
|
||||
"person_id": 1,
|
||||
"location": {"x": 220, "y": 180},
|
||||
"confidence": 0.92,
|
||||
"video_clip_url": "/clips/fall_12345.mp4"
|
||||
},
|
||||
"actions_required": ["medical_response", "notification"]
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Standard Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "POSE_DATA_NOT_FOUND",
|
||||
"message": "No pose data available for the specified time range",
|
||||
"details": {
|
||||
"requested_range": {
|
||||
"start": "2025-01-07T00:00:00Z",
|
||||
"end": "2025-01-07T01:00:00Z"
|
||||
},
|
||||
"available_range": {
|
||||
"start": "2025-01-07T02:00:00Z",
|
||||
"end": "2025-01-07T04:46:32Z"
|
||||
}
|
||||
},
|
||||
"timestamp": "2025-01-07T04:46:32Z",
|
||||
"request_id": "req_12345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### HTTP Status Codes
|
||||
|
||||
#### Success Codes
|
||||
- `200 OK`: Request successful
|
||||
- `201 Created`: Resource created successfully
|
||||
- `202 Accepted`: Request accepted for processing
|
||||
- `204 No Content`: Request successful, no content returned
|
||||
|
||||
#### Client Error Codes
|
||||
- `400 Bad Request`: Invalid request format or parameters
|
||||
- `401 Unauthorized`: Authentication required or invalid
|
||||
- `403 Forbidden`: Insufficient permissions
|
||||
- `404 Not Found`: Resource not found
|
||||
- `409 Conflict`: Resource conflict (e.g., system already running)
|
||||
- `422 Unprocessable Entity`: Validation errors
|
||||
- `429 Too Many Requests`: Rate limit exceeded
|
||||
|
||||
#### Server Error Codes
|
||||
- `500 Internal Server Error`: Unexpected server error
|
||||
- `502 Bad Gateway`: Upstream service error
|
||||
- `503 Service Unavailable`: System not ready or overloaded
|
||||
- `504 Gateway Timeout`: Request timeout
|
||||
|
||||
### Validation Error Response
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Request validation failed",
|
||||
"details": {
|
||||
"field_errors": [
|
||||
{
|
||||
"field": "confidence_threshold",
|
||||
"message": "Value must be between 0.0 and 1.0",
|
||||
"received_value": 1.5
|
||||
},
|
||||
{
|
||||
"field": "max_persons",
|
||||
"message": "Value must be a positive integer",
|
||||
"received_value": -1
|
||||
}
|
||||
]
|
||||
},
|
||||
"timestamp": "2025-01-07T04:46:32Z",
|
||||
"request_id": "req_12346"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Rate Limit Headers
|
||||
|
||||
All responses include rate limiting information:
|
||||
|
||||
```http
|
||||
X-RateLimit-Limit: 1000
|
||||
X-RateLimit-Remaining: 999
|
||||
X-RateLimit-Reset: 1704686400
|
||||
X-RateLimit-Window: 3600
|
||||
```
|
||||
|
||||
### Rate Limits by Endpoint Type
|
||||
|
||||
- **REST API**: 1000 requests per hour per API key
|
||||
- **WebSocket**: 100 connections per IP address
|
||||
- **Streaming**: 10 concurrent streams per account
|
||||
- **Webhook**: 10,000 events per hour per endpoint
|
||||
|
||||
### Rate Limit Exceeded Response
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RATE_LIMIT_EXCEEDED",
|
||||
"message": "Rate limit exceeded. Try again later.",
|
||||
"details": {
|
||||
"limit": 1000,
|
||||
"window_seconds": 3600,
|
||||
"reset_time": "2025-01-07T05:46:32Z"
|
||||
},
|
||||
"timestamp": "2025-01-07T04:46:32Z",
|
||||
"request_id": "req_12347"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Code Examples
|
||||
|
||||
### Python Example
|
||||
|
||||
```python
|
||||
import requests
|
||||
import json
|
||||
from datetime import datetime, timedelta
|
||||
|
||||
class WiFiDensePoseClient:
|
||||
def __init__(self, base_url, token):
|
||||
self.base_url = base_url
|
||||
self.headers = {
|
||||
'Authorization': f'Bearer {token}',
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
|
||||
def get_latest_pose(self):
|
||||
"""Get the latest pose data."""
|
||||
response = requests.get(
|
||||
f'{self.base_url}/pose/latest',
|
||||
headers=self.headers
|
||||
)
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
|
||||
def get_historical_poses(self, start_time=None, end_time=None, limit=100):
|
||||
"""Get historical pose data."""
|
||||
params = {'limit': limit}
|
||||
if start_time:
|
||||
params['start_time'] = start_time.isoformat()
|
||||
if end_time:
|
||||
params['end_time'] = end_time.isoformat()
|
||||
|
||||
response = requests.get(
|
||||
f'{self.base_url}/pose/history',
|
||||
headers=self.headers,
|
||||
params=params
|
||||
)
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
|
||||
def start_system(self, domain='general', environment_id='default'):
|
||||
"""Start the pose estimation system."""
|
||||
data = {
|
||||
'configuration': {
|
||||
'domain': domain,
|
||||
'environment_id': environment_id,
|
||||
'calibration_required': True
|
||||
}
|
||||
}
|
||||
response = requests.post(
|
||||
f'{self.base_url}/system/start',
|
||||
headers=self.headers,
|
||||
json=data
|
||||
)
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
|
||||
# Usage example
|
||||
client = WiFiDensePoseClient('http://localhost:8000/api/v1', 'your-token')
|
||||
|
||||
# Get latest pose data
|
||||
latest = client.get_latest_pose()
|
||||
print(f"Found {len(latest['persons'])} persons")
|
||||
|
||||
# Get historical data for the last hour
|
||||
end_time = datetime.now()
|
||||
start_time = end_time - timedelta(hours=1)
|
||||
history = client.get_historical_poses(start_time, end_time)
|
||||
print(f"Retrieved {len(history['poses'])} historical records")
|
||||
```
|
||||
|
||||
### JavaScript Example
|
||||
|
||||
```javascript
|
||||
class WiFiDensePoseClient {
|
||||
constructor(baseUrl, token) {
|
||||
this.baseUrl = baseUrl;
|
||||
this.headers = {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json'
|
||||
};
|
||||
}
|
||||
|
||||
async getLatestPose() {
|
||||
const response = await fetch(`${this.baseUrl}/pose/latest`, {
|
||||
headers: this.headers
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP error! status: ${response.status}`);
|
||||
}
|
||||
|
||||
return await response.json();
|
||||
}
|
||||
|
||||
async updateConfiguration(config) {
|
||||
const response = await fetch(`${this.baseUrl}/config`, {
|
||||
method: 'PUT',
|
||||
headers: this.headers,
|
||||
body: JSON.stringify(config)
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP error! status: ${response.status}`);
|
||||
}
|
||||
|
||||
return await response.json();
|
||||
}
|
||||
|
||||
connectWebSocket() {
|
||||
const ws = new WebSocket(`ws://localhost:8000/ws/pose?token=${this.token}`);
|
||||
|
||||
ws.onopen = () => {
|
||||
console.log('WebSocket connected');
|
||||
// Subscribe to pose updates
|
||||
ws.send(JSON.stringify({
|
||||
type: 'subscribe',
|
||||
channel: 'pose_updates',
|
||||
filters: {
|
||||
min_confidence: 0.7
|
||||
}
|
||||
}));
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Received:', data);
|
||||
};
|
||||
|
||||
ws.onerror = (error) => {
|
||||
console.error('WebSocket error:', error);
|
||||
};
|
||||
|
||||
return ws;
|
||||
}
|
||||
}
|
||||
|
||||
// Usage example
|
||||
const client = new WiFiDensePoseClient('http://localhost:8000/api/v1', 'your-token');
|
||||
|
||||
// Get latest pose data
|
||||
client.getLatestPose()
|
||||
.then(data => console.log('Latest pose:', data))
|
||||
.catch(error => console.error('Error:', error));
|
||||
|
||||
// Connect to WebSocket for real-time updates
|
||||
const ws = client.connectWebSocket();
|
||||
```
|
||||
|
||||
### cURL Examples
|
||||
|
||||
```bash
|
||||
# Get authentication token
|
||||
curl -X POST http://localhost:8000/api/v1/auth/token \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "password"}'
|
||||
|
||||
# Get latest pose data
|
||||
curl http://localhost:8000/api/v1/pose/latest \
|
||||
-H "Authorization: Bearer <token>"
|
||||
|
||||
# Start system
|
||||
curl -X POST http://localhost:8000/api/v1/system/start \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"configuration": {
|
||||
"domain": "healthcare",
|
||||
"environment_id": "room_001"
|
||||
}
|
||||
}'
|
||||
|
||||
# Update configuration
|
||||
curl -X PUT http://localhost:8000/api/v1/config \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"detection": {
|
||||
"confidence_threshold": 0.8
|
||||
}
|
||||
}'
|
||||
|
||||
# Get healthcare analytics
|
||||
curl "http://localhost:8000/api/v1/analytics/healthcare?period=day" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
For more detailed information, see:
|
||||
- [Getting Started Guide](getting-started.md)
|
||||
- [Configuration Guide](configuration.md)
|
||||
- [WebSocket API Documentation](../api/websocket-api.md)
|
||||
- [Authentication Guide](../api/authentication.md)
|
||||
722
v1/docs/user-guide/configuration.md
Normal file
722
v1/docs/user-guide/configuration.md
Normal file
@@ -0,0 +1,722 @@
|
||||
# Configuration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers comprehensive configuration options for the WiFi-DensePose system, including domain-specific settings, hardware configuration, performance tuning, and security settings.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Configuration Files](#configuration-files)
|
||||
2. [Environment Variables](#environment-variables)
|
||||
3. [Domain-Specific Configuration](#domain-specific-configuration)
|
||||
4. [Hardware Configuration](#hardware-configuration)
|
||||
5. [Performance Tuning](#performance-tuning)
|
||||
6. [Security Configuration](#security-configuration)
|
||||
7. [Integration Settings](#integration-settings)
|
||||
8. [Monitoring and Logging](#monitoring-and-logging)
|
||||
9. [Advanced Configuration](#advanced-configuration)
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Primary Configuration File
|
||||
|
||||
The system uses environment variables and configuration files for settings management:
|
||||
|
||||
```bash
|
||||
# Main configuration file
|
||||
.env
|
||||
|
||||
# Domain-specific configurations
|
||||
config/domains/healthcare.yaml
|
||||
config/domains/retail.yaml
|
||||
config/domains/security.yaml
|
||||
|
||||
# Hardware configurations
|
||||
config/hardware/routers.yaml
|
||||
config/hardware/processing.yaml
|
||||
```
|
||||
|
||||
### Configuration Hierarchy
|
||||
|
||||
Configuration is loaded in the following order (later values override earlier ones):
|
||||
|
||||
1. Default values in [`src/config/settings.py`](../../src/config/settings.py)
|
||||
2. Environment-specific configuration files
|
||||
3. `.env` file
|
||||
4. Environment variables
|
||||
5. Command-line arguments
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Application Settings
|
||||
|
||||
```bash
|
||||
# Basic application settings
|
||||
APP_NAME="WiFi-DensePose API"
|
||||
VERSION="1.0.0"
|
||||
ENVIRONMENT="development" # development, staging, production
|
||||
DEBUG=false
|
||||
|
||||
# Server configuration
|
||||
HOST="0.0.0.0"
|
||||
PORT=8000
|
||||
RELOAD=false
|
||||
WORKERS=1
|
||||
```
|
||||
|
||||
### Security Settings
|
||||
|
||||
```bash
|
||||
# JWT Configuration
|
||||
SECRET_KEY="your-super-secret-key-change-in-production"
|
||||
JWT_ALGORITHM="HS256"
|
||||
JWT_EXPIRE_HOURS=24
|
||||
|
||||
# CORS and Host Settings
|
||||
ALLOWED_HOSTS="localhost,127.0.0.1,your-domain.com"
|
||||
CORS_ORIGINS="http://localhost:3000,https://your-frontend.com"
|
||||
|
||||
# Rate Limiting
|
||||
RATE_LIMIT_REQUESTS=100
|
||||
RATE_LIMIT_AUTHENTICATED_REQUESTS=1000
|
||||
RATE_LIMIT_WINDOW=3600 # seconds
|
||||
```
|
||||
|
||||
### Database Configuration
|
||||
|
||||
```bash
|
||||
# Database Settings
|
||||
DATABASE_URL="postgresql://user:password@localhost:5432/wifi_densepose"
|
||||
DATABASE_POOL_SIZE=10
|
||||
DATABASE_MAX_OVERFLOW=20
|
||||
|
||||
# Redis Configuration
|
||||
REDIS_URL="redis://localhost:6379/0"
|
||||
REDIS_PASSWORD=""
|
||||
REDIS_DB=0
|
||||
```
|
||||
|
||||
### Hardware Settings
|
||||
|
||||
```bash
|
||||
# WiFi Interface
|
||||
WIFI_INTERFACE="wlan0"
|
||||
CSI_BUFFER_SIZE=1000
|
||||
HARDWARE_POLLING_INTERVAL=0.1
|
||||
|
||||
# Development/Testing
|
||||
MOCK_HARDWARE=false
|
||||
MOCK_POSE_DATA=false
|
||||
```
|
||||
|
||||
### Pose Estimation Settings
|
||||
|
||||
```bash
|
||||
# Model Configuration
|
||||
POSE_MODEL_PATH="./models/densepose_model.pth"
|
||||
POSE_CONFIDENCE_THRESHOLD=0.5
|
||||
POSE_PROCESSING_BATCH_SIZE=32
|
||||
POSE_MAX_PERSONS=10
|
||||
|
||||
# Streaming Settings
|
||||
STREAM_FPS=30
|
||||
STREAM_BUFFER_SIZE=100
|
||||
WEBSOCKET_PING_INTERVAL=60
|
||||
WEBSOCKET_TIMEOUT=300
|
||||
```
|
||||
|
||||
### Storage Settings
|
||||
|
||||
```bash
|
||||
# Storage Paths
|
||||
DATA_STORAGE_PATH="./data"
|
||||
MODEL_STORAGE_PATH="./models"
|
||||
TEMP_STORAGE_PATH="./temp"
|
||||
MAX_STORAGE_SIZE_GB=100
|
||||
```
|
||||
|
||||
### Feature Flags
|
||||
|
||||
```bash
|
||||
# Feature Toggles
|
||||
ENABLE_AUTHENTICATION=true
|
||||
ENABLE_RATE_LIMITING=true
|
||||
ENABLE_WEBSOCKETS=true
|
||||
ENABLE_HISTORICAL_DATA=true
|
||||
ENABLE_REAL_TIME_PROCESSING=true
|
||||
ENABLE_TEST_ENDPOINTS=false
|
||||
```
|
||||
|
||||
## Domain-Specific Configuration
|
||||
|
||||
### Healthcare Domain
|
||||
|
||||
Healthcare deployments require enhanced privacy and accuracy settings:
|
||||
|
||||
```yaml
|
||||
# config/domains/healthcare.yaml
|
||||
domain: healthcare
|
||||
description: "Healthcare monitoring and patient safety"
|
||||
|
||||
detection:
|
||||
confidence_threshold: 0.8
|
||||
max_persons: 3
|
||||
tracking_enabled: true
|
||||
privacy_mode: true
|
||||
|
||||
alerts:
|
||||
fall_detection:
|
||||
enabled: true
|
||||
sensitivity: 0.9
|
||||
notification_delay_seconds: 5
|
||||
emergency_contacts:
|
||||
- "nurse-station@hospital.com"
|
||||
- "+1-555-0123"
|
||||
|
||||
inactivity_detection:
|
||||
enabled: true
|
||||
threshold_minutes: 30
|
||||
alert_levels: ["warning", "critical"]
|
||||
|
||||
vital_signs_monitoring:
|
||||
enabled: true
|
||||
heart_rate_estimation: true
|
||||
breathing_pattern_analysis: true
|
||||
|
||||
privacy:
|
||||
data_retention_days: 30
|
||||
anonymization_enabled: true
|
||||
audit_logging: true
|
||||
hipaa_compliance: true
|
||||
|
||||
notifications:
|
||||
webhook_urls:
|
||||
- "https://hospital-system.com/api/alerts"
|
||||
mqtt_topics:
|
||||
- "hospital/room/{room_id}/alerts"
|
||||
email_alerts: true
|
||||
```
|
||||
|
||||
### Retail Domain
|
||||
|
||||
Retail deployments focus on customer analytics and traffic patterns:
|
||||
|
||||
```yaml
|
||||
# config/domains/retail.yaml
|
||||
domain: retail
|
||||
description: "Retail analytics and customer insights"
|
||||
|
||||
detection:
|
||||
confidence_threshold: 0.7
|
||||
max_persons: 15
|
||||
tracking_enabled: true
|
||||
zone_detection: true
|
||||
|
||||
analytics:
|
||||
traffic_counting:
|
||||
enabled: true
|
||||
entrance_zones: ["entrance", "exit"]
|
||||
dwell_time_tracking: true
|
||||
|
||||
heat_mapping:
|
||||
enabled: true
|
||||
zone_definitions:
|
||||
- name: "entrance"
|
||||
coordinates: [[0, 0], [100, 50]]
|
||||
- name: "electronics"
|
||||
coordinates: [[100, 0], [200, 100]]
|
||||
- name: "checkout"
|
||||
coordinates: [[200, 0], [300, 50]]
|
||||
|
||||
conversion_tracking:
|
||||
enabled: true
|
||||
interaction_threshold_seconds: 10
|
||||
purchase_correlation: true
|
||||
|
||||
privacy:
|
||||
data_retention_days: 90
|
||||
anonymization_enabled: true
|
||||
gdpr_compliance: true
|
||||
|
||||
reporting:
|
||||
daily_reports: true
|
||||
weekly_summaries: true
|
||||
real_time_dashboard: true
|
||||
```
|
||||
|
||||
### Security Domain
|
||||
|
||||
Security deployments prioritize intrusion detection and perimeter monitoring:
|
||||
|
||||
```yaml
|
||||
# config/domains/security.yaml
|
||||
domain: security
|
||||
description: "Security monitoring and intrusion detection"
|
||||
|
||||
detection:
|
||||
confidence_threshold: 0.9
|
||||
max_persons: 10
|
||||
tracking_enabled: true
|
||||
motion_sensitivity: 0.95
|
||||
|
||||
security:
|
||||
intrusion_detection:
|
||||
enabled: true
|
||||
restricted_zones:
|
||||
- name: "secure_area"
|
||||
coordinates: [[50, 50], [150, 150]]
|
||||
alert_immediately: true
|
||||
- name: "perimeter"
|
||||
coordinates: [[0, 0], [300, 300]]
|
||||
alert_delay_seconds: 10
|
||||
|
||||
unauthorized_access:
|
||||
enabled: true
|
||||
authorized_persons: [] # Empty for general detection
|
||||
time_restrictions:
|
||||
- days: ["monday", "tuesday", "wednesday", "thursday", "friday"]
|
||||
hours: ["09:00", "17:00"]
|
||||
|
||||
threat_assessment:
|
||||
enabled: true
|
||||
aggressive_behavior_detection: true
|
||||
crowd_formation_detection: true
|
||||
|
||||
alerts:
|
||||
immediate_notification: true
|
||||
escalation_levels:
|
||||
- level: 1
|
||||
delay_seconds: 0
|
||||
contacts: ["security@company.com"]
|
||||
- level: 2
|
||||
delay_seconds: 30
|
||||
contacts: ["security@company.com", "manager@company.com"]
|
||||
- level: 3
|
||||
delay_seconds: 60
|
||||
contacts: ["security@company.com", "manager@company.com", "emergency@company.com"]
|
||||
|
||||
integration:
|
||||
security_system_api: "https://security-system.com/api"
|
||||
camera_system_integration: true
|
||||
access_control_integration: true
|
||||
```
|
||||
|
||||
## Hardware Configuration
|
||||
|
||||
### Router Configuration
|
||||
|
||||
```yaml
|
||||
# config/hardware/routers.yaml
|
||||
routers:
|
||||
- id: "router_001"
|
||||
type: "atheros"
|
||||
model: "TP-Link Archer C7"
|
||||
ip_address: "192.168.1.1"
|
||||
mac_address: "aa:bb:cc:dd:ee:01"
|
||||
location:
|
||||
room: "living_room"
|
||||
coordinates: [0, 0, 2.5] # x, y, z in meters
|
||||
csi_config:
|
||||
sampling_rate: 30 # Hz
|
||||
antenna_count: 3
|
||||
subcarrier_count: 56
|
||||
data_port: 5500
|
||||
|
||||
- id: "router_002"
|
||||
type: "atheros"
|
||||
model: "Netgear Nighthawk"
|
||||
ip_address: "192.168.1.2"
|
||||
mac_address: "aa:bb:cc:dd:ee:02"
|
||||
location:
|
||||
room: "living_room"
|
||||
coordinates: [5, 0, 2.5]
|
||||
csi_config:
|
||||
sampling_rate: 30
|
||||
antenna_count: 3
|
||||
subcarrier_count: 56
|
||||
data_port: 5501
|
||||
|
||||
network:
|
||||
csi_data_interface: "eth0"
|
||||
buffer_size: 1000
|
||||
timeout_seconds: 5
|
||||
retry_attempts: 3
|
||||
```
|
||||
|
||||
### Processing Hardware Configuration
|
||||
|
||||
```yaml
|
||||
# config/hardware/processing.yaml
|
||||
processing:
|
||||
cpu:
|
||||
cores: 8
|
||||
threads_per_core: 2
|
||||
optimization: "performance" # performance, balanced, power_save
|
||||
|
||||
memory:
|
||||
total_gb: 16
|
||||
allocation:
|
||||
csi_processing: 4
|
||||
neural_network: 8
|
||||
api_services: 2
|
||||
system_overhead: 2
|
||||
|
||||
gpu:
|
||||
enabled: true
|
||||
device_id: 0
|
||||
memory_gb: 8
|
||||
cuda_version: "11.8"
|
||||
optimization:
|
||||
batch_size: 32
|
||||
mixed_precision: true
|
||||
tensor_cores: true
|
||||
|
||||
storage:
|
||||
data_drive:
|
||||
path: "/data"
|
||||
type: "ssd"
|
||||
size_gb: 500
|
||||
|
||||
model_drive:
|
||||
path: "/models"
|
||||
type: "ssd"
|
||||
size_gb: 100
|
||||
|
||||
temp_drive:
|
||||
path: "/tmp"
|
||||
type: "ram"
|
||||
size_gb: 8
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Processing Pipeline Optimization
|
||||
|
||||
```bash
|
||||
# Neural Network Settings
|
||||
POSE_PROCESSING_BATCH_SIZE=32 # Adjust based on GPU memory
|
||||
POSE_CONFIDENCE_THRESHOLD=0.7 # Higher = fewer false positives
|
||||
POSE_MAX_PERSONS=5 # Limit for performance
|
||||
|
||||
# Streaming Optimization
|
||||
STREAM_FPS=30 # Reduce for lower bandwidth
|
||||
STREAM_BUFFER_SIZE=100 # Increase for smoother streaming
|
||||
WEBSOCKET_PING_INTERVAL=60 # Connection keep-alive
|
||||
|
||||
# Database Optimization
|
||||
DATABASE_POOL_SIZE=20 # Increase for high concurrency
|
||||
DATABASE_MAX_OVERFLOW=40 # Additional connections when needed
|
||||
|
||||
# Caching Settings
|
||||
REDIS_URL="redis://localhost:6379/0"
|
||||
CACHE_TTL_SECONDS=300 # Cache expiration time
|
||||
```
|
||||
|
||||
### Resource Allocation
|
||||
|
||||
```yaml
|
||||
# docker-compose.override.yml
|
||||
version: '3.8'
|
||||
services:
|
||||
wifi-densepose-api:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '4.0'
|
||||
memory: 8G
|
||||
reservations:
|
||||
cpus: '2.0'
|
||||
memory: 4G
|
||||
environment:
|
||||
- WORKERS=4
|
||||
- POSE_PROCESSING_BATCH_SIZE=64
|
||||
|
||||
neural-network:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '2.0'
|
||||
memory: 6G
|
||||
reservations:
|
||||
cpus: '1.0'
|
||||
memory: 4G
|
||||
runtime: nvidia
|
||||
environment:
|
||||
- CUDA_VISIBLE_DEVICES=0
|
||||
```
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
```bash
|
||||
# Enable performance monitoring
|
||||
PERFORMANCE_MONITORING=true
|
||||
METRICS_ENABLED=true
|
||||
HEALTH_CHECK_INTERVAL=30
|
||||
|
||||
# Logging for performance analysis
|
||||
LOG_LEVEL="INFO"
|
||||
LOG_PERFORMANCE_METRICS=true
|
||||
LOG_SLOW_QUERIES=true
|
||||
SLOW_QUERY_THRESHOLD_MS=1000
|
||||
```
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### Authentication and Authorization
|
||||
|
||||
```bash
|
||||
# JWT Configuration
|
||||
SECRET_KEY="$(openssl rand -base64 32)" # Generate secure key
|
||||
JWT_ALGORITHM="HS256"
|
||||
JWT_EXPIRE_HOURS=8 # Shorter expiration for production
|
||||
|
||||
# API Key Configuration
|
||||
API_KEY_LENGTH=32
|
||||
API_KEY_EXPIRY_DAYS=90
|
||||
API_KEY_ROTATION_ENABLED=true
|
||||
```
|
||||
|
||||
### Network Security
|
||||
|
||||
```bash
|
||||
# HTTPS Configuration
|
||||
ENABLE_HTTPS=true
|
||||
SSL_CERT_PATH="/etc/ssl/certs/wifi-densepose.crt"
|
||||
SSL_KEY_PATH="/etc/ssl/private/wifi-densepose.key"
|
||||
|
||||
# Firewall Settings
|
||||
ALLOWED_IPS="192.168.1.0/24,10.0.0.0/8"
|
||||
BLOCKED_IPS=""
|
||||
RATE_LIMIT_ENABLED=true
|
||||
```
|
||||
|
||||
### Data Protection
|
||||
|
||||
```bash
|
||||
# Encryption Settings
|
||||
DATABASE_ENCRYPTION=true
|
||||
DATA_AT_REST_ENCRYPTION=true
|
||||
BACKUP_ENCRYPTION=true
|
||||
|
||||
# Privacy Settings
|
||||
ANONYMIZATION_ENABLED=true
|
||||
DATA_RETENTION_DAYS=30
|
||||
AUDIT_LOGGING=true
|
||||
GDPR_COMPLIANCE=true
|
||||
```
|
||||
|
||||
## Integration Settings
|
||||
|
||||
### MQTT Configuration
|
||||
|
||||
```bash
|
||||
# MQTT Broker Settings
|
||||
MQTT_BROKER_HOST="localhost"
|
||||
MQTT_BROKER_PORT=1883
|
||||
MQTT_USERNAME="wifi_densepose"
|
||||
MQTT_PASSWORD="secure_password"
|
||||
MQTT_TLS_ENABLED=true
|
||||
|
||||
# Topic Configuration
|
||||
MQTT_TOPIC_PREFIX="wifi-densepose"
|
||||
MQTT_QOS_LEVEL=1
|
||||
MQTT_RETAIN_MESSAGES=false
|
||||
```
|
||||
|
||||
### Webhook Configuration
|
||||
|
||||
```bash
|
||||
# Webhook Settings
|
||||
WEBHOOK_TIMEOUT_SECONDS=30
|
||||
WEBHOOK_RETRY_ATTEMPTS=3
|
||||
WEBHOOK_RETRY_DELAY_SECONDS=5
|
||||
|
||||
# Security
|
||||
WEBHOOK_SIGNATURE_ENABLED=true
|
||||
WEBHOOK_SECRET_KEY="webhook_secret_key"
|
||||
```
|
||||
|
||||
### External API Integration
|
||||
|
||||
```bash
|
||||
# Restream Integration
|
||||
RESTREAM_API_KEY="your_restream_api_key"
|
||||
RESTREAM_ENABLED=false
|
||||
RESTREAM_PLATFORMS="youtube,twitch"
|
||||
|
||||
# Third-party APIs
|
||||
EXTERNAL_API_TIMEOUT=30
|
||||
EXTERNAL_API_RETRY_ATTEMPTS=3
|
||||
```
|
||||
|
||||
## Monitoring and Logging
|
||||
|
||||
### Logging Configuration
|
||||
|
||||
```bash
|
||||
# Log Levels
|
||||
LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL
|
||||
LOG_FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
|
||||
|
||||
# Log Files
|
||||
LOG_FILE="/var/log/wifi-densepose/app.log"
|
||||
LOG_MAX_SIZE=10485760 # 10MB
|
||||
LOG_BACKUP_COUNT=5
|
||||
|
||||
# Structured Logging
|
||||
LOG_JSON_FORMAT=true
|
||||
LOG_CORRELATION_ID=true
|
||||
```
|
||||
|
||||
### Metrics and Monitoring
|
||||
|
||||
```bash
|
||||
# Prometheus Metrics
|
||||
METRICS_ENABLED=true
|
||||
METRICS_PORT=9090
|
||||
METRICS_PATH="/metrics"
|
||||
|
||||
# Health Checks
|
||||
HEALTH_CHECK_INTERVAL=30
|
||||
HEALTH_CHECK_TIMEOUT=10
|
||||
DEEP_HEALTH_CHECKS=true
|
||||
|
||||
# Performance Monitoring
|
||||
PERFORMANCE_MONITORING=true
|
||||
SLOW_QUERY_LOGGING=true
|
||||
RESOURCE_MONITORING=true
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Custom Model Configuration
|
||||
|
||||
```yaml
|
||||
# config/models/custom_model.yaml
|
||||
model:
|
||||
name: "custom_densepose_v2"
|
||||
path: "./models/custom_densepose_v2.pth"
|
||||
type: "pytorch"
|
||||
|
||||
preprocessing:
|
||||
input_size: [256, 256]
|
||||
normalization:
|
||||
mean: [0.485, 0.456, 0.406]
|
||||
std: [0.229, 0.224, 0.225]
|
||||
|
||||
inference:
|
||||
batch_size: 32
|
||||
device: "cuda:0"
|
||||
precision: "fp16" # fp32, fp16, int8
|
||||
|
||||
postprocessing:
|
||||
confidence_threshold: 0.7
|
||||
nms_threshold: 0.5
|
||||
max_detections: 10
|
||||
```
|
||||
|
||||
### Environment-Specific Overrides
|
||||
|
||||
```bash
|
||||
# config/environments/production.env
|
||||
ENVIRONMENT=production
|
||||
DEBUG=false
|
||||
LOG_LEVEL=WARNING
|
||||
WORKERS=8
|
||||
POSE_PROCESSING_BATCH_SIZE=64
|
||||
ENABLE_TEST_ENDPOINTS=false
|
||||
MOCK_HARDWARE=false
|
||||
```
|
||||
|
||||
```bash
|
||||
# config/environments/development.env
|
||||
ENVIRONMENT=development
|
||||
DEBUG=true
|
||||
LOG_LEVEL=DEBUG
|
||||
WORKERS=1
|
||||
RELOAD=true
|
||||
MOCK_HARDWARE=true
|
||||
ENABLE_TEST_ENDPOINTS=true
|
||||
```
|
||||
|
||||
### Configuration Validation
|
||||
|
||||
The system automatically validates configuration on startup:
|
||||
|
||||
```bash
|
||||
# Run configuration validation
|
||||
python -m src.config.validate
|
||||
|
||||
# Check specific configuration
|
||||
python -c "
|
||||
from src.config.settings import get_settings, validate_settings
|
||||
settings = get_settings()
|
||||
issues = validate_settings(settings)
|
||||
if issues:
|
||||
print('Configuration issues:')
|
||||
for issue in issues:
|
||||
print(f' - {issue}')
|
||||
else:
|
||||
print('Configuration is valid')
|
||||
"
|
||||
```
|
||||
|
||||
### Dynamic Configuration Updates
|
||||
|
||||
Some settings can be updated without restarting the system:
|
||||
|
||||
```bash
|
||||
# Update detection settings
|
||||
curl -X PUT http://localhost:8000/api/v1/config \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"detection": {
|
||||
"confidence_threshold": 0.8,
|
||||
"max_persons": 3
|
||||
}
|
||||
}'
|
||||
|
||||
# Update alert settings
|
||||
curl -X PUT http://localhost:8000/api/v1/config \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"alerts": {
|
||||
"fall_detection": {
|
||||
"sensitivity": 0.9
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Configuration Best Practices
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
1. **Use Strong Secret Keys**: Generate cryptographically secure keys
|
||||
2. **Restrict CORS Origins**: Don't use wildcards in production
|
||||
3. **Enable Rate Limiting**: Protect against abuse
|
||||
4. **Use HTTPS**: Encrypt all communications
|
||||
5. **Regular Key Rotation**: Rotate API keys and JWT secrets
|
||||
|
||||
### Performance Best Practices
|
||||
|
||||
1. **Right-size Resources**: Allocate appropriate CPU/memory
|
||||
2. **Use GPU Acceleration**: Enable CUDA for neural network processing
|
||||
3. **Optimize Batch Sizes**: Balance throughput and latency
|
||||
4. **Configure Caching**: Use Redis for frequently accessed data
|
||||
5. **Monitor Resource Usage**: Set up alerts for resource exhaustion
|
||||
|
||||
### Operational Best Practices
|
||||
|
||||
1. **Environment Separation**: Use different configs for dev/staging/prod
|
||||
2. **Configuration Validation**: Validate settings before deployment
|
||||
3. **Backup Configurations**: Version control all configuration files
|
||||
4. **Document Changes**: Maintain change logs for configuration updates
|
||||
5. **Test Configuration**: Validate configuration in staging environment
|
||||
|
||||
---
|
||||
|
||||
For more specific configuration examples, see:
|
||||
- [Hardware Setup Guide](../hardware/router-setup.md)
|
||||
- [API Reference](api-reference.md)
|
||||
- [Deployment Guide](../developer/deployment-guide.md)
|
||||
501
v1/docs/user-guide/getting-started.md
Normal file
501
v1/docs/user-guide/getting-started.md
Normal file
@@ -0,0 +1,501 @@
|
||||
# Getting Started with WiFi-DensePose
|
||||
|
||||
## Overview
|
||||
|
||||
WiFi-DensePose is a revolutionary privacy-preserving human pose estimation system that transforms commodity WiFi infrastructure into a powerful human sensing platform. This guide will help you install, configure, and start using the system.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [System Requirements](#system-requirements)
|
||||
2. [Installation](#installation)
|
||||
3. [Quick Start](#quick-start)
|
||||
4. [Basic Configuration](#basic-configuration)
|
||||
5. [First Pose Detection](#first-pose-detection)
|
||||
6. [Troubleshooting](#troubleshooting)
|
||||
7. [Next Steps](#next-steps)
|
||||
|
||||
## System Requirements
|
||||
|
||||
### Hardware Requirements
|
||||
|
||||
#### WiFi Router Requirements
|
||||
- **Compatible Hardware**: Atheros-based routers (TP-Link Archer series, Netgear Nighthawk), Intel 5300 NIC-based systems, or ASUS RT-AC68U series
|
||||
- **Antenna Configuration**: Minimum 3×3 MIMO antenna configuration
|
||||
- **Frequency Bands**: 2.4GHz and 5GHz support
|
||||
- **Firmware**: OpenWRT firmware compatibility with CSI extraction patches
|
||||
|
||||
#### Processing Hardware
|
||||
- **CPU**: Multi-core processor (4+ cores recommended)
|
||||
- **RAM**: 8GB minimum, 16GB recommended
|
||||
- **Storage**: 50GB available space
|
||||
- **Network**: Gigabit Ethernet for CSI data streams
|
||||
- **GPU** (Optional): NVIDIA GPU with CUDA capability and 4GB+ memory for real-time processing
|
||||
|
||||
### Software Requirements
|
||||
|
||||
#### Operating System
|
||||
- **Primary**: Linux (Ubuntu 20.04+, CentOS 8+)
|
||||
- **Secondary**: Windows 10/11 with WSL2
|
||||
- **Container**: Docker support for deployment
|
||||
|
||||
#### Runtime Dependencies
|
||||
- Python 3.8+
|
||||
- PyTorch (GPU-accelerated recommended)
|
||||
- OpenCV
|
||||
- FFmpeg
|
||||
- FastAPI
|
||||
|
||||
## Installation
|
||||
|
||||
### Method 1: Docker Installation (Recommended)
|
||||
|
||||
#### Prerequisites
|
||||
```bash
|
||||
# Install Docker and Docker Compose
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Install Docker Compose
|
||||
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
|
||||
sudo chmod +x /usr/local/bin/docker-compose
|
||||
```
|
||||
|
||||
#### Download and Setup
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-org/wifi-densepose.git
|
||||
cd wifi-densepose
|
||||
|
||||
# Copy environment configuration
|
||||
cp .env.example .env
|
||||
|
||||
# Edit configuration (see Configuration section)
|
||||
nano .env
|
||||
|
||||
# Start the system
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Method 2: Native Installation
|
||||
|
||||
#### Install System Dependencies
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update
|
||||
sudo apt install -y python3.9 python3.9-pip python3.9-venv
|
||||
sudo apt install -y build-essential cmake
|
||||
sudo apt install -y libopencv-dev ffmpeg
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum update
|
||||
sudo yum install -y python39 python39-pip
|
||||
sudo yum groupinstall -y "Development Tools"
|
||||
sudo yum install -y opencv-devel ffmpeg
|
||||
```
|
||||
|
||||
#### Install Python Dependencies
|
||||
```bash
|
||||
# Create virtual environment
|
||||
python3.9 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# Install requirements
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Install PyTorch with CUDA support (if GPU available)
|
||||
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
|
||||
```
|
||||
|
||||
#### Install WiFi-DensePose
|
||||
```bash
|
||||
# Install in development mode
|
||||
pip install -e .
|
||||
|
||||
# Or install from PyPI (when available)
|
||||
pip install wifi-densepose
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Environment Configuration
|
||||
|
||||
Create and configure your environment file:
|
||||
|
||||
```bash
|
||||
# Copy the example configuration
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit the `.env` file with your settings:
|
||||
|
||||
```bash
|
||||
# Application settings
|
||||
APP_NAME="WiFi-DensePose API"
|
||||
VERSION="1.0.0"
|
||||
ENVIRONMENT="development"
|
||||
DEBUG=true
|
||||
|
||||
# Server settings
|
||||
HOST="0.0.0.0"
|
||||
PORT=8000
|
||||
|
||||
# Security settings (CHANGE IN PRODUCTION!)
|
||||
SECRET_KEY="your-secret-key-here"
|
||||
JWT_EXPIRE_HOURS=24
|
||||
|
||||
# Hardware settings
|
||||
WIFI_INTERFACE="wlan0"
|
||||
CSI_BUFFER_SIZE=1000
|
||||
MOCK_HARDWARE=true # Set to false when using real hardware
|
||||
|
||||
# Pose estimation settings
|
||||
POSE_CONFIDENCE_THRESHOLD=0.5
|
||||
POSE_MAX_PERSONS=5
|
||||
|
||||
# Storage settings
|
||||
DATA_STORAGE_PATH="./data"
|
||||
MODEL_STORAGE_PATH="./models"
|
||||
```
|
||||
|
||||
### 2. Start the System
|
||||
|
||||
#### Using Docker
|
||||
```bash
|
||||
# Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# Check service status
|
||||
docker-compose ps
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
#### Using Native Installation
|
||||
```bash
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Start the API server
|
||||
python -m src.api.main
|
||||
|
||||
# Or use uvicorn directly
|
||||
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload
|
||||
```
|
||||
|
||||
### 3. Verify Installation
|
||||
|
||||
Check that the system is running:
|
||||
|
||||
```bash
|
||||
# Check API health
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# Expected response:
|
||||
# {"status": "healthy", "timestamp": "2025-01-07T10:00:00Z"}
|
||||
```
|
||||
|
||||
Access the web interface:
|
||||
- **API Documentation**: http://localhost:8000/docs
|
||||
- **Alternative Docs**: http://localhost:8000/redoc
|
||||
- **Health Check**: http://localhost:8000/health
|
||||
|
||||
## Basic Configuration
|
||||
|
||||
### Domain Configuration
|
||||
|
||||
WiFi-DensePose supports different domain-specific configurations:
|
||||
|
||||
#### Healthcare Domain
|
||||
```bash
|
||||
# Set healthcare-specific settings
|
||||
export DOMAIN="healthcare"
|
||||
export POSE_CONFIDENCE_THRESHOLD=0.8
|
||||
export ENABLE_FALL_DETECTION=true
|
||||
export ALERT_SENSITIVITY=0.9
|
||||
```
|
||||
|
||||
#### Retail Domain
|
||||
```bash
|
||||
# Set retail-specific settings
|
||||
export DOMAIN="retail"
|
||||
export POSE_CONFIDENCE_THRESHOLD=0.7
|
||||
export ENABLE_TRAFFIC_ANALYTICS=true
|
||||
export ZONE_TRACKING=true
|
||||
```
|
||||
|
||||
#### Security Domain
|
||||
```bash
|
||||
# Set security-specific settings
|
||||
export DOMAIN="security"
|
||||
export POSE_CONFIDENCE_THRESHOLD=0.9
|
||||
export ENABLE_INTRUSION_DETECTION=true
|
||||
export ALERT_IMMEDIATE=true
|
||||
```
|
||||
|
||||
### Router Configuration
|
||||
|
||||
#### Configure WiFi Routers for CSI Extraction
|
||||
|
||||
1. **Flash OpenWRT Firmware**:
|
||||
```bash
|
||||
# Download OpenWRT firmware for your router model
|
||||
wget https://downloads.openwrt.org/releases/22.03.0/targets/...
|
||||
|
||||
# Flash firmware (router-specific process)
|
||||
# Follow your router's flashing instructions
|
||||
```
|
||||
|
||||
2. **Install CSI Extraction Patches**:
|
||||
```bash
|
||||
# SSH into router
|
||||
ssh root@192.168.1.1
|
||||
|
||||
# Install CSI tools
|
||||
opkg update
|
||||
opkg install csi-tools
|
||||
|
||||
# Configure CSI extraction
|
||||
echo "csi_enable=1" >> /etc/config/wireless
|
||||
echo "csi_rate=30" >> /etc/config/wireless
|
||||
```
|
||||
|
||||
3. **Configure Network Settings**:
|
||||
```bash
|
||||
# Set router to monitor mode
|
||||
iwconfig wlan0 mode monitor
|
||||
|
||||
# Start CSI data streaming
|
||||
csi_tool -i wlan0 -d 192.168.1.100 -p 5500
|
||||
```
|
||||
|
||||
### Database Configuration
|
||||
|
||||
#### SQLite (Development)
|
||||
```bash
|
||||
# Default SQLite database (no additional configuration needed)
|
||||
DATABASE_URL="sqlite:///./data/wifi_densepose.db"
|
||||
```
|
||||
|
||||
#### PostgreSQL (Production)
|
||||
```bash
|
||||
# Install PostgreSQL with TimescaleDB extension
|
||||
sudo apt install postgresql-14 postgresql-14-timescaledb
|
||||
|
||||
# Configure database
|
||||
DATABASE_URL="postgresql://user:password@localhost:5432/wifi_densepose"
|
||||
DATABASE_POOL_SIZE=10
|
||||
DATABASE_MAX_OVERFLOW=20
|
||||
```
|
||||
|
||||
#### Redis (Caching)
|
||||
```bash
|
||||
# Install Redis
|
||||
sudo apt install redis-server
|
||||
|
||||
# Configure Redis
|
||||
REDIS_URL="redis://localhost:6379/0"
|
||||
REDIS_PASSWORD="" # Set password for production
|
||||
```
|
||||
|
||||
## First Pose Detection
|
||||
|
||||
### 1. Start the System
|
||||
|
||||
```bash
|
||||
# Using Docker
|
||||
docker-compose up -d
|
||||
|
||||
# Using native installation
|
||||
python -m src.api.main
|
||||
```
|
||||
|
||||
### 2. Initialize Hardware
|
||||
|
||||
```bash
|
||||
# Check system status
|
||||
curl http://localhost:8000/api/v1/system/status
|
||||
|
||||
# Start pose estimation system
|
||||
curl -X POST http://localhost:8000/api/v1/system/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"configuration": {
|
||||
"domain": "general",
|
||||
"environment_id": "room_001",
|
||||
"calibration_required": true
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. Get Pose Data
|
||||
|
||||
#### REST API
|
||||
```bash
|
||||
# Get latest pose data
|
||||
curl http://localhost:8000/api/v1/pose/latest
|
||||
|
||||
# Get historical data
|
||||
curl "http://localhost:8000/api/v1/pose/history?limit=10"
|
||||
```
|
||||
|
||||
#### WebSocket Streaming
|
||||
```javascript
|
||||
// Connect to WebSocket
|
||||
const ws = new WebSocket('ws://localhost:8000/ws/pose');
|
||||
|
||||
// Subscribe to pose updates
|
||||
ws.onopen = function() {
|
||||
ws.send(JSON.stringify({
|
||||
type: 'subscribe',
|
||||
channel: 'pose_updates',
|
||||
filters: {
|
||||
min_confidence: 0.7
|
||||
}
|
||||
}));
|
||||
};
|
||||
|
||||
// Handle pose data
|
||||
ws.onmessage = function(event) {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Pose data:', data);
|
||||
};
|
||||
```
|
||||
|
||||
### 4. View Results
|
||||
|
||||
Access the web dashboard:
|
||||
- **Main Dashboard**: http://localhost:8000/dashboard
|
||||
- **Real-time View**: http://localhost:8000/dashboard/live
|
||||
- **Analytics**: http://localhost:8000/dashboard/analytics
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. System Won't Start
|
||||
```bash
|
||||
# Check logs
|
||||
docker-compose logs
|
||||
|
||||
# Common solutions:
|
||||
# - Verify port 8000 is available
|
||||
# - Check environment variables
|
||||
# - Ensure sufficient disk space
|
||||
```
|
||||
|
||||
#### 2. No Pose Data
|
||||
```bash
|
||||
# Check hardware status
|
||||
curl http://localhost:8000/api/v1/system/status
|
||||
|
||||
# Verify router connectivity
|
||||
ping 192.168.1.1
|
||||
|
||||
# Check CSI data reception
|
||||
netstat -an | grep 5500
|
||||
```
|
||||
|
||||
#### 3. Poor Detection Accuracy
|
||||
```bash
|
||||
# Adjust confidence threshold
|
||||
curl -X PUT http://localhost:8000/api/v1/config \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"detection": {"confidence_threshold": 0.6}}'
|
||||
|
||||
# Recalibrate environment
|
||||
curl -X POST http://localhost:8000/api/v1/system/calibrate
|
||||
```
|
||||
|
||||
#### 4. High CPU/Memory Usage
|
||||
```bash
|
||||
# Check resource usage
|
||||
docker stats
|
||||
|
||||
# Optimize settings
|
||||
export POSE_PROCESSING_BATCH_SIZE=16
|
||||
export STREAM_FPS=15
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
#### Log Analysis
|
||||
```bash
|
||||
# View application logs
|
||||
docker-compose logs wifi-densepose-api
|
||||
|
||||
# View system logs
|
||||
journalctl -u wifi-densepose
|
||||
|
||||
# Enable debug logging
|
||||
export LOG_LEVEL="DEBUG"
|
||||
```
|
||||
|
||||
#### Health Checks
|
||||
```bash
|
||||
# Comprehensive system check
|
||||
curl http://localhost:8000/api/v1/system/status
|
||||
|
||||
# Component-specific checks
|
||||
curl http://localhost:8000/api/v1/hardware/status
|
||||
curl http://localhost:8000/api/v1/processing/status
|
||||
```
|
||||
|
||||
#### Support Resources
|
||||
- **Documentation**: [docs/](../README.md)
|
||||
- **API Reference**: [api-reference.md](api-reference.md)
|
||||
- **Troubleshooting Guide**: [troubleshooting.md](troubleshooting.md)
|
||||
- **GitHub Issues**: https://github.com/your-org/wifi-densepose/issues
|
||||
|
||||
## Next Steps
|
||||
|
||||
### 1. Configure for Your Domain
|
||||
- Review [configuration.md](configuration.md) for domain-specific settings
|
||||
- Set up alerts and notifications
|
||||
- Configure external integrations
|
||||
|
||||
### 2. Integrate with Your Applications
|
||||
- Review [API Reference](api-reference.md)
|
||||
- Set up webhooks for events
|
||||
- Configure MQTT for IoT integration
|
||||
|
||||
### 3. Deploy to Production
|
||||
- Review [deployment guide](../developer/deployment-guide.md)
|
||||
- Set up monitoring and alerting
|
||||
- Configure backup and recovery
|
||||
|
||||
### 4. Optimize Performance
|
||||
- Tune processing parameters
|
||||
- Set up GPU acceleration
|
||||
- Configure load balancing
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Development Environment
|
||||
- Use strong secret keys
|
||||
- Enable authentication
|
||||
- Restrict network access
|
||||
|
||||
### Production Environment
|
||||
- Use HTTPS/TLS encryption
|
||||
- Configure firewall rules
|
||||
- Set up audit logging
|
||||
- Regular security updates
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Hardware Optimization
|
||||
- Use SSD storage for better I/O performance
|
||||
- Ensure adequate cooling for continuous operation
|
||||
- Use dedicated network interface for CSI data
|
||||
|
||||
### Software Optimization
|
||||
- Enable GPU acceleration when available
|
||||
- Tune batch sizes for your hardware
|
||||
- Configure appropriate worker processes
|
||||
- Use Redis for caching frequently accessed data
|
||||
|
||||
---
|
||||
|
||||
**Congratulations!** You now have WiFi-DensePose up and running. Continue with the [Configuration Guide](configuration.md) to customize the system for your specific needs.
|
||||
948
v1/docs/user-guide/troubleshooting.md
Normal file
948
v1/docs/user-guide/troubleshooting.md
Normal 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)
|
||||
Reference in New Issue
Block a user