Introduction

Vortex is integrated to ROS2 by mean of C++ extensions and python scripts. Such extensions and scripts are subscribing or publishing topics. The C++ extensions implement specific existing ROS2 message types (see below for a list). Python3 embedded scripts allow the users to write any publishers or subscribers on any topic type they need.

Please, visit ROS2 Tutorial 5: Using Python3 Embedded Scripts for more details on this topic.

C++ extensions

Here is a list of C++ extensions that are used to interface Vortex to ROS2. They are part of the plugin file called ROS2Plugin.vxp

ROS2 must be installed and the path variable must be set for the Vortex to find the ROS2 dlls at run time. This version of Vortex is based on the binary packages for ROS 2 Foxy Fitzroy Patch Release 4 (2020-12-11)

ROS2Module

The ROS2Module is required to be in the setup file that is loaded by the Vortex Application that does co-simulation with ROS2. Otherwise, the C++ extension listed below will not work properly. The Vortex log file should contains some information if such problems is encountered.

Adding the ROS2Module to a setup document is done like others, follow the link for more details, Editor Setup.

The ROS2Module is found in the toolbox in the Module category.

The ROS2Module contains one parameter called "Root Frame ID". It's a string that is used to define the static frame_id of tf2.

Note that the default value is "map". See ROS2 Transform Stamped for more details.

TF2

Any Vortex Application can broadcast a full TF2 tree over ROS2. There is two C++ extensions involved in this process.

The 'Transform Broadcaster' and the 'Transform Stamped Message'. These extensions can be added to a mechanism or a scene. They are found in the toolbox under the ROS2 category.

ROS2 Transform Broadcaster

This extension can be found in the toolbox with name 'Transform Broadcaster' under the ROS2 category. It implements the broadcasting of Transform Stamped Message over ROS2. Internally, the extension creates a ROS2 Broadcaster with the given 'Node Name' and the given 'Namespace'. The ROS2 node is created at simulation start and is destroyed at simulation stop. For convenience, the FQN of the ROS2 node is given in the output section of the extension. This extension is used by 'Transform Stamped Message' extensions.

See next section ROS2 Transform Stamped for more details.

ROS2 Transform Stamped

This C++ extension can be found in the toolbox with the name 'Transform Stamped Message' under the ROS2 category. It is responsible to broadcast over ROS2 geometry_msgs::msg::TransformStamped messages.

The property view of a 'Transform Stamped Message' extension is as follow:

The first parameter called 'Broadcaster' takes an extension of type 'Transform Broadcaster' (ROS2 Transform Broadcaster). Not having the broadcaster set will result in an error at start of the simulation.

The parameter 'Frame ID' is of type string. This value is the base name for the child_frame_id data member of the TransformStamped struct.

The parameter 'IMobile' takes the value of the Vortex object for which its transform will be published.

The output 'Frame ID' takes the final name that will be used in the published transform stamped message, see Setting name for frame ids . This is provided for convenience.

The output 'Relative Position' and 'Relative Orientation' take the relative position and orientation as being broadcast.

Setting name for frame ids

Tf2 is expecting that all frame_id published are unique in a given simulation. In vortex, it's common to use several instances of a same mechanism in a scene. For such mechanisms that are publishing TF2 structures, this will generate some frame_id collision. To help in re-usability of mechanism in scenes, the 'Transform Stamped Messages' contains a set of rules to generate the final 'frame_id' that will published. The rules are inspired from the ROS2 naming convention for topics.

The rules are summarized as follows:

starts with	the rule (note: never starts with '/')	examples ( NS == namespace, NN == name of the node, foo == frame_id )
'~/'	prepends the namespace and the node name.	~/foo -> NS/NN/foo
'/'	absolute name -> no change (but leading '/' is removed).	/foo -> foo
''	relative name -> prepends the namespace of the node.	foo -> NS/frame_id

(notice to respect ros naming rules for frame_id, never a frame_id starts with '/')

Vortex doesn't make any check about if the Tf2 tree is consistent about unicity of named frame ids. Also, there is no characters filtering other than removing any '/' at the beginning of a named frame id.

TF tree structure

A TF tree can be made by parenting instances of a 'Transform Stamped Message'.
In the Vortex Editor, this can be achieved by dragging one instance of a 'Transform Stamped Message' over an other one (the parent). An entire TF tree can be created with this process.
The published transformation matrix of one 'Transform Stamped Message' is defined to be the relative transformation matrix between its parent and itself.

In general, in Vortex, it's up to the user to define the name of the extensions that are created.
For ROS2 Transform Stamped extension, the FQN of the frame_id is used to overwrite the name of the extension. This way, the explorer view of the Vortex Editor shows the Tf2 tree as it would appear in rviz2. It also allow to use the search of the Vortex Editor explorer view to quickly find a specific frame id. Notice that the final name is set at simulation start.

Explorer view	Rviz2 view

ROS2 Node

In order for Vortex to publish or subscribe topics over ROS2, some rclcpp::node must be created and be updated during simulation. The ROS2Node extension is meant for that. Whatever Vortex ROS2 extensions that publishes or subscribes a topic will use such ROS2Node.

The property window of the ROS2Node extension looks as the following.

The parameter called 'Node Name' is the name of the rclcpp::node that will be created by the extension.

The parameter called 'Namespace' is the name of the namespace in which the rclcpp::node will be created.

The parameter called 'QoS' is used to create the rclcpp::node with a choice of two Quality of Signal profiles: Default and Sensor. Please see the ROS2 documentation for more details about QoS profiles.

The output called 'FQN Node Name' is the fully qualified name of the rclcpp::node. If successfully created, the rclcpp::node will take that name. This is provided for convenience.

Not following the ROS2 node naming rules will fail creating the node. In such cases, the following error message is given:

Electro-Optical Sensor Co-Simulation

There are a few ROS sensor message types supported in Vortex. Among them, Electro-Optical sensors of type point_cloud2, laser_scan and image. Each of them requires a dedicated C++ extension. C++ implementation has been chosen over python for performance reasons.

ROS2 PointCloud2 Publisher

This extension can be found in the tool box under the category ROS2. It can be added to a scene, a mechanism or an assembly document.

The property window of the ROS2 PointCloud2 Publisher is as follow:

The parameter called 'ROS2 Node' must be assigned to an extension pointer of type ROS2 Node (see the previous section ROS2 Node). Otherwise an error message will be given.

The parameter called 'Lidar Sensor' must be assigned to a Lidar Sensor extension pointer. Not providing a Lidar for this field will result in an error message. Please, make sure that the parameter 'Output as distance field' of the lidar is not selected.

The parameter called 'Topic Base Name' will be used to set the name of the topic be published. Not following the ROS2 topic naming rules will result in a failure to create the topic and hence the extension will not work properly.

The parameter called 'Frame ID' is the name of the TF2 frame_id used in the point cloud2 message. During simulation, TF2 must contain a frame_id with this name in order to have this message properly processed by the ROS2 simulation. Look at the TF2 section above to see how to manage TF2 data in Vortex ROS2 Integration. In particular, please, pay attention to the naming rules used by ROS2 Transform Stamped to deals with frame_ids (Setting name for frame ids).

The output called 'FQN Topic Name' gives the final name of topic as set by ROS2 upon the creation of the publisher. This output is for convenience. Take note that simulation must be stepped in order to have the value of the output defined. An empty field indicates that the topic has been successfully created by ROS2. Check for error message on the extension and/or the log file of the application.

Browser not supported