Debugging with ToolX¶

This guide explains how to use ToolX for debugging video streaming and network issues in GVA systems. ToolX is the primary tool for SAP/SDP stream discovery, video stream testing, SNMP diagnostics, and network troubleshooting.

When to Use ToolX¶

Use ToolX when you need to:

Getting Started¶

ToolX Interface Overview¶

When you launch ToolX, you'll see the welcome screen:

Launching ToolX¶

cd build/bin
./toolx

Selecting a Video Codec¶

Choose the appropriate codec for your hardware:

# Intel/AMD GPU (recommended for desktop)
./toolx --vaapi

# Software encoding (works everywhere)
./toolx --openh264

# NVIDIA Jetson platforms
./toolx --omx

# Native encoders (lower latency)
./toolx --vaapi-native
./toolx --openh264-native

Debugging Workflows¶

Workflow 1: Debugging Video Stream Discovery¶

When video streams aren't being discovered:

Step 1: Open ToolX RTP-SAP tab

Step 2: Check if SAP announcements are being received

The SAP Listener table should show:

• Stream name
• Multicast IP address
• Port number
• Encoding type

Step 3: If no streams appear, run diagnostics

Go to the Diagnostics tab and click "Run Diagnostics":

Common Issues:

Step 4: Verify multicast routing

# Check multicast group membership
netstat -g | grep 224.2

# Verify route for SAP multicast
ip route get 224.2.127.254

Workflow 2: Testing Video Stream Generation¶

When you need to generate test video for receivers:

Step 1: Configure stream parameters

In the RTP-SAP tab, Stream Generator section:

1. Set Session Name (e.g., "Test Stream 1")
2. Set IP Address (multicast, e.g., 239.192.1.1)
3. Set Port (e.g., 5004)
4. Select Resolution (e.g., 1920x1080)
5. Select Frame Rate (e.g., 25 fps)
6. Select Encoding (e.g., H.264)
7. Select Test Pattern (e.g., EBU Colour Bars)

Step 2: Start the stream

Click "Start" to begin streaming. The stream will:

• Generate video frames with the test pattern
• Encode using the selected codec
• Transmit via RTP to the multicast address
• Announce via SAP for discovery

Step 3: Verify stream in SAP Listener

Your stream should appear in the SAP Listener table within 1-2 seconds.

Step 4: Test with a receiver

On another machine (or another ToolX instance):

• Open ToolX
• Go to RTP-SAP tab
• Double-click the stream to play it

Test Patterns Available:

Workflow 3: Debugging SNMP/VIVOE Equipment¶

When testing VIVOE compliance or SNMP connectivity:

Step 1: Open ToolX SNMP tab

Step 2: Configure target

1. Enter IP Address of the device
2. Set Community String (usually "public")
3. Select SNMP Version (v2c for most devices)

Step 3: Click "Walk" to scan the device

The MIB browser will populate with OID tree.

Step 4: Inspect VIVOE-specific OIDs

For VIVOE compliance, check:

• .1.3.6.1.4.1.35990 - VIVOE enterprise OID
• Video stream configuration
• Encoding parameters
• Network settings

Common Issues:

Workflow 4: Network Diagnostics¶

When experiencing general network issues:

Step 1: Open ToolX Diagnostics tab

Step 2: Click "Run Diagnostics"

The diagnostics will check:

• Network interface status
• IP configuration
• Multicast group memberships
• IGMP snooping status
• Routing table

Step 3: Review results

Look for:

• ✅ Interface UP with valid IP
• ✅ Multicast groups joined (224.x.x.x)
• ✅ Default route configured
• ❌ Interface DOWN
• ❌ No multicast groups
• ❌ Missing routes

Step 4: Fix identified issues

# Bring interface up
sudo ip link set eth0 up

# Add multicast route
sudo ip route add 224.0.0.0/4 dev eth0

# Join multicast group manually
sudo ip maddr add 239.192.1.1 dev eth0

