Debug Plugin Lifecycle Transport

Debug Plugin Lifecycle and Transport

Use this skill when the failure is in the bridge layer between devices and the external ROS 2 side, not in scene-only behavior. The goal is to identify the exact lifecycle stage or transport registration step that failed, then validate that slice with the cheapest discriminating check.

When to Use

• World or model loading stalls on plugin startup
• A plugin never reaches Started
• port_list or device_list is missing expected entries
• A plugin binds ports but no data flows
• Service requests fail, time out, or return the wrong payload
• Destroy or reload paths leave ports allocated or threads alive

Current Runtime Contract

Plugin startup path

Awake() -> SetCustomHandleRequestMessage() -> OnAwake() -> Start() -> OnPluginLoad() -> name resolution -> DelayedOnStart() -> stagger by _globalSequence frames -> OnStart() -> _thread.Start() -> IsStarted = true -> Started event

Load-side coordination

• PluginStartTracker.Bind(...) subscribes to all CLOiSimPlugin instances under the loaded root.
• Main.LoadWorld() and Main.LoadModel() wait up to 30 seconds for all plugins to report Started.
• If a plugin never completes OnStart(), the load path times out and the world/model does not finish loading.

Transport registration path

• RegisterTxDevice, RegisterRxDevice, RegisterServiceDevice, and RegisterClientDevice all flow through PrepareDevice().
• PrepareDevice() allocates the hash key and port via BridgeManager.AllocateDevice(...), stores them in the plugin's local tracking lists, then initializes the corresponding NetMQ socket in Transporter.
• On destroy, the base class disposes threads, disposes transport, then deregisters the cached ports and hash keys.

Diagnostic Workflow

1. Start from the concrete symptom

Pick one entry point:

• timeout while loading a world or model
• missing port in port_list
• missing device in device_list
• request handler failure
• duplicate allocation or stale port after reload

Do not start by reading unrelated plugin families. Step directly to the plugin instance named by the world, test, stack trace, or log.

2. Identify the failing lifecycle stage

Ask which stage the plugin reached:

1. Awake() never ran or failed early
2. OnAwake() ran, but Start() setup did not complete
3. DelayedOnStart() began, but OnStart() never completed
4. OnStart() completed, but transport registration or thread startup is wrong
5. plugin started, but service or data flow is broken later
6. destroy or reload leaked ports or handlers

Use the cheapest local evidence you already have:

• timeout message from Main
• PluginStartTracker progress count
• BridgeManager.PrintAllocatedHistory()
• WebSocket port_list / device_list
• one failing request path or message flow

3. Form one local hypothesis

Write one claim that can fail. Examples:

• OnStart() exits early because RegisterTxDevice() fails and no fallback path reports the failure.
• The plugin never fires Started because OnStart() throws before _thread.Start().
• The request handler is wired, but the plugin-specific overload is not the one actually invoked.
• Teardown is re-entering with stale cached ports because deregistration did not clear the local lists.

Do not keep multiple speculative theories unless one nearby read is required to separate them.

4. Choose the cheapest discriminating check

Prefer checks in this order:

1. the exact failing load, request, or teardown behavior
2. the narrow EditMode test for the touched plugin
3. port_list / device_list or BridgeManager allocation history
4. a local compile of the touched plugin or test slice

git diff is not a transport or lifecycle check.

Symptom-Driven Checks

A. Load times out waiting for plugins

Focus on the plugin's OnStart() body.

Check:

• Does OnAwake() set _type correctly before registration?
• Does OnStart() always reach yield return null?
• Are Register*Device(...) return values checked, or does the plugin silently proceed after failure?
• Does the plugin depend on a device/component that can be null on this GameObject?
• Is Started being blocked because OnStart() throws or yields forever?

Why it matters:

• Started is fired only after OnStart() returns and _thread.Start() runs.
• The load path now has a 30-second timeout, so a hung plugin blocks the world/model load instead of hanging forever.