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/docs/guides/CAMERA_RECOVERY_GUIDE.md
+++ b/camera-management-api/docs/guides/CAMERA_RECOVERY_GUIDE.md
@@ -0,0 +1,158 @@
+# Camera Recovery and Diagnostics Guide
+
+This guide explains the new camera recovery functionality implemented in the USDA Vision Camera System API.
+
+## Overview
+
+The system now includes comprehensive camera recovery capabilities to handle connection issues, initialization failures, and other camera-related problems. These features use the underlying mvsdk (python demo) library functions to perform various recovery operations.
+
+## Available Recovery Operations
+
+### 1. Connection Test (`/cameras/{camera_name}/test-connection`)
+- **Purpose**: Test if the camera connection is working
+- **SDK Function**: `CameraConnectTest()`
+- **Use Case**: Diagnose connection issues
+- **HTTP Method**: POST
+- **Response**: `CameraTestResponse`
+
+### 2. Reconnect (`/cameras/{camera_name}/reconnect`)
+- **Purpose**: Soft reconnection to the camera
+- **SDK Function**: `CameraReConnect()`
+- **Use Case**: Most common fix for connection issues
+- **HTTP Method**: POST
+- **Response**: `CameraRecoveryResponse`
+
+### 3. Restart Grab (`/cameras/{camera_name}/restart-grab`)
+- **Purpose**: Restart the camera grab process
+- **SDK Function**: `CameraRestartGrab()`
+- **Use Case**: Fix issues with image capture
+- **HTTP Method**: POST
+- **Response**: `CameraRecoveryResponse`
+
+### 4. Reset Timestamp (`/cameras/{camera_name}/reset-timestamp`)
+- **Purpose**: Reset camera timestamp
+- **SDK Function**: `CameraRstTimeStamp()`
+- **Use Case**: Fix timing-related issues
+- **HTTP Method**: POST
+- **Response**: `CameraRecoveryResponse`
+
+### 5. Full Reset (`/cameras/{camera_name}/full-reset`)
+- **Purpose**: Complete camera reset (uninitialize and reinitialize)
+- **SDK Functions**: `CameraUnInit()` + `CameraInit()`
+- **Use Case**: Hard reset for persistent issues
+- **HTTP Method**: POST
+- **Response**: `CameraRecoveryResponse`
+
+### 6. Reinitialize (`/cameras/{camera_name}/reinitialize`)
+- **Purpose**: Reinitialize cameras that failed initial setup
+- **SDK Functions**: Complete recorder recreation
+- **Use Case**: Cameras that never initialized properly
+- **HTTP Method**: POST
+- **Response**: `CameraRecoveryResponse`
+
+## Recommended Troubleshooting Workflow
+
+When a camera has issues, follow this order:
+
+1. **Test Connection** - Diagnose the problem
+   ```http
+   POST http://localhost:8000/cameras/camera1/test-connection
+   ```
+
+2. **Try Reconnect** - Most common fix
+   ```http
+   POST http://localhost:8000/cameras/camera1/reconnect
+   ```
+
+3. **Restart Grab** - If reconnect doesn't work
+   ```http
+   POST http://localhost:8000/cameras/camera1/restart-grab
+   ```
+
+4. **Full Reset** - For persistent issues
+   ```http
+   POST http://localhost:8000/cameras/camera1/full-reset
+   ```
+
+5. **Reinitialize** - For cameras that never worked
+   ```http
+   POST http://localhost:8000/cameras/camera1/reinitialize
+   ```
+
+## Response Format
+
+All recovery operations return structured responses:
+
+### CameraTestResponse
+```json
+{
+  "success": true,
+  "message": "Camera camera1 connection test passed",
+  "camera_name": "camera1",
+  "timestamp": "2024-01-01T12:00:00"
+}
+```
+
+### CameraRecoveryResponse
+```json
+{
+  "success": true,
+  "message": "Camera camera1 reconnected successfully",
+  "camera_name": "camera1",
+  "operation": "reconnect",
+  "timestamp": "2024-01-01T12:00:00"
+}
+```
+
+## Implementation Details
+
+### CameraRecorder Methods
+- `test_connection()`: Tests camera connection
+- `reconnect()`: Performs soft reconnection
+- `restart_grab()`: Restarts grab process
+- `reset_timestamp()`: Resets timestamp
+- `full_reset()`: Complete reset with cleanup and reinitialization
+
+### CameraManager Methods
+- `test_camera_connection(camera_name)`: Test specific camera
+- `reconnect_camera(camera_name)`: Reconnect specific camera
+- `restart_camera_grab(camera_name)`: Restart grab for specific camera
+- `reset_camera_timestamp(camera_name)`: Reset timestamp for specific camera
+- `full_reset_camera(camera_name)`: Full reset for specific camera
+- `reinitialize_failed_camera(camera_name)`: Reinitialize failed camera
+
+### State Management
+All recovery operations automatically update the camera status in the state manager:
+- Success: Status set to "connected"
+- Failure: Status set to appropriate error state with error message
+
+## Error Handling
+
+The system includes comprehensive error handling:
+- SDK exceptions are caught and logged
+- State manager is updated with error information
+- Proper HTTP status codes are returned
+- Detailed error messages are provided
+
+## Testing
+
+Use the provided test files:
+- `api-tests.http`: Manual API testing with VS Code REST Client
+- `test_camera_recovery_api.py`: Automated testing script
+
+## Safety Features
+
+- Recording is automatically stopped before recovery operations
+- Camera resources are properly cleaned up
+- Thread-safe operations with proper locking
+- Graceful error handling prevents system crashes
+
+## Common Use Cases
+
+1. **Camera Lost Connection**: Use reconnect
+2. **Camera Won't Capture**: Use restart-grab
+3. **Camera Initialization Failed**: Use reinitialize
+4. **Persistent Issues**: Use full-reset
+5. **Timing Problems**: Use reset-timestamp
+
+This recovery system provides robust tools to handle most camera-related issues without requiring system restart or manual intervention.
--- a/camera-management-api/docs/guides/MQTT_LOGGING_GUIDE.md
+++ b/camera-management-api/docs/guides/MQTT_LOGGING_GUIDE.md
@@ -0,0 +1,187 @@
+# MQTT Console Logging & API Guide
+
+## 🎯 Overview
+
+Your USDA Vision Camera System now has **enhanced MQTT console logging** and **comprehensive API endpoints** for monitoring machine status via MQTT.
+
+## ✨ What's New
+
+### 1. **Enhanced Console Logging**
+- **Colorful emoji-based console output** for all MQTT events
+- **Real-time visibility** of MQTT connections, subscriptions, and messages
+- **Clear status indicators** for debugging and monitoring
+
+### 2. **New MQTT Status API Endpoint**
+- **GET /mqtt/status** - Detailed MQTT client statistics
+- **Message counts, error tracking, uptime monitoring**
+- **Real-time connection status and broker information**
+
+### 3. **Existing Machine Status APIs** (already available)
+- **GET /machines** - All machine states from MQTT
+- **GET /system/status** - Overall system status including MQTT
+
+## 🖥️ Console Logging Examples
+
+When you run the system, you'll see:
+
+```bash
+🔗 MQTT CONNECTED: 192.168.1.110:1883
+📋 MQTT SUBSCRIBED: vibratory_conveyor → vision/vibratory_conveyor/state
+📋 MQTT SUBSCRIBED: blower_separator → vision/blower_separator/state
+📡 MQTT MESSAGE: vibratory_conveyor → on
+📡 MQTT MESSAGE: blower_separator → off
+⚠️ MQTT DISCONNECTED: Unexpected disconnection (code: 1)
+🔗 MQTT CONNECTED: 192.168.1.110:1883
+```
+
+## 🌐 API Endpoints
+
+### MQTT Status
+```http
+GET http://localhost:8000/mqtt/status
+```
+
+**Response:**
+```json
+{
+  "connected": true,
+  "broker_host": "192.168.1.110",
+  "broker_port": 1883,
+  "subscribed_topics": [
+    "vision/vibratory_conveyor/state",
+    "vision/blower_separator/state"
+  ],
+  "last_message_time": "2025-07-28T12:00:00",
+  "message_count": 42,
+  "error_count": 0,
+  "uptime_seconds": 3600.5
+}
+```
+
+### Machine Status
+```http
+GET http://localhost:8000/machines
+```
+
+**Response:**
+```json
+{
+  "vibratory_conveyor": {
+    "name": "vibratory_conveyor",
+    "state": "on",
+    "last_updated": "2025-07-28T12:00:00",
+    "last_message": "on",
+    "mqtt_topic": "vision/vibratory_conveyor/state"
+  },
+  "blower_separator": {
+    "name": "blower_separator",
+    "state": "off",
+    "last_updated": "2025-07-28T12:00:00",
+    "last_message": "off",
+    "mqtt_topic": "vision/blower_separator/state"
+  }
+}
+```
+
+### System Status
+```http
+GET http://localhost:8000/system/status
+```
+
+**Response:**
+```json
+{
+  "system_started": true,
+  "mqtt_connected": true,
+  "last_mqtt_message": "2025-07-28T12:00:00",
+  "machines": { ... },
+  "cameras": { ... },
+  "active_recordings": 0,
+  "total_recordings": 5,
+  "uptime_seconds": 3600.5
+}
+```
+
+## 🚀 How to Use
+
+### 1. **Start the Full System**
+```bash
+python main.py
+```
+You'll see enhanced console logging for all MQTT events.
+
+### 2. **Test MQTT Demo (MQTT only)**
+```bash
+python demo_mqtt_console.py
+```
+Shows just the MQTT client with enhanced logging.
+
+### 3. **Test API Endpoints**
+```bash
+python test_mqtt_logging.py
+```
+Tests all the API endpoints and shows expected responses.
+
+### 4. **Query APIs Directly**
+```bash
+# Check MQTT status
+curl http://localhost:8000/mqtt/status
+
+# Check machine states
+curl http://localhost:8000/machines
+
+# Check overall system status
+curl http://localhost:8000/system/status
+```
+
+## 🔧 Configuration
+
+The MQTT settings are in `config.json`:
+
+```json
+{
+  "mqtt": {
+    "broker_host": "192.168.1.110",
+    "broker_port": 1883,
+    "username": null,
+    "password": null,
+    "topics": {
+      "vibratory_conveyor": "vision/vibratory_conveyor/state",
+      "blower_separator": "vision/blower_separator/state"
+    }
+  }
+}
+```
+
+## 🎨 Console Output Features
+
+- **🔗 Connection Events**: Green for successful connections
+- **📋 Subscriptions**: Blue for topic subscriptions
+- **📡 Messages**: Real-time message display with machine name and payload
+- **⚠️ Warnings**: Yellow for unexpected disconnections
+- **❌ Errors**: Red for connection failures and errors
+- **❓ Unknown Topics**: Purple for unrecognized MQTT topics
+
+## 📊 Monitoring & Debugging
+
+### Real-time Monitoring
+- **Console**: Watch live MQTT events as they happen
+- **API**: Query `/mqtt/status` for statistics and health
+- **Logs**: Check `usda_vision_system.log` for detailed logs
+
+### Troubleshooting
+1. **No MQTT messages?** Check broker connectivity and topic configuration
+2. **Connection issues?** Verify broker host/port in config.json
+3. **API not responding?** Ensure the system is running with `python main.py`
+
+## 🎯 Use Cases
+
+1. **Development**: See MQTT messages in real-time while developing
+2. **Debugging**: Identify connection issues and message patterns
+3. **Monitoring**: Use APIs to build dashboards or monitoring tools
+4. **Integration**: Query machine states from external applications
+5. **Maintenance**: Track MQTT statistics and error rates
+
+---
+
+**🎉 Your MQTT monitoring is now fully enhanced with both console logging and comprehensive APIs!**
--- a/camera-management-api/docs/guides/STREAMING_GUIDE.md
+++ b/camera-management-api/docs/guides/STREAMING_GUIDE.md
@@ -0,0 +1,240 @@
+# 🎥 USDA Vision Camera Live Streaming Guide
+
+This guide explains how to use the new live preview streaming functionality that allows you to view camera feeds in real-time without blocking recording operations.
+
+## 🌟 Key Features
+
+- **Non-blocking streaming**: Live preview doesn't interfere with recording
+- **Separate camera connections**: Streaming uses independent camera instances
+- **MJPEG streaming**: Standard web-compatible video streaming
+- **Multiple concurrent viewers**: Multiple browsers can view the same stream
+- **REST API control**: Start/stop streaming via API endpoints
+- **Web interface**: Ready-to-use HTML interface for live preview
+
+## 🏗️ Architecture
+
+The streaming system creates separate camera connections for preview that are independent from recording:
+
+```
+Camera Hardware
+├── Recording Connection (CameraRecorder)
+│   ├── Used for video file recording
+│   ├── Triggered by MQTT machine states
+│   └── High quality, full FPS
+└── Streaming Connection (CameraStreamer)
+    ├── Used for live preview
+    ├── Controlled via API endpoints
+    └── Optimized for web viewing (lower FPS, JPEG compression)
+```
+
+## 🚀 Quick Start
+
+### 1. Start the System
+```bash
+python main.py
+```
+
+### 2. Open the Web Interface
+Open `camera_preview.html` in your browser and click "Start Stream" for any camera.
+
+### 3. API Usage
+```bash
+# Start streaming for camera1
+curl -X POST http://localhost:8000/cameras/camera1/start-stream
+
+# View live stream (open in browser)
+http://localhost:8000/cameras/camera1/stream
+
+# Stop streaming
+curl -X POST http://localhost:8000/cameras/camera1/stop-stream
+```
+
+## 📡 API Endpoints
+
+### Start Streaming
+```http
+POST /cameras/{camera_name}/start-stream
+```
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Started streaming for camera camera1"
+}
+```
+
+### Stop Streaming
+```http
+POST /cameras/{camera_name}/stop-stream
+```
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Stopped streaming for camera camera1"
+}
+```
+
+### Live Stream (MJPEG)
+```http
+GET /cameras/{camera_name}/stream
+```
+**Response:** Multipart MJPEG stream
+**Content-Type:** `multipart/x-mixed-replace; boundary=frame`
+
+## 🌐 Web Interface Usage
+
+The included `camera_preview.html` provides a complete web interface:
+
+1. **Camera Grid**: Shows all configured cameras
+2. **Stream Controls**: Start/Stop/Refresh buttons for each camera
+3. **Live Preview**: Real-time video feed display
+4. **Status Information**: System and camera status
+5. **Responsive Design**: Works on desktop and mobile
+
+### Features:
+- ✅ Real-time camera status
+- ✅ One-click stream start/stop
+- ✅ Automatic stream refresh
+- ✅ System health monitoring
+- ✅ Error handling and status messages
+
+## 🔧 Technical Details
+
+### Camera Streamer Configuration
+- **Preview FPS**: 10 FPS (configurable)
+- **JPEG Quality**: 70% (configurable)
+- **Frame Buffer**: 5 frames (prevents memory buildup)
+- **Timeout**: 200ms per frame capture
+
+### Memory Management
+- Automatic frame buffer cleanup
+- Queue-based frame management
+- Proper camera resource cleanup on stop
+
+### Thread Safety
+- Thread-safe streaming operations
+- Independent from recording threads
+- Proper synchronization with locks
+
+## 🧪 Testing
+
+### Run the Test Script
+```bash
+python test_streaming.py
+```
+
+This will test:
+- ✅ API endpoint functionality
+- ✅ Stream start/stop operations
+- ✅ Concurrent recording and streaming
+- ✅ Error handling
+
+### Manual Testing
+1. Start the system: `python main.py`
+2. Open `camera_preview.html` in browser
+3. Start streaming for a camera
+4. Trigger recording via MQTT or manual API
+5. Verify both work simultaneously
+
+## 🔄 Concurrent Operations
+
+The system supports these concurrent operations:
+
+| Operation | Recording | Streaming | Notes |
+|-----------|-----------|-----------|-------|
+| Recording Only | ✅ | ❌ | Normal operation |
+| Streaming Only | ❌ | ✅ | Preview without recording |
+| Both Concurrent | ✅ | ✅ | **Independent connections** |
+
+### Example: Concurrent Usage
+```bash
+# Start streaming
+curl -X POST http://localhost:8000/cameras/camera1/start-stream
+
+# Start recording (while streaming continues)
+curl -X POST http://localhost:8000/cameras/camera1/start-recording \
+  -H "Content-Type: application/json" \
+  -d '{"filename": "test_recording.avi"}'
+
+# Both operations run independently!
+```
+
+## 🛠️ Configuration
+
+### Stream Settings (in CameraStreamer)
+```python
+self.preview_fps = 10.0          # Lower FPS for preview
+self.preview_quality = 70        # JPEG quality (1-100)
+self._frame_queue.maxsize = 5    # Frame buffer size
+```
+
+### Camera Settings
+The streamer uses the same camera configuration as recording:
+- Exposure time from `camera_config.exposure_ms`
+- Gain from `camera_config.gain`
+- Optimized trigger mode for continuous streaming
+
+## 🚨 Important Notes
+
+### Camera Access Patterns
+- **Recording**: Blocks camera during active recording
+- **Streaming**: Uses separate connection, doesn't block
+- **Health Checks**: Brief, non-blocking camera tests
+- **Multiple Streams**: Multiple browsers can view same stream
+
+### Performance Considerations
+- Streaming uses additional CPU/memory resources
+- Lower preview FPS reduces system load
+- JPEG compression reduces bandwidth usage
+- Frame queue prevents memory buildup
+
+### Error Handling
+- Automatic camera resource cleanup
+- Graceful handling of camera disconnections
+- Stream auto-restart capabilities
+- Detailed error logging
+
+## 🔍 Troubleshooting
+
+### Stream Not Starting
+1. Check camera availability: `GET /cameras`
+2. Verify camera not in error state
+3. Check system logs for camera initialization errors
+4. Try camera reconnection: `POST /cameras/{name}/reconnect`
+
+### Poor Stream Quality
+1. Adjust `preview_quality` setting (higher = better quality)
+2. Increase `preview_fps` for smoother video
+3. Check network bandwidth
+4. Verify camera exposure/gain settings
+
+### Browser Issues
+1. Try different browser (Chrome/Firefox recommended)
+2. Check browser console for JavaScript errors
+3. Verify CORS settings in API server
+4. Clear browser cache and refresh
+
+## 📈 Future Enhancements
+
+Potential improvements for the streaming system:
+
+- 🔄 WebRTC support for lower latency
+- 📱 Mobile app integration
+- 🎛️ Real-time camera setting adjustments
+- 📊 Stream analytics and monitoring
+- 🔐 Authentication and access control
+- 🌐 Multi-camera synchronized viewing
+
+## 📞 Support
+
+For issues with streaming functionality:
+
+1. Check the system logs: `usda_vision_system.log`
+2. Run the test script: `python test_streaming.py`
+3. Verify API health: `http://localhost:8000/health`
+4. Check camera status: `http://localhost:8000/cameras`
+
+---
+
+**✅ Live streaming is now ready for production use!**