Usage¶
Prerequisites¶
Completed ROSie installer and workspace setup.
Generating ROS 2 - PLC Connection¶
1. Create interface description file config.yaml¶
At first a YAML file has to be created, which specifies the interfaces between ROS 2 and the used PLC program according to the rules described in the YAML Configuration Structure. This YAML file should be saved into the input folder in your ROSie Workspace.
A template for a working configuration looks like this:
# System description of the generated PLC code and ROS 2 package
system:
ros2:
package_name: rosie_example_package # Generated ROS 2 package name
node_name: rosie_node # Generated ROS 2 node name
rib:
RIB_App_IPv4: 127.0.0.1 # IPv4 address of the SHM control app: RIB_App
RIB_App_port: 27567 # Port of the SHM control app: RIB_App
# All topics that subscribe to a ROS 2 topic and write its data to the PLC
ros2_to_plc:
topics:
- type: "geometry_msgs/msg/Twist.msg" # The full ROS 2 message type defintion
ros2_topic: "/cmd_vel" # The ROS 2 topic name, also acts as DataBlock identifier in the PLC
rate: 200.0 # in [Hz]
# All topics that read data from the PLC and publish it on a ROS 2 topic
plc_to_ros2:
topics:
- type: "sensor_msgs/msg/BatteryState.msg" # The full ROS 2 message type defintion
ros2_topic: "/battery_state" # The ROS 2 topic name, also acts as DataBlock identifier in the PLC
rate: 10.0 # in [Hz]
Please note that there is also a provided example file under
workspace/input/valid_config_example.yaml
2. Start ROSie container¶
If you completed the ROSie setup successfully, you can now start the ROSie container by running the following command in the terminal:
start-rosie
Optional: Manual setup of the ROSie environment and start of the container
In case the install script was not executed, the ROSie environment can also be set up manually. Navigate to the installed ROSie package:cd path/to/rosie_workspace
# [REQUIRED]
# The users ROS 2 base installation path share directory that contains all standard interfaces including their .msg files.
# This directory has to be be mounted in the ROSie container to be able to lookup all standard types.
# Default: /opt/ros/humble
USER_ROS2_INSTALLATION_PATH=/opt/ros/humble
# [OPTIONAL]
# The user directory where the optionally needed custom interface is installed, e.g. /home/user/ros2_ws/install
USER_ROS2_INTERFACE_INSTALLATION_PATH=/home/user/ros2_ws/install
# [REQUIRED]
# The current directory where this .env file and the whole provided ROSie workspace is located
USER_ROSIE_WORKSPACE_PATH=/home/user/rosie_ws
docker compose run --name ROSie --rm ROSie
3. Generate PLC code using the ROSie command line tool¶
In the container environment, start the generation of the PLC code by choosing a configuration .yaml file located within the Workspace input folder.
rosie -c <config_file_name>.yaml
If your configuration is valid the output should look similar to this:
$ rosie -c config.yaml
##################################### ROSie #####################################
# Version: 0.2.0 #
# Date: 08.05.2025 #
# Time: 14:21:38 #
# Copyright © Siemens AG, 2025, and licensors. All rights reserved. #
# Portions include Open Source Software. See ReadMe_OSS_0.2.0.html for details. #
# The usage for safety-related applications is not intended. #
###################################################################################
Gathering ROS 2 message types information ...
Generating PLC code ...
Please import the generated PLC code into your TIA project, export the TIA project .psc file, and place into the ROSie input folder.
Please provide the file name of the .psc in the prompt when requested, e.g., 'tia_project.psc' and press ENTER to continue the generation process or 'n' and ENTER to exit the program.
Inside the output folder of your ROSie workspace a time-stamped folder has been created, that contains the generated PLC code. The path to the generated PLC sources is similar to the following:
workspace/output/time-stamp/output/plc_code/<time-stamp>_rosie_generated_rib_scl_structs.scl
4. Move generated PLC code to TIA V19 engineering machine¶
Now move the generated PLC source file <time-stamp>_rosie_generated_rib_scl_structs.scl to your TIA engineering machine. If you use a virtual machine you can use shared folders for example.
5. Import generated PLC source as external source file¶
Open the TIA project of your IPC or OpenController that shall establish a connection to ROS 2. Select the Software-Controller of the device and import the previously generated PLC source file into your TIA V19 project.
6. Generate blocks from external PLC source file¶
The imported source file can now be used to generate the PLC program blocks of the ROS 2 <-> PLC connection:
There will be a warning message informing you that any duplicate blocks will be overwritten. Make sure to have a backup of your project and acknowledge the warning dialog.
Afterwards the following blocks are generated into your TIA project:
And the following UDTs representing the ROS 2 msg types inside your TIA portal:
7. Create .psc file of the device containing the ROSie generated blocks¶
To proceed with the generation of the ROS 2 package of the ROS 2 <-> PLC connection a .psc file has to be created from your device inside the TIA project.
This can be done by pressing on Project/Memory card file/New/PC system configuration file:
Select the name of the .psc file. Don't use whitespaces inside the filename as this file will be used in a Linux-based OS in another step of the generation process.
Load your OpenController or IPC device into the .psc file by dragging and dropping the device onto the created Memory Card file:
A dialog will open. Press on load to load the device configuration into the .psc file.
8. Move .psc file to ROSie input directory¶
Now copy the created .psc file into the input directory of your ROSie workspace. If you are using a virtual machine you can use shared folders, or if using WSL, you can directly save into your WSL filesystem (normally found under \wsl$\Ubuntu)
9. Use .psc file to continue ROSie process to generate ROS 2 package¶
As the .psc file is now located in the ROSie context, you can now proceed with the generation of the ros2 package. The ROSie cli tool should still be waiting for the .psc file, at the state of the end of Step3. Type in the name of the .psc file you created and press enter.
$ rosie -c config.yaml
##################################### ROSie #####################################
# Version: 0.2.0 #
# Date: 08.05.2025 #
# Time: 14:26:42 #
# Copyright © Siemens AG, 2025, and licensors. All rights reserved. #
# Portions include Open Source Software. See ReadMe_OSS_0.2.0.html for details. #
# The usage for safety-related applications is not intended. #
###################################################################################
Gathering ROS 2 message types information ...
Generating PLC code ...
Please import the generated PLC code into your TIA project, export the TIA project .psc file, and place into the ROSie input folder.
Please provide the file name of the .psc in the prompt when requested, e.g., 'tia_project.psc' and press ENTER to continue the generation process or 'n' and ENTER to exit the program.
plc-system-config.psc
If the generation was successful, the output of the cli tool should look similar to this:
$ rosie -c config.yaml
##################################### ROSie #####################################
# Version: 0.2.0 #
# Date: 08.05.2025 #
# Time: 14:28:35 #
# Copyright © Siemens AG, 2025, and licensors. All rights reserved. #
# Portions include Open Source Software. See ReadMe_OSS_0.2.0.html for details. #
# The usage for safety-related applications is not intended. #
###################################################################################
Gathering ROS 2 message types information ...
Generating PLC code ...
Please import the generated PLC code into your TIA project, export the TIA project .psc file, and place into the ROSie input folder.
Please provide the file name of the .psc in the prompt when requested, e.g., 'tia_project.psc' and press ENTER to continue the generation process or 'n' and ENTER to exit the program.
plc-system-config.psc
User Input: plc-system-config.psc
TIA project .psc file <plc-system-config.psc> found in input workspace. Continuing generation process ...
Generating ROSie API library and ROS 2 package ...
Successfully generated ROS 2 package and PLC code.
10. Move generated ROS 2 package to your desired workspace and build the package¶
Congratulations the generation process is now done. You can find the generated ROS 2 package in the output folder of your ROSie workspace under:
workspace/time-stamp/output/ros2_package/ros2_package_name
Additionally, in the same output folder you will find the configuration .yaml file that was used for the creation of the ROS node, as well as logs from the creation process.
Please be sure to exit the ROSie container before continuing the process of moving your generated package. Otherwise some problems might arise while moving files around. To exit the container simply type exit into the command line.
a. Working on an existing ROS Workspace¶
In order to move the generated packages from your engineering system to your Runtime system, you can copy the complete folder containing the package that was created as an output, and copy it over to your runtime system's ROS workspace.
Afterwards, yo will need to install the RIB libraries on your IndustrialOS by running the install_rib_support_libs.sh script in the 3rd_party folder:
cd 3rd_party
sudo bash install_rib_support_libs.sh
Then run colcon build to build the ROSie generated ROS 2 package.
b. Creating a new container based ROS 2 Workspace¶
Another option is to create a docker image with the generated ROS 2 node in order to to copy it in the IndustrialOS. For that, copy the previously generated ROS 2 package - and in case of custom messages also ROS 2 packages containing the custom message definitions - to the ros2_ws/src directory in the application_example_ros2_deployment folder:
workspace/application_example_ros2_deployment/ros2_ws/src
Then, navigate to the package folder and run the following command to build the application example:
cd application_example_ros2_deployment
bash build_application_example.sh
The script will first search for the ROSie generated ROS 2 packages in the ros2_ws/src directory. If there are multiple ROSie generated ROS 2 packages the script will ask you to select the one you want to deploy.
Found multiple ROSie generated packages:
1) Package name: rosie_example_package
Node name: rosie_node
Version: 0.2.0
2) Package name: test_package
Node name: test_node
Version: 0.2.0
Please select an option: 1
After selecting the package, the script will build a docker image based on the ROS 2 Humble docker image, compiling the ROS 2 packages in the ros2_ws/src directory and setting up the required runtime dependencies for the generated ROSie node. Afterwards, the docker-compose.yaml file will be updated to use the selected package.
Save the docker image.
docker save rosie_app_example > rosie_app_example.tar
Copy the docker image into the IndustrialOS.
scp rosie_app_example.tar [USER]@[DESTINATION_HOST_IP]:rosie_app_example.tar
Copy the docker-compose.yaml file into the IndustrialOS.
scp docker-compose.yaml [USER]@[DESTINATION_HOST_IP]:docker-compose.yaml
Load the image again in the IndustrialOS.
ssh [USER]@[DESTINATION_HOST_IP]
docker load < rosie_app_example.tar
Now you are ready to run the generated ROS 2 package in the IndustrialOS.
Running the Generated Interface¶
1. Load PLC program to the SW-PLC¶
If not done already load the TIA project that was extended by the ROSie generated program blocks to the SW-PLC. The PLC-side will try to automatically connect to the RIB_App.
2. Start RIB_App¶
Start the RIB_App executable inside the Industrial OS of your selected device.
RIB_App
This application serves as a RIB participant broker like shown in the following illustration:
3. Start ROS 2 Node¶
Start the ROS 2 node using the docker-compose.yaml file in your IndustrialOS:
ssh [USER]@[DESTINATION_HOST_IP]
docker compose up