Files

Alireza Vaezi fc2da16728 Chore: rename api->camera-management-api and web->management-dashboard-web-app; update compose, ignore, README references

2025-08-07 22:07:25 -04:00

21 KiB

Raw Blame History

🚀 USDA Vision Camera System - Complete API Documentation

This document provides comprehensive documentation for all API endpoints in the USDA Vision Camera System, including recent enhancements and new features.

🔧 System Status & Health

Get System Status

GET /system/status

Response: SystemStatusResponse

{
  "system_started": true,
  "mqtt_connected": true,
  "last_mqtt_message": "2024-01-15T10:30:00Z",
  "machines": {
    "vibratory_conveyor": {
      "name": "vibratory_conveyor",
      "state": "ON",
      "last_updated": "2024-01-15T10:30:00Z"
    }
  },
  "cameras": {
    "camera1": {
      "name": "camera1",
      "status": "ACTIVE",
      "is_recording": false,
      "auto_recording_enabled": true
    }
  },
  "active_recordings": 0,
  "total_recordings": 15,
  "uptime_seconds": 3600.5
}

Health Check

GET /health

Response: Simple health status

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}

📷 Camera Management

Get All Cameras

GET /cameras

Response: Dict[str, CameraStatusResponse]

Get Specific Camera Status

GET /cameras/{camera_name}/status

Response: CameraStatusResponse

{
  "name": "camera1",
  "status": "ACTIVE",
  "is_recording": false,
  "last_checked": "2024-01-15T10:30:00Z",
  "last_error": null,
  "device_info": {
    "model": "GigE Camera",
    "serial": "12345"
  },
  "current_recording_file": null,
  "recording_start_time": null,
  "auto_recording_enabled": true,
  "auto_recording_active": false,
  "auto_recording_failure_count": 0,
  "auto_recording_last_attempt": null,
  "auto_recording_last_error": null
}

🎥 Recording Control

Start Recording

POST /cameras/{camera_name}/start-recording
Content-Type: application/json

{
  "filename": "test_recording.avi",
  "exposure_ms": 2.0,
  "gain": 4.0,
  "fps": 5.0
}

Request Model: StartRecordingRequest

filename (optional): Custom filename (datetime prefix will be added automatically)
exposure_ms (optional): Exposure time in milliseconds
gain (optional): Camera gain value
fps (optional): Target frames per second

Response: StartRecordingResponse

{
  "success": true,
  "message": "Recording started for camera1",
  "filename": "20240115_103000_test_recording.avi"
}

Key Features:

✅ Automatic datetime prefix: All filenames get YYYYMMDD_HHMMSS_ prefix
✅ Dynamic camera settings: Adjust exposure, gain, and FPS per recording
✅ Backward compatibility: All existing API calls work unchanged

Stop Recording

POST /cameras/{camera_name}/stop-recording

Response: StopRecordingResponse

{
  "success": true,
  "message": "Recording stopped for camera1",
  "duration_seconds": 45.2
}

🤖 Auto-Recording Management

Enable Auto-Recording for Camera

POST /cameras/{camera_name}/auto-recording/enable

Response: AutoRecordingConfigResponse

{
  "success": true,
  "message": "Auto-recording enabled for camera1",
  "camera_name": "camera1",
  "enabled": true
}

Disable Auto-Recording for Camera

POST /cameras/{camera_name}/auto-recording/disable

Response: AutoRecordingConfigResponse

Get Auto-Recording Status

GET /auto-recording/status

Response: AutoRecordingStatusResponse

{
  "running": true,
  "auto_recording_enabled": true,
  "retry_queue": {},
  "enabled_cameras": ["camera1", "camera2"]
}

Auto-Recording Features:

🤖 MQTT-triggered recording: Automatically starts/stops based on machine state
🔄 Retry logic: Failed recordings are retried with configurable delays
📊 Per-camera control: Enable/disable auto-recording individually
📈 Status tracking: Monitor failure counts and last attempts

🎛️ Camera Configuration

Get Camera Configuration

GET /cameras/{camera_name}/config

Response: CameraConfigResponse

