Proposal for simulation interfaces

CMakeLists.txt

@@ -0,0 +1,55 @@
+cmake_minimum_required(VERSION 3.8)
+project(simulation_interfaces)
+
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 17)
+  set(CMAKE_CXX_STANDARD_REQUIRED ON)
+endif()
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+find_package(ament_cmake REQUIRED)
+find_package(builtin_interfaces REQUIRED)
+find_package(geometry_msgs REQUIRED)
+find_package(rosidl_default_generators REQUIRED)
+find_package(std_msgs REQUIRED)
+
+set(msg_files
+    "msg/Entity.msg"
+    "msg/EntityState.msg"
+    "msg/EntityWithState.msg"
+    "msg/Spawnable.msg"
+    "msg/SpawnableBounds.msg"
+    "msg/SpawnPose.msg"
+)
+
+set(srv_files
+    "srv/DeleteEntity.srv"
+    "srv/GetEntities.srv"
+    "srv/GetEntityState.srv"
+    "srv/GetSimulatorFeatures.srv"
+    "srv/GetSpawnables.srv"
+    "srv/GetSpawnPoses.srv"
+    "srv/ResetSimulation.srv"
+    "srv/SetEntityState.srv"
+    "srv/SetSimulationPaused.srv"
+    "srv/SpawnEntity.srv"
+    "srv/StepSimulation.srv"
+)
+
+set(action_files
+    "action/MultiStepSimulation.action"
+)
+
+rosidl_generate_interfaces(${PROJECT_NAME}
+  ${msg_files}
+  ${srv_files}
+  ${action_files}
+  DEPENDENCIES builtin_interfaces std_msgs geometry_msgs
+  ADD_LINTER_TESTS
+)
+
+ament_export_dependencies(rosidl_default_runtime)
+
+ament_package()

README.md

@@ -1,2 +1,4 @@
-# simulation_interfaces
-Standard interfaces for interacting with simulators from ROS 2
+# Simulation Interfaces
+
+Standard ROS 2 interfaces for interacting with simulators. 
+Messages and services are documented in their respective files.

action/MultiStepSimulation.action

@@ -0,0 +1,11 @@
+# Assuming the simulation is paused, simulate a finite number of steps and return to paused state. 
+# The action returns feedback after each complete step.
+# For a service alternative, see StepSimulation, which often makes more sense when doing a single step (steps = 1).
+
+uint16 steps                        # Action goal: step through the simulation loop this many times.
+---
+bool success                        # Return true if stepping is supported and was successful.
+string status_message               # Additional comments or error status.
+                                    # Calling with simulation not paused will return failure and an appropriate message.
+---
+uint16 completed_steps              # Action feedback: number of completed steps in this action so far.

msg/Entity.msg

@@ -0,0 +1,4 @@
+# Entity name and description
+
+string name                                 # Scoped name of the entity. It must be unique (including namespace).
+string description                          # Optional: additional information about entity.

msg/EntityState.msg

@@ -0,0 +1,8 @@
+# Entity current pose and twist
+
+std_msgs/Header header                  # Frame and timestamp for pose and twist. Empty frame defaults to world.
+geometry_msgs/Pose pose                 # Pose in reference frame, ground truth.
+geometry_msgs/Twist twist               # Ground truth body twist in the reference frame.
+                                        # It is observed and defined in the local coordinates system of the body.
+                                        # See https://github.com/ros2/common_interfaces/pull/240 for conventions.
+geometry_msgs/Accel acceleration        # Linear and angular acceleration ground truth, following the same convention.

msg/EntityWithState.msg

@@ -0,0 +1,4 @@
+# Entity with its current ground truth state
+
+Entity entity                               # Entity name and description
+EntityState state                           # Entity current state

msg/SpawnPose.msg

@@ -0,0 +1,7 @@
+# A named spawn pose
+
+string pose_name                          # Name of a spawn pose. It does not need to be unique.
+string pose_description                 # Description for the user, e.g. "near the charging station".
+geometry_msgs/Pose pose                   # Spawn pose, which can be used with SpawnEntity.srv.
+
+SpawnableBounds spawn_bounds              # Optional spawn area bounds.

msg/Spawnable.msg

@@ -0,0 +1,5 @@
+# Robot or other object which can be spawned in simulation runtime.
+
+string uri                                # URI which will be accepted by SpawnEntity service.
+string description                        # Optional description for the user, e.g. "robot X with sensors A,B,C".
+SpawnableBounds spawn_bounds              # Optional spawn area bounds which fully encompass this object.

msg/SpawnableBounds.msg

