The chat responses are generated using Generative AI technology for intuitive search and may not be entirely accurate. They are not intended as professional advice. For full details, including our use rights, privacy practices and potential export control restrictions, please refer to our Generative AI Service Terms of Use and Generative AI Service Privacy Information. As this is a test version, please let us know if something irritating comes up. Like you get recommended a chocolate fudge ice cream instead of an energy managing application. If that occurs, please use the feedback button in our contact form!
Skip to content

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
Make sure the following Environment variables in the `.env` file inside the folder are set according to your ROS 2 environment.
# [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
Afterwards start ROSie with:
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.

TIA Import External Source

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:

TIA Generate Blocks From Source

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.

TIA Generate Warning Blocks Get Overwritten

Afterwards the following blocks are generated into your TIA project:

TIA Generated Blocks

And the following UDTs representing the ROS 2 msg types inside your TIA portal:

TIA Generated UDTs

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:

TIA Create PSC

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.

TIA PSC Naming

Load your OpenController or IPC device into the .psc file by dragging and dropping the device onto the created Memory Card file:

TIA Create PSC Of Device

A dialog will open. Press on load to load the device configuration into the .psc file.

TIA Load PSC

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.

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 inside the Industrial OS of your selected device.

RIB_App

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