{
  "name": "camera1",
  "machine_topic": "blower_separator",
  "storage_path": "/storage/camera1",
  "exposure_ms": 0.3,
  "gain": 4.0,
  "target_fps": 0,
  "enabled": true,
  "video_format": "mp4",
  "video_codec": "mp4v",
  "video_quality": 95,
  "auto_start_recording_enabled": true,
  "auto_recording_max_retries": 3,
  "auto_recording_retry_delay_seconds": 2,
  "contrast": 100,
  "saturation": 100,
  "gamma": 100,
  "noise_filter_enabled": false,
  "denoise_3d_enabled": false,
  "auto_white_balance": false,
  "color_temperature_preset": 0,
  "wb_red_gain": 0.94,
  "wb_green_gain": 1.0,
  "wb_blue_gain": 0.87,
  "anti_flicker_enabled": false,
  "light_frequency": 0,
  "bit_depth": 8,
  "hdr_enabled": false,
  "hdr_gain_mode": 2
}

Update Camera Configuration

PUT /cameras/{camera_name}/config
Content-Type: application/json

{
  "exposure_ms": 2.0,
  "gain": 4.0,
  "target_fps": 5.0,
  "sharpness": 130
}

Apply Configuration (Restart Required)

POST /cameras/{camera_name}/apply-config

Configuration Categories:

✅ Real-time: exposure_ms, gain, target_fps, sharpness, contrast, etc.
⚠️ Restart required: noise_filter_enabled, denoise_3d_enabled, bit_depth, video_format, video_codec, video_quality

For detailed configuration options, see Camera Configuration API Guide.

📡 MQTT & Machine Status

Get All Machines

GET /machines

Response: Dict[str, MachineStatusResponse]

Get MQTT Status

GET /mqtt/status

Response: MQTTStatusResponse

{
  "connected": true,
  "broker_host": "192.168.1.110",
  "broker_port": 1883,
  "subscribed_topics": ["vibratory_conveyor", "blower_separator"],
  "last_message_time": "2024-01-15T10:30:00Z",
  "message_count": 1250,
  "error_count": 2,
  "uptime_seconds": 3600.5
}

Get MQTT Events History

GET /mqtt/events?limit=10

Response: MQTTEventsHistoryResponse

{
  "events": [
    {
      "machine_name": "vibratory_conveyor",
      "topic": "vibratory_conveyor",
      "payload": "ON",
      "normalized_state": "ON",
      "timestamp": "2024-01-15T10:30:00Z",
      "message_number": 1250
    }
  ],
  "total_events": 1250,
  "last_updated": "2024-01-15T10:30:00Z"
}

💾 Storage & File Management

Get Storage Statistics

GET /storage/stats

Response: StorageStatsResponse

{
  "base_path": "/storage",
  "total_files": 150,
  "total_size_bytes": 5368709120,
  "cameras": {
    "camera1": {
      "file_count": 75,
      "total_size_bytes": 2684354560
    },
    "camera2": {
      "file_count": 75,
      "total_size_bytes": 2684354560
    }
  },
  "disk_usage": {
    "total_bytes": 107374182400,
    "used_bytes": 53687091200,
    "free_bytes": 53687091200,
    "usage_percent": 50.0
  }
}

Get File List

POST /storage/files
Content-Type: application/json

{
  "camera_name": "camera1",
  "start_date": "2024-01-15",
  "end_date": "2024-01-16",
  "limit": 50
}

Response: FileListResponse

{
  "files": [
    {
      "filename": "20240115_103000_test_recording.avi",
      "camera_name": "camera1",
      "size_bytes": 52428800,
      "created_time": "2024-01-15T10:30:00Z",
      "duration_seconds": 30.5
    }
  ],
  "total_count": 1
}

Cleanup Old Files

POST /storage/cleanup
Content-Type: application/json

{
  "max_age_days": 30
}

Response: CleanupResponse

{
  "files_removed": 25,
  "bytes_freed": 1073741824,
  "errors": []
}

🔄 Camera Recovery & Diagnostics

Test Camera Connection

POST /cameras/{camera_name}/test-connection

Response: CameraTestResponse