Replace BatchSpawnEntities with SpawnEntities using SpawnEntity/SpawnResult messages.

Signed-off-by: Michał Pełka <michal.pelka@robotec.ai>

Author: michalpelka

CMakeLists.txt

@@ -27,13 +27,14 @@ set(msg_files
     "msg/Result.msg"
     "msg/SimulationState.msg"
     "msg/SimulatorFeatures.msg"
+    "msg/SpawnEntity.msg"
+    "msg/SpawnResult.msg"
     "msg/Spawnable.msg"
     "msg/TagsFilter.msg"
     "msg/WorldResource.msg"
 )
 
 set(srv_files
-    "srv/BatchSpawnEntities.srv"
     "srv/DeleteEntity.srv"
     "srv/GetAvailableWorlds.srv"
     "srv/GetCurrentWorld.srv"
@@ -53,6 +54,7 @@ set(srv_files
     "srv/SetEntityState.srv"
     "srv/SetSimulationState.srv"
     "srv/SpawnEntity.srv"
+    "srv/SpawnEntities.srv"
     "srv/StepSimulation.srv"
     "srv/UnloadWorld.srv"
 )

msg/SimulatorFeatures.msg

@@ -38,7 +38,7 @@ uint8 WORLD_UNLOADING           = 43      # Supports UnloadWorld interface
 uint8 WORLD_INFO_GETTING        = 44      # Supports GetCurrentWorld interface
 uint8 AVAILABLE_WORLDS          = 45      # Supports GetAvailableWorlds interface
 
-uint8 SPAWNING_BATCH            = 50      # Support batch spawning (SpawnEntities)
+uint8 SPAWNING_ENTITIES         = 50      # Support spawn multiple entities
 
 uint16[] features                         # A list of simulation features as specified by the list above.
 

msg/SpawnEntity.msg

@@ -0,0 +1,24 @@
+# Information about spawning an individual entity.
+
+string name                             # A name to give to the spawned entity.
+                                        # If empty, the name field in the URI file or resource_string will be used,
+                                        # if supported and not empty (e.g. "name" field in SDFormat, URDF).
+                                        # If the name is still empty or not unique (as determined by the simulator),
+                                        # the service returns a generated name in the entity_name response field if the
+                                        # allow_renaming field is set to true. Otherwise, the service call fails and an
+                                        # error is returned.
+bool allow_renaming                     # Determines whether the spawning succeeds with a non-unique name.
+                                        # If it is set to true, the user should always check entity_name response field
+                                        # and use it for any further interactions.
+
+Resource entity_resource                # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc.
+                                        # Valid URIs can be determined by calling GetSpawnables first. 
+                                        # Check simulator format support via the spawn_formats field in GetSimulatorFeatures.
+                                        # Using resource_string is supported if GetSimulatorFeatures includes
+                                        # the SPAWNING_RESOURCE_STRING feature.
+
+string entity_namespace                 # Spawn the entity with all its interfaces under this namespace.
+geometry_msgs/PoseStamped initial_pose  # Initial entity pose.
+                                        # The header contains a reference frame, which defaults to global "world" frame.
+                                        # This frame must be known to the simulator, e.g. of an object spawned earlier.
+                                        # The timestamp field in the header is ignored.

msg/SpawnResult.msg

@@ -0,0 +1,18 @@
+# Result of spawning.
+uint8 NAME_NOT_UNIQUE       = 101       # Given name is already taken by entity and allow_renaming is false.
+uint8 NAME_INVALID          = 102       # Given name is invalid in the simulator (e.g. does not meet naming
+                                        # requirements such as allowed characters). This is also returned if name is
+                                        # empty and allow_renaming is false.
+uint8 UNSUPPORTED_FORMAT    = 103       # Format for uri or resource string is unsupported. Check supported formats
+                                        # through GetSimulatorFeatures service, in spawn_formats field.
+uint8 NO_RESOURCE           = 104       # Both uri and resource string are empty.
+uint8 NAMESPACE_INVALID     = 105       # Namespace does not meet namespace naming standards.
+uint8 RESOURCE_PARSE_ERROR  = 106       # Resource file or string failed to parse.
+uint8 MISSING_ASSETS        = 107       # At least one of resource assets (such as meshes) was not found.
+uint8 UNSUPPORTED_ASSETS    = 108       # At least one of resource assets (such as meshes) is not supported.
+uint8 INVALID_POSE          = 109       # initial_pose is invalid, such as when the quaternion is invalid or position
+                                        # exceeds simulator world bounds.
+
+Result result
+string entity_name                      # Spawned entity full name, guaranteed to be unique in the simulation.
+                                        # If allow_renaming is true, it may differ from the request name field.

srv/BatchSpawnEntities.srv

@@ -0,0 +1,12 @@
+# Spawn multiple entities (robots, objects) by name or URI.
+# Support for this interface is indicated through the SPAWNING_ENTITIES value in GetSimulatorFeatures.
+
+SpawnEntity spawn_requests[]            # List of spawn requests.
+
+---
+
+# Additional result.result_code values for this service. Check result.error_message for further details.
+uint8 ENTITIES_SPAWN_FAILED    = 120       # There was at least one failed spawn request. Check individual results in the `results`.
+
+Result result                           # If one or more requests failed, it will give ENTITIES_SPAWN_FAILED otherwise RESULT_OK
+SpawnResult results[]                   # List of results for each spawn request.

srv/SpawnEntities.srv

@@ -1,8 +1,9 @@
 # Spawn an entity (a robot, other object) by name or URI
+# This interface is deprecated in favour of SpawnEntities.srv
 # Support for this interface is indicated through the SPAWNING value in GetSimulationFeatures.
 
 string name                             # A name to give to the spawned entity.
-                                        # If empty, a name field in the uri file or resource_string will be used,
+                                        # If empty, the name field in the URI file or resource_string will be used,
                                         # if supported and not empty (e.g. "name" field in SDFormat, URDF).
                                         # If the name is still empty or not unique (as determined by the simulator),
                                         # the service returns a generated name in the entity_name response field if the