usda-vision/management-dashboard-web-app/API Documentations/docs/legacy/README_SYSTEM.md

USDA Vision Camera System

A comprehensive system for monitoring machines via MQTT and automatically recording video from GigE cameras when machines are active.

Overview

This system integrates MQTT machine monitoring with automated video recording from GigE cameras. When a machine turns on (detected via MQTT), the system automatically starts recording from the associated camera. When the machine turns off, recording stops and the video is saved with a timestamp.

Features

• MQTT Integration: Listens to multiple machine state topics
• Automatic Recording: Starts/stops recording based on machine states
• GigE Camera Support: Uses the python demo library (mvsdk) for camera control
• Multi-threading: Concurrent MQTT listening, camera monitoring, and recording
• REST API: FastAPI server for dashboard integration
• WebSocket Support: Real-time status updates
• Storage Management: Organized file storage with cleanup capabilities
• Comprehensive Logging: Detailed logging with rotation and error tracking
• Configuration Management: JSON-based configuration system

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MQTT Broker   │    │   GigE Camera   │    │   Dashboard     │
│                 │    │                 │    │   (React)       │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │ Machine States       │ Video Streams        │ API Calls
          │                      │                      │
┌─────────▼──────────────────────▼──────────────────────▼───────┐
│                USDA Vision Camera System                      │
├───────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │ MQTT Client │  │   Camera    │  │ API Server  │           │
│  │             │  │  Manager    │  │             │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   State     │  │   Storage   │  │   Event     │           │
│  │  Manager    │  │  Manager    │  │  System     │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└───────────────────────────────────────────────────────────────┘

Installation

1. Prerequisites:

   • Python 3.11+
   • GigE cameras with python demo library
   • MQTT broker (e.g., Mosquitto)
   • uv package manager (recommended)

2. Install Dependencies:

   uv sync
   

3. Setup Storage Directory:

   sudo mkdir -p /storage
   sudo chown $USER:$USER /storage
   

Configuration

Edit config.json to configure your system:

{
  "mqtt": {
    "broker_host": "192.168.1.110",
    "broker_port": 1883,
    "topics": {
      "vibratory_conveyor": "vision/vibratory_conveyor/state",
      "blower_separator": "vision/blower_separator/state"
    }
  },
  "cameras": [
    {
      "name": "camera1",
      "machine_topic": "vibratory_conveyor",
      "storage_path": "/storage/camera1",
      "exposure_ms": 1.0,
      "gain": 3.5,
      "target_fps": 3.0,
      "enabled": true
    }
  ]
}

Usage

Basic Usage

1. Start the System:

   python main.py
   

2. With Custom Config:

   python main.py --config my_config.json
   

3. Debug Mode:

   python main.py --log-level DEBUG
   

API Endpoints

The system provides a REST API on port 8000:

• GET /system/status - Overall system status
• GET /cameras - All camera statuses
• GET /machines - All machine states
• POST /cameras/{name}/start-recording - Manual recording start
• POST /cameras/{name}/stop-recording - Manual recording stop
• GET /storage/stats - Storage statistics
• WebSocket /ws - Real-time updates

Dashboard Integration

The system is designed to integrate with your existing React + Vite + Tailwind + Supabase dashboard:

1. API Integration: Use the REST endpoints to display system status
2. WebSocket: Connect to /ws for real-time updates
3. Supabase Storage: Store recording metadata and system logs

File Organization

/storage/
├── camera1/
│   ├── camera1_recording_20250726_143022.avi
│   └── camera1_recording_20250726_143155.avi
├── camera2/
│   ├── camera2_recording_20250726_143025.avi
│   └── camera2_recording_20250726_143158.avi
└── file_index.json

Monitoring and Logging

Log Files

• usda_vision_system.log - Main system log (rotated)
• Console output with colored formatting
• Component-specific log levels

Performance Monitoring

The system includes built-in performance monitoring:

• Startup times
• Recording session metrics
• MQTT message processing rates
• Camera status check intervals

Error Tracking

Comprehensive error tracking with:

• Error counts per component
• Detailed error context
• Automatic recovery attempts

Troubleshooting

Common Issues

1. Camera Not Found:

   • Check camera connections
   • Verify python demo library installation
   • Run camera discovery: Check logs for enumeration results

2. MQTT Connection Failed:

   • Verify broker IP and port
   • Check network connectivity
   • Verify credentials if authentication is enabled

3. Recording Fails:

   • Check storage permissions
   • Verify available disk space
   • Check camera initialization logs

4. API Server Won't Start:

   • Check if port 8000 is available
   • Verify FastAPI dependencies
   • Check firewall settings

Debug Commands

# Check system status
curl http://localhost:8000/system/status

# Check camera status
curl http://localhost:8000/cameras

# Manual recording start
curl -X POST http://localhost:8000/cameras/camera1/start-recording \
  -H "Content-Type: application/json" \
  -d '{"camera_name": "camera1"}'

Development

Project Structure

usda_vision_system/
├── core/           # Core functionality
├── mqtt/           # MQTT client and handlers
├── camera/         # Camera management and recording
├── storage/        # File management
├── api/            # FastAPI server
└── main.py         # Application coordinator

Adding New Features

1. New Camera Type: Extend camera/recorder.py
2. New MQTT Topics: Update config.json and mqtt/handlers.py
3. New API Endpoints: Add to api/server.py
4. New Events: Define in core/events.py

Testing

# Run basic system test
python -c "from usda_vision_system import USDAVisionSystem; s = USDAVisionSystem(); print('OK')"

# Test MQTT connection
python -c "from usda_vision_system.mqtt.client import MQTTClient; # ... test code"

# Test camera discovery
python -c "import sys; sys.path.append('python demo'); import mvsdk; print(len(mvsdk.CameraEnumerateDevice()))"

License

This project is developed for USDA research purposes.

Support

For issues and questions:

1. Check the logs in usda_vision_system.log
2. Review the troubleshooting section
3. Check API status at http://localhost:8000/health