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