Warning

Warning: Unity Simulation is deprecated as of December 2023, and is no longer available.

Migrate from ROS-TCP-Connector to Simulation-ROS-Integrations

This section helps you migrate your code from our old ROS-TCP-Connector to our new packages. You can skip this section if you did use ROS-TCP-Connector package previously.

Migration Steps

These are the exact steps needed to move from ROS-TCP-Connector to Simulation-ROS-Integrations. The latter half of the page will go into greater detail on why each change was needed.

1. Change packages

In your Packages/manifest.json, remove the entry for ROS-TCP-Connector and add the entries for Simulation-Foundation and Simulation-ROS-Integrations (hopefully you already did this when reading Install the Authoring Tools)

2. Change Assembly References

Navigate to the Assembly Definitions in your Project's Scripts directory and remove any Assembly Definition References starting with Unity.Robotics.ROSTCPConnector or that say (Missing Reference). Add Unity.Simulation.Foundation and Unity.Simulation.ROS-Integrations to the Assembly Definition References list.

3. Update code to new API's

While there may be more to do depending on your particular project, at a minimum you will need to do the following, in the correct order.

  1. In any file with any using Unity.Robotics.* directives - remove all statements with this prefix and add a single using Unity.Simulation.Foundation
find . -type f -name "*.cs" -exec sed -i 's/Unity.Robotics.ROSTCPConnector;/Unity.Simulation.Foundation;/' {} \; &&
# catch and replace files that only had sub-domains of the Unity.Robotics.ROSTCPConnector namespace
find . -type f -name "*.cs" \( ! -exec grep -q "using Unity.Simulation.Foundation" {} \;  -exec grep -q "using Unity.Robotics.ROSTCPConnector" {} \; \) -exec sed -i 's/using Unity.Robotics.ROSTCPConnector.*;/using Unity.Simulation.Foundation;/' {} \; &&
# of the files we just modified, find and remove any extraneous Unity.Robotics includes
find . -type f -name "*.cs" \( -exec grep -q "using Unity.Simulation.Foundation" {} \;  -exec grep -q "using Unity.Robotics.ROSTCPConnector" {} \; \) -exec sed -i '/using Unity.Robotics.ROSTCPConnector/d' {} \;
  1. Find and replace all instances of ROSConnection.GetOrCreateInstance() with ConnectorInjector.FindConnector(this)
find . -type f -name "*.cs" -exec sed -i 's/ROSConnection.GetOrCreateInstance()/ConnectorInjector.FindConnector(this)/' {} \;
  1. Find and replace all member variables of type ROSConnection with IConnector (optionally, rename your m_Ros variables to something more generic like m_Connector)
find . -type f -name "*.cs" -exec sed -i 's/ROSConnection/IConnector/' {} \; &&
find . -type f -name "*.cs" -exec sed -i 's/m_Ros/m_Connector/' {} \;
  1. You should see deprecation warnings for any usage of the obsolete interface ROSConnection.Publish, which is no longer supported. You can manually change these now to this:
// member declaration in top of class:
IPublisher m_Publisher;
// ...
// In Start():
m_Publisher = m_Connector.RegisterPublisher<MessageType>(topicName);
// Where original publish call was:
m_Publisher.Publish(message);

or you may choose to tempt fate and continue using the deprecated method - it's up to you.

  1. Finally, clean up any dangling issues. The above steps are not an exhaustive migration, and there may still be instances in your code where you are depending on old versions of an API or class. Typically, if something (besides URDFImporter) depends on the Unity.Robotics namespace, that may be replaced with using Unity.Simulation.Foundation. Here is a small list of changes that may need to be made depending on what previous functionality you were using:

Clock: This has been moved from Unity.Robotics.Core to Unity.Simulation.Foundation - most of the Clock static interfaces for current time have been deprecated and can be safely replaced with Clock.Now