@@ -0,0 +1,11 @@
+# Bounds for spawning an entity, e.g. to avoid spawning with other object overlap.
+# Spawn pose might be valid for a small object, but not suitable for a large one, or a differently shaped one.
+# These limits are relative to spawn pose or entity's top link transform, following ROS rep-103 conventions.
+
+# By default, both fields are zero vectors which means that spawning is unbounded.
+# Otherwise, the fields are expected to form a valid box containing the (0,0,0) point which is the spawn position.
+# You should check whether the entity simulation model fits within the bounds before spawning, to avoid overlaps and
+# unstable behavior.
+
+geometry_msgs/Vector3 upper_right        # Optional: the upper right corner of the spawn box.
+geometry_msgs/Vector3 lower_left         # Optional: the lower left corner of the spawn box.

package.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>simulation_interfaces</name>
+  <version>1.0.0</version>
+  <description>A package containing simulation interfaces including messages and services</description>
+  <maintainer email="adam.dabrowski@robotec.ai">Adam Dabrowski</maintainer>
+  <license>Apache License 2.0</license>
+  <url type="repository">https://github.com/ros-simulation/simulation-interfaces</url>
+  <author email="adam.dabrowski@robotec.ai">Adam Dabrowski</author>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <buildtool_depend>rosidl_default_generators</buildtool_depend>
+
+  <depend>builtin_interfaces</depend>
+  <depend>geometry_msgs</depend>
+  <depend>std_msgs</depend>
+
+  <exec_depend>rosidl_default_runtime</exec_depend>
+
+  <test_depend>ament_lint_common</test_depend>
+
+  <member_of_group>rosidl_interface_packages</member_of_group>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

srv/DeleteEntity.srv

@@ -0,0 +1,8 @@
+# Remove an entity (a robot, other object) by unique name from the simulation
+
+string name                         # Unique name with a namespace, as returned by SpawnEntity or GetEntities.
+
+---
+
+bool success                        # return true if deleted successfully.
+string status_message               # On failure, a user-friendly error message.

srv/GetEntities.srv

@@ -0,0 +1,12 @@
+# Get objects in the scene which can be interacted, e.g. with using SetEntityState.
+
+string filter                                       # Optional, defaults to empty. Return entities with matching names.
+                                                    # Entity names are matched with the filter regular expression.
+                                                    # An empty filter will result in all entities being returned.
+
+---
+
+EntityWithState[] entities                          # All entities with their states, matching the filter.
+
+bool success                                        # Return true if successful.
+string status_message                               # Additional comments or error status.

srv/GetEntityState.srv

@@ -0,0 +1,10 @@
+# Get state of an object. Valid objects are on the list returned by GetEntities.
+
+string name                                             # Unique name as returned by GetEntities / SpawnEntity.
+
+---
+
+EntityState entity_state                                # Entity ground truth state.
+
+bool success                                            # Return true if successful.
+string status_message                                   # Additional comments or error status.

srv/GetSimulatorFeatures.srv

@@ -0,0 +1,32 @@
+# Get a list of features supported by the simulator.
+# Simulators adhering to the standard need to implement at least this interface.
+
+---
+
+uint8 SPAWNING                  = 0      # Supports spawn interface (SpawnEntity).
+uint8 DELETING                  = 1      # Supports deleting entities (DeleteEntity).
+uint8 SPAWN_POSES               = 2      # Supports predefined spawn poses (GetSpawnPoses).
+uint8 SPAWN_BOUNDS              = 3      # Supports spawn bounds (SpawnableBounds).
+uint8 SPAWN_FORMAT_SDF          = 4      # Supports spawning from SDFormat specified in the uri field of SpawnEntity.
+uint8 SPAWN_FORMAT_URDF         = 5
+uint8 SPAWN_FORMAT_USD          = 6
+uint8 SPAWN_FORMAT_NATIVE       = 7      # Supports spawning from prefab / other simulator native format.
+
+uint8 ENTITY_STATE_LISTING      = 8      # Supports GetEntityState interface.
+uint8 ENTITY_STATE_SETTING      = 9      # Supports SetEntityState interface.
+
+uint8 SIMULATION_RESET          = 10     # Supports one or more ways to reset the simulation through ResetSimulation.
+uint8 SIMULATION_RESET_TIME     = 11     # Supports TIME flag for resetting.
+uint8 SIMULATION_RESET_OBJECTS  = 12     # Supports OBJECTS flag for resetting.
+uint8 SIMULATION_RESET_SPAWNED  = 13     # Supports SPAWNED flag for resetting.
+
+uint8 SIMULATION_PAUSE          = 14     # Supports SetSimulationPaused interface
+uint8 STEP_SIMULATION_SINGLE    = 15     # Supports single stepping through simulation with StepSimulation interface.
+uint8 STEP_SIMULATION_MULTIPLE  = 16     # Supports multi-stepping through simulation, either through StepSimulation.
+                                         # service or through MultiStepSimulation action.
+uint8 STEP_SIMULATION_ACTION    = 17     # Supports MultiStepSimulation action interface.
+
+
+uint8[] features                 # A list of simulation features as specified by the list above.
+string custom_info               # Optional: additional information for the caller, which could point to documentation,
+                                 # version compatibility and other useful meta information.

