Proposal for simulation interfaces

CMakeLists.txt

@@ -0,0 +1,46 @@
+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/Spawnable.msg"
+    "msg/SpawnPose.msg"
+)
+
+set(srv_files
+    "srv/DeleteEntity.srv"
+    "srv/GetEntities.srv"
+    "srv/GetEntityState.srv"
+    "srv/GetSpawnables.srv"
+    "srv/GetSpawnPoses.srv"
+    "srv/ResetSimulation.srv"
+    "srv/SetEntityState.srv"
+    "srv/SetSimulationPaused.srv"
+    "srv/SpawnEntity.srv"
+)
+
+rosidl_generate_interfaces(${PROJECT_NAME}
+  ${msg_files}
+  ${srv_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.

msg/Entity.msg

@@ -0,0 +1,5 @@
+# Entity ground truth state in the simulation
+
+string name                                 # Entity's scoped, unique name (including namespace)
+string description                          # Optional: additional information about entity.
+EntityState state                           # Entity current state

msg/EntityState.msg

@@ -0,0 +1,5 @@
+# Entity current pose and twist
+
+std_msgs/Header header                  # Frame and timestamp for pose and twist. Empty frame defaults world.
+geometry_msgs/Pose pose                 # Pose in reference frame, ground truth.
+geometry_msgs/Twist twist               # Twist in reference frame, ground truth.

msg/SpawnPose.msg

@@ -0,0 +1,6 @@
+# A named spawn pose (point)
+
+string point_name                         # Name of a spawn point.
+string point_description                  # Description for the user, e.g. "near the charging station".
+geometry_msgs/Pose spawn_pose             # Spawn point pose, which can be used with SpawnEntity.srv.
+geometry_msgs/Polygon bounds              # Optional: limits of spawning area around pose, e.g. ground level.

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".
+geometry_msgs/Polygon bounds              # Optional: shape bounding the entity, e.g. to determine valid spawn poses.

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, an user-ready error message.

srv/GetEntities.srv

@@ -0,0 +1,10 @@
+# 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[] entities                                   # All entities with names matching the filter, poses and twists.
+
+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 including pose and twist.
+
+bool success                                            # Return true if successful.
+string status_message                                   # Additional comments or error status.

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,7 @@
+# Reset the simulation to the start, including the entire scene and the simulation time.
+# Objects that were dynamically spawned are de-spawned.
+
+---
+
+bool success                        # Return true if successful.
+string status_message               # Additional comments or error status..

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,16 @@
+# 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 robot_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.
+geometry_msgs/Pose initial_pose     # Initial entity pose.
+
+---
+
+bool success                        # Return true if spawned successfully.
+string status_message               # Spawned entity full name (with namespace) on success or user-ready error message.