Libraries

Beside osc.standard provided by OpenSCENARIO 2 (which we divide into osc.standard and osc.standard_base), multiple libraries are provided with scenario execution.

Name	Description
osc.gazebo	Gazebo Library (provided with libs/scenario_execution_gazebo)
osc.helpers	Helpers Library (provided with scenario_execution)
osc.kubernetes	Kubernetes Library (provided with libs/scenario_execution_kubernetes)
osc.nav2	ROS Nav2 navigation stack Library (provided with libs/scenario_execution_nav2)
osc.os	Library to interact with the operating system (provided with libs/scenario_execution_os)
osc.robotics	Robotics Library (provided with scenario_execution)
osc.ros	ROS Library (provided with scenario_execution_ros)
osc.x11	X11 Library (provided with libs/scenario_execution_x11)

Additional features can be implemented by defining your own library.

Gazebo

The library contains actions to interact with the Gazebo Simulation. Import it with import osc.gazebo. It's provided by the package libs/scenario_execution_gazebo.

actor_exists()

Waits for an actor to exist within simulation.

Parameter	Type	Default	Description
entity_name	string		Entity name within simulation
world_name	string	default	Gazebo world name

osc_object.delete()

Delete an object from the simulation.

Parameter	Type	Default	Description
entity_name	string		Entity name within simulation
world_name	string	default	Gazebo world name

osc_object.relative_spawn()

Spawn an actor relative to a given frame_id within simulation (at a specified distance in front of frame_id).

Parameter	Type	Default	Description
frame_id	string	base_link	The frame Id to spawn the actor relative to.
parent_frame_id	string	map	The parent frame ID against which movement is evaluated.
distance	length		distance value relative to the frame_id at which to spawn the new actor
world_name	string	default	Gazebo world name
model	string		Model definition
xacro_arguments	string		(optional) Comma-separated list of argument key:=value pairs

osc_object.spawn()

Spawn an actor within simulation.

Parameter	Type	Default	Description
spawn_pose: pose_3d	pose_3d		Pose of the spawned actor.
model	string		Model definition
world_name	string	default	Gazebo world name
xacro_arguments	string		(optional) Comma-separated list of argument key:=value pairs

Note

The model definition can be specified in different formats:

• file://<path-to-model>: Local path to model file

• model://<path-to-model>: Path relative to available model search paths

• <package-name>://<path-to-model>: Path relative to an available package (e.g. test/scenario_execution_gazebo_test/scenarios/test_spawn_exists_delete.osc)

• https:://fuel: Model from fuel.gazebosim.org (e.g. https://fuel.gazebosim.org/1.0/OpenRobotics/models/Beer)

If the file ending is .xacro the model is forwarded to xacro before getting spawned.

wait_for_sim()

Wait for simulation to become active (checks for simulation clock).

Parameter	Type	Default	Description
timeout	time	60s	time to wait for the simulation. return failure afterwards.
world_name	string	default	Gazebo world name

Helpers

The library contains basic helper methods. Import it with import osc.helpers.

Modifiers

inverter()

Modifier to invert the action result. A failing action will report success, a succeeding action will report failure.

repeat()

Modifier to repeat a sub-tree. If any of the included children report failure, the repetition stops and failure is reported.

Parameter	Type	Default	Description
count	int	-1	Repeat this many times (-1 to repeat indefinitely)

retry()

Modifier to retry a sub-tree until it succeeds.

Parameter	Type	Default	Description
count	int		Maximum number of permitted failures

timeout()

Modifier to set a timeout for a sub-tree.

Parameter	Type	Default	Description
count	int		Maximum number of permitted failures

failure_is_running()

Don't stop running.

failure_is_success()

Be positive, always succeed.

running_is_failure()

Got to be snappy! We want results...yesterday.

running_is_success()

Don't hang around...

success_is_failure()

Be depressed, always fail.

success_is_running()

The tickling never ends...

