Class RosEndpointConnector
An IConnector that communicates with a ROS endpoint over a persistent TCP connection using the ROS TCP Connector protocol, supporting both ROS 1 and ROS 2.
Implements
Inherited Members
Namespace: Unity.SimulationPro.RosIntegrations
Assembly: Unity.SimulationPro.RosIntegrations.dll
Syntax
public class RosEndpointConnector : IConnector
Remarks
Manages pub/sub, service calls, and system commands on a background thread. Use Subscribe<T>(string, Action<T>) to receive messages, RegisterPublisher<T>(string) and GetTopic(string) to publish, and ImplementService<TRequest, TResponse>(string, Func<TRequest, TResponse>) to host Unity-side ROS services. Add a RosEndpointConnectorComponent to a scene GameObject for Inspector-driven configuration.
Constructors
RosEndpointConnector(bool, string, int, float, float, float, float)
Initializes a new RosEndpointConnector.
Declaration
public RosEndpointConnector(bool isRos2, string ipAddress = "127.0.0.1", int port = 10000, float keepaliveTime = 1, float networkTimeoutSeconds = 2, float sleepTimeSeconds = 0.01, float serviceResponseTimeoutSeconds = 30)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | isRos2 |
|
| string | ipAddress | IP address of the ROS TCP server. Defaults to |
| int | port | TCP port of the ROS TCP server. Defaults to |
| float | keepaliveTime | Seconds of inactivity before a keepalive ping is sent. |
| float | networkTimeoutSeconds | Seconds to wait for a network response before considering the connection lost. |
| float | sleepTimeSeconds | Time in seconds the send loop sleeps between iterations. |
| float | serviceResponseTimeoutSeconds | Seconds a service request waits for its response before failing. Pass |
Properties
EndPointPort
Gets or sets the TCP port of the ROS endpoint. Defaults to 10000.
Declaration
public int EndPointPort { get; set; }
Property Value
| Type | Description |
|---|---|
| int |
EndpointIPAddress
Gets or sets the IP address of the ROS TCP endpoint. Defaults to "127.0.0.1".
Declaration
public string EndpointIPAddress { get; set; }
Property Value
| Type | Description |
|---|---|
| string |
HasConnectionError
The HasConnectionError.
Declaration
public bool HasConnectionError { get; }
Property Value
| Type | Description |
|---|---|
| bool |
ServiceResponseTimeoutSeconds
Gets or sets how long a service request waits for its response before failing with a
TimeoutException. Defaults to 30. Set to 0 to wait forever.
Declaration
public float ServiceResponseTimeoutSeconds { get; set; }
Property Value
| Type | Description |
|---|---|
| float |
Methods
AddNewTopicsListener(Action<ITopicInfo>, bool)
Registers a callback that is invoked whenever a new topic is discovered.
Declaration
public void AddNewTopicsListener(Action<ITopicInfo> callback, bool notifyAllExistingTopics = false)
Parameters
| Type | Name | Description |
|---|---|---|
| Action<ITopicInfo> | callback | The callback to invoke with the new ITopicInfo. |
| bool | notifyAllExistingTopics | When |
Connect()
Initiates the TCP connection to the configured endpoint using the current EndpointIPAddress and EndPointPort.
Declaration
public void Connect()
Connect(string, int)
Updates the endpoint address and port, then initiates the TCP connection.
Declaration
public void Connect(string ipAddress, int port)
Parameters
| Type | Name | Description |
|---|---|---|
| string | ipAddress | The IP address or hostname of the ROS TCP endpoint. |
| int | port | The TCP port of the ROS TCP endpoint. |
Disconnect()
Cancels the background connection thread and closes the TCP connection.
Declaration
public void Disconnect()
GetAllTopics()
Returns all currently known topic states.
Declaration
public IEnumerable<ITopicInfo> GetAllTopics()
Returns
| Type | Description |
|---|---|
| IEnumerable<ITopicInfo> | An enumerable of ITopicInfo for every known topic. |
GetOrCreateTopic(string, MessageTypeId, bool)
Returns the existing RosTopicState for topic, creating a new one if necessary.
If the topic already exists with a different message type, the type is updated.
Declaration
public RosTopicState GetOrCreateTopic(string topic, MessageTypeId messageTypeId, bool isService = false)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| MessageTypeId | messageTypeId | The expected ROS message type for this topic. |
| bool | isService | Pass |
Returns
| Type | Description |
|---|---|
| RosTopicState | The result. |
GetTopic(string)
Returns the RosTopicState for the given topic name, or null if no such topic exists.
Declaration
public RosTopicState GetTopic(string topic)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
Returns
| Type | Description |
|---|---|
| RosTopicState | The result. |
GetTopicInfo(string, MessageDisambiguator)
Returns the ITopicInfo for the given topic, or null if the topic is unknown.
Declaration
public ITopicInfo GetTopicInfo(string topic, MessageDisambiguator disambiguator = MessageDisambiguator.Default)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| MessageDisambiguator | disambiguator | Pass Response to retrieve the service response topic state instead of the request state. |
Returns
| Type | Description |
|---|---|
| ITopicInfo | The ITopicInfo for the topic, or |
IPFormatIsCorrect(string)
IPFormatIsCorrect method.
Declaration
public static bool IPFormatIsCorrect(string ipAddress)
Parameters
| Type | Name | Description |
|---|---|---|
| string | ipAddress | The ipAddress. |
Returns
| Type | Description |
|---|---|
| bool |
|
ImplementService(string, MessageTypeId, MessageTypeId, Func<IMessage, IMessage>)
Registers an untyped synchronous Unity-side service implementation using explicit message type identifiers and the default queue size.
Declaration
public void ImplementService(string topic, MessageTypeId requestTypeId, MessageTypeId responseTypeId, Func<IMessage, IMessage> callback)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| MessageTypeId | requestTypeId | The message type identifier for the service request. |
| MessageTypeId | responseTypeId | The message type identifier for the service response. |
| Func<IMessage, IMessage> | callback | The function invoked with the request IMessage and returning the response. |
ImplementService(string, MessageTypeId, MessageTypeId, Func<IMessage, IMessage>, int?)
Registers an untyped synchronous Unity-side service implementation using explicit message type identifiers.
Declaration
public void ImplementService(string topic, MessageTypeId requestTypeId, MessageTypeId responseTypeId, Func<IMessage, IMessage> callback, int? queueSize = null)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| MessageTypeId | requestTypeId | The message type identifier for the service request. |
| MessageTypeId | responseTypeId | The message type identifier for the service response. |
| Func<IMessage, IMessage> | callback | The function invoked with the request IMessage and returning the response. |
| int? | queueSize | Maximum number of queued responses. Uses the default queue size when |
ImplementService<TRequest, TResponse>(string, Func<TRequest, Task<TResponse>>, int?)
Registers an asynchronous Unity-side service implementation for the given topic. The callback is awaited before the response is sent back to ROS.
Declaration
public void ImplementService<TRequest, TResponse>(string topic, Func<TRequest, Task<TResponse>> callback, int? queueSize = null) where TRequest : IMessage where TResponse : IMessage
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| Func<TRequest, Task<TResponse>> | callback | The async function invoked with the request and returning a task that produces the response. |
| int? | queueSize | Maximum number of queued responses. Uses the default queue size when |
Type Parameters
| Name | Description |
|---|---|
| TRequest | The ROS service request message type. |
| TResponse | The ROS service response message type. |
ImplementService<TRequest, TResponse>(string, Func<TRequest, TResponse>)
Registers a synchronous Unity-side service implementation for the given topic using the default queue size.
Declaration
public void ImplementService<TRequest, TResponse>(string topic, Func<TRequest, TResponse> callback) where TRequest : IMessage where TResponse : IMessage
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| Func<TRequest, TResponse> | callback | The function invoked with the request and returning the response. |
Type Parameters
| Name | Description |
|---|---|
| TRequest | The ROS service request message type. |
| TResponse | The ROS service response message type. |
ImplementService<TRequest, TResponse>(string, Func<TRequest, TResponse>, int?)
Registers a synchronous Unity-side service implementation for the given topic.
Declaration
public void ImplementService<TRequest, TResponse>(string topic, Func<TRequest, TResponse> callback, int? queueSize = null) where TRequest : IMessage where TResponse : IMessage
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| Func<TRequest, TResponse> | callback | The function invoked with the request and returning the response. |
| int? | queueSize | Maximum number of queued responses. Uses the default queue size when |
Type Parameters
| Name | Description |
|---|---|
| TRequest | The ROS service request message type. |
| TResponse | The ROS service response message type. |
Ping(Action<TimeSpan>)
Sends a ping to the endpoint and measures the round-trip time.
Declaration
public void Ping(Action<TimeSpan> callback)
Parameters
| Type | Name | Description |
|---|---|---|
| Action<TimeSpan> | callback | Invoked with the measured round-trip time when the response arrives. |
Publish(string, IMessage)
Publish method.
Declaration
public void Publish(string topicName, IMessage message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topicName | The topicName. |
| IMessage | message | The message data to visualize. |
RegisterPublisher(string, MessageTypeId)
Registers an untyped publisher for the given topic using an explicit message type identifier.
Declaration
public IPublisher RegisterPublisher(string topic, MessageTypeId messageTypeId)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| MessageTypeId | messageTypeId | The ROS message type identifier for this topic. |
Returns
| Type | Description |
|---|---|
| IPublisher | An IPublisher that can be used to publish messages. |
RegisterPublisher(string, MessageTypeId, int?, bool?)
Registers an untyped publisher for the given topic with optional queue size and latch overrides.
Declaration
public IPublisher RegisterPublisher(string topic, MessageTypeId messageTypeId, int? queueSize = null, bool? latch = null)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| MessageTypeId | messageTypeId | The ROS message type identifier for this topic. |
| int? | queueSize | Overrides the default outgoing message queue depth. Pass |
| bool? | latch | When |
Returns
| Type | Description |
|---|---|
| IPublisher | An IPublisher that can be used to publish messages. |
RegisterPublisher<T>(string)
Registers a typed publisher for the given topic, using the default queue size and latch setting.
Declaration
public IPublisher RegisterPublisher<T>(string rosTopicName) where T : IMessage
Parameters
| Type | Name | Description |
|---|---|---|
| string | rosTopicName | The ROS topic name to publish on. |
Returns
| Type | Description |
|---|---|
| IPublisher | An IPublisher that can be used to publish messages. |
Type Parameters
| Name | Description |
|---|---|
| T | The ROS message type to publish. |
RegisterPublisher<T>(string, int?, bool?)
Registers a typed publisher for the given topic with optional queue size and latch overrides.
Declaration
public IPublisher RegisterPublisher<T>(string rosTopicName, int? queue_size = null, bool? latch = null) where T : IMessage
Parameters
| Type | Name | Description |
|---|---|---|
| string | rosTopicName | The ROS topic name to publish on. |
| int? | queue_size | Overrides the default outgoing message queue depth. Pass |
| bool? | latch | When |
Returns
| Type | Description |
|---|---|
| IPublisher | An IPublisher that can be used to publish messages. |
Type Parameters
| Name | Description |
|---|---|
| T | The ROS message type to publish. |
RegisterServiceClient(string, MessageTypeId, MessageTypeId)
Creates an untyped IServiceClient using explicit message type identifiers.
Declaration
public IServiceClient RegisterServiceClient(string serviceName, MessageTypeId requestTypeId, MessageTypeId responseTypeId)
Parameters
| Type | Name | Description |
|---|---|---|
| string | serviceName | The ROS service topic name. |
| MessageTypeId | requestTypeId | The message type identifier for the service request. |
| MessageTypeId | responseTypeId | The message type identifier for the service response. |
Returns
| Type | Description |
|---|---|
| IServiceClient | An IServiceClient ready to send requests. |
RegisterServiceClient<TRequest, TResponse>(string)
Creates a typed IServiceClient for calling a ROS service.
Declaration
public IServiceClient RegisterServiceClient<TRequest, TResponse>(string serviceName) where TRequest : IMessage where TResponse : IMessage
Parameters
| Type | Name | Description |
|---|---|---|
| string | serviceName | The ROS service topic name. |
Returns
| Type | Description |
|---|---|
| IServiceClient | An IServiceClient ready to send requests. |
Type Parameters
| Name | Description |
|---|---|
| TRequest | The ROS service request message type. |
| TResponse | The ROS service response message type. |
RequestTopicListRefresh()
Requests an updated topic-and-type list from the ROS endpoint, rate-limited to once every five seconds.
Declaration
public void RequestTopicListRefresh()
SetIPPref(string)
SetIPPref method.
Declaration
public static void SetIPPref(string ipAddress)
Parameters
| Type | Name | Description |
|---|---|---|
| string | ipAddress | The ipAddress. |
SetPortPref(int)
SetPortPref method.
Declaration
public static void SetPortPref(int port)
Parameters
| Type | Name | Description |
|---|---|---|
| int | port | The port. |
Subscribe(string, MessageTypeId, Action<IMessage>)
Registers an untyped subscriber callback for the given topic using an explicit message type identifier.
Declaration
public void Subscribe(string topic, MessageTypeId messageTypeId, Action<IMessage> callback)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| MessageTypeId | messageTypeId | The ROS message type expected on this topic. |
| Action<IMessage> | callback | The action invoked with the deserialized message. |
Subscribe<T>(string, Action<T>)
Registers a typed subscriber callback for the given topic. The callback is invoked on the Unity main thread whenever a message is received.
Declaration
public void Subscribe<T>(string topic, Action<T> callback) where T : IMessage
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |
| Action<T> | callback | The action invoked with the deserialized message. |
Type Parameters
| Name | Description |
|---|---|
| T | The expected IMessage type for this topic. |
Unsubscribe(string)
Removes all subscriber callbacks registered for topic and sends an unsubscribe command to the ROS endpoint.
Declaration
public void Unsubscribe(string topic)
Parameters
| Type | Name | Description |
|---|---|---|
| string | topic | ROS topic name. |