YAML Configuration Structure¶
Table of Contents¶
Introduction¶
As ROSie provides a command line based interface for users, a service was needed to give users the possibility to specify their system using a YAML based configuration file.
In this configuration, users can declare the system, which stands for the ROS 2 package that will be the wrapper for all defined data structures. Additionally, users shall define the data structure connections based on ROS 2 topics.
System¶
An example of a system definition is shown below.
The generated package will setup a fully functional ROS 2 package, that works out out of the box by using the parameters specified below.
system:
ros2:
package_name: example_package
node_name: example_node
rib:
RIB_App_IPv4: 127.0.0.1
RIB_App_port: 27567
# optional
plc:
# optional
rib_config_db_name: "rib_config_topic_DB"
rib_connect_state_machine_fc_name: "rib_connect_build_up_FC"
system (required)
¶
The system
keyword specifies the content of the generated ROS 2 package.
system:
ros2 (required)
¶
The ros2
keyword declares all content that is ROS 2 specific.
ros2:
package_name (required)
¶
The package_name
keyword is used to define the name for the generated ROS 2 package.
package_name: <name>
node_name (required)
¶
The node_name
keyword is used to define the name for the generated ROS 2 node inside the package.
node_name: <name>
rib (required)
¶
The rib
keyword defines the connection to the RIB_App, that is used to manage different shared memory connections of the RIB.
rib:
RIB_App_IPv4 (required)
¶
The RIB_App_IPv4
keyword specifies the IPv4 address of the RIB_App, to which the RIB API will be connected to via TCP based connection.
Valid values are either localhost
or a correctly set IPv4 address e.g. 127.0.0.1
.
Note: The value can later be changed in the source code.
RIB_App_IPv4: localhost
RIB_App_port (required)
¶
The RIB_App_port
keyword is used to define the TCP based port, at which the RIB_App is reachable.
Valid are full numbers e.g. 80
.
Note: The value can later be changed in the source code.
RIB_App_port: <name>
plc (optional)
¶
The plc
keyword declares all content that is PLC specific.
plc:
rib_config_db_name (optional)
¶
The rib_config_db_name
keyword can be used to change the name of the data block associated to the connection control and status of the RIB. The default value is "RIB_CONFIG_DB".
rib_config_db_name: <name>
rib_connect_state_machine_fc_name (optional)
¶
The rib_connect_state_machine_fc_name
keyword can be used to change the name of the function block handling the automatic connection build up to the RIB. The default value is "RIB_CONNECT_STATE_MACHINE_FC".
rib_connect_state_machine_fc_name: <name>
Topic¶
The Topic
area relies on the principles of the ROS 2 topic system and is divided into two possible connection directions, either from ROS 2 to PLC or from PLC to ROS 2.
Those connections are based on the data structures that are defined within them.
ROS 2 to PLC¶
To define a ROS 2 subscriber that writes its received data to the PLC, the ros2_to_plc
tag shall be used.
Within it, all needed data structures can be specified. Each type specification will be used to create a corresponding subscriber within the generated ROS 2 package.
An example is provided below.
ros2_to_plc:
topics:
- type: "custom_msgs/msg/Type.msg"
ros2_topic: "/topic"
rate: 100.0
- type: "custom_msgs/msg/AnotherType.msg"
ros2_topic: "/another_topic"
rate: 5.0
ros2_to_plc (required)
¶
The ros2_to_plc
keyword defines the connection direction from ROS 2 to the PLC.
ros2_to_plc:
topics (required)
¶
The topics
keyword is used to clarify, that the created ROS 2 part will be a subscriber, that listens on a specified topic.
topics:
type (required)
¶
The type
keyword defines the ROS 2 based topic message type, that will be searched for either in the provided custom interface path or the ROS 2 standard installation path.
- type: "<package_name>/msg/<Type>.msg"
✔️ Valid values are:
- In case of a standard ROS 2 based message type e.g. geometry_msgs/msg/Twist located at the path specified via
USER_ROS2_INSTALLATION_PATH
ENV variable:
"geometry_msgs/msg/Twist.msg"
- In case of a custom message type from a custom interface package located at the path specified via
USER_ROS2_INTERFACE_INSTALLATION_PATH
ENV variable:
"custom_msgs/msg/Type.msg"
❌ Wrong values are e.g.:
"geometry_msgs/msg/Twist"
"geometry_msgs/Twist"
ros2_topic (required)
¶
The ros2_topic
keyword defines the ROS 2 topic name of the desired message type, where the '/' is optional.
⚠️ The name must be unique in the YAML configuration!
ros2_topic: "/<topic_name>"
ROS 2 topic namespaces can be provided e.g.:
ros2_topic: "robot_1/topic_name"
rate (required)
¶
The rate
keyword is used to define the rate in Hz, in which messages will be written to the PLC on the specified topic.
It is used to configure the interrupt cycle of the PLC side for this topic.
rate: 10.0 # in Hz
✔️ Valid subscription rates [Hz] are (as floating point values):
- All values > 0.0
- All values <= 1000.0
⚠️ Values must not match the exact real subscription rate, but one has to keep in mind, that each generated PLC interrupt OB will provide a cycle time with the same rate as specified in the YAML!
PLC to ROS 2¶
To define a ROS 2 publisher that reads the data received from the PLC and publishes it to ROS 2, the plc_to_ros2
tag shall be used.
Within it, all needed data structures can be specified similar to the configurations in the section ROS 2 to PLC. Each type specification will be used to create a corresponding publisher within the generated ROS 2 package.
An example is provided below.
plc_to_ros2:
topics:
- type: "custom_msgs/msg/Type.msg"
ros2_topic: "/topic"
rate: 250.0
- type: "sensor_msgs/msg/BatteryState.msg"
ros2_topic: "/battery"
rate: 1.0
plc_to_ros2 (required)
¶
The plc_to_ros2
keyword defines the connection direction from the PLC to ROS 2.
plc_to_ros2:
topics (required)
¶
The topics
keyword is used to clarify, that the created ROS 2 part will be a publisher, that publishes PLC data on a specified topic.
topics:
type (required)
¶
The type
keyword defines the ROS 2 based topic message type, that will be searched for either in the provided custom interface path or the ROS 2 standard installation path.
- type: "<package_name>/msg/<Type>.msg"
✔️ Valid values are:
- In case of a standard ROS 2 based message type e.g. geometry_msgs/msg/Twist located at the path specified via
USER_ROS2_INSTALLATION_PATH
ENV variable:
"geometry_msgs/msg/Twist.msg"
- In case of a custom message type from a custom interface package located at the path specified via
USER_ROS2_INTERFACE_INSTALLATION_PATH
ENV variable:
"custom_msgs/msg/Type.msg"
❌ Wrong values are e.g.:
"geometry_msgs/msg/Twist"
"geometry_msgs/Twist"
ros2_topic (required)
¶
The ros2_topic
keyword defines the ROS 2 topic name of the desired message type, where the '/' is optional.
⚠️ The name must be unique in the YAML configuration!
ros2_topic: "/<topic_name>"
ROS 2 topic namespaces can be provided e.g.:
ros2_topic: "robot_1/topic_name"
rate (required)
¶
The rate
keyword is used to define the rate in Hz, in which messages will be read from the PLC on the specified topic.
It is used to configure the interrupt cycle of the PLC side as well as a ROS 2 based timer callback to read the data at the provided rate.
rate: 10.0 # in Hz
✔️ Valid subscription rates [Hz] are (as floating point values):
- All values > 0.0
- All values <= 1000.0
⚠️ Values must not match the exact real subscription rate, but one has to keep in mind, that each generated PLC interrupt OB will provide a cycle time with the same rate as specified in the YAML!
Example¶
Based on provided message type definitions in a custom interface_package
, a ROSie YAML configuration config.yaml
could look like the following:
system:
ros2:
package_name: custom_package
node_name: custom_node
rib:
RIB_App_IPv4: 127.0.0.1
RIB_App_port: 27567
ros2_to_plc:
topics:
- type: "interface_package/msg/Type.msg"
ros2_topic: "/topic"
rate: 50.0
- type: "interface_package/msg/AnotherType.msg"
ros2_topic: "/another_topic"
rate: 10.0
- type: "gemetry_msgs/msg/Twist.msg"
ros2_topic: "cmd_vel"
rate: 100.0
plc_to_ros2:
topics:
- type: "interface_package/msg/Type2.msg"
ros2_topic: "namespaced/topic2"
rate: 250.0
- type: "geometry_msgs/msg/PoseStamped.msg"
ros2_topic: "/pose"
rate: 50.0