Accessing ROSTCPConnector parameters directly: If you still need to set ROS connection params directly, you may do so by replacing the old reference to ROSConnection with RosEndpointConnectorComponent. The fields you were accessing may have changed, though, so check for deprecation warnings, or you may need to inspect RosEndpointConnectorComponent to determine what the new name of your field is.

4. Update Unity Scenes

Previously, if ROSConnection and the TFSystem were not in the Scene when PlayMode started, they would be silently and automatically created. This is no longer true; the Scene runs as configured in the Editor. Since old versions of ROSConnection and TFSystem no longer, exist, this means that whether or not you had these Components in your scene, you will need to manually add instances of their new versions.

ROSConnection

The new version of the ROSConnection component is called the RosEndpointConnectorComponent. If you previously had the ROSConnection component in the scene, find it the object that held it and remove the Inspector panel which now holds the "Missing (Mono Script)" MonoBehaviour panel. Use "Add Component" to add the RosEndpointConnectorComponent, and configure it appropriately for your project.

TFSystem

TFSystem is now called TFSystemComponent. In most cases, it's good to attach this component to the same one that holds your Connector.

Clock publishing

If you previously had an object in the Scene which published a Clock message to ROS, you will want to replace it with the new ClockPublisher boilerplate in Foundation. Simply delete the old object, and create a new one with this new Component attached. For more information on clock management, see our pages on Controlling Time.

Other missing Components

It's possible that even after fixing the two above Components, when you enter PlayMode you will see additional Warnings like this:

776

some of these errors may have obvious fixes. For other subscribers/broadcasters that may be broken due to hard dependencies on the old packages, you will need to deal with them on a case by case basis to determine whether they should be fully re-written, or simply re-targeted at the new Package and its associated API's.

Explanation of Changes

Migrating ROSConnection Class

In ROS-TCP-Connector package, there was a singular ROSConnection class you would use. There were two ways to change the ROS settings:

  1. From the Unity menu bar, select Robotics -> ROS Settings. This would bring up the ROSConnection window.
  2. Add the ROSConnection component to your scene and configure the settings from the inspector window.

Both of these methods change the universal settings across the scene.

This has been replaced with RosEndpointConnectorComponent in Simulation-ROS-Integrations. Multiple connections can be supported by multiple RosEndpointConnectorComponent in the scene.

Migrating the Publishing Workflow

In ROS-TCP-Connector, we used the ROSConnection class to publish messages.

In Simulation-Foundation and Simulation-ROS-Integration, we have separated the interfaces for establishing the connection and publishing messages over that connection. We use IConnector/RosEndpointConnector interface/class to establish the connection and RegisterPublisher to register an IPublisher. The IPublisher is used to publish the messages. Refer to Sending and Receiving Messages Using the IPublisher Interface and Subscribe Method for more information.

Migrating the Subscription workflow

There is no significant change in the subscription workflow. ROS-TCP-Connector uses the ROSConnection class to subscribe a callback function for incoming messages on a topic.

Similarly, in Simulation-Foundation and Simulation-ROS-Integration, we use the"IConnector/ROSEndpointConnector" interface/class to subscribe to incoming messages. Refer to Sending and Receiving Messages Using the IPublisher Interface and Subscribe Method for more information.

Migrating the Service workflow

Hosting a Service in Unity

Similar to ROS-TCP-Connector, we useImplementService API in IConnector to implement the service in Simulation-Foundation. In "Simulation-Foundation", you are restricted to use the IMessage type to send and receive response from a service. There are four different function signatures of the new ImplementService API. Refer to Hosting a Service in Unity for more information.

Creating a service client in Unity

In ROS-TCP-Connector, we used the ROSConnection class's RegisterRosService API to register a service client.

In Simulation-Foundation and Simulation-ROS-Integration, we have separated the interfaces for creating a service client and sending service requests to that service. We use RegisterServiceClient to create an IServiceClient. The IServiceClient is used to send the requests to the service and receive a response to callback function or an asynchronous Task. Refer to Sending and Receiving Service Requests and Response Using the ImplementService Method and IServiceClient Interface.

Updated 2022-09-22T21:35:46.000Z