log()

For debugging purposes, log a string using the available log mechanism.

Parameter	Type	Default	Description
msg	string		String to log

run_process()

Run a process. Reports running while the process has not finished.

If wait_for_shutdown is false and the process is still running on scenario shutdown, shutdown_signal is sent. If the process does not shutdown within shutdown_timeout, signal.sigkill is sent.

Parameter	Type	Default	Description
command	string		Command to execute
wait_for_shutdown	bool	true	Wait for the process to be finished. If false, the action immediately finishes
shutdown_signal	signal	signal!sigterm	(Only used if wait_for_shutdown is false) Signal that is sent if a process is still running on scenario shutdown
shutdown_timeout	time	10s	(Only used if wait_for_shutdown is false) time to wait between shutdown_signal and SIGKILL getting sent, if process is still running on scenario shutdown

Kubernetes

The library contains actions to interact with the Kubernetes API. Import it with import osc.kubernetes. It's provided by the package libs/scenario_execution_kubernetes.

kubernetes_create_from_yaml()

Create a Kubernetes object (e.g., a pod or network policy) from a yaml file.

Parameter	Type	Default	Description
namespace	string	default	Kubernetes namespace
within_cluster	bool	false	set to true if you want to access the cluster from within a running container/pod
yaml_file	string		The yaml-file to use create the object from

kubernetes_delete()

Delete a Kubernetes element (e.g., a pod or network policy).

Parameter	Type	Default	Description
namespace	string	default	Kubernetes namespace
within_cluster	bool	false	set to true if you want to access the cluster from within a running container/pod
target	string		The target element to delete
regex	bool	false	Is the specified target a regular expression
element_type	kubernetes_element_type		Type of the element to delete (e.g., kubernetes_element_type!pod)
grace_period	time	5s	Grace period to wait before forcing deletion

kubernetes_patch_network_policy()

Patch an existing Kubernetes network policy.

Parameter	Type	Default	Description
namespace	string	default	Kubernetes namespace
within_cluster	bool	false	set to true if you want to access the cluster from within a running container/pod
target	string		The target network policy to patch
ingress_enabled	bool		Should ingress (i.e., incoming) network traffic be enabled
egress_enabled	bool		Should egress (i.e., outgoing) network traffic be enabled
match_label	key_value		key-value pair to match (e.g., key_value("app", "pod_name"))

kubernetes_patch_pod()

Patch an existing pod. If patching resources, please check feature gates

Parameter	Type	Default	Description
namespace	string	default	Kubernetes namespace
within_cluster	bool	false	set to true if you want to access the cluster from within a running container/pod
target	string		The target pod to patch
body	string		Patch to apply. Example: '{\"spec\":{\"containers\":[{\"name\":\"main\", \"resources\":{\"requests\":{\"cpu\":\"200m\"}, \"limits\":{\"cpu\":\"200m\"}}}]}}'

kubernetes_pod_exec()

Execute a command within a running pod

Parameter	Type	Default	Description
namespace	string	default	Kubernetes namespace
within_cluster	bool	false	set to true if you want to access the cluster from within a running container/pod
target	string		The target pod to execute the command in
command	list of string		Command to execute
regex	bool	false	Is the specified target a regular expression

kubernetes_wait_for_network_policy_status()

Wait for an existing Kubernetes network policy to reach a specified state.

Parameter	Type	Default	Description
namespace	string	default	Kubernetes namespace
within_cluster	bool	false	set to true if you want to access the cluster from within a running container/pod
target	string		The target network policy to monitor
status	kubernetes_network_policy_status		Expected status of the network policy, e.g., kubernetes_network_policy_status!added

kubernetes_wait_for_pod_status()

Wait for a Kubernetes pod to reach a specified state.

