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
parent 28dab3a366
commit fc2da16728
281 changed files with 19 additions and 19 deletions
--- a/camera-management-api/ai_agent/guides/AI_AGENT_INSTRUCTIONS.md
+++ b/camera-management-api/ai_agent/guides/AI_AGENT_INSTRUCTIONS.md
@@ -0,0 +1,175 @@
+# Instructions for AI Agent: Auto-Recording Feature Integration
+
+## 🎯 Task Overview
+Update the React application to support the new auto-recording feature that has been added to the USDA Vision Camera System backend.
+
+## 📋 What You Need to Know
+
+### System Context
+- **Camera 1** monitors the **vibratory conveyor** (conveyor/cracker cam)
+- **Camera 2** monitors the **blower separator** machine
+- Auto-recording automatically starts when machines turn ON and stops when they turn OFF
+- The system includes retry logic for failed recording attempts
+- Manual recording always takes precedence over auto-recording
+
+### New Backend Capabilities
+The backend now supports:
+1. **Automatic recording** triggered by MQTT machine state changes
+2. **Retry mechanism** for failed recording attempts (configurable retries and delays)
+3. **Status tracking** for auto-recording state, failures, and attempts
+4. **API endpoints** for enabling/disabling and monitoring auto-recording
+
+## 🔧 Required React App Changes
+
+### 1. Update TypeScript Interfaces
+
+Add these new fields to existing `CameraStatusResponse`:
+```typescript
+interface CameraStatusResponse {
+  // ... existing fields
+  auto_recording_enabled: boolean;
+  auto_recording_active: boolean;
+  auto_recording_failure_count: number;
+  auto_recording_last_attempt?: string;
+  auto_recording_last_error?: string;
+}
+```
+
+Add new response types:
+```typescript
+interface AutoRecordingConfigResponse {
+  success: boolean;
+  message: string;
+  camera_name: string;
+  enabled: boolean;
+}
+
+interface AutoRecordingStatusResponse {
+  running: boolean;
+  auto_recording_enabled: boolean;
+  retry_queue: Record<string, any>;
+  enabled_cameras: string[];
+}
+```
+
+### 2. Add New API Endpoints
+
+```typescript
+// Enable auto-recording for a camera
+POST /cameras/{camera_name}/auto-recording/enable
+
+// Disable auto-recording for a camera  
+POST /cameras/{camera_name}/auto-recording/disable
+
+// Get overall auto-recording system status
+GET /auto-recording/status
+```
+
+### 3. UI Components to Add/Update
+
+#### Camera Status Display
+- Add auto-recording status badge/indicator
+- Show auto-recording enabled/disabled state
+- Display failure count if > 0
+- Show last error message if any
+- Distinguish between manual and auto-recording states
+
+#### Auto-Recording Controls
+- Toggle switch to enable/disable auto-recording per camera
+- System-wide auto-recording status display
+- Retry queue information
+- Machine state correlation display
+
+#### Error Handling
+- Clear display of auto-recording failures
+- Retry attempt information
+- Last attempt timestamp
+- Quick retry/reset actions
+
+### 4. Visual Design Guidelines
+
+**Status Priority (highest to lowest):**
+1. Manual Recording (red/prominent) - user initiated
+2. Auto-Recording Active (green) - machine ON, recording
+3. Auto-Recording Enabled (blue) - ready but machine OFF
+4. Auto-Recording Disabled (gray) - feature disabled
+
+**Machine Correlation:**
+- Show machine name next to camera (e.g., "Vibratory Conveyor", "Blower Separator")
+- Display machine ON/OFF status
+- Alert if machine is ON but auto-recording failed
+
+## 🎨 Specific Implementation Tasks
+
+### Task 1: Update Camera Cards
+- Add auto-recording status indicators
+- Add enable/disable toggle controls
+- Show machine state correlation
+- Display failure information when relevant
+
+### Task 2: Create Auto-Recording Dashboard
+- Overall system status
+- List of enabled cameras
+- Active retry queue display
+- Recent events/errors
+
+### Task 3: Update Recording Status Logic
+- Distinguish between manual and auto-recording
+- Show appropriate controls based on recording type
+- Handle manual override scenarios
+
+### Task 4: Add Error Handling
+- Display auto-recording failures clearly
+- Show retry attempts and timing
+- Provide manual retry options
+
+## 📱 User Experience Requirements
+
+### Key Behaviors
+1. **Non-Intrusive:** Auto-recording status shouldn't clutter the main interface
+2. **Clear Hierarchy:** Manual controls should be more prominent than auto-recording
+3. **Informative:** Users should understand why recording started/stopped
+4. **Actionable:** Clear options to enable/disable or retry failed attempts
+
+### Mobile Considerations
+- Auto-recording controls should work well on mobile
+- Status information should be readable on small screens
+- Consider collapsible sections for detailed information
+
+## 🔍 Testing Requirements
+
+Ensure the React app correctly handles:
+- [ ] Toggling auto-recording on/off per camera
+- [ ] Displaying real-time status updates
+- [ ] Showing error states and retry information
+- [ ] Manual recording override scenarios
+- [ ] Machine state changes and correlation
+- [ ] Mobile interface functionality
+
+## 📚 Reference Files
+
+Key files to review for implementation details:
+- `AUTO_RECORDING_FEATURE_GUIDE.md` - Comprehensive technical details
+- `api-endpoints.http` - API endpoint documentation
+- `config.json` - Configuration structure
+- `usda_vision_system/api/models.py` - Response type definitions
+
+## 🎯 Success Criteria
+
+The React app should:
+1. **Display** auto-recording status for each camera clearly
+2. **Allow** users to enable/disable auto-recording per camera
+3. **Show** machine state correlation and recording triggers
+4. **Handle** error states and retry scenarios gracefully
+5. **Maintain** existing manual recording functionality
+6. **Provide** clear visual hierarchy between manual and auto-recording
+
+## 💡 Implementation Tips
+
+1. **Start Small:** Begin with basic status display, then add controls
+2. **Use Existing Patterns:** Follow the current app's design patterns
+3. **Test Incrementally:** Test each feature as you add it
+4. **Consider State Management:** Update your state management to handle new data
+5. **Mobile First:** Ensure mobile usability from the start
+
+The goal is to seamlessly integrate auto-recording capabilities while maintaining the existing user experience and adding valuable automation features for the camera operators.
--- a/camera-management-api/ai_agent/guides/AI_INTEGRATION_GUIDE.md
+++ b/camera-management-api/ai_agent/guides/AI_INTEGRATION_GUIDE.md
@@ -0,0 +1,595 @@
+# 🤖 AI Integration Guide: USDA Vision Camera Streaming for React Projects
+
+This guide is specifically designed for AI assistants to understand and implement the USDA Vision Camera streaming functionality in React applications.
+
+## 📋 System Overview
+
+The USDA Vision Camera system provides live video streaming through REST API endpoints. The streaming uses MJPEG format which is natively supported by HTML `<img>` tags and can be easily integrated into React components.
+
+### Key Characteristics:
+- **Base URL**: `http://vision:8000` (production) or `http://localhost:8000` (development)
+- **Stream Format**: MJPEG (Motion JPEG)
+- **Content-Type**: `multipart/x-mixed-replace; boundary=frame`
+- **Authentication**: None (add if needed for production)
+- **CORS**: Enabled for all origins (configure for production)
+
+### Base URL Configuration:
+- **Production**: `http://vision:8000` (requires hostname setup)
+- **Development**: `http://localhost:8000` (local testing)
+- **Custom IP**: `http://192.168.1.100:8000` (replace with actual IP)
+- **Custom hostname**: Configure DNS or /etc/hosts as needed
+
+## 🔌 API Endpoints Reference
+
+### 1. Get Camera List
+```http
+GET /cameras
+```
+**Response:**
+```json
+{
+  "camera1": {
+    "name": "camera1",
+    "status": "connected",
+    "is_recording": false,
+    "last_checked": "2025-01-28T10:30:00",
+    "device_info": {...}
+  },
+  "camera2": {...}
+}
+```
+
+### 2. Start Camera Stream
+```http
+POST /cameras/{camera_name}/start-stream
+```
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Started streaming for camera camera1"
+}
+```
+
+### 3. Stop Camera Stream
+```http
+POST /cameras/{camera_name}/stop-stream
+```
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Stopped streaming for camera camera1"
+}
+```
+
+### 4. Live Video Stream
+```http
+GET /cameras/{camera_name}/stream
+```
+**Response:** MJPEG video stream
+**Usage:** Set as `src` attribute of HTML `<img>` element
+
+## ⚛️ React Integration Examples
+
+### Basic Camera Stream Component
+
+```jsx
+import React, { useState, useEffect } from 'react';
+
+const CameraStream = ({ cameraName, apiBaseUrl = 'http://vision:8000' }) => {
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const startStream = async () => {
+    setLoading(true);
+    setError(null);
+    
+    try {
+      const response = await fetch(`${apiBaseUrl}/cameras/${cameraName}/start-stream`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+      
+      if (response.ok) {
+        setIsStreaming(true);
+      } else {
+        const errorData = await response.json();
+        setError(errorData.detail || 'Failed to start stream');
+      }
+    } catch (err) {
+      setError(`Network error: ${err.message}`);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const stopStream = async () => {
+    setLoading(true);
+    
+    try {
+      const response = await fetch(`${apiBaseUrl}/cameras/${cameraName}/stop-stream`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+      
+      if (response.ok) {
+        setIsStreaming(false);
+      } else {
+        const errorData = await response.json();
+        setError(errorData.detail || 'Failed to stop stream');
+      }
+    } catch (err) {
+      setError(`Network error: ${err.message}`);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="camera-stream">
+      <h3>Camera: {cameraName}</h3>
+      
+      {/* Video Stream */}
+      <div className="stream-container">
+        {isStreaming ? (
+          <img
+            src={`${apiBaseUrl}/cameras/${cameraName}/stream?t=${Date.now()}`}
+            alt={`${cameraName} live stream`}
+            style={{
+              width: '100%',
+              maxWidth: '640px',
+              height: 'auto',
+              border: '2px solid #ddd',
+              borderRadius: '8px',
+            }}
+            onError={() => setError('Stream connection lost')}
+          />
+        ) : (
+          <div style={{
+            width: '100%',
+            maxWidth: '640px',
+            height: '360px',
+            backgroundColor: '#f0f0f0',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            border: '2px solid #ddd',
+            borderRadius: '8px',
+          }}>
+            <span>No Stream Active</span>
+          </div>
+        )}
+      </div>
+
+      {/* Controls */}
+      <div className="stream-controls" style={{ marginTop: '10px' }}>
+        <button
+          onClick={startStream}
+          disabled={loading || isStreaming}
+          style={{
+            padding: '8px 16px',
+            marginRight: '8px',
+            backgroundColor: '#28a745',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            cursor: loading ? 'not-allowed' : 'pointer',
+          }}
+        >
+          {loading ? 'Loading...' : 'Start Stream'}
+        </button>
+        
+        <button
+          onClick={stopStream}
+          disabled={loading || !isStreaming}
+          style={{
+            padding: '8px 16px',
+            backgroundColor: '#dc3545',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            cursor: loading ? 'not-allowed' : 'pointer',
+          }}
+        >
+          {loading ? 'Loading...' : 'Stop Stream'}
+        </button>
+      </div>
+
+      {/* Error Display */}
+      {error && (
+        <div style={{
+          marginTop: '10px',
+          padding: '8px',
+          backgroundColor: '#f8d7da',
+          color: '#721c24',
+          border: '1px solid #f5c6cb',
+          borderRadius: '4px',
+        }}>
+          Error: {error}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default CameraStream;
+```
+
+### Multi-Camera Dashboard Component
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import CameraStream from './CameraStream';
+
+const CameraDashboard = ({ apiBaseUrl = 'http://vision:8000' }) => {
+  const [cameras, setCameras] = useState({});
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    fetchCameras();
+    
+    // Refresh camera status every 30 seconds
+    const interval = setInterval(fetchCameras, 30000);
+    return () => clearInterval(interval);
+  }, []);
+
+  const fetchCameras = async () => {
+    try {
+      const response = await fetch(`${apiBaseUrl}/cameras`);
+      if (response.ok) {
+        const data = await response.json();
+        setCameras(data);
+        setError(null);
+      } else {
+        setError('Failed to fetch cameras');
+      }
+    } catch (err) {
+      setError(`Network error: ${err.message}`);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (loading) {
+    return <div>Loading cameras...</div>;
+  }
+
+  if (error) {
+    return (
+      <div style={{ color: 'red', padding: '20px' }}>
+        Error: {error}
+        <button onClick={fetchCameras} style={{ marginLeft: '10px' }}>
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="camera-dashboard">
+      <h1>USDA Vision Camera Dashboard</h1>
+      
+      <div style={{
+        display: 'grid',
+        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, 1fr))',
+        gap: '20px',
+        padding: '20px',
+      }}>
+        {Object.entries(cameras).map(([cameraName, cameraInfo]) => (
+          <div key={cameraName} style={{
+            border: '1px solid #ddd',
+            borderRadius: '8px',
+            padding: '15px',
+            backgroundColor: '#f9f9f9',
+          }}>
+            <CameraStream 
+              cameraName={cameraName} 
+              apiBaseUrl={apiBaseUrl}
+            />
+            
+            {/* Camera Status */}
+            <div style={{ marginTop: '10px', fontSize: '14px' }}>
+              <div>Status: <strong>{cameraInfo.status}</strong></div>
+              <div>Recording: <strong>{cameraInfo.is_recording ? 'Yes' : 'No'}</strong></div>
+              <div>Last Checked: {new Date(cameraInfo.last_checked).toLocaleString()}</div>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export default CameraDashboard;
+```
+
+### Custom Hook for Camera Management
+
+```jsx
+import { useState, useEffect, useCallback } from 'react';
+
+const useCameraStream = (cameraName, apiBaseUrl = 'http://vision:8000') => {
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  const startStream = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    
+    try {
+      const response = await fetch(`${apiBaseUrl}/cameras/${cameraName}/start-stream`, {
+        method: 'POST',
+      });
+      
+      if (response.ok) {
+        setIsStreaming(true);
+        return { success: true };
+      } else {
+        const errorData = await response.json();
+        const errorMsg = errorData.detail || 'Failed to start stream';
+        setError(errorMsg);
+        return { success: false, error: errorMsg };
+      }
+    } catch (err) {
+      const errorMsg = `Network error: ${err.message}`;
+      setError(errorMsg);
+      return { success: false, error: errorMsg };
+    } finally {
+      setLoading(false);
+    }
+  }, [cameraName, apiBaseUrl]);
+
+  const stopStream = useCallback(async () => {
+    setLoading(true);
+    
+    try {
+      const response = await fetch(`${apiBaseUrl}/cameras/${cameraName}/stop-stream`, {
+        method: 'POST',
+      });
+      
+      if (response.ok) {
+        setIsStreaming(false);
+        return { success: true };
+      } else {
+        const errorData = await response.json();
+        const errorMsg = errorData.detail || 'Failed to stop stream';
+        setError(errorMsg);
+        return { success: false, error: errorMsg };
+      }
+    } catch (err) {
+      const errorMsg = `Network error: ${err.message}`;
+      setError(errorMsg);
+      return { success: false, error: errorMsg };
+    } finally {
+      setLoading(false);
+    }
+  }, [cameraName, apiBaseUrl]);
+
+  const getStreamUrl = useCallback(() => {
+    return `${apiBaseUrl}/cameras/${cameraName}/stream?t=${Date.now()}`;
+  }, [cameraName, apiBaseUrl]);
+
+  return {
+    isStreaming,
+    loading,
+    error,
+    startStream,
+    stopStream,
+    getStreamUrl,
+  };
+};
+
+export default useCameraStream;
+```
+
+## 🎨 Styling with Tailwind CSS
+
+```jsx
+const CameraStreamTailwind = ({ cameraName }) => {
+  const { isStreaming, loading, error, startStream, stopStream, getStreamUrl } = useCameraStream(cameraName);
+
+  return (
+    <div className="bg-white rounded-lg shadow-md p-6">
+      <h3 className="text-lg font-semibold mb-4">Camera: {cameraName}</h3>
+      
+      {/* Stream Container */}
+      <div className="relative mb-4">
+        {isStreaming ? (
+          <img
+            src={getStreamUrl()}
+            alt={`${cameraName} live stream`}
+            className="w-full max-w-2xl h-auto border-2 border-gray-300 rounded-lg"
+            onError={() => setError('Stream connection lost')}
+          />
+        ) : (
+          <div className="w-full max-w-2xl h-64 bg-gray-100 border-2 border-gray-300 rounded-lg flex items-center justify-center">
+            <span className="text-gray-500">No Stream Active</span>
+          </div>
+        )}
+      </div>
+
+      {/* Controls */}
+      <div className="flex gap-2 mb-4">
+        <button
+          onClick={startStream}
+          disabled={loading || isStreaming}
+          className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {loading ? 'Loading...' : 'Start Stream'}
+        </button>
+        
+        <button
+          onClick={stopStream}
+          disabled={loading || !isStreaming}
+          className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {loading ? 'Loading...' : 'Stop Stream'}
+        </button>
+      </div>
+
+      {/* Error Display */}
+      {error && (
+        <div className="p-3 bg-red-100 border border-red-400 text-red-700 rounded">
+          Error: {error}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+## 🔧 Configuration Options
+
+### Environment Variables (.env)
+```env
+# Production configuration (using 'vision' hostname)
+REACT_APP_CAMERA_API_URL=http://vision:8000
+REACT_APP_STREAM_REFRESH_INTERVAL=30000
+REACT_APP_STREAM_TIMEOUT=10000
+
+# Development configuration (using localhost)
+# REACT_APP_CAMERA_API_URL=http://localhost:8000
+
+# Custom IP configuration
+# REACT_APP_CAMERA_API_URL=http://192.168.1.100:8000
+```
+
+### API Configuration
+```javascript
+const apiConfig = {
+  baseUrl: process.env.REACT_APP_CAMERA_API_URL || 'http://vision:8000',
+  timeout: parseInt(process.env.REACT_APP_STREAM_TIMEOUT) || 10000,
+  refreshInterval: parseInt(process.env.REACT_APP_STREAM_REFRESH_INTERVAL) || 30000,
+};
+```
+
+### Hostname Setup Guide
+```bash
+# Option 1: Add to /etc/hosts (Linux/Mac)
+echo "127.0.0.1 vision" | sudo tee -a /etc/hosts
+
+# Option 2: Add to hosts file (Windows)
+# Add to C:\Windows\System32\drivers\etc\hosts:
+# 127.0.0.1 vision
+
+# Option 3: Configure DNS
+# Point 'vision' hostname to your server's IP address
+
+# Verify hostname resolution
+ping vision
+```
+
+## 🚨 Important Implementation Notes
+
+### 1. MJPEG Stream Handling
+- Use HTML `<img>` tag with `src` pointing to stream endpoint
+- Add timestamp query parameter to prevent caching: `?t=${Date.now()}`
+- Handle `onError` event for connection issues
+
+### 2. Error Handling
+- Network errors (fetch failures)
+- HTTP errors (4xx, 5xx responses)
+- Stream connection errors (img onError)
+- Timeout handling for long requests
+
+### 3. Performance Considerations
+- Streams consume bandwidth continuously
+- Stop streams when components unmount
+- Limit concurrent streams based on system capacity
+- Consider lazy loading for multiple cameras
+
+### 4. State Management
+- Track streaming state per camera
+- Handle loading states during API calls
+- Manage error states with user feedback
+- Refresh camera list periodically
+
+## 📱 Mobile Considerations
+
+```jsx
+// Responsive design for mobile
+const mobileStyles = {
+  container: {
+    padding: '10px',
+    maxWidth: '100vw',
+  },
+  stream: {
+    width: '100%',
+    maxWidth: '100vw',
+    height: 'auto',
+  },
+  controls: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8px',
+  },
+};
+```
+
+## 🧪 Testing Integration
+
+```javascript
+// Test API connectivity
+const testConnection = async () => {
+  try {
+    const response = await fetch(`${apiBaseUrl}/health`);
+    return response.ok;
+  } catch {
+    return false;
+  }
+};
+
+// Test camera availability
+const testCamera = async (cameraName) => {
+  try {
+    const response = await fetch(`${apiBaseUrl}/cameras/${cameraName}/test-connection`, {
+      method: 'POST',
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+};
+```
+
+## 📁 Additional Files for AI Integration
+
+### TypeScript Definitions
+- `camera-api.types.ts` - Complete TypeScript definitions for all API types
+- `streaming-api.http` - REST Client file with all streaming endpoints
+- `STREAMING_GUIDE.md` - Comprehensive user guide for streaming functionality
+
+### Quick Integration Checklist for AI Assistants
+
+1. **Copy TypeScript types** from `camera-api.types.ts`
+2. **Use API endpoints** from `streaming-api.http`
+3. **Implement error handling** as shown in examples
+4. **Add CORS configuration** if needed for production
+5. **Test with multiple cameras** using provided examples
+
+### Key Integration Points
+
+- **Stream URL Format**: `${baseUrl}/cameras/${cameraName}/stream?t=${Date.now()}`
+- **Start Stream**: `POST /cameras/{name}/start-stream`
+- **Stop Stream**: `POST /cameras/{name}/stop-stream`
+- **Camera List**: `GET /cameras`
+- **Error Handling**: Always wrap in try-catch blocks
+- **Loading States**: Implement for better UX
+
+### Production Considerations
+
+- Configure CORS for specific origins
+- Add authentication if required
+- Implement rate limiting
+- Monitor system resources with multiple streams
+- Add reconnection logic for network issues
+
+This documentation provides everything an AI assistant needs to integrate the USDA Vision Camera streaming functionality into React applications, including complete code examples, error handling, and best practices.