python-detector-worker/WEBSOCKET_DEBUG_GUIDE.md

WebSocket RX/TX Debugging Guide

🔍 Problem Solved

The original issue was that you couldn't see the actual data being sent from the CMS backend. The worker was receiving subscriptionIdentifier: "null" with empty fields, making it impossible to debug the communication.

📡 RX/TX Logging Implementation

Where It's Implemented

The bulletproof RX/TX logging is implemented in:

• File: detector_worker/communication/websocket_handler.py
• RX Logging: Lines 241-246 (in _process_messages method)
• TX Logging: Lines 218-224 (in _send_heartbeat method) and other response methods

What You'll See Now

When you run the worker, you'll see clear console output like:

🔗 WebSocket connection accepted from 192.168.1.100:54321
🔄 WebSocket handler ready - waiting for messages from CMS backend...
📡 All RX/TX communication will be logged below:
================================================================================

🔵 WEBSOCKET RX <- {"type":"setSubscriptionList","subscriptions":[{"subscriptionIdentifier":"null","rtspUrl":"","modelUrl":"","modelName":null,"modelId":null}]}

🟢 WEBSOCKET TX -> {"type":"stateReport","cpuUsage":12.5,"memoryUsage":45.2,"cameraConnections":[]}

Logging Methods Used

The implementation uses 3 different logging methods to guarantee visibility:

1. print() statements - Always visible in console (bulletproof)
2. Standard Python logging - Via logger.info()
3. WebSocket-specific logging - Via ws_rxtx_logger.info()

🚀 How to Use

1. Start the Worker

# For debugging, use staging port with verbose output
make run-staging

# Or use debug mode for even more logging
make run-debug

2. Connect Your CMS Backend

Point your CMS backend to connect to:

• Staging: ws://your-worker-ip:8001/
• Production: ws://your-worker-ip:8000/

3. Watch the Console Output

You'll immediately see:

• 🔵 RX messages - Everything the CMS backend sends
• 🟢 TX messages - Everything the worker sends back
• Connection events - When clients connect/disconnect
• Detailed payload analysis - Full JSON message contents

🔧 Testing Without CMS Backend

Use the included test script:

python3 websocket_rx_tx_demo.py

This will:

1. Connect to your worker
2. Send test messages
3. Show you exactly what RX/TX logging looks like

🐛 Debugging the "null" Issue

Based on your error message, the CMS backend is sending:

{
  "subscriptionIdentifier": "null",
  "rtspUrl": "",
  "modelUrl": "",  
  "modelName": null,
  "modelId": null
}

Possible Causes:

1. CMS Configuration Issue: The CMS might not be properly configured with camera details
2. Database Issue: The CMS might not be getting camera data from its database
3. Authentication Issue: The CMS might not have access to camera/model information
4. Network Issue: The CMS might be failing to retrieve configuration data

What to Look For:

With the new RX/TX logging, you can now see:

1. Is the CMS actually connecting? - Look for connection messages
2. What exact data is being sent? - Every field will be logged
3. Is the CMS sending multiple messages? - You'll see each one
4. Are there any error patterns? - Failed retries, timeouts, etc.

📋 Log Analysis

Example of Good Data:

🔵 WEBSOCKET RX <- {"type":"setSubscriptionList","subscriptions":[{"subscriptionIdentifier":"display-001;cam-001","rtspUrl":"rtsp://192.168.1.50:554/stream","modelId":45,"modelUrl":"http://storage.com/model.mpta"}]}

Example of Bad Data (what you're seeing):

🔵 WEBSOCKET RX <- {"type":"setSubscriptionList","subscriptions":[{"subscriptionIdentifier":"null","rtspUrl":"","modelUrl":"","modelName":null,"modelId":null}]}

🔄 Next Steps

1. Run the worker with make run-staging
2. Connect your CMS backend
3. Watch the console for RX messages
4. Share the exact RX message content to debug the CMS configuration issue

The worker is now ready to show you exactly what the CMS backend is sending, making it much easier to identify and fix the configuration issue on the CMS side.

🛠️ Advanced Debugging

Enable More Logging

You can also enable WebSocket debugging via the REST API:

# Enable debugging
curl -X POST http://localhost:8001/debug/websocket/enable

# Check status  
curl http://localhost:8001/debug/websocket

# Disable when done
curl -X POST http://localhost:8001/debug/websocket/disable

Log Files

WebSocket communication is also logged to files if configured in the application settings.

---

The key improvement: You now have bulletproof visibility into all WebSocket communication, making it easy to debug CMS backend configuration issues.