srv/GetSpawnPoses.srv

@@ -0,0 +1,10 @@
+# Get predefined spawn poses which is convenient to avoid spawning in invalid spaces.
+# This is an optional simulation feature: check status_message if you receive an empty spawn_poses vector,
+# to determine whether this feature is not supported by your simulator, or spawn poses are simply not defined.
+
+---
+
+SpawnPose[] spawn_poses                             # A list of predefined spawn_poses, which may be empty.
+
+bool success                                        # Return true if successful.
+string status_message                               # Additional comments or error status.

srv/GetSpawnables.srv

@@ -0,0 +1,9 @@
+# Return a list of resources which are valid as SpawnEntity uri fields (e.g. visible to or registered in simulator).
+# This interface is an optional extension and might not be implemented by your simulator, check the status_message.
+
+---
+
+Spawnable[] spawnables                              # Spawnable objects with URI and additional information.
+
+bool success                                        # Return true if successful.
+string status_message                               # Additional comments or error status.

srv/ResetSimulation.srv

@@ -0,0 +1,15 @@
+# Reset the simulation to the start, including the entire scene and the simulation time.
+# Objects that were dynamically spawned are de-spawned.
+
+uint8 DEFAULT=0                     # same as ALL.
+uint8 TIME=1                        # Reset simulation time to start.
+uint8 OBJECTS=2                     # Reset all poses and velocities.
+uint8 SPAWNED=4                     # De-spawns all spawned entities.
+uint8 ALL=7                         # Fully resets simulation to the start, as if it was closed and launched again.
+
+uint8 reset_scope                   # Scope of the reset. Note that simulators might only support some types of resets.
+
+---
+
+bool success                        # Return true if successful.
+string status_message               # Additional comments or error status, such as what reset types are supported.

srv/SetEntityState.srv

@@ -0,0 +1,9 @@
+# Set a state of an object, which will result in an instant change in its pose and/or twist.
+
+string name                             # Unique name as returned by GetEntities or SpawnEntity.
+EntityState state                       # New state to set immediately. The timestamp in header is ignored.
+
+---
+
+bool success                            # Return true if successful.
+string status_message                   # Additional comments or error status.

srv/SetSimulationPaused.srv

@@ -0,0 +1,9 @@
+# Pauses or unpauses the simulation
+
+bool pause                          # If true, sets simulation state to paused, otherwise sets it to running.
+                                    # If already in target state, nothing happens but status_message informs about it.
+
+---
+
+bool success                        # Return true if pausing / resuming was successful.
+string status_message               # Additional comments or error status.

srv/SpawnEntity.srv

@@ -0,0 +1,19 @@
+# Spawn an entity (a robot, other object) by name or URI
+
+string name                         # Suggest a name to give to the spawned entity. If left empty, it will be generated.
+                                    # Due to requirement for name uniqueness and the namespace, check the status_message
+                                    # to get an actual unique name to use for further queries.
+string uri                          # Resource such as SDF or URDF file, or in native format such as prefab.
+                                    # Valid URIs can be determined by calling GetSpawnables first,
+                                    # if the feature is supported by your simulator.
+string entity_namespace             # Spawn robot or another object with all its interfaces under this namespace.
+string reference_frame              # Optional initial pose reference frame. Defaults to global "world" frame.
+                                    # This ROS frame must be known to the simulator, e.g. of an object spawned earlier.
+geometry_msgs/Pose initial_pose     # Initial entity pose. Simulators should spawn the entity with its top-level link
+                                    # transform matching this pose.
+
+---
+
+bool success                        # Return true if spawned successfully.
+string status_message               # On failure, a user-friendly error message.
+string unique_name                  # Spawned entity full name (with namespace).

srv/StepSimulation.srv

@@ -0,0 +1,11 @@
+# If simulation is paused, take N steps and pause it back. The service only returns once stepping is complete, which
+# might take considerable time.
+# There is an alternative in MultiStepSimulation action, which is worth considering for a multi-step interface.
+
+uint16 steps                        # Step through the simulation loop this many times.
+
+---
+
+bool success                        # Return true if stepping is supported and was successful.
+string status_message               # Additional comments or error status.
+                                    # Calling with simulation not paused will return failure and an appropriate message.