add-new-plugin

name	add-new-plugin
description	Add a new CLOiSimPlugin for bridging a device to the ROS 2 transport layer. Use when: creating a transport bridge for an existing device, adding bidirectional control, implementing a new actuator plugin.

Add a New Plugin

Step-by-step procedure for creating a new CLOiSimPlugin subclass that bridges a device (sensor or actuator) to the external ROS 2 bridge via NetMQ transport.

When to Use

• Bridging an existing Device subclass to the ROS 2 ecosystem
• Adding a new actuator/controller plugin (e.g., elevator, gripper, arm)
• Creating a bidirectional plugin that both publishes sensor data and receives commands

Procedure

1. Determine Plugin Architecture

Decide the transport topology:

Pattern	Ports	Use Case
TX-only	Service + TX	Read-only sensors (GPS, IMU, Lidar)
TX+RX	Service + TX + RX	Bidirectional (MicomPlugin: publishes encoder data, receives twist commands)
Service-only	Service	Config/query endpoints
TX+RX+Client	Service + TX + RX + Client	Full control (SimulationWorld: clock TX, control client)

2. Create the Plugin Class

Create Assets/Scripts/CLOiSimPlugins/MyPlugin.cs:

/*
 * Copyright (c) 2026 LG Electronics Inc.
 *
 * SPDX-License-Identifier: MIT
 */

using System.Collections;
using UnityEngine;
using Any = cloisim.msgs.Any;

public class MyPlugin : CLOiSimPlugin
{
	private SensorDevices.MySensor _sensor;
	// For bidirectional: private SensorDevices.MyCommand _command;

	protected override void OnAwake()
	{
		_type = ICLOiSimPlugin.Type.SENSOR;
		_sensor = gameObject.GetComponent<SensorDevices.MySensor>();
		// _command = gameObject.GetComponent<SensorDevices.MyCommand>();
	}

	protected override IEnumerator OnStart()
	{
		// 1. Service port (always first — handles info/config queries)
		if (RegisterServiceDevice(out var portService, "Info"))
		{
			AddThread(portService, ServiceThread);
		}

		// 2. TX port (sensor data publishing)
		if (RegisterTxDevice(out var portTx, "Data"))
		{
			AddThread(portTx, SenderThread, _sensor);
		}

		// 3. RX port (command reception — bidirectional only)
		// if (RegisterRxDevice(out var portRx, "Rx"))
		// {
		//     AddThread(portRx, ReceiverThread, _command);
		// }

		yield return null;
	}

	protected override void HandleCustomRequestMessage(
		in string requestType, in Any requestValue, ref DeviceMessage response)
	{
		switch (requestType)
		{
			case "request_transform":
				var devicePose = _sensor.GetPose();
				var deviceName = _sensor.DeviceName;
				SetTransformInfoResponse(ref response, deviceName, devicePose, _parentLinkName);
				break;

			// Add plugin-specific request handlers:
			// case "request_output_type":
			//     SetMyCustomResponse(ref response);
			//     break;

			default:
				break;
		}
	}

	// Overload for children-based requests (messages.Param with sub-params)
	protected override void HandleCustomRequestMessage(
		in string requestType, in List<messages.Param> requestChildren, ref DeviceMessage response)
	{
		switch (requestType)
		{
			default:
				break;
		}
	}
}

3. Read Plugin Parameters from SDF (Optional)

If the plugin needs SDF <plugin> parameters:

protected override IEnumerator OnStart()
{
	var pluginParameters = GetPluginParameters();
	if (pluginParameters != null)
	{
		// Read specific elements
		var myParam = pluginParameters.GetValue<float>("my_parameter");
		// Read nested elements
		var noiseElem = pluginParameters.GetElement("noise");
	}

	// ... register devices and threads ...
	yield return null;
}

4. Wire to SDF

The SDF world/model file references the plugin:

<plugin name="MyPlugin" filename="MyPlugin">
  <my_parameter>42.0</my_parameter>
  <ros2>
    <topic_name>/my_topic</topic_name>
    <frame_id>my_frame</frame_id>
  </ros2>
</plugin>

The filename attribute must exactly match the C# class name — the importer uses Type.GetType().

5. Add Common Response Helpers

Use base class static helpers for standard responses:

// Transform info (pose + frame_id)
SetTransformInfoResponse(ref response, deviceName, pose, parentLinkName);

// Camera info (intrinsics, distortion)
SetCameraInfoResponse(ref response, cameraSensor);

// ROS 2 common info (topic, frame_id)
SetROS2CommonInfoResponse(ref response, topicName, frameId);

// Empty ack (boolean true)
SetEmptyResponse(ref response);

6. Handle Cleanup

Cleanup is automatic via the base class OnDestroy():

• Threads joined with 50ms timeout per step
• Transport sockets closed
• Ports deallocated from BridgeManager

Override OnReset() only if the plugin has state that needs resetting:

protected override void OnReset()
{
	// Reset plugin-specific state
}

Multi-Device Plugin

For plugins managing multiple devices (e.g., MicomPlugin with motors + encoders), use CLOiSimMultiPlugin base class or manage multiple device references:

protected override void OnAwake()
{
	_type = ICLOiSimPlugin.Type.MICOM;
	_sensorDevice = gameObject.GetComponent<SensorDevices.MicomSensor>();
	_commandDevice = gameObject.GetComponent<SensorDevices.MicomCommand>();
}

protected override IEnumerator OnStart()
{
	if (RegisterServiceDevice(out var portService, "Info"))
		AddThread(portService, ServiceThread);

	if (RegisterTxDevice(out var portTx, "Tx"))
		AddThread(portTx, SenderThread, _sensorDevice);

	if (RegisterRxDevice(out var portRx, "Rx"))
		AddThread(portRx, ReceiverThread, _commandDevice);

	yield return null;
}

Checklist

• _type set in OnAwake() to appropriate ICLOiSimPlugin.Type
• Device component cached via GetComponent<>() in OnAwake()
• Service port registered and ServiceThread added
• TX/RX ports registered with correct keys
• HandleCustomRequestMessage() handles at least "request_transform"
• SDF <plugin filename=""> matches class name exactly
• OnStart() ends with yield return null
• License header on file
• No cleanup code needed — base class handles it