usda-vision/camera-management-api/docs/guides/MQTT_LOGGING_GUIDE.md

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:

🔗 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

GET http://localhost:8000/mqtt/status

Response:

{
  "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

GET http://localhost:8000/machines

Response:

{
  "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

GET http://localhost:8000/system/status

Response:

{
  "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

python main.py

You'll see enhanced console logging for all MQTT events.

2. Test MQTT Demo (MQTT only)

python demo_mqtt_console.py

Shows just the MQTT client with enhanced logging.

3. Test API Endpoints

python test_mqtt_logging.py

Tests all the API endpoints and shows expected responses.

4. Query APIs Directly

# 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:

{
  "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!