Parameter	Type	Default	Description
namespace	string	default	Kubernetes namespace
within_cluster	bool	false	set to true if you want to access the cluster from within a running container/pod
target	string		The name of the pod to monitor
status	kubernetes_pod_status		Expected status of the pod, e.g., kubernetes_pod_status!running
regex	bool	false	Is the specified target a regular expression

Nav2

The library contains actions to interact with the Nav2 navigation stack. Import it with import osc.nav2. It is provided by the package libs/scenario_execution_nav2.

differential_drive_robot.init_nav2()

Initialize nav2.

Parameter	Type	Default	Description
initial_pose	pose_3d		The initial pose to set during initialization
base_frame_id	string	base_link	Base Frame ID
use_initial_pose	bool	true	If false, no initial_pose is needed (useful when using slam instead of amcl for localization)
namespace_override	string		If set, it's used as namespace (instead of the associated actor's namespace)
wait_for_initial_pose	bool	false	If true the initial pose needs to be set externally (e.g. manually through rviz)

differential_drive_robot.nav_through_poses()

Use nav2 to navigate through poses.

Parameter	Type	Default	Description
goal_poses	list of pose_3d		Goal poses to navigate through
namespace_override	string	''	If set, it's used as namespace (instead of the associated actor's namespace)
action_topic	string	navigate_through_poses	Action name
success_on_acceptance	bool	false	succeed on goal acceptance

differential_drive_robot.nav_to_pose()

Use nav2 to navigate to goal pose.

Parameter	Type	Default	Description
goal_pose	pose_3d		Goal pose to navigate to
namespace_override	string		If set, it's used as namespace (instead of the associated actor's namespace)
action_topic	string	navigate_to_pose	Action name
success_on_acceptance	bool	false	succeed on goal acceptance

OS

The library contains actions to interact with the operating system. Import it with import osc.os. It is provided by the package libs/scenario_execution_os.

check_file_exists()

Report success if a file exists.

Parameter	Type	Default	Description
file_name	string		File to check

Robotics

The library contains elements reusable in different robotic contexts. Import it with import osc.robotics. It is provided by the package scenario_execution.

Actors

robot

A general robot actor.

ROS

The library contains actions to interact with ROS nodes. Import it with import osc.ros. It is provided by the package scenario_execution_ros.

Actors

differential_drive_robot

A differential drive robot actor inheriting from the more general robot actor

action_call()

Call a ROS action and wait for the result.

