Proposal for simulation interfaces

CMakeLists.txt

@@ -0,0 +1,66 @@
+cmake_minimum_required(VERSION 3.16)
+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/Bounds.msg"
+    "msg/EntityCategory.msg"
+    "msg/EntityFilters.msg"
+    "msg/EntityInfo.msg"
+    "msg/EntityState.msg"
+    "msg/NamedPose.msg"
+    "msg/Result.msg"
+    "msg/SimulationState.msg"
+    "msg/SimulatorFeatures.msg"
+    "msg/Spawnable.msg"
+    "msg/TagsFilter.msg"
+)
+
+set(srv_files
+    "srv/DeleteEntity.srv"
+    "srv/GetEntities.srv"
+    "srv/GetEntitiesStates.srv"
+    "srv/GetEntityBounds.srv"
+    "srv/GetEntityInfo.srv"
+    "srv/GetEntityState.srv"
+    "srv/GetNamedPoseBounds.srv"
+    "srv/GetNamedPoses.srv"
+    "srv/GetSimulationState.srv"
+    "srv/GetSimulatorFeatures.srv"
+    "srv/GetSpawnables.srv"
+    "srv/ResetSimulation.srv"
+    "srv/SetEntityInfo.srv"
+    "srv/SetEntityState.srv"
+    "srv/SetSimulationState.srv"
+    "srv/SpawnEntity.srv"
+    "srv/StepSimulation.srv"
+)
+
+set(action_files
+    "action/SimulateSteps.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,25 @@
-# simulation_interfaces
-Standard interfaces for interacting with simulators from ROS 2
+# Simulation Interfaces
+
+Standard ROS 2 interfaces for interacting with simulators. 
+Messages, services, and actions are documented in their respective files.
+
+## Result.msg
+
+The standard includes a generic message for handling service responses, [Result.msg](msg/Result.msg),
+which will likely not be included in the final version of the standard. Since it is generic, it will either be promoted to a common message or included in the
+service mechanism itself. 
+
+## Suggested interface implementation priorities
+
+[GetSimulatorFeatures](msg/GetSimulationFeatures.msg) should be implemented first, as it provides users with information about
+the state of support for all standard simulation interfaces.
+
+Following that, aim for maintaining consistency within the implemented feature, such as enabling both
+_Get_ and _Set_ parts.
+
+Some interfaces represent optional utility and are considered lower priority:
+- [GetEntityBounds](srv/GetEntityBounds.srv)
+- [GetNamedPoseBounds](srv/GetNamedPoseBounds.srv)
+- [GetNamedPoses](srv/GetNamedPoses.srv)
+- [GetSpawnables](srv/GetSpawnables.srv)
+- [SetEntityInfo](srv/SetEntityInfo.srv)

action/SimulateSteps.action

@@ -0,0 +1,13 @@
+# 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).
+# Support for this interface is indicated through the STEP_SIMULATION_ACTION value in GetSimulationFeatures.
+
+uint64 steps                        # Action goal: step through the simulation loop this many times.
+---
+
+Result result                       # Calling with simulation unpaused will return OPERATION_FAILED and error message.
+
+---
+uint64 completed_steps              # number of completed steps in this action so far.
+uint64 remaining_steps              # number of steps remaining to be completed in this action.

msg/Bounds.msg

@@ -0,0 +1,25 @@
+# Bounds which are useful in several contexts, e.g. to avoid spawning with other object overlap,
+# or parking in a spot that is too small.
+# Certain goals or points might be valid for a small object, but not suitable for a large one,
+# or a differently shaped one.
+# Bounds can be also checked to ensure certain scenario conditions are met.
+# For entities, these limits are relative to entity's canonical link transform, following ROS rep-103 convention.
+
+# As bounds are optional in most interfaces, TYPE_EMPTY signifies empty bounds, to be understood as "unbounded".
+# Otherwise, the fields are expected to define a valid volume.
+# For spawning with a named pose, you should check whether the entity simulation model fits within the bounds
+# before calling SpawnEntity, to avoid overlaps and unstable behavior.
+
+# bounds type
+uint8 TYPE_EMPTY         = 0      # No bounds. The points vector will be empty.
+uint8 TYPE_BOX           = 1      # Axis-aligned bounding box, points field should have two values,
+                                  # which are upper right and lower left corners of the box.
+uint8 TYPE_CONVEX_HULL   = 2      # Points define a convex hull (at least 3 non-collinear points).
+uint8 TYPE_SPHERE        = 3      # A sphere with center and radius. First element of points vector is the center.
+                                  # The x field of the second point of the vector is the radius (y and z are ignored).
+
+
+uint8 type
+geometry_msgs/Vector3[] points           # Points defining the bounded area. Check type field to determine semantics.
+                                         # Valid sizes are zero (no bounds), 2 (sphere or box, depending on type field),
+                                         # and 3 or more (convex hull).

msg/EntityCategory.msg

@@ -0,0 +1,16 @@
+# Entity major category, which often warrants a specific way to handle such entity, e.g. when handling humans
+# or mapping persistence for dynamic vs static objects.
+
+uint8 CATEGORY_OBJECT         = 0    # Generic or unspecified type.
+uint8 CATEGORY_ROBOT          = 1    # A broad category for mobile robots, arms, drones etc.,
+                                     # usually with ROS 2 interfaces.
+uint8 CATEGORY_HUMAN          = 2    # Simulated humans, e.g. pedestrians, warehouse workers.
+                                     # Compared to CATEGORY_DYNAMIC_OBJECT, humans are often expected to be treated
+                                     # exceptionally in regards to safety constraints.
+uint8 CATEGORY_DYNAMIC_OBJECT = 4    # Vehicles, animals, mobile obstacles, typically to present a detection and
+                                     # tracking challenge, such as when simulation is used to test robot perception
+                                     # or navigation stack.
+uint8 CATEGORY_STATIC_OBJECT  = 5    # Any object which is static, e.g. not supposed to change its pose
+                                     # unless by means of SetEntityState.
+
+uint8 category

msg/EntityFilters.msg

@@ -0,0 +1,25 @@
+# A set of filters to apply to entity queries. See GetEntities, GetEntitiesStates.
+
+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.
+                                                    # The regular expression syntax is POSIX Extended,
+                                                    # see https://pubs.opengroup.org/onlinepubs/9799919799/ definitions.
+                                                    # Applies together with other filters (categories, tags).
+EntityCategory[] categories                         # Optional, defaults to empty, which means no category filter.
+                                                    # Entities matching any of the categories will be returned.
+                                                    # To get entity category, use GetEntityInfo.
+                                                    # Applies together with other filters (filter, tags).
+                                                    # Check ENTITY_CATEGORIES in GetSimulatorFeatures to determine if
+                                                    # your simulator supports entity categories.
+TagsFilter tags                                     # Tags filter to apply. To get entity tags, use GetEntityInfo.
+                                                    # Applies together with other filters (filter, categories).
+                                                    # Check support for this feature (ENTITY_TAGS) in GetSimulationFeatures.
+Bounds bounds                                       # if bounds are not empty, the overlap filter is applied
+                                                    # and entities overlapping with bounds will be returned.
+                                                    # Note that not all bound types might be supported by the simulator,
+                                                    # though at least TYPE_SPHERE needs to be supported.
+                                                    # Check ENTITY_BOUNDS_BOX and ENTITY_BOUNDS_CONVEX in GetSimulationFeatures
+                                                    # to determine whether your simulator supports other bound types.
+                                                    # If service is called with filter bounds set to an unsupported type,
+                                                    # a FEATURE_UNSUPPORTED result will be returned.

msg/EntityInfo.msg

@@ -0,0 +1,5 @@
+# Entity type and additional information
+
+EntityCategory category     # Major category for the entity. Extra entity type distinction can be made through tags.
+string description          # optional: verbose, human-readable description of the entity.
+string[] tags               # optional: tags which are useful for filtering and categorizing entities further.

msg/EntityState.msg

@@ -0,0 +1,8 @@
+# Entity current pose, twist and acceleration
+
+std_msgs/Header header                  # Reference 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 linear and angular velocities
+                                        # observed in the frame specified by header.frame_id
+                                        # 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/NamedPose.msg

@@ -0,0 +1,8 @@
+# A named pose defined in the simulation for certain purposes such as spawning.
+
+string name                               # Unique name.
+string description                        # Description for the user, e.g. "near the charging station".
+string[] tags                             # Optional tags which can be used to determine the named pose
+                                          # purpose, for example: "spawn", "parking", "navigation_goal",
+                                          # as well as fitting entity types e.g. "drone", "turtlebot3".
+geometry_msgs/Pose pose                   # Pose relative to world, which can be used with SpawnEntity.srv.

msg/Result.msg

@@ -0,0 +1,18 @@
+# Result code and message for service calls.
+# Note that additional results for specific services can defined within them using values above 100.
+
+uint8 RESULT_FEATURE_UNSUPPORTED   = 0    # Feature is not supported by the simulator, check GetSimulatorFeatures.
+                                          # While feature support can sometimes be deduced from presence of corresponding
+                                          # service / action interface, in other cases it is about supporting certain
+                                          # call parameters, formats and options within interface call.
+uint8 RESULT_OK                    = 1
+uint8 RESULT_NOT_FOUND             = 2    # No match for input (such as when entity name does not exist).
+uint8 RESULT_INCORRECT_STATE       = 3    # Simulator is in an incorrect state for this interface call, e.g. a service
+                                          # requires paused state but the simulator is not paused.
+uint8 RESULT_OPERATION_FAILED      = 4    # Request could not be completed successfully even though feature is supported
+                                          # and the input is correct; check error_message for details.
+                                          # Implementation rule: check extended codes for called service
+                                          #  (e.g. SpawnEntity) to provide a return code which is more specific.
+
+uint8 result                              # Result to be checked on return from service interface call
+string error_message                      # Additional error description when useful.

msg/SimulationState.msg

@@ -0,0 +1,16 @@
+# Simulation states used in SetSimulationState and returned in GetSimulationState
+
+uint8 STATE_STOPPED      = 0           # Simulation is stopped, which is equivalent to pausing and resetting with ALL.
+                                       # This is typically the default state when simulator is launched.
+                                       # Stopped simulation can be played. It can also be paused, which means
+                                       # starting simulation in a paused state immediately,
+                                       # without any time steps for physics or simulated clock ticks.
+uint8 STATE_PLAYING      = 1           # Simulation is playing, can be either paused or stopped.
+uint8 STATE_PAUSED       = 2           # Simulation is paused, can be either stopped (which will reset it) or played.
+uint8 STATE_QUITTING     = 3           # Closing the simulator application. Switching from STATE_PLAYING or STATE_PAUSED
+                                       # states is expected to stop the simulation first, and then exit.
+                                       # Simulation interfaces will become unavailable after quitting.
+                                       # Running simulation application is outside of the simulation interfaces as
+                                       # there is no service to handle the call when the simulator is not up.
+
+uint8 state

msg/SimulatorFeatures.msg

@@ -0,0 +1,45 @@
+# Features supported by the simulator.
+
+uint8 SPAWNING                  = 0       # Supports spawn interface (SpawnEntity).
+uint8 DELETING                  = 1       # Supports deleting entities (DeleteEntity).
+uint8 NAMED_POSES               = 2       # Supports predefined named poses (GetNamedPoses).
+uint8 POSE_BOUNDS               = 3       # Supports pose bounds (GetNamedPoseBounds).
+uint8 ENTITY_TAGS               = 4       # Supports entity tags in interfaces using EntityFilters, such as GetEntities.
+uint8 ENTITY_BOUNDS             = 5       # Supports entity bounds (GetEntityBounds).
+uint8 ENTITY_BOUNDS_BOX         = 6       # Supports entity filtering with bounds with TYPE_BOX.
+uint8 ENTITY_BOUNDS_CONVEX      = 7       # Supports entity filtering with Bounds TYPE_CONVEX_HULL.
+uint8 ENTITY_CATEGORIES         = 8       # Supports entity categories, such as in use with EntityFilters or SetEntityInfo.
+uint8 SPAWNING_RESOURCE_STRING  = 9       # Supports SpawnEntity resource_string field.
+
+uint8 ENTITY_STATE_GETTING      = 10      # Supports GetEntityState interface.
+uint8 ENTITY_STATE_SETTING      = 11      # Supports SetEntityState interface.
+uint8 ENTITY_INFO_GETTING       = 12      # Supports GetEntityInfo interface.
+uint8 ENTITY_INFO_SETTING       = 13      # Supports SetEntityInfo interface.
+uint8 SPAWNABLES                = 14      # Supports GetSpawnables interface.
+
+uint8 SIMULATION_RESET          = 20      # Supports one or more ways to reset the simulation through ResetSimulation.
+uint8 SIMULATION_RESET_TIME     = 21      # Supports SCOPE_TIME flag for resetting.
+uint8 SIMULATION_RESET_STATE    = 22      # Supports SCOPE_STATE flag for resetting.
+uint8 SIMULATION_RESET_SPAWNED  = 23      # Supports SCOPE_SPAWNED flag for resetting.
+uint8 SIMULATION_STATE_GETTING  = 24      # Supports GetSimulationState interface.
+uint8 SIMULATION_STATE_SETTING  = 25      # Supports SetSimulationState interface. Check SIMULATION_STATE_PAUSE feature
+                                          # for setting STATE_PAUSED.
+uint8 SIMULATION_STATE_PAUSE    = 26      # Supports the STATE_PAUSED SimulationState in SetSimulationState interface.
+
+uint8 STEP_SIMULATION_SINGLE    = 31      # Supports single stepping through simulation with StepSimulation interface.
+uint8 STEP_SIMULATION_MULTIPLE  = 32      # Supports multi-stepping through simulation, either through StepSimulation.
+                                          # service or through SimulateSteps action.
+uint8 STEP_SIMULATION_ACTION    = 33      # Supports SimulateSteps action interface.
+
+
+uint16[] features                         # A list of simulation features as specified by the list above.
+
+# A list of additional supported formats for spawning, which might be empty. Values may include
+#  * sdf (SDFormat)
+#  * urdf (Unified Robot Description Format)
+#  * usd (Universal Scene Description)
+#  * mjcf (MuJoCo's XML format)
+# or whatever simulator-native formats that are supported. 
+string[] spawn_formats
+string custom_info                       # Optional: extra information for the caller, which could point to
+                                         # documentation, version compatibility and other useful meta information.

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".
+Bounds spawn_bounds                       # Optional spawn area bounds which fully encompass this object.

msg/TagsFilter.msg

@@ -0,0 +1,10 @@
+# An utility message type for specification of tag-based filtering
+
+string[] tags                           # Optional, defaults to empty, which means no tags filter.
+                                        # Results matching any or all of tags will be returned, depending
+                                        # on tags_filter_mode.
+
+uint8 FILTER_MODE_ANY    = 0            # Filter with OR mode (any tag can match).
+uint8 FILTER_MODE_ALL    = 1            # Filter with AND mode (all tags need to match).
+
+uint8 filter_mode                       # Set to control filter application for tags.

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, services and actions</description>
+  <maintainer email="[email protected]">Adam Dabrowski</maintainer>
+  <license>Apache License 2.0</license>
+  <url type="repository">https://github.com/ros-simulation/simulation-interfaces</url>
+  <author email="[email protected]">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,9 @@
+# Remove an entity (a robot, other object) from the simulation.
+# Support for this interface is indicated through the DELETING value in GetSimulationFeatures.
+
+string entity                         # Entity identified by its unique name with a namespace,
+                                      # as returned by SpawnEntity or GetEntities.
+
+---
+
+Result result