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 |
---|---|
|
Gazebo Library (provided with libs/scenario_execution_gazebo) |
|
Helpers Library (provided with scenario_execution) |
|
Kubernetes Library (provided with libs/scenario_execution_kubernetes) |
|
ROS Nav2 navigation stack Library (provided with libs/scenario_execution_nav2) |
|
Library to interact with the operating system (provided with libs/scenario_execution_os) |
|
Robotics Library (provided with scenario_execution) |
|
ROS Library (provided with scenario_execution_ros) |
|
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 within simulation |
|
|
|
|
Gazebo world name |
osc_object.delete()
Delete an object from the simulation.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Entity name within simulation |
|
|
|
|
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 |
---|---|---|---|
|
|
|
The frame Id to spawn the actor relative to. |
|
|
|
The parent frame ID against which movement is evaluated. |
|
|
distance value relative to the frame_id at which to spawn the new actor |
|
|
|
|
Gazebo world name |
|
|
Model definition |
|
|
|
(optional) Comma-separated list of argument key:=value pairs |
osc_object.spawn()
Spawn an actor within simulation.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Pose of the spawned actor. |
|
|
|
Model definition |
|
|
|
|
Gazebo world name |
|
|
(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 filemodel://<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 |
---|---|---|---|
|
|
|
time to wait for the simulation. return failure afterwards. |
|
|
|
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 |
---|---|---|---|
|
|
|
Repeat this many times (-1 to repeat indefinitely) |
retry()
Modifier to retry a sub-tree until it succeeds.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Maximum number of permitted failures |
timeout()
Modifier to set a timeout for a sub-tree.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
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 |
---|---|---|---|
|
|
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 to execute |
|
|
|
|
Wait for the process to be finished. If false, the action immediately finishes |
|
|
|
(Only used if |
|
|
|
(Only used if |
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 |
---|---|---|---|
|
|
|
Kubernetes namespace |
|
|
|
set to true if you want to access the cluster from within a running container/pod |
|
|
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 |
---|---|---|---|
|
|
|
Kubernetes namespace |
|
|
|
set to true if you want to access the cluster from within a running container/pod |
|
|
The target element to delete |
|
|
|
|
Is the specified target a regular expression |
|
|
Type of the element to delete (e.g., |
|
|
|
|
Grace period to wait before forcing deletion |
kubernetes_patch_network_policy()
Patch an existing Kubernetes network policy.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
|
Kubernetes namespace |
|
|
|
set to true if you want to access the cluster from within a running container/pod |
|
|
The target network policy to patch |
|
|
|
Should ingress (i.e., incoming) network traffic be enabled |
|
|
|
Should egress (i.e., outgoing) network traffic be enabled |
|
|
|
key-value pair to match (e.g., |
kubernetes_patch_pod()
Patch an existing pod. If patching resources, please check feature gates
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
|
Kubernetes namespace |
|
|
|
set to true if you want to access the cluster from within a running container/pod |
|
|
The target pod to patch |
|
|
|
Patch to apply. Example: |
kubernetes_pod_exec()
Execute a command within a running pod
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
|
Kubernetes namespace |
|
|
|
set to true if you want to access the cluster from within a running container/pod |
|
|
The target pod to execute the command in |
|
|
|
Command to execute |
|
|
|
|
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 |
---|---|---|---|
|
|
|
Kubernetes namespace |
|
|
|
set to true if you want to access the cluster from within a running container/pod |
|
|
The target network policy to monitor |
|
|
|
Expected status of the network policy, e.g., |
kubernetes_wait_for_pod_status()
Wait for a Kubernetes pod to reach a specified state.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
|
Kubernetes namespace |
|
|
|
set to true if you want to access the cluster from within a running container/pod |
|
|
The name of the pod to monitor |
|
|
|
Expected status of the pod, e.g., |
|
|
|
|
Is the specified target a regular expression |
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 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 |
---|---|---|---|
|
|
Name of the action to connect to |
|
|
|
Class of the action type (e.g. |
|
|
|
Call content (e.g. |
|
|
|
|
succeed on goal acceptance |
assert_lifecycle_state()
Checks for the state of a lifecycle-managed node.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Name of |
|
|
|
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 |
|
|
|
|
If true, allows skipping of states at the beginning of |
|
|
|
If true and an unexpected transition or final state occurs, the action fails. Otherwise it succeed. |
|
|
|
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 |
---|---|---|---|
|
|
The frame Id to check for movement. |
|
|
|
|
The parent frame ID against which movement is evaluated. |
|
|
Timeout without movement. |
|
|
|
|
Translation speed below this threshold is skipped. |
|
|
|
Rotational speed below this threshold is skipped. |
|
|
|
If true, start measuring only after first message is received. |
|
|
|
namespace of tf and tf_static topic. |
|
|
|
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 to wait for message |
|
|
|
The time to compare. |
|
|
|
|
operator to compare latency time. |
|
|
|
check for the latency over the x elements. |
|
|
|
if true, start measuring only after first message is received. |
|
|
Class of message type, only required when 'wait_for_first_message' is set to false (e.g. |
bag_play()
Play back a ROS bag.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
path to ROS bag directory, either absolute or relative to scenario-file directory |
|
|
|
topics to publish, if empty all topics are published |
|
|
|
|
wether to publish to /clock |
|
|
|
if |
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 |
---|---|---|---|
|
|
List of topics to capture |
|
|
|
|
Add a timestamp suffix to output directory name |
|
|
|
Whether to record hidden topics |
|
|
|
Storage type to use (empty string: use ROS bag record default) |
|
|
|
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 |
---|---|---|---|
|
|
Name of the topic to connect to |
|
|
|
Class of the message type (e.g. |
|
|
|
|
QoS Preset Profile for the subscriber |
|
|
|
Name of the type member to check. If empty, the whole type is checked |
|
|
Expected value |
|
|
|
|
The comparison operator to apply |
|
|
|
return failure if there is no data yet |
|
|
|
return failure if comparison failed |
|
|
|
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 |
---|---|---|---|
|
|
Name of the topic to connect to |
|
|
|
Class of the message type (e.g. |
|
|
|
|
QoS Preset Profile for the subscriber |
|
|
Path to python file containing the external check function |
|
|
|
python function to be called. The function is expected to have the signature: |
|
|
|
|
return failure if there is no data yet |
|
|
|
return failure if comparison failed |
|
|
|
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 |
---|---|---|---|
|
|
Traveled distance at which the action succeeds. |
|
|
|
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 |
---|---|---|---|
|
|
Distance at which the action succeeds. |
|
|
|
Reference point to measure to distance to (z is not considered) |
|
|
|
|
Defines the TF frame id of the robot |
|
|
|
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 |
|
|
|
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 |
---|---|---|---|
|
|
|
if specified, a matching message must also match the module name |
|
|
list of strings (in python syntax, e.g. "['foo', 'bar']") |
ros_launch()
Execute a ROS launch file.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Package that contains the launch file |
|
|
|
Launch file name |
|
|
|
ROS arguments (get forwarded as key:=value pairs) |
|
|
|
|
If true, the action waits until the execution is finished |
|
|
|
(Only used |
service_call()
Call a ROS service and wait for the reply.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Name of the service to connect to |
|
|
|
Class of the message type (e.g. |
|
|
|
Service call content |
set_node_parameter()
Set a parameter of a node.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Name of the node |
|
|
|
Name of the parameter |
|
|
|
Value of the parameter |
topic_monitor()
Subscribe to a topic and store the last message within a variable.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
name of the topic to monitor |
|
|
|
class of the message type (e.g. |
|
|
|
variable to store the received value (e.g. a |
|
|
|
|
QoS profile for the subscriber (default: |
topic_publish()
Publish a message on a topic.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Name of the topic to publish to |
|
|
|
Class of the message type (e.g. |
|
|
|
Value to publish (can either be a string that gets parsed, a struct or a message object stored within a variable) |
|
|
|
|
QoS Preset Profile for the subscriber (default: |
wait_for_data()
Wait for any message on a ROS topic.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
Name of the topic to connect to |
|
|
|
Class of the message type (e.g. |
|
|
|
|
QoS Preset Profile for the subscriber (default: |
wait_for_nodes()
Wait for nodes to get available.
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
List of nodes to wait for |
wait_for_topics()
Wait for topics to get available (i.e. publisher gets available).
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
|
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 |
---|---|---|---|
|
|
|
Name of the resulting video file (use |
|
|
|
Frame-rate of the resulting video |