Parameter	Type	Default	Description
action_name	string		Name of the action to connect to
action_type	string		Class of the action type (e.g. example_interfaces.action.Fibonacci)
data	string		Call content (e.g. {\"order\": 3})
success_on_acceptance	bool	false	succeed on goal acceptance

assert_lifecycle_state()

Checks for the state of a lifecycle-managed node.

Parameter	Type	Default	Description
node_name	string		Name of lifecycle-managed node.
state_sequence	list of lifecycle_state		List of states that a node is expected to transition through. The last entry is the state that a node is expected to remain in. Allowed ['unconfigured', 'inactive', 'active', 'finalized] (e.g. [lifecycle_state!inactive, lifecycle_state!active])
allow_initial_skip	bool	false	If true, allows skipping of states at the beginning of state_sequence without reporting failure.
fail_on_unexpected	bool	true	If true and an unexpected transition or final state occurs, the action fails. Otherwise it succeed.
keep_running	bool	true	If true, the action keeps running while the last state in the state_sequence remains

assert_tf_moving()

Checks that a tf frame_id keeps moving in respect to a parent_frame_id. If there is no movement within timeout the action with failure. Speeds below threshold_translation and threshold_rotation are discarded. By default the action waits for the first transform to get available before starting the timeout timer. This can be changed by setting wait_for_first_transform to false. If the tf topics are not available on /tf and /tf_static you can specify a namespace by setting tf_topic_namespace.

Parameter	Type	Default	Description
frame_id	string		The frame Id to check for movement.
parent_frame_id	string	map	The parent frame ID against which movement is evaluated.
timeout	time		Timeout without movement.
threshold_translation	speed	0.01mps	Translation speed below this threshold is skipped.
threshold_rotation	angular_rate	0.01radps	Rotational speed below this threshold is skipped.
wait_for_first_transform	bool	true	If true, start measuring only after first message is received.
tf_topic_namespace	string	''	namespace of tf and tf_static topic.
use_sim_time	bool	false	In simulation, we need to look up the transform at a different time as the scenario execution node is not allowed to use the sim time

assert_topic_latency()

Check the latency of the specified topic (in system time). If the check with comparison_operator gets true, the action ends with failure.

Parameter	Type	Default	Description
topic_name	string		Topic name to wait for message
latency	time		The time to compare.
comparison_operator	comparison_operator	comparison_operator!le	operator to compare latency time.
rolling_average_count	int	1	check for the latency over the x elements.
wait_for_first_message	bool	true	if true, start measuring only after first message is received.
topic_type	string		Class of message type, only required when 'wait_for_first_message' is set to false (e.g. std_msgs.msg.String)

bag_play()

Play back a ROS bag.

Parameter	Type	Default	Description
source	string		path to ROS bag directory, either absolute or relative to scenario-file directory
topics	list of string		topics to publish, if empty all topics are published
publish_clock	bool	false	wether to publish to /clock
publish_clock_rate	float	1.0	if publish_clock is true, publish to /clock at the specified frequency in Hz, to act as a ROS Time Source.

bag_record()

Record a ROS bag, stored in directory output_dir defined by command-line parameter (default: .). If topics is specified, this action waits for all topics to be subscribed until it returns with success otherwise it immediately returns. The recording is active until the end of the scenario.

A common topic to record is /scenario_execution/snapshots which publishes changes within the behavior tree. When replaying the bag-file, this allows to visualize the current state of the scenario in RViz, using the scenario_execution_rviz plugin.

Parameter	Type	Default	Description
topics	list of string		List of topics to capture
timestamp_suffix	bool	true	Add a timestamp suffix to output directory name
hidden_topics	bool	false	Whether to record hidden topics
storage	string	''	Storage type to use (empty string: use ROS bag record default)
use_sim_time	bool	false	Use simulation time for message timestamps by subscribing to the /clock topic

check_data()

Compare received topic messages using the given comparison_operator, against the specified value. Either the whole message gets compared or a member defined by member_name.

Parameter	Type	Default	Description
topic_name	string		Name of the topic to connect to
topic_type	string		Class of the message type (e.g. std_msgs.msg.String)
qos_profile	qos_preset_profiles	qos_preset_profiles!system_default	QoS Preset Profile for the subscriber
member_name	string	''	Name of the type member to check. If empty, the whole type is checked
expected_value	string		Expected value
comparison_operator	comparison_operator	comparison_operator!eq	The comparison operator to apply
fail_if_no_data	bool	false	return failure if there is no data yet
fail_if_bad_comparison	bool	true	return failure if comparison failed
wait_for_first_message	bool	true	start checking with the first received message after action execution. If false, the check is executed on the last received message.

check_data_external()

Compare received topic messages using an external python function function_name defined in python file file_path relative to the scenario-file.

Parameter	Type	Default	Description
topic_name	string		Name of the topic to connect to
topic_type	string		Class of the message type (e.g. std_msgs.msg.String)
qos_profile	qos_preset_profiles	qos_preset_profiles!system_default	QoS Preset Profile for the subscriber
file_path	string		Path to python file containing the external check function
function_name	string		python function to be called. The function is expected to have the signature: def function_name(msg) -> bool
fail_if_no_data	bool	false	return failure if there is no data yet
fail_if_bad_comparison	bool	true	return failure if comparison failed
wait_for_first_message	bool	true	start checking with the first received message after action execution. If false, the check is executed on the last received message.

differential_drive_robot.odometry_distance_traveled()

Wait until a defined distance was traveled, based on odometry.

Parameter	Type	Default	Description
distance	length		Traveled distance at which the action succeeds.
namespace_override	string		if set, it's used as namespace (instead of the associated actor's namespace)

differential_drive_robot.tf_close_to()

Wait until a TF frame is close to a defined reference point.

Parameter	Type	Default	Description
threshold	length		Distance at which the action succeeds.
reference_point	position_3d		Reference point to measure to distance to (z is not considered)
robot_frame_id	string	base_link	Defines the TF frame id of the robot
sim	bool	false	In simulation, we need to look up the transform map --> base_link at a different time as the scenario execution node is not allowed to use the sim time
namespace_override	string	''	if set, it's used as namespace (instead of the associated actor's namespace)

log_check()

Wait for specific output in ROS log (i.e. /rosout topic). If any of the entries within values the action succeeds.

Parameter	Type	Default	Description
module_name	string	[]	if specified, a matching message must also match the module name
values	list of string		list of strings (in python syntax, e.g. "['foo', 'bar']")

ros_launch()

Execute a ROS launch file.

Parameter	Type	Default	Description
package_name	string		Package that contains the launch file
launch_file	string		Launch file name
arguments	list of key_value		ROS arguments (get forwarded as key:=value pairs)
wait_for_shutdown	bool	true	If true, the action waits until the execution is finished
shutdown_timeout	time	10s	(Only used if wait_for_shutdown is false) Time to wait between SIGINT and SIGKILL getting sent, if process is still running on scenario shutdown

service_call()

Call a ROS service and wait for the reply.

Parameter	Type	Default	Description
service_name	string		Name of the service to connect to
service_type	string		Class of the message type (e.g. std_srvs.msg.Empty)
data	string		Service call content

set_node_parameter()

Set a parameter of a node.

Parameter	Type	Default	Description
node_name	string		Name of the node
parameter_name	string		Name of the parameter
parameter_value	string		Value of the parameter

topic_monitor()

Subscribe to a topic and store the last message within a variable.

Parameter	Type	Default	Description
topic_name	string		name of the topic to monitor
topic_type	string		class of the message type (e.g. std_msgs.msg.String)
target_variable	variable		variable to store the received value (e.g. a var within an actor instance)
qos_profile	qos_preset_profiles	qos_preset_profiles!system_default	QoS profile for the subscriber (default: qos_preset_profiles!system_default)

topic_publish()

Publish a message on a topic.

Parameter	Type	Default	Description
topic_name	string		Name of the topic to publish to
topic_type	string		Class of the message type (e.g. std_msgs.msg.String)
value	string		Value to publish (can either be a string that gets parsed, a struct or a message object stored within a variable)
qos_profile	qos_preset_profiles	qos_preset_profiles!system_default	QoS Preset Profile for the subscriber (default: qos_preset_profiles!system_default)

wait_for_data()

Wait for any message on a ROS topic.

Parameter	Type	Default	Description
topic_name	string		Name of the topic to connect to
topic_type	string		Class of the message type (e.g. std_msgs.msg.String)
qos_profile	qos_preset_profiles	qos_preset_profiles!system_default	QoS Preset Profile for the subscriber (default: qos_preset_profiles!system_default)

wait_for_nodes()

Wait for nodes to get available.

Parameter	Type	Default	Description
nodes	list of string		List of nodes to wait for

wait_for_topics()

Wait for topics to get available (i.e. publisher gets available).

Parameter	Type	Default	Description
topics	list of string		List of topics to wait for

X11

The library contains actions to interact with the X11 window system. Import it with import osc.x11. It is provided by the package libs/scenario_execution_x11.

capture_screen()

Capture the screen content within a video.

Parameter	Type	Default	Description
output_filename	string	capture.mp4	Name of the resulting video file (use --output-dir command-line argument to store the file within a specific directory)
frame_rate	float	25.0	Frame-rate of the resulting video