debug-transport

name	debug-transport
description	Debug and troubleshoot the NetMQ transport layer, port allocation, and device communication. Use when: diagnosing connection failures, debugging message flow, troubleshooting port conflicts, verifying device registration.

Debug Transport Issues

Reference guide for diagnosing and fixing issues in CLOiSim's NetMQ transport layer.

When to Use

• Plugin fails to start or register its transport ports
• External ROS 2 bridge cannot connect to a device
• Messages are not being received or published
• Port allocation conflicts
• Device appears in device_list but data doesn't flow

Transport Architecture

CLOiSimPlugin                    External Bridge (cloisim_ros)
    ↓                                      ↓
 Transporter                          connects to
    ├── Publisher  (PUB, bind)  ←─── Subscriber (SUB, connect)
    ├── Subscriber (SUB, bind) ←─── Publisher  (PUB, connect)
    ├── Responsor  (REP, bind) ←─── Requestor  (REQ, connect)
    └── Requestor  (REQ, bind) ←─── Responsor  (REP, connect)

All CLOiSim sockets bind on tcp://*:{port}. The bridge connects.

Diagnostic Steps

1. Check Port Allocation

Via WebSocket API:

# Get all registered devices and ports
echo '{"command":"port_list"}' | websocat ws://localhost:8080/control

# Get device map (grouped by model/plugin/parts)
echo '{"command":"device_list"}' | websocat ws://localhost:8080/control

Via code (Unity Console):

// BridgeManager logs all allocations after world load:
BridgeManager.PrintAllocatedHistory();

// Check if a specific port is allocated:
var port = BridgeManager.SearchSensorPort(hashKey);

Port hash key format: {modelName}{partsName}{subPartsName}{controlKey}

2. Check Plugin Startup

Every plugin fires a Started event. If a plugin doesn't start:

1. Check PluginStartTracker — it logs which plugins haven't started
2. Verify SDF <plugin filename="ClassName"> matches the actual C# class name exactly
3. Check Unity Console for "[Plugin] No plugin(xxx) exist" warnings
4. Verify OnStart() coroutine completes (must yield return null at the end)

3. Verify Thread Health

// In a plugin, check if threads are running:
// CLOiSimPluginThread manages background threads
// Each thread has a 50ms timeout join during cleanup

// Thread naming convention:
// Threads are added via AddThread(port, threadFunction, device)
// Thread functions: SenderThread, ReceiverThread, ServiceThread

4. Common Failure Modes

Symptom	Cause	Fix
"Failed to Bind" in Console	Port already in use	Kill previous CLOiSim instance; check ss -tlnp | grep 49152
Plugin not in device_list	filename doesn't match class name	Fix SDF <plugin filename=""> to match C# class name exactly
TX data not flowing	Device Mode mismatch	Ensure device Mode matches plugin thread type (TX_THREAD for SenderThread)
RX data not received	Hash mismatch	Verify subscriber hash matches publisher hash
Service timeout	HandleCustomRequestMessage not handling request	Add case for the request type in the plugin
NullReferenceException in thread	Device component not found	Check GetComponent<>() in OnAwake(), ensure device is on same GameObject

5. Message Flow Debugging

TX (publishing) flow:

Device.GenerateMessage() or Device.EnqueueMessage()
  → DeviceMessageQueue.Enqueue()
  → SenderThread: DeviceMessageQueue.Dequeue()
  → Publisher.Publish(data, hash)
  → NetMQ PUB socket send

RX (receiving) flow:

NetMQ SUB socket recv
  → ReceiverThread: Subscriber.Subscribe()
  → Device.ProcessReceivedDeviceMessage()

Service (request/reply) flow:

NetMQ REP socket recv
  → ServiceThread: Responsor receives request
  → CLOiSimPlugin.HandleCustomRequestMessage()
  → Responsor sends response

6. Port Range

• Range: 49152–65535 (ephemeral ports)
• Allocation: sequential scan from 49152, checks IPGlobalProperties.GetActiveTcpConnections()
• Each device port is unique per CLOiSim instance

7. Hash-Based Message Tagging

Each transport connection uses a ulong hash for message routing:

// Hash is computed from the device path:
// StdHash.Hash64(modelName + partsName + subPartsName + controlKey)

// Publisher tags each message with hash
// Subscriber filters by matching hash
// If hashes don't match, messages are silently dropped

8. Cleanup Verification

On OnDestroy(), plugins automatically:

1. Join all threads (50ms timeout per step, up to 500ms total)
2. Dispose Transporter (closes all NetMQ sockets)
3. Deallocate ports from BridgeManager

If ports aren't freed, check:

• _thread.Dispose() is being called
• DeregisterDevice() runs (logs removed hash keys)
• No orphaned CLOiSimPlugin instances (destroyed GameObjects should trigger OnDestroy)

Network Debugging Commands

# Check which ports CLOiSim is binding:
ss -tlnp | grep -E '4915[2-9]|49[2-9][0-9]{2}|[5-6][0-9]{4}'

# Check WebSocket service:
curl -s http://localhost:8080/

# Test WebSocket commands:
echo '{"command":"fps"}' | websocat ws://localhost:8080/control
echo '{"command":"reset"}' | websocat ws://localhost:8080/control

Adding Debug Logging to a Plugin

protected override IEnumerator OnStart()
{
	if (RegisterTxDevice(out var portTx, "Data"))
	{
		Debug.Log($"[{name}] TX registered on port {portTx}");
		AddThread(portTx, SenderThread, _sensor);
	}
	else
	{
		Debug.LogError($"[{name}] Failed to register TX device");
	}

	yield return null;
}