Advanced Debugging¶

Debugging Multicast Issues¶

Problem: Streams work locally but not across switches

1. Run ToolX Diagnostics on both machines
2. Compare multicast group memberships
3. Check switch IGMP snooping configuration

# On sender
./toolx --vaapi
# Start a test stream

# On receiver (different subnet)
./toolx
# Check if stream appears in SAP listener

Switch Configuration (example for managed switch):

# Enable IGMP snooping
igmp snooping enable
igmp snooping vlan 1

# Enable IGMP querier if no multicast router
igmp snooping querier enable

Debugging Codec Issues¶

Problem: Stream generates but receiver shows artifacts

1. Try different codecs:

# Test with software encoder
./toolx --openh264

# Test with native encoder (lower latency)
./toolx --openh264-native

1. Check encoder availability:

# Check GStreamer VAAPI
gst-inspect-1.0 vaapih264enc

# Check GStreamer OpenH264
gst-inspect-1.0 openh264enc

# Check VA-API support
vainfo

1. Monitor encoding errors in terminal output

Debugging High Latency¶

Problem: Video has noticeable delay

1. Use native encoders for lower latency:

./toolx --vaapi-native
# or
./toolx --openh264-native

1. Reduce resolution for testing:
2. Start with 640x480

3. Gradually increase to find limit

4. Check network latency:

ping -c 100 <receiver_ip> | tail -1

Capturing Stream Metadata¶

For detailed stream analysis:

1. Start ToolX and discover streams
2. Note the SDP information shown for each stream
3. Use this to configure other tools:

# Use ffmpeg to capture stream
ffmpeg -i "rtp://239.192.1.1:5004" -c copy output.ts

# Use VLC to view stream
vlc rtp://239.192.1.1:5004

Common Debugging Scenarios¶

Scenario: Video Freezes Intermittently¶

Symptom: Video plays then freezes, resumes, freezes again

Debug Steps:

1. Check network statistics:

netstat -su  # UDP statistics
# Look for packet drops

1. Run ToolX diagnostics - check for interface errors

2. Monitor CPU usage during streaming:

top -p $(pgrep toolx)

1. Try software encoder to rule out GPU issues:

./toolx --openh264

Scenario: SAP Announcements Not Received¶

Symptom: Stream generator works but SAP listener empty

Debug Steps:

1. Verify SAP multicast is reaching the interface:

sudo tcpdump -i eth0 host 224.2.127.254 -n

1. Check if firewall blocks SAP:

sudo iptables -L -n | grep 9875

1. Verify multicast route exists:

ip route get 224.2.127.254

Scenario: SNMP Walk Returns Empty¶

Symptom: Walk completes but no OIDs shown

Debug Steps:

1. Verify basic connectivity:

ping <device_ip>

1. Test with command-line snmpwalk:

snmpwalk -v2c -c public <device_ip> .1.3.6

1. Check if device supports SNMPv2c:

snmpwalk -v1 -c public <device_ip> .1.3.6

Best Practices¶

During Development¶

1. Test streams locally first before network testing
2. Use software encoding (--openh264) for portability
3. Start with low resolution (640x480) then scale up
4. Monitor terminal output for encoder errors

During Integration Testing¶

1. Document working configurations (codec, resolution, IP)
2. Test across network segments to verify multicast routing
3. Run diagnostics on all participating nodes
4. Verify SNMP compliance on VIVOE equipment

During Production Debugging¶

1. Start ToolX on the problem node first
2. Run diagnostics before making changes
3. Compare with known-working configuration
4. Capture stream metadata for support requests

Quick Reference¶

Keyboard Shortcuts¶

Common Multicast Addresses¶

Default Ports¶

See Also¶

• ToolX Reference - Complete feature reference
• Debugging with LdmX - DDS debugging
• External Applications - Building GVA apps
• BMS Application - Example with video integration