From 2e3930d2fd240947024ce3c24d7b0167661160a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Tue, 25 Feb 2025 16:25:44 +0100 Subject: [PATCH 01/13] Intial Commit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Pełka --- rfcs/RFC Simulation Interfaces.md | 65 +++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 rfcs/RFC Simulation Interfaces.md diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md new file mode 100644 index 0000000..3821d57 --- /dev/null +++ b/rfcs/RFC Simulation Interfaces.md @@ -0,0 +1,65 @@ +# Introduce Simulation Interfaces to ROS 2 Gem + + +### Summary: + + +There is an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standarized simulation interfaces existing robotics simulators. + + +### What is the relevance of this feature? + + +Citing [RFC](https://github.com/ros-infrastructure/rep/issues/410) in ros-infrastructure/rep: +``` +Standardization would improve user experience when using their validation, testing and ML pipelines with several simulators, or when switching between one simulator and the other as they needs come to better match another platform. It would also make it easier to benchmark simulators. +``` + +### Feature design description: + + +### Technical design description: + + + + +### What are the advantages of the feature? + + +### What are the disadvantages of the feature? + + +### How will this be implemented or integrated into the O3DE environment? + + +### Are there any alternatives to this feature? + + +### How will users learn this feature? + + +### Are there any open questions? + From 2b18eda1d7b928259a4dd3409dea90c36efe838f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Tue, 25 Feb 2025 17:19:40 +0100 Subject: [PATCH 02/13] WIP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Pełka --- rfcs/RFC Simulation Interfaces.md | 89 +++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md index 3821d57..c6bfd89 100644 --- a/rfcs/RFC Simulation Interfaces.md +++ b/rfcs/RFC Simulation Interfaces.md @@ -31,8 +31,97 @@ Standardization would improve user experience when using their validation, testi - If there is any new terminology, it should be defined here. --> +The ROS 2 simulator that is compatible with simulation interfaces has a number of requirements to follow. + +It needs to advertise supported features via the ROS 2 service [GetSimulatorFeatures.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulatorFeatures.srv) +That service in its response provides the caller with a list of features [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg) +In this RFC we are proposing to support the following features: + + - SPAWNING + - DELETING + - NAMED_POSES + - POSE_BOUNDS + - ENTITY_BOUNDS + + - ENTITY_STATE_LISTING + - ENTITY_STATE_SETTING + + - SIMULATION_RESET + - SIMULATION_RESET_TIME + - SIMULATION_RESET_SPAWNED + + - SIMULATION_PAUSE + +We do not plan to support the moment: + - SIMULATION_RESET_STATE + - STEP_SIMULATION_SINGLE + - STEP_SIMULATION_MULTIPLE + - STEP_SIMULATION_ACTION + +Following formats will be supported for spawnaning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)): +``` +[`.spawnables`] +``` + +**Note** other formats e.g. `URDF` and `SDF` are supported by ROS 2 Gem but only in Editor. +Those tools are not available in the game mode, so spawning `SDF` and `URDF` would require: + - Handling mesh importing in Game Launcher and preparing it to use with Mesh Feature processor + - Creating materials and texture assets in runtime + - PhysX (or other Physics engine) collider mesh cooking with decomposition. + +Such feature, would be usefull, but it is out of scope of this RFC. + ### Technical design description: +Spawning, gathering information and despawning will be carried by +`ROS 2 Entity manager`. +This manager will be a system component that will be part of ROS 2 Gem. +It will advertise following services: + +#### GetSpawnables +Service definition : [GetSpawnables](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSpawnables.srv) +``` +# 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 result_code. + +string[] sources # Optional field for additional sources (local or remote) to search. + # By default, each simulator has visibility of spawnables through + # some mechanisms, e.g. a set of paths, registered assets etc. + # Since the simulator cannot possibly look everywhere, + # this field allows the user to specify additional sources. + # Unrecognized values are listed as such in the result.error_message, + # but do not hinder success of the response. + # Sources may include subcategories and be simulator-specific. + +--- + +Result result +Spawnable[] spawnables # Spawnable objects with URI and additional information. +``` +Definition of individual spawnable [Spawnable.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Spawnable.msg) +``` +# 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. +``` + +This service is advertising available spawnables that can be used in simulation. +We will take asset catalog to find spawnables. +There is usefull API in the Engine to get products assets: +```cpp + AZ::Data::AssetCatalogRequestBus::Broadcast(&AZ::Data::AssetCatalogRequests::EnumerateAssets, nullptr, enumerateCallback, nullptr); +``` +Asset catalog contains product assets (such as spawnables, azmodel, azbuffer). +We will introduce a product assets called `SimulationInfo`. + + + +#### GetEntitiesStates +Service definition : [GetEntitiesStates](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SetEntityState.srv) +- + -There is an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standarized simulation interfaces existing robotics simulators. +There is an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardized simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). ### What is the relevance of this feature? -Citing [RFC](https://github.com/ros-infrastructure/rep/issues/410) in ros-infrastructure/rep: +Citing [RFC-410](https://github.com/ros-infrastructure/rep/issues/410) in [ros-infrastructure/rep](https://github.com/ros-infrastructure/rep): ``` Standardization would improve user experience when using their validation, testing and ML pipelines with several simulators, or when switching between one simulator and the other as they needs come to better match another platform. It would also make it easier to benchmark simulators. ``` @@ -31,12 +31,40 @@ Standardization would improve user experience when using their validation, testi - If there is any new terminology, it should be defined here. --> -The ROS 2 simulator that is compatible with simulation interfaces has a number of requirements to follow. +The feature is an API for handling number of ROS 2 [services](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Services/Understanding-ROS2-Services.html) and [actions](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Actions/Understanding-ROS2-Actions.html). + +There is a terminology that was created in [RFC-410](https://github.com/ros-infrastructure/rep/issues/410) in [ros-infrastructure/rep](https://github.com/ros-infrastructure/rep): + +|Term | Description | +|-----------------|-----------------------------------------------------------------------------------------------------| +|Spawnable | Robot or other object which can be spawned in simulation runtime. | +|Entity | Spawned spawnable, it has unique name. +|Bound | Region defined by axis-aligned box shape, convex hull or sphere. +|NamedPose | SE3 (translation and rotation) transform with unique name +|Tag | A string that allow filtering entities and named poses + + +The implementation will be split to three (or more system components): +- ROS 2 Entities manager \ + It will be responsible for lifetime of spawned objects, it will cache initial positions. +- ROS 2 Named poses manager \ + It will be responsible for aggregating information in Named Pose Game Component. +- ROS 2 Simulator manager \ + It will be responsible for modifying global state ofr the simulation (e.g., pausing, reloading). + +We will decouple implementation of those managers from ROS 2 service. +Every manager will need to expose public methods that will be callable both from C++ and ROS 2. +Purpose of that approach is to enable testability without need for ROS domain. + +# ROS 2 API +In this section detailed plan of the implementation with potential limitations is presented. + +## GetSimulationFeatures service It needs to advertise supported features via the ROS 2 service [GetSimulatorFeatures.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulatorFeatures.srv) That service in its response provides the caller with a list of features [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg) -In this RFC we are proposing to support the following features: +In this RFC we are proposing to support the following features: - SPAWNING - DELETING - NAMED_POSES @@ -49,36 +77,35 @@ In this RFC we are proposing to support the following features: - SIMULATION_RESET - SIMULATION_RESET_TIME - SIMULATION_RESET_SPAWNED + - SIMULATION_RESET_STATE - SIMULATION_PAUSE We do not plan to support the moment: - - SIMULATION_RESET_STATE - STEP_SIMULATION_SINGLE - STEP_SIMULATION_MULTIPLE - STEP_SIMULATION_ACTION -Following formats will be supported for spawnaning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)): +Following formats will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)): ``` [`.spawnables`] ``` -**Note** other formats e.g. `URDF` and `SDF` are supported by ROS 2 Gem but only in Editor. +**Note** Other formats e.g. `URDF` and `SDF` are supported by ROS 2 Gem, but only in Editor. Those tools are not available in the game mode, so spawning `SDF` and `URDF` would require: - - Handling mesh importing in Game Launcher and preparing it to use with Mesh Feature processor - - Creating materials and texture assets in runtime + - handling mesh importing in Game Launcher and preparing it to use with Mesh Feature processor, + - creating materials and texture assets in runtime, - PhysX (or other Physics engine) collider mesh cooking with decomposition. -Such feature, would be usefull, but it is out of scope of this RFC. +Such feature, would be useful, but it is out of scope of this RFC. -### Technical design description: +Features ` SIMULATION_RESET_STATE, STEP_SIMULATION_SINGLE, STEP_SIMULATION_MULTIPLE, STEP_SIMULATION_ACTION` will be introduced in next RFC, since it requires multiple changes in PhysX gem, AzPhysics API. +Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. -Spawning, gathering information and despawning will be carried by -`ROS 2 Entity manager`. -This manager will be a system component that will be part of ROS 2 Gem. -It will advertise following services: +## GetSpawnables service + +This service allows users to find simulated spawnables to spawn (place) in the simulation. -#### GetSpawnables Service definition : [GetSpawnables](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSpawnables.srv) ``` # Return a list of resources which are valid as SpawnEntity uri fields (e.g. visible to or registered in simulator). @@ -98,7 +125,7 @@ string[] sources # Optional field for additio Result result Spawnable[] spawnables # Spawnable objects with URI and additional information. ``` -Definition of individual spawnable [Spawnable.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Spawnable.msg) +Definition of individual spawnables [Spawnable.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Spawnable.msg): ``` # Robot or other object which can be spawned in simulation runtime. @@ -108,19 +135,565 @@ Bounds spawn_bounds # Optional spawn area bounds which ful ``` This service is advertising available spawnables that can be used in simulation. -We will take asset catalog to find spawnables. -There is usefull API in the Engine to get products assets: +We will utilize asset catalog to find those spawnables. +There is useful API in the Engine to get products assets from asset catalog: +```cpp +AZ::Data::AssetCatalogRequests::EnumerateAssets +``` +Asset catalog contains product assets (such as `.spawnables`, `.azmodel`, `.azbuffer`). +We will introduce an another product assets called `.simulationinfo`. +This asset will be contain necessary data about Prefab that can be spawned or adjusted by Simulation Interfaces. + +The `.simulationinfo` product asset will be a XML / JSON file (similar other products assets like `.physxmaterial`) and will contain at least following information: + + - a description (as a string), + - bounds (as variant of chosen bound region), + - list of tags, + - category, + - Asset Id of the corresponding prefab. + + +The `.simulationinfo` will be created by the asset builder that will be registered by ROS 2 Gem. +This asset builder will consume source assets called `SimulationInfo` and eventually corresponding prefabs. +It will create `SimulationInfo` product asset in the `Cache` directory. + +The `SimulationInfo` source asset will be a side car (a file with the same filename) to a prefab. +It will contain: + + - a description (as a string), + - bounds (as variant of chosen bound region), + - list of tags, + - category. + +A simulation expert who wants to create a robot (or other simulation ready asset) needs: +- design a new prefab using standard O3DE workflow, using all available components, +- save the prefab with a name e.g., `Robots/FooRobot.prefab` +- create and fill `SimulationInfo` file as `Robots/FooRobot.SimulationInfo` using text editor or some tooling in O3DE: + * fill description, + * fill tags, + * fill category, + * and hand-fill bounds (e.g., sphere radius), +- export simulation with export script and [bundle assets](https://docs.o3de.org/docs/user-guide/packaging/asset-bundler/) + +A ROS 2 user who will call the `GetSpawnables` service against GameLauncher will trigger following sequence: +- a call to asset catalog to find all product assets of the type `.simulationinfo`. +- The `ROS 2 Entity manager` will aggregate found assets and will prepare a response that will contain: + * `uri` as `spawnable://@cache@/robot/foorobot.spawnable` + * the description copied from `Robots/FooRobot.SimulationInfo`, + * the bound information copied from `Robots/FooRobot.SimulationInfo`, + * tag list copied from `Robots/FooRobot.SimulationInfo`, + * category copied from `Robots/FooRobot.SimulationInfo`. +- Prepared response will be returned to ROS 2 user. + +## SpawnEntity service + +Service allows to spawn entities found previously with `GetSpawnables` service. + +Service definition [SpawnEntity](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SpawnEntity.srv): + +``` +# Spawn an entity (a robot, other object) by name or URI + +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 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. +string uri # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc. + # Valid URIs can be determined by calling GetSpawnables first, and you can check + # the simulator format support by reading SimulatorFeatures spawn_formats field. + # If uri field is empty, resource_string must not be empty. +string resource_string # An entity definition file passed as a string. + # Simulators may support spawning from a file generated on the fly (e.g. XACRO). + # Check whether it is supported by your simulator through GetSimulatorFeatures. + # If uri field is not empty, resource_string field will be ignored. +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. + +--- + +# Additional result.result_code values for this service. Check result.error_message for further details. +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. +``` + +The ROS 2 user who want to spawn a new object in their simulation has to have a valid URI e.g.,`spawnable://@cache@/robot/foorobot.spawnable`. + +**Note !** +Spawning assets from the file system e.g., `spawnable://home/michalpelka/robots/FooRobot.spawnables` will not be supported. + +With that URI `ROS 2 Entity manager` will find respective Asset Id. +Next the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn and spawnable. + +During spawning the spawnable will be modified: +- change a name of the root entity to that given by the `name` field, +- [Transform Component](https://docs.o3de.org/docs/user-guide/components/reference/transform/) of the root entity will modified to reflect value of the `initial_pose` field, +- [ROS2 Frame](https://www.docs.o3de.org/docs/user-guide/components/reference/ros2/core/ros2-frame/) to set correct namespace. +- A component called `SimulationInfoComponent` will be created and attached to root entity . + That component will be used to cache information in `simulationinfo` to be easily accessible in future. +- [TagComponent](https://www.docs.o3de.org/docs/user-guide/components/reference/gameplay/tag/) from LmbrCentral gem at root entity will be created (if not present in prefab). +- TagComponent will be updated with list of new tags from. + + +`SimulationInfoComponent` will be handling a `SimulationInfoComponentRequestBus`. +`SimulationInfoComponentRequestBus` will have an unique, string key, which will be a resulting name of spawned entity. +This bus will allow to aggregate all handling entities, and provide and API to find all spawned entities, get their state. + +## GetEntities service + +The service allows to discover spawned entities. + +Service definition : [GetEntities](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntities.srv ) + +``` +# Get objects in the scene which can be interacted with, e.g. with using SetEntityState. +# You can get further information about entities through GetEntityInfo and GetEntityState services. +# There is also a GetEntitiesStates service if you would like to get state for each entity. + +EntityFilters filters # Optional filters for the query, including name, category, tags, + # and overlap filters. + +--- + +Result result +Entity[] entities # All entities matching the filters. +``` + +where [Entity](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Entity.msg) is defined: +``` +# Entity identified by its unique name. Entities are objects in the simulation such as models and links. +# Each simulator might define what an entity is in a (slightly) different way. + +string name # Entity unique name. +``` + +We will serve this by calling `SimulationInfoComponentRequestBus` with `AZ::EBusAggregateResults`. +With that, we will obtain vector of EntiesId, that can be converted to list of entities names. + +## GetEntitiesStates service + +This service allows users to get state (speed, location, acceleration) of chosen entities. + +Service definition : [GetEntitiesStates.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntitiesStates.srv) +``` +# Get objects in the scene which can be interacted, e.g. with using SetEntityState. +# Use GetEntities service instead if EntityState information for all entities is not needed. + +EntityFilters filters # Optional filters for the query, including name, category, tags, + # and overlap filters. + +--- + +Result result +Entity[] entities # All entities matching the filters. +EntityState[] states # States for these entities. +``` + +where [EntityState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityState.msg) is: +``` +# Entity current pose, twist and acceleration + +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 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. +``` + +The service handling will be similar to [GetEntities](#GetEntities). +There will be more calls to : + - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to find current twist, + - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) to find current pose, + - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) to find frame id. + +**Note !** acceleration is will not be filled, and will not be supported. + +#### SetEntityState service + +This service allows to modify state of chosen entity. + +Service definition [SetEntityState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SetEntityState.srv) +``` +# Set a state of an object, which will result in an instant change in its pose and/or twist. + +Entity entity # Entity identified by its unique name as returned by GetEntities / SpawnEntity. +EntityState state # New state to set immediately. The timestamp in header is ignored. + # Note that the acceleration field may be ignored by simulators. + +--- + +Result `result`: +``` +where [EntityState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityState.msg) is: +``` +# Entity current pose, twist and acceleration + +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 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. +``` + +The O3DE entity Id will be discovered by calling `SimulationInfoComponentRequestBus` with entity name provided in service request. +Next, having the EntityId the corresponding API will be called to adjust state: + - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) or + [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to + adjust position of simulated entity. + - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) to eventually change frame id, + - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to + adjust speed or acceleration. + +Note that serving this service is a bit tricky in O3DE. +Due to modularity of O3DE the entities can be moved around in several ways: +- Simulated PhysX Rigid Body, +- Kinematic PhysX Rigid Body, +- TransformCompetent (due to parent-child relation), +- TransformComponent (due to calls to EBuses), +- PhysX character component, +- PhysX ragdoll, +- PhysX articulations, +- Potential 3rd physics engine. + +Some of those methods respects calls to `TranformComponentRequests`, but some of them needs to call directly methods in PhysX gem. +| Method | TransformComponentRequests API| RigidBodyRequestBus API | Custom API | +|----------------------------------------|--------------------------------|--------------------------|------------| +|Simulated PhysX Rigid Body | | supports | | +|Kinematic PhysX Rigid Body | supports | | | +|TransformComponent due to parent-child | supports | | | +|TransformComponent (custom calls) | | | | +|PhysX character component | | | ? | +|PhysX ragdoll | | | ? | +|PhysX articulations | | | supports | + +The correct API need to be chosen to get expected outcome that it can be quite tricky. +Let us investigate moving a `Simulated PhysX Rigid Body'. +We cannot simply call : +```cpp + AZ::TransformBus::Event(entityId, &AZ::TransformBus::Events::SetWorldTM, transform); +``` +Above snippet will work fine in setup where the entity has PhysX rigid body component set to kinematic. +When PhysX rigid body component is set to simulated type, it will have no effect. +Proper way to move such entity (respecting joints and contacts) will be: +- call `SetKinematic(true)` from RigidBodyRequestBus to stop simulation, +- wait for SetKinematic to be effective, +- set `SetKinematicTarget` and wait for target reached, +- set `SetKinematic(false)` and wait for effect, +- finally, call `ForceAwake` to make sure that PhysX will run simulation of the body. + +It can take multiple cycles to achieve this. + +This can lead to few problems: + - ROS2 Gem need to be heavily reliable on PhysX5 gem to support moving entities with articulations, characters. + - Some of methods to adjust pose can be quite challenging. + - Introducing new physics engine can lead to conflicts here. + +Alternative, approach would be to cycle through: +- disable physics simulation of [simulated body](https://docs.o3de.org/docs/user-guide/interactivity/physics/nvidia-physx/simulated-bodies/), +- Use `TransformBus::Events::SetWorldTM` to change location, +- enable simulation of [simulated body](https://docs.o3de.org/docs/user-guide/interactivity/physics/nvidia-physx/simulated-bodies/). + +The velocity (twist) can be applied using `RigidBodyRequestBus::SetLinearVelocity` and `RigidBodyRequestBus::SetAngularVelocity`. +It will be effective against Simulated PhysX Rigid Body and Kinematic PhysX Rigid Body and should give a warning if it called against +unsupported type. + + +The acceleration can be applied using `RigidBodyRequestBus::ApplyLinearImpulse` w.r.t object's mass. +It will be effective against Simulated PhysX Rigid Body and should give a warning if it called against +unsupported type. + +**Important :** Currently ROS2 Gem is heavily dependant on PhysX5 (due to SDF importer). The decoupling of those need to be done in future. + +## DeleteEntity service + +Despawn previously spawned entity + +Service definition [DeleteEntity.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/DeleteEntity.srv) +``` +# Remove an entity (a robot, other object) from the simulation + +Entity entity # Entity identified by its unique name with a namespace, + # as returned by SpawnEntity or GetEntities. + +--- + +Result result +``` + +The O3DE entity ID and their spawn ticket ID will be discovered by `SimulationInfoComponentRequestBus`. +Next the component `ROS 2 Entity manager` will be asked to despawn and remove corresponding spawn ticket. + +**Important :** This mechanism will now allow to delete entities that are part of the level prefab (e.g., prefab instantiated in Editor). + + +## GetEntityBounds service + +Returns bounds of spawned entity. + +Service definition [GetEntityBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityBounds.srv) +``` +# Get geometrical bounds for entity. This feature is available if GetSimulatorFeatures includes ENTITY_BOUNDS feature. + +Entity entity # Entity identified by its unique name as returned by GetEntities / SpawnEntity. + +--- + +Result result +Bounds bounds +``` + +The bounds for particular entities will be get by calling `SimulationInfoComponentRequestBus`. + + +## GetEntityInfo service + +Returns tags and category of spawned entity. + +Service definition [GetEntityInfo.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityInfo.srv): +``` +# Get type and other information about an entity. + +Entity entity # Entity identified by its unique name as returned by GetEntities / SpawnEntity. + +--- + +Result result +EntityInfo info # Only valid if result.result_code is OK. +``` +where [EntityInfo.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityInfo.msg): +``` +# Entity type and additional information + +uint8 category # Major category for the entity. Extra entity type distinction can be made through tags. + # See EntityCategories for defined category values. +string description # optional: verbose, human-readable description of the entity. +string[] tags # optional: tags which are useful for filtering and categorizing entities further. +``` + +Those information will be obtained from `SimulationInfoComponentRequestBus`. + +## GetNamedPoses service + +Simulation expert using O3DE Editor can add entity with component from ROS2 gem called `Named Pose Editor Component`. +This component will require `TransformService` and dependent service `BoxShapeService` and `SphereShapeService` +The `Named Pose Component` will contain two configurable field called `description` and `tags`. +During creation of game component (`CreateGameEntity`) the TagComponent from LmbrCentral gem will be created and fed with list of tags. +Creating the TagComponent is useful to make this feature compatible with O3DE's tag system. +The box or sphere shape component allows to define optional boundaries around named pose. + +**Important** Convex hull bound shape will not be supported yet. + +Calling service `GetNamedPose` will discover those components and returns theirs configuration. + +Service definition [GetNamedPoses.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoses.srv): +``` +# Get predefined poses which are convenient to for spawning, navigation goals etc. + +TagsFilter tags # Tags filter to apply. Only named poses with matching tags field + # will be returned. Can be empty (see TagsFilter). + +--- + +Result result +NamedPose[] poses # A list of predefined poses, which may be empty. +``` +where: [TagsFilter.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/TagsFilter.msg), +[NamedPose.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/NamedPose.msg): +``` +# 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. +``` + +During simulation entities with `Named Pose Component` will be discovered (e.g., using designated request bus or o3de tag system), +the aggregation will be filtered and returned to caller. + +**Important** Since O3DE does not requires those names to be unique, the ROS 2 gem needs to skip or extend names of duplicates. + + +## GetNamedPoseBounds service + +Service allows to get boundaries defined in Named Pose. + +Service definition [GetNamedPoseBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoseBounds.srv): +``` +# Get bounds for the named pose. This feature is available if GetSimulatorFeatures includes POSE_BOUNDS feature. + +string name # unique names (as returned from GetNamedPoses). + +--- + +Result result +Bounds bounds # bounds for the named pose. +``` + +It will expose data in Named Pose Game Component and corresponding Shape Components. + +## Reset Simulation service + +Allows ROS 2 user to reset simulation. + +Service definition [ResetSimulation.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/ResetSimulation.srv) +``` +# Reset the simulation to the start, including the entire scene and the simulation time. +# Objects that were dynamically spawned are de-spawned. + +uint8 SCOPE_DEFAULT = 0 # same as ALL. +uint8 SCOPE_TIME = 1 # Reset simulation time to start. +uint8 SCOPE_STATE = 2 # Reset state such as poses and velocities. This may include state randomization + # if such feature is available and turned on. +uint8 SCOPE_SPAWNED = 4 # De-spawns all spawned entities. +uint8 SCOPE_ALL = 255 # Fully resets simulation to the start, as if it was closed and launched again. + +uint8 scope # Scope of the reset. Note that simulators might only support some scopes. + # This is a bit field which may be checked for each scope e.g. scope & TIME. + +--- + +Result result +``` + +This service will be need to use multiple APIs to give results. + +|Scope | Planned API and usage | +|----------------|-------------------- +|SCOPE_ALL | ConsoleRequestBus and `LoadLevel` command. +|SCOPE_SPAWNED | Internal gem API to destroy all spawn tickets in ROS 2 Entities manager. +|SCOPE_STATE | Move all spawned entities to intial poses cached in ROS 2 Entities manager. +|SCOPE_TIME | New ROS2Bus call + +## SetSimulationState service + +Allows ROS 2 user to set state of the simulation (STOPPED, PAUSED, PLAYING, QUITTING) + +``` +# Change the simulation state + + +SimulationState state # Target state to set for the simulation. + +--- + +uint8 ALREADY_IN_TARGET_STATE = 101 # Additional result type for this call, which means simulation was already + # in the target state (e.g. was already stopped when STOP was requested). +uint8 STATE_TRANSITION_ERROR = 102 # The simulator failed to transition to the target state. This might happen + # especially with the transition to PLAYING from STOPPED. + # See result.error_message for details. +uint8 INCORRECT_TRANSITION = 103 # Incorrect transition (pausing when in stopped state). + +Result result + +``` +where [SimulationState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulationState.msg) is defined as: +``` +# Simulation states used in SetSimulationState and returned in GetSimulationState + +uint8 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 PLAYING = 1 # Simulation is playing, can be either paused or stopped. +uint8 PAUSED = 2 # Simulation is paused, can be either stopped (which will reset it) or played. +uint8 QUITTING = 3 # Closing the simulator application. Switching from PLAYING or 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 +``` + +Transition from PLAYING to STOPPED will trigger level reloading. That will take a while to complete. \ +Transition from PLAYING to PAUSED will ask default physics scene to be disabled. +It will stop movement of all PhysX articulations, rigid bodies (both kinematic and simulated) and characters, but some animations will be played. +Transition from PLAYING to QUITTING will simply calling : +```cpp + int* ptr = nullptr; + *ptr= 99; +``` +alternatively: ```cpp - AZ::Data::AssetCatalogRequestBus::Broadcast(&AZ::Data::AssetCatalogRequests::EnumerateAssets, nullptr, enumerateCallback, nullptr); +#pragma clang diagnostic ignored "-Winfinite-recursion" +auto exit = [&]() { exit(); }; exit(); +``` + +The ROS 2 Simulator manager will contain state of the simulation and perform necessary transitions. + +## GetSimulationState service + +Allows ROS 2 user to get current state of the simulation. + +Service definition [GetSimulationState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulationState.srv) + +``` +# Gets the simulation state (paused, playing, stopped) + +--- + +SimulationState state # Current state of the simulation. + +Result result ``` -Asset catalog contains product assets (such as spawnables, azmodel, azbuffer). -We will introduce a product assets called `SimulationInfo`. +The ROS 2 Simulator manager will return current state. +If transition is in progress (e.g. reloading level or despawning), the old state will be returned. + + + +## Retired components in ROS 2 Gem + +During this effort some components will be retired, and some moved outside of scope of supported and canonical repos. +### ROS2SpawnerComponent +ROS2Spawner component will be retired and hidden away from users with CMake variable. +This component can co-exists with managers for Simulation Interfaces, but ROS 2 package that components requires will be removed from upcoming ROS 2 distribution (Kilted Kaiju). +The said package (`gazebo_msgs`) will be replaced by simulation_interfaces. +Component will be retired (instead of complete removal from codebase) to make transition to Simulation interfaces easier experience. +However using ROS2Spawner component will require few extra steps (after EOL of gazebo_msgs package): +- cloning and building the latest [gazebo_ros_pkgs/gazebo_msgs](https://github.com/ros-simulation/gazebo_ros_pkgs/tree/3.9.0/gazebo_msgs) +- sourcing custom workspace +- setting CMake flag +- building ROS2 gem from source. + +### ROS2ContactSensorComponent + +This component's code also depends on [`gazebo_msgs`](https://github.com/ros-simulation/gazebo_ros_pkgs/blob/3.9.0/gazebo_msgs/msg/ContactState.msg). +Since there is no equivalent message in simulation_interfaces component will be retired and hidden from Users with CMakeVariable. +The steps to use this component will be the same to those in ROS2SpawnerComponent. + +Note that ROS 2 community probably propose suitable replacement message in future. -#### GetEntitiesStates -Service definition : [GetEntitiesStates](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SetEntityState.srv) -- + - Leading of standardization in robotics domain, + - easier usage of O3DE in robotics and ML pipelines, + - improve testability of the ROS 2 features, + - adjustments to EOL of `gazebo_msgs` ### What are the disadvantages of the feature? +Significant increase in code base size ### How will this be implemented or integrated into the O3DE environment? +It was explained in great details in section [ROS 2 API](#ros-2-api) ### Are there any alternatives to this feature? +Really, the effort needs to be taken to adjust code to deprecation of gazebo classic and `gazebo_msgs`. + ### How will users learn this feature? +- Posts by OpenRobotics in their social media +- documentation in [o3de.org](o3de.org) and [docs.ros.org](https://docs.ros.org/en/jazzy/Tutorials/Advanced/Simulators/Simulation-Main.html) + ### Are there any open questions? - + +- Handling integration of physics engine. +- Timing of implementation and release. \ No newline at end of file From 0371f98c09198b3fa67ac6b4bd345a5cf9d6f09f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Wed, 5 Mar 2025 12:09:12 +0100 Subject: [PATCH 04/13] AI spell check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Pełka --- rfcs/RFC Simulation Interfaces.md | 221 +++++++++++++++--------------- 1 file changed, 110 insertions(+), 111 deletions(-) diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md index ec4b23c..2fd3e1b 100644 --- a/rfcs/RFC Simulation Interfaces.md +++ b/rfcs/RFC Simulation Interfaces.md @@ -14,7 +14,7 @@ As a rule of thumb, receiving encouraging feedback from long-standing project de ### Summary: -There is an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardized simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). +There is an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardize simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). ### What is the relevance of this feature? @@ -37,34 +37,34 @@ There is a terminology that was created in [RFC-410](https://github.com/ros-infr |Term | Description | |-----------------|-----------------------------------------------------------------------------------------------------| -|Spawnable | Robot or other object which can be spawned in simulation runtime. | -|Entity | Spawned spawnable, it has unique name. -|Bound | Region defined by axis-aligned box shape, convex hull or sphere. -|NamedPose | SE3 (translation and rotation) transform with unique name -|Tag | A string that allow filtering entities and named poses +|Spawnable | Robot or other object that can be spawned in simulation runtime. +|Entity | Spawned spawnable, it has a unique name. +|Bound | A region that is defined by an axis-aligned box shape, convex hull, or a sphere. +|NamedPose | SE3 (translation and rotation) transform with a unique name +|Tag | A string that allows filtering entities and named poses -The implementation will be split to three (or more system components): +The implementation will be split into three (or more system components): - ROS 2 Entities manager \ - It will be responsible for lifetime of spawned objects, it will cache initial positions. + It will be responsible for the lifetime of spawned objects, it will cache initial positions. - ROS 2 Named poses manager \ - It will be responsible for aggregating information in Named Pose Game Component. + It will be responsible for aggregating information in the Named Pose Game Component. - ROS 2 Simulator manager \ - It will be responsible for modifying global state ofr the simulation (e.g., pausing, reloading). + It will be responsible for modifying the global state of the simulation (e.g., pausing, reloading). -We will decouple implementation of those managers from ROS 2 service. +We will decouple the implementation of those managers from the ROS 2 service. Every manager will need to expose public methods that will be callable both from C++ and ROS 2. -Purpose of that approach is to enable testability without need for ROS domain. +The purpose of that approach is to enable testability without the need for a ROS domain. # ROS 2 API -In this section detailed plan of the implementation with potential limitations is presented. +In this section, a detailed plan of the implementation with potential limitations is presented. ## GetSimulationFeatures service -It needs to advertise supported features via the ROS 2 service [GetSimulatorFeatures.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulatorFeatures.srv) +The simulator needs to advertise supported features via the ROS 2 service [GetSimulatorFeatures.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulatorFeatures.srv) That service in its response provides the caller with a list of features [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg) -In this RFC we are proposing to support the following features: +In the RFC we are proposing to support the following features: - SPAWNING - DELETING - NAMED_POSES @@ -97,9 +97,9 @@ Those tools are not available in the game mode, so spawning `SDF` and `URDF` wou - creating materials and texture assets in runtime, - PhysX (or other Physics engine) collider mesh cooking with decomposition. -Such feature, would be useful, but it is out of scope of this RFC. +Such a feature would be useful, but it is out of the scope of this RFC. -Features ` SIMULATION_RESET_STATE, STEP_SIMULATION_SINGLE, STEP_SIMULATION_MULTIPLE, STEP_SIMULATION_ACTION` will be introduced in next RFC, since it requires multiple changes in PhysX gem, AzPhysics API. +The features ` SIMULATION_RESET_STATE, STEP_SIMULATION_SINGLE, STEP_SIMULATION_MULTIPLE, STEP_SIMULATION_ACTION` will be introduced in the next RFC since they require multiple changes in the PhysX gem and AzPhysics API. Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. ## GetSpawnables service @@ -134,56 +134,56 @@ string description # Optional description for the user, e Bounds spawn_bounds # Optional spawn area bounds which fully encompass this object. ``` -This service is advertising available spawnables that can be used in simulation. -We will utilize asset catalog to find those spawnables. -There is useful API in the Engine to get products assets from asset catalog: +This service advertises available spawnables that can be used in simulation. +We will utilize the asset catalog to find those spawnables. +There is a useful API in the Engine to get products assets from the asset catalog: ```cpp AZ::Data::AssetCatalogRequests::EnumerateAssets ``` -Asset catalog contains product assets (such as `.spawnables`, `.azmodel`, `.azbuffer`). -We will introduce an another product assets called `.simulationinfo`. -This asset will be contain necessary data about Prefab that can be spawned or adjusted by Simulation Interfaces. +The asset catalog contains product assets (such as `.spawnables`, `.azmodel`, `.azbuffer`). +We will introduce another product asset called `.simulationinfo`. +This asset will contain necessary data about Prefab that can be spawned or adjusted by Simulation Interfaces. -The `.simulationinfo` product asset will be a XML / JSON file (similar other products assets like `.physxmaterial`) and will contain at least following information: +The `.simulationinfo` product asset will be an XML / JSON file (similar to other product assets like `.physxmaterial`) and will contain at least the following information: - a description (as a string), - - bounds (as variant of chosen bound region), + - bounds (as a variant of the chosen bound region), - list of tags, - category, - - Asset Id of the corresponding prefab. + - Asset ID of the corresponding prefab. The `.simulationinfo` will be created by the asset builder that will be registered by ROS 2 Gem. This asset builder will consume source assets called `SimulationInfo` and eventually corresponding prefabs. -It will create `SimulationInfo` product asset in the `Cache` directory. +It will create a `SimulationInfo` product asset in the `Cache` directory. -The `SimulationInfo` source asset will be a side car (a file with the same filename) to a prefab. +The `SimulationInfo` source asset will be a sidecar (a file with the same filename) to a prefab. It will contain: - a description (as a string), - - bounds (as variant of chosen bound region), + - bounds (as a variant of the chosen bound region), - list of tags, - category. -A simulation expert who wants to create a robot (or other simulation ready asset) needs: +A simulation expert who wants to create a robot (or other simulation-ready asset) needs: - design a new prefab using standard O3DE workflow, using all available components, - save the prefab with a name e.g., `Robots/FooRobot.prefab` -- create and fill `SimulationInfo` file as `Robots/FooRobot.SimulationInfo` using text editor or some tooling in O3DE: +- create and fill the `SimulationInfo` file as `Robots/FooRobot.SimulationInfo` using a text editor or some tooling in O3DE: * fill description, * fill tags, * fill category, * and hand-fill bounds (e.g., sphere radius), -- export simulation with export script and [bundle assets](https://docs.o3de.org/docs/user-guide/packaging/asset-bundler/) +- export simulation with the export script and [bundle assets](https://docs.o3de.org/docs/user-guide/packaging/asset-bundler/) -A ROS 2 user who will call the `GetSpawnables` service against GameLauncher will trigger following sequence: -- a call to asset catalog to find all product assets of the type `.simulationinfo`. +A ROS 2 user who calls the `GetSpawnables` service against GameLauncher will trigger the following sequence: +- a call to the asset catalog to find all product assets of the type `.simulationinfo`. - The `ROS 2 Entity manager` will aggregate found assets and will prepare a response that will contain: * `uri` as `spawnable://@cache@/robot/foorobot.spawnable` * the description copied from `Robots/FooRobot.SimulationInfo`, * the bound information copied from `Robots/FooRobot.SimulationInfo`, * tag list copied from `Robots/FooRobot.SimulationInfo`, * category copied from `Robots/FooRobot.SimulationInfo`. -- Prepared response will be returned to ROS 2 user. +- Prepared response will be returned to the ROS 2 user. ## SpawnEntity service @@ -240,32 +240,31 @@ string entity_name # Spawned entity full name, guaranteed t # If allow_renaming is true, it may differ from the request name field. ``` -The ROS 2 user who want to spawn a new object in their simulation has to have a valid URI e.g.,`spawnable://@cache@/robot/foorobot.spawnable`. +The ROS 2 user who wants to spawn a new object in their simulation has to have a valid URI e.g.,`spawnable://@cache@/robot/foorobot.spawnable`. **Note !** Spawning assets from the file system e.g., `spawnable://home/michalpelka/robots/FooRobot.spawnables` will not be supported. -With that URI `ROS 2 Entity manager` will find respective Asset Id. -Next the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn and spawnable. +With that URI `ROS 2 Entity Manager` will find respective Asset Id. +Next, the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn. -During spawning the spawnable will be modified: -- change a name of the root entity to that given by the `name` field, -- [Transform Component](https://docs.o3de.org/docs/user-guide/components/reference/transform/) of the root entity will modified to reflect value of the `initial_pose` field, +During spawning the spawned O3DE entities will be modified: +- change the name of the root entity to that given by the `name` field, +- [Transform Component](https://docs.o3de.org/docs/user-guide/components/reference/transform/) of the root entity will modified to reflect the value of the `initial_pose` field, - [ROS2 Frame](https://www.docs.o3de.org/docs/user-guide/components/reference/ros2/core/ros2-frame/) to set correct namespace. -- A component called `SimulationInfoComponent` will be created and attached to root entity . - That component will be used to cache information in `simulationinfo` to be easily accessible in future. +- A component called `SimulationInfoComponent` will be created and attached to the root entity. + That component will be used to cache information in `simulationinfo` to be easily accessible in the future. - [TagComponent](https://www.docs.o3de.org/docs/user-guide/components/reference/gameplay/tag/) from LmbrCentral gem at root entity will be created (if not present in prefab). -- TagComponent will be updated with list of new tags from. +- TagComponent will be updated with a list of new tags. `SimulationInfoComponent` will be handling a `SimulationInfoComponentRequestBus`. -`SimulationInfoComponentRequestBus` will have an unique, string key, which will be a resulting name of spawned entity. +`SimulationInfoComponentRequestBus` will have a unique, string key, which will be the resulting name of spawned entity. This bus will allow to aggregate all handling entities, and provide and API to find all spawned entities, get their state. ## GetEntities service -The service allows to discover spawned entities. - +The service allows to discover of spawned entities. Service definition : [GetEntities](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntities.srv ) ``` @@ -291,11 +290,11 @@ string name # Entity unique name. ``` We will serve this by calling `SimulationInfoComponentRequestBus` with `AZ::EBusAggregateResults`. -With that, we will obtain vector of EntiesId, that can be converted to list of entities names. +With that, we will obtain a AZStd::vector of EntityId, that can be converted to a list of entity names. ## GetEntitiesStates service -This service allows users to get state (speed, location, acceleration) of chosen entities. +This service allows users to get the state (speed, location, acceleration) of chosen entities. Service definition : [GetEntitiesStates.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntitiesStates.srv) ``` @@ -334,7 +333,7 @@ There will be more calls to : #### SetEntityState service -This service allows to modify state of chosen entity. +This service allows modifying the state of the chosen entity. Service definition [SetEntityState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SetEntityState.srv) ``` @@ -360,17 +359,17 @@ geometry_msgs/Twist twist # Ground truth linear and angular veloci geometry_msgs/Accel acceleration # Linear and angular acceleration ground truth, following the same convention. ``` -The O3DE entity Id will be discovered by calling `SimulationInfoComponentRequestBus` with entity name provided in service request. -Next, having the EntityId the corresponding API will be called to adjust state: +The O3DE EntityId will be discovered by calling `SimulationInfoComponentRequestBus` with the entity name provided in the service request. +Next, having the EntityId the corresponding API will be called to adjust the state: - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) or - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to - adjust position of simulated entity. + [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to + adjust the position of the simulated entity. - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) to eventually change frame id, - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to - adjust speed or acceleration. + adjust speed or acceleration. Note that serving this service is a bit tricky in O3DE. -Due to modularity of O3DE the entities can be moved around in several ways: +Due to the modularity of O3DE, the entities can be moved around in several ways: - Simulated PhysX Rigid Body, - Kinematic PhysX Rigid Body, - TransformCompetent (due to parent-child relation), @@ -380,7 +379,7 @@ Due to modularity of O3DE the entities can be moved around in several ways: - PhysX articulations, - Potential 3rd physics engine. -Some of those methods respects calls to `TranformComponentRequests`, but some of them needs to call directly methods in PhysX gem. +Some of those methods respect calls to `TranformComponentRequests`, but some of them need to call directly methods in the PhysX gem. | Method | TransformComponentRequests API| RigidBodyRequestBus API | Custom API | |----------------------------------------|--------------------------------|--------------------------|------------| |Simulated PhysX Rigid Body | | supports | | @@ -391,29 +390,29 @@ Some of those methods respects calls to `TranformComponentRequests`, but some of |PhysX ragdoll | | | ? | |PhysX articulations | | | supports | -The correct API need to be chosen to get expected outcome that it can be quite tricky. +The correct API needs to be chosen to get the expected outcome it can be quite tricky. Let us investigate moving a `Simulated PhysX Rigid Body'. We cannot simply call : ```cpp AZ::TransformBus::Event(entityId, &AZ::TransformBus::Events::SetWorldTM, transform); ``` -Above snippet will work fine in setup where the entity has PhysX rigid body component set to kinematic. -When PhysX rigid body component is set to simulated type, it will have no effect. -Proper way to move such entity (respecting joints and contacts) will be: -- call `SetKinematic(true)` from RigidBodyRequestBus to stop simulation, +The above snippet will work fine in a setup where the entity has a PhysX rigid body component set to kinematic. +When the PhysX rigid body component is set to the simulated type, it will have no effect. +The proper way to move such an entity (respecting joints and contacts) will be: +- call `SetKinematic(true)` from RigidBodyRequestBus to stop the simulation, - wait for SetKinematic to be effective, -- set `SetKinematicTarget` and wait for target reached, +- set `SetKinematicTarget` and wait for the target reached, - set `SetKinematic(false)` and wait for effect, -- finally, call `ForceAwake` to make sure that PhysX will run simulation of the body. +- finally, call `ForceAwake` to make sure that PhysX will run a simulation of the body. It can take multiple cycles to achieve this. -This can lead to few problems: - - ROS2 Gem need to be heavily reliable on PhysX5 gem to support moving entities with articulations, characters. - - Some of methods to adjust pose can be quite challenging. - - Introducing new physics engine can lead to conflicts here. +This can lead to a few problems: + - ROS2 Gem needs to be heavily reliable on PhysX5 gem to support moving entities with articulations, and characters. + - Some methods to adjust pose can be quite challenging. + - Introducing a new physics engine can lead to conflicts here. -Alternative, approach would be to cycle through: +The alternative, approach would be to cycle through: - disable physics simulation of [simulated body](https://docs.o3de.org/docs/user-guide/interactivity/physics/nvidia-physx/simulated-bodies/), - Use `TransformBus::Events::SetWorldTM` to change location, - enable simulation of [simulated body](https://docs.o3de.org/docs/user-guide/interactivity/physics/nvidia-physx/simulated-bodies/). @@ -424,10 +423,10 @@ unsupported type. The acceleration can be applied using `RigidBodyRequestBus::ApplyLinearImpulse` w.r.t object's mass. -It will be effective against Simulated PhysX Rigid Body and should give a warning if it called against +It will be effective against Simulated PhysX Rigid Body and should give a warning if it is called against unsupported type. -**Important :** Currently ROS2 Gem is heavily dependant on PhysX5 (due to SDF importer). The decoupling of those need to be done in future. +**Important :** Currently ROS2 Gem is heavily dependant on PhysX5 (due to SDF importer). The decoupling of those needs to be done in the future. ## DeleteEntity service @@ -446,14 +445,13 @@ Result result ``` The O3DE entity ID and their spawn ticket ID will be discovered by `SimulationInfoComponentRequestBus`. -Next the component `ROS 2 Entity manager` will be asked to despawn and remove corresponding spawn ticket. - -**Important :** This mechanism will now allow to delete entities that are part of the level prefab (e.g., prefab instantiated in Editor). +Next the component `ROS 2 Entity manager` will be asked to despawn and remove the corresponding spawn ticket. +**Important:** This mechanism will now allow to delete of entities that are part of the level prefab (e.g., prefab instantiated in Editor). ## GetEntityBounds service -Returns bounds of spawned entity. +Returns bounds of the spawned entity. Service definition [GetEntityBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityBounds.srv) ``` @@ -467,12 +465,11 @@ Result result Bounds bounds ``` -The bounds for particular entities will be get by calling `SimulationInfoComponentRequestBus`. - +The bounds for particular entities will be obtained by calling `SimulationInfoComponentRequestBus`. ## GetEntityInfo service -Returns tags and category of spawned entity. +Returns tags and category of the spawned entity. Service definition [GetEntityInfo.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityInfo.srv): ``` @@ -495,20 +492,20 @@ string description # optional: verbose, human-readable description of t string[] tags # optional: tags which are useful for filtering and categorizing entities further. ``` -Those information will be obtained from `SimulationInfoComponentRequestBus`. +This information will be obtained from `SimulationInfoComponentRequestBus`. ## GetNamedPoses service Simulation expert using O3DE Editor can add entity with component from ROS2 gem called `Named Pose Editor Component`. -This component will require `TransformService` and dependent service `BoxShapeService` and `SphereShapeService` -The `Named Pose Component` will contain two configurable field called `description` and `tags`. +This component will require `TransformService` and dependent services `BoxShapeService` and `SphereShapeService` +The `Named Pose Component` will contain two configurable fields called `description` and `tags`. During creation of game component (`CreateGameEntity`) the TagComponent from LmbrCentral gem will be created and fed with list of tags. Creating the TagComponent is useful to make this feature compatible with O3DE's tag system. -The box or sphere shape component allows to define optional boundaries around named pose. +The box or sphere shape component allows to definition of optional boundaries around the named pose. **Important** Convex hull bound shape will not be supported yet. -Calling service `GetNamedPose` will discover those components and returns theirs configuration. +Calling service `GetNamedPose` will discover those components and return their configuration. Service definition [GetNamedPoses.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoses.srv): ``` @@ -536,10 +533,9 @@ geometry_msgs/Pose pose # Pose relative to world, which can be ``` During simulation entities with `Named Pose Component` will be discovered (e.g., using designated request bus or o3de tag system), -the aggregation will be filtered and returned to caller. - -**Important** Since O3DE does not requires those names to be unique, the ROS 2 gem needs to skip or extend names of duplicates. +the aggregation will be filtered and returned to the caller. +**Important** Since O3DE does not require those names to be unique, the ROS 2 gem needs to skip or extend the names of duplicates. ## GetNamedPoseBounds service @@ -557,11 +553,11 @@ Result result Bounds bounds # bounds for the named pose. ``` -It will expose data in Named Pose Game Component and corresponding Shape Components. +It will expose data in the Named Pose Game Component and corresponding Shape Components. ## Reset Simulation service -Allows ROS 2 user to reset simulation. +Allows ROS 2 user to reset the simulation. Service definition [ResetSimulation.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/ResetSimulation.srv) ``` @@ -583,18 +579,18 @@ uint8 scope # Scope of the reset. Note that simula Result result ``` -This service will be need to use multiple APIs to give results. +This service will need to use multiple APIs to give results. |Scope | Planned API and usage | |----------------|-------------------- |SCOPE_ALL | ConsoleRequestBus and `LoadLevel` command. |SCOPE_SPAWNED | Internal gem API to destroy all spawn tickets in ROS 2 Entities manager. -|SCOPE_STATE | Move all spawned entities to intial poses cached in ROS 2 Entities manager. +|SCOPE_STATE | Move all spawned entities to initial poses cached in ROS 2 Entities manager. |SCOPE_TIME | New ROS2Bus call ## SetSimulationState service -Allows ROS 2 user to set state of the simulation (STOPPED, PAUSED, PLAYING, QUITTING) +Allows ROS 2 user to set the state of the simulation (STOPPED, PAUSED, PLAYING, QUITTING) ``` # Change the simulation state @@ -634,10 +630,10 @@ uint8 QUITTING = 3 # Closing the simulator application. Swit uint8 state ``` -Transition from PLAYING to STOPPED will trigger level reloading. That will take a while to complete. \ -Transition from PLAYING to PAUSED will ask default physics scene to be disabled. -It will stop movement of all PhysX articulations, rigid bodies (both kinematic and simulated) and characters, but some animations will be played. -Transition from PLAYING to QUITTING will simply calling : +The transition from PLAYING to STOPPED will trigger level reloading. That will take a while to complete. \ +The transition from PLAYING to PAUSED will ask the default physics scene to be disabled. +It will stop movement of all PhysX articulations, rigid bodies (both kinematic and simulated), and characters, but some animations will be played. +The transition from PLAYING to QUITTING will simply call: ```cpp int* ptr = nullptr; *ptr= 99; @@ -648,11 +644,11 @@ alternatively: auto exit = [&]() { exit(); }; exit(); ``` -The ROS 2 Simulator manager will contain state of the simulation and perform necessary transitions. +The ROS 2 Simulator manager will contain the state of the simulation and perform necessary transitions. ## GetSimulationState service -Allows ROS 2 user to get current state of the simulation. +Allows ROS 2 user to get the current state of the simulation. Service definition [GetSimulationState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulationState.srv) @@ -676,11 +672,11 @@ During this effort some components will be retired, and some moved outside of sc ### ROS2SpawnerComponent -ROS2Spawner component will be retired and hidden away from users with CMake variable. -This component can co-exists with managers for Simulation Interfaces, but ROS 2 package that components requires will be removed from upcoming ROS 2 distribution (Kilted Kaiju). -The said package (`gazebo_msgs`) will be replaced by simulation_interfaces. -Component will be retired (instead of complete removal from codebase) to make transition to Simulation interfaces easier experience. -However using ROS2Spawner component will require few extra steps (after EOL of gazebo_msgs package): +The ROS2Spawner component will be retired and hidden away from users with the CMake variable. +This component can co-exist with managers for Simulation Interfaces, but ROS 2 package that the ROS2Spawner requires will be removed from upcoming ROS 2 distribution (Kilted Kaiju). +The said package (`gazebo_msgs`) will be replaced by `simulation_interfaces`. +The component will be retired (instead of completely removed from the codebase) to make the transition to Simulation interfaces an easier experience. +However, using ROS2Spawner component will require a few extra steps (after the EOL of the gazebo_msgs package): - cloning and building the latest [gazebo_ros_pkgs/gazebo_msgs](https://github.com/ros-simulation/gazebo_ros_pkgs/tree/3.9.0/gazebo_msgs) - sourcing custom workspace - setting CMake flag @@ -690,9 +686,9 @@ However using ROS2Spawner component will require few extra steps (after EOL of g This component's code also depends on [`gazebo_msgs`](https://github.com/ros-simulation/gazebo_ros_pkgs/blob/3.9.0/gazebo_msgs/msg/ContactState.msg). Since there is no equivalent message in simulation_interfaces component will be retired and hidden from Users with CMakeVariable. -The steps to use this component will be the same to those in ROS2SpawnerComponent. +The steps to use this component will be the same as those in the ROS2SpawnerComponent. -Note that ROS 2 community probably propose suitable replacement message in future. +Note that the ROS 2 community probably propose suitable replacement messages in the future. - - Leading of standardization in robotics domain, + - Leading standardization of simulation in the robotics domain, - easier usage of O3DE in robotics and ML pipelines, - - improve testability of the ROS 2 features, + - improve the testability of the ROS 2 features, - adjustments to EOL of `gazebo_msgs` ### What are the disadvantages of the feature? -Significant increase in code base size +Significant increase in code base size for ROS2 Gem. ### How will this be implemented or integrated into the O3DE environment? -It was explained in great details in section [ROS 2 API](#ros-2-api) +It was explained in great detail in the section [ROS 2 API](#ros-2-api). + ### Are there any alternatives to this feature? -Really, the effort needs to be taken to adjust code to deprecation of gazebo classic and `gazebo_msgs`. +The effort needs to be taken to adjust the existing code to the eprecation of Gazebo Classic and `gazebo_msgs`. ### How will users learn this feature? @@ -731,10 +728,12 @@ Really, the effort needs to be taken to adjust code to deprecation of gazebo cla - Explain how it would be taught to new and existing O3DE users. - Include any significant impacts to documentation such as; Required official video updates, required product screenshot updates (i.e. Editor UX changes), new documentation site sections. --> -- Posts by OpenRobotics in their social media +- Posts by OpenRobotics and Robotec.AI in their social media - documentation in [o3de.org](o3de.org) and [docs.ros.org](https://docs.ros.org/en/jazzy/Tutorials/Advanced/Simulators/Simulation-Main.html) +- tutorials, conferences ### Are there any open questions? - Handling integration of physics engine. -- Timing of implementation and release. \ No newline at end of file +- Timing of implementation and release. +- Avoid coupling ROS2 Gem with PhysX5 Gem. \ No newline at end of file From ab9dfb777ab9284d0b47bed05b9be55466303113 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Thu, 6 Mar 2025 13:26:03 +0100 Subject: [PATCH 05/13] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Paweł Liberadzki Co-authored-by: Jan Hanca Signed-off-by: Michał Pełka --- rfcs/RFC Simulation Interfaces.md | 44 ++++++++++++++++--------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md index 2fd3e1b..80d2b22 100644 --- a/rfcs/RFC Simulation Interfaces.md +++ b/rfcs/RFC Simulation Interfaces.md @@ -14,7 +14,7 @@ As a rule of thumb, receiving encouraging feedback from long-standing project de ### Summary: -There is an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardize simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). +This RFC is a follow-up to an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardize simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). Current implementation of similar interfaces is limited to ROS 2 Spawner Component, that utilizes gazebo messages for ROS 2 communication. Proposed approach includes three new Components that will fulfill the design presented at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1), and that are planned to be developed alongside updates to simulation interfaces. Backward compatibility will be ensured for ROS2SpawnerComponent and ROS2ContactSensor - they will be available through CMake configuration. ### What is the relevance of this feature? @@ -44,7 +44,7 @@ There is a terminology that was created in [RFC-410](https://github.com/ros-infr |Tag | A string that allows filtering entities and named poses -The implementation will be split into three (or more system components): +The implementation will be split into three (or more) system components: - ROS 2 Entities manager \ It will be responsible for the lifetime of spawned objects, it will cache initial positions. - ROS 2 Named poses manager \ @@ -52,12 +52,14 @@ The implementation will be split into three (or more system components): - ROS 2 Simulator manager \ It will be responsible for modifying the global state of the simulation (e.g., pausing, reloading). -We will decouple the implementation of those managers from the ROS 2 service. -Every manager will need to expose public methods that will be callable both from C++ and ROS 2. +We will decouple the implementation of those features from their ROS 2 interfaces. +Every manager will need to expose public methods that: +- will be callable from C++, +- will be handled through dedicated ROS 2 interface and exposed as service. The purpose of that approach is to enable testability without the need for a ROS domain. # ROS 2 API -In this section, a detailed plan of the implementation with potential limitations is presented. +This section presents the detailed plan for implementation, including potential limitation. ## GetSimulationFeatures service @@ -88,7 +90,7 @@ We do not plan to support the moment: Following formats will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)): ``` -[`.spawnables`] +[`.spawnable`] ``` **Note** Other formats e.g. `URDF` and `SDF` are supported by ROS 2 Gem, but only in Editor. @@ -136,11 +138,11 @@ Bounds spawn_bounds # Optional spawn area bounds which ful This service advertises available spawnables that can be used in simulation. We will utilize the asset catalog to find those spawnables. -There is a useful API in the Engine to get products assets from the asset catalog: +There is a useful API in the Engine to get product assets from the asset catalog: ```cpp AZ::Data::AssetCatalogRequests::EnumerateAssets ``` -The asset catalog contains product assets (such as `.spawnables`, `.azmodel`, `.azbuffer`). +The asset catalog contains product assets (such as `.spawnable`, `.azmodel`, `.azbuffer`). We will introduce another product asset called `.simulationinfo`. This asset will contain necessary data about Prefab that can be spawned or adjusted by Simulation Interfaces. @@ -175,7 +177,7 @@ A simulation expert who wants to create a robot (or other simulation-ready asset * and hand-fill bounds (e.g., sphere radius), - export simulation with the export script and [bundle assets](https://docs.o3de.org/docs/user-guide/packaging/asset-bundler/) -A ROS 2 user who calls the `GetSpawnables` service against GameLauncher will trigger the following sequence: +A simulation interfaces user who calls the `GetSpawnables` service against GameLauncher will trigger the following sequence: - a call to the asset catalog to find all product assets of the type `.simulationinfo`. - The `ROS 2 Entity manager` will aggregate found assets and will prepare a response that will contain: * `uri` as `spawnable://@cache@/robot/foorobot.spawnable` @@ -246,25 +248,25 @@ The ROS 2 user who wants to spawn a new object in their simulation has to have a Spawning assets from the file system e.g., `spawnable://home/michalpelka/robots/FooRobot.spawnables` will not be supported. With that URI `ROS 2 Entity Manager` will find respective Asset Id. -Next, the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn. +Next, the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn entity. During spawning the spawned O3DE entities will be modified: - change the name of the root entity to that given by the `name` field, - [Transform Component](https://docs.o3de.org/docs/user-guide/components/reference/transform/) of the root entity will modified to reflect the value of the `initial_pose` field, - [ROS2 Frame](https://www.docs.o3de.org/docs/user-guide/components/reference/ros2/core/ros2-frame/) to set correct namespace. - A component called `SimulationInfoComponent` will be created and attached to the root entity. - That component will be used to cache information in `simulationinfo` to be easily accessible in the future. + That component will be used to cache information from `simulationinfo` to be easily accessible in the future. - [TagComponent](https://www.docs.o3de.org/docs/user-guide/components/reference/gameplay/tag/) from LmbrCentral gem at root entity will be created (if not present in prefab). -- TagComponent will be updated with a list of new tags. +- TagComponent will be updated with a list of tags from 'simulationinfo'. `SimulationInfoComponent` will be handling a `SimulationInfoComponentRequestBus`. -`SimulationInfoComponentRequestBus` will have a unique, string key, which will be the resulting name of spawned entity. -This bus will allow to aggregate all handling entities, and provide and API to find all spawned entities, get their state. +`SimulationInfoComponentRequestBus` will have a unique string key that will come from the name of spawned entity. +This approach will result in a centralized aggregation of entities information, and will provide an API to i.a. find all spawned entities get their states. ## GetEntities service -The service allows to discover of spawned entities. +This service provides an access to a list of all spawned entities. Service definition : [GetEntities](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntities.srv ) ``` @@ -290,7 +292,7 @@ string name # Entity unique name. ``` We will serve this by calling `SimulationInfoComponentRequestBus` with `AZ::EBusAggregateResults`. -With that, we will obtain a AZStd::vector of EntityId, that can be converted to a list of entity names. +With that, we will obtain a 'AZStd::Vector' of 'AZ::EntityId', that can be converted to a list of entity names. ## GetEntitiesStates service @@ -329,9 +331,9 @@ There will be more calls to : - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) to find current pose, - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) to find frame id. -**Note !** acceleration is will not be filled, and will not be supported. +**Note !** Acceleration is will not be filled, and will not be supported. -#### SetEntityState service +## SetEntityState service This service allows modifying the state of the chosen entity. @@ -666,7 +668,7 @@ If transition is in progress (e.g. reloading level or despawning), the old state -## Retired components in ROS 2 Gem +## Deprecated components in ROS 2 Gem During this effort some components will be retired, and some moved outside of scope of supported and canonical repos. @@ -676,7 +678,7 @@ The ROS2Spawner component will be retired and hidden away from users with the CM This component can co-exist with managers for Simulation Interfaces, but ROS 2 package that the ROS2Spawner requires will be removed from upcoming ROS 2 distribution (Kilted Kaiju). The said package (`gazebo_msgs`) will be replaced by `simulation_interfaces`. The component will be retired (instead of completely removed from the codebase) to make the transition to Simulation interfaces an easier experience. -However, using ROS2Spawner component will require a few extra steps (after the EOL of the gazebo_msgs package): +However, using ROS2Spawner component will require a few extra steps (after the EOL of the `gazebo_msgs` package): - cloning and building the latest [gazebo_ros_pkgs/gazebo_msgs](https://github.com/ros-simulation/gazebo_ros_pkgs/tree/3.9.0/gazebo_msgs) - sourcing custom workspace - setting CMake flag @@ -719,7 +721,7 @@ It was explained in great detail in the section [ROS 2 API](#ros-2-api). ### Are there any alternatives to this feature? -The effort needs to be taken to adjust the existing code to the eprecation of Gazebo Classic and `gazebo_msgs`. +The effort needs to be taken to adjust the existing code to the deprecation of Gazebo Classic and `gazebo_msgs`. ### How will users learn this feature? From fcb1ee258376c2371cc744ff385f9705a67b81e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Fri, 7 Mar 2025 11:50:06 +0100 Subject: [PATCH 06/13] Update rfcs/RFC Simulation Interfaces.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Paweł Liberadzki Signed-off-by: Michał Pełka --- rfcs/RFC Simulation Interfaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md index 80d2b22..7e01dfc 100644 --- a/rfcs/RFC Simulation Interfaces.md +++ b/rfcs/RFC Simulation Interfaces.md @@ -471,7 +471,7 @@ The bounds for particular entities will be obtained by calling `SimulationInfoCo ## GetEntityInfo service -Returns tags and category of the spawned entity. +Returns category, description and tags for spawned entity. Service definition [GetEntityInfo.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityInfo.srv): ``` From 9605515003265b5fc59b488aca452f52b4d9ef2d Mon Sep 17 00:00:00 2001 From: Jan Hanca Date: Fri, 7 Mar 2025 18:23:31 +0100 Subject: [PATCH 07/13] Code review changes up to GetNamedPoses Signed-off-by: Jan Hanca --- rfcs/RFC Simulation Interfaces.md | 407 +++++++----------------------- 1 file changed, 86 insertions(+), 321 deletions(-) diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md index 7e01dfc..88a6cba 100644 --- a/rfcs/RFC Simulation Interfaces.md +++ b/rfcs/RFC Simulation Interfaces.md @@ -14,7 +14,7 @@ As a rule of thumb, receiving encouraging feedback from long-standing project de ### Summary: -This RFC is a follow-up to an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardize simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). Current implementation of similar interfaces is limited to ROS 2 Spawner Component, that utilizes gazebo messages for ROS 2 communication. Proposed approach includes three new Components that will fulfill the design presented at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1), and that are planned to be developed alongside updates to simulation interfaces. Backward compatibility will be ensured for ROS2SpawnerComponent and ROS2ContactSensor - they will be available through CMake configuration. +This RFC is a follow-up to an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardize simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). Current implementation of similar interfaces is limited to `ROS2SpawnerComponent`, that utilizes *Gazebo* messages for ROS 2 communication. The messages were marked deprecated in the latest ROS 2 release and should be superseded. Proposed approach includes three new *Components* that will fulfill the design presented in [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1), and that are planned to be developed alongside updates to simulation interfaces. Backward compatibility will be ensured for `ROS2SpawnerComponent` and `ROS2ContactSensor` through CMake configuration with the deprecation information. ### What is the relevance of this feature? @@ -33,15 +33,15 @@ Standardization would improve user experience when using their validation, testi The feature is an API for handling number of ROS 2 [services](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Services/Understanding-ROS2-Services.html) and [actions](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Actions/Understanding-ROS2-Actions.html). -There is a terminology that was created in [RFC-410](https://github.com/ros-infrastructure/rep/issues/410) in [ros-infrastructure/rep](https://github.com/ros-infrastructure/rep): +The following terminology that was created in [RFC-410](https://github.com/ros-infrastructure/rep/issues/410) in [ros-infrastructure/rep](https://github.com/ros-infrastructure/rep): -|Term | Description | -|-----------------|-----------------------------------------------------------------------------------------------------| -|Spawnable | Robot or other object that can be spawned in simulation runtime. -|Entity | Spawned spawnable, it has a unique name. -|Bound | A region that is defined by an axis-aligned box shape, convex hull, or a sphere. -|NamedPose | SE3 (translation and rotation) transform with a unique name -|Tag | A string that allows filtering entities and named poses +| Term | Description | +| --------- | -------------------------------------------------------------------------------- | +| Spawnable | Robot or other object that can be spawned in simulation runtime. | +| Entity | Spawned spawnable, it has a unique name. | +| Bound | A region that is defined by an axis-aligned box shape, convex hull, or a sphere. | +| NamedPose | SE3 (translation and rotation) transform with a unique name | +| Tag | A string that allows filtering entities and named poses | The implementation will be split into three (or more) system components: @@ -53,10 +53,10 @@ The implementation will be split into three (or more) system components: It will be responsible for modifying the global state of the simulation (e.g., pausing, reloading). We will decouple the implementation of those features from their ROS 2 interfaces. -Every manager will need to expose public methods that: +Every manager will expose public methods that: - will be callable from C++, - will be handled through dedicated ROS 2 interface and exposed as service. -The purpose of that approach is to enable testability without the need for a ROS domain. +The purpose of that approach is to enable testability without the need for a ROS framework. # ROS 2 API This section presents the detailed plan for implementation, including potential limitation. @@ -66,7 +66,7 @@ This section presents the detailed plan for implementation, including potential The simulator needs to advertise supported features via the ROS 2 service [GetSimulatorFeatures.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulatorFeatures.srv) That service in its response provides the caller with a list of features [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg) -In the RFC we are proposing to support the following features: +The following features are the subject of this RFC: - SPAWNING - DELETING - NAMED_POSES @@ -83,85 +83,31 @@ In the RFC we are proposing to support the following features: - SIMULATION_PAUSE -We do not plan to support the moment: - - STEP_SIMULATION_SINGLE - - STEP_SIMULATION_MULTIPLE - - STEP_SIMULATION_ACTION +The features ` SIMULATION_RESET_STATE, STEP_SIMULATION_SINGLE, STEP_SIMULATION_MULTIPLE, STEP_SIMULATION_ACTION` will be introduced in the next RFC since they require multiple changes in the *PhysX Gem* and *AzPhysics API*. Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. -Following formats will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)): -``` -[`.spawnable`] -``` - -**Note** Other formats e.g. `URDF` and `SDF` are supported by ROS 2 Gem, but only in Editor. -Those tools are not available in the game mode, so spawning `SDF` and `URDF` would require: - - handling mesh importing in Game Launcher and preparing it to use with Mesh Feature processor, +Only `[.spawnable]` format will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)). Other formats, such as `URDF` and `SDF`, are supported only in the Editor mode in ROS 2 Gem. Spawning `SDF` and `URDF` would require support for the Game mode: + - handling mesh importing in game mode and preparing it to use with the *Mesh Feature Processor*, - creating materials and texture assets in runtime, - PhysX (or other Physics engine) collider mesh cooking with decomposition. Such a feature would be useful, but it is out of the scope of this RFC. -The features ` SIMULATION_RESET_STATE, STEP_SIMULATION_SINGLE, STEP_SIMULATION_MULTIPLE, STEP_SIMULATION_ACTION` will be introduced in the next RFC since they require multiple changes in the PhysX gem and AzPhysics API. -Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. - ## GetSpawnables service -This service allows users to find simulated spawnables to spawn (place) in the simulation. - -Service definition : [GetSpawnables](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSpawnables.srv) -``` -# 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 result_code. - -string[] sources # Optional field for additional sources (local or remote) to search. - # By default, each simulator has visibility of spawnables through - # some mechanisms, e.g. a set of paths, registered assets etc. - # Since the simulator cannot possibly look everywhere, - # this field allows the user to specify additional sources. - # Unrecognized values are listed as such in the result.error_message, - # but do not hinder success of the response. - # Sources may include subcategories and be simulator-specific. - ---- - -Result result -Spawnable[] spawnables # Spawnable objects with URI and additional information. -``` -Definition of individual spawnables [Spawnable.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Spawnable.msg): -``` -# 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. -``` +This service allows users to find simulated *spawnables* to spawn (place) in the simulation. \ +Service definition: [GetSpawnables](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSpawnables.srv) \ +Individual *spawnables* definition: [Spawnable.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Spawnable.msg) -This service advertises available spawnables that can be used in simulation. -We will utilize the asset catalog to find those spawnables. -There is a useful API in the Engine to get product assets from the asset catalog: -```cpp -AZ::Data::AssetCatalogRequests::EnumerateAssets -``` -The asset catalog contains product assets (such as `.spawnable`, `.azmodel`, `.azbuffer`). -We will introduce another product asset called `.simulationinfo`. -This asset will contain necessary data about Prefab that can be spawned or adjusted by Simulation Interfaces. +We will utilize the asset catalog to find the available *spawnables*. The asset catalog contains product assets (such as `.spawnable`, `.azmodel`, `.azbuffer`). We will introduce another product asset called `.simulationinfo`. It will contain necessary data about *prefab* that can be spawned or adjusted by Simulation Interfaces. The Engine's API will be used to get product assets, namely `AZ::Data::AssetCatalogRequests::EnumerateAssets`. The `.simulationinfo` product asset will be an XML / JSON file (similar to other product assets like `.physxmaterial`) and will contain at least the following information: +- a description (as a string), +- bounds (as a variant of the chosen bound region), +- list of tags, +- category, +- Asset ID of the corresponding prefab. - - a description (as a string), - - bounds (as a variant of the chosen bound region), - - list of tags, - - category, - - Asset ID of the corresponding prefab. - - -The `.simulationinfo` will be created by the asset builder that will be registered by ROS 2 Gem. -This asset builder will consume source assets called `SimulationInfo` and eventually corresponding prefabs. -It will create a `SimulationInfo` product asset in the `Cache` directory. - -The `SimulationInfo` source asset will be a sidecar (a file with the same filename) to a prefab. -It will contain: - +The `.simulationinfo` will be created by the asset builder (registered by ROS 2 Gem) based on the `SimulationInfo` source assets and, eventually, the corresponding prefabs. The `SimulationInfo` source asset will be a sidecar (a file with the same filename) to a prefab. It will contain: - a description (as a string), - bounds (as a variant of the chosen bound region), - list of tags, @@ -170,205 +116,68 @@ It will contain: A simulation expert who wants to create a robot (or other simulation-ready asset) needs: - design a new prefab using standard O3DE workflow, using all available components, - save the prefab with a name e.g., `Robots/FooRobot.prefab` -- create and fill the `SimulationInfo` file as `Robots/FooRobot.SimulationInfo` using a text editor or some tooling in O3DE: - * fill description, - * fill tags, - * fill category, - * and hand-fill bounds (e.g., sphere radius), +- create and fill the `SimulationInfo` sidecar file as `Robots/FooRobot.SimulationInfo` using a text editor or the O3DE tooling - export simulation with the export script and [bundle assets](https://docs.o3de.org/docs/user-guide/packaging/asset-bundler/) -A simulation interfaces user who calls the `GetSpawnables` service against GameLauncher will trigger the following sequence: -- a call to the asset catalog to find all product assets of the type `.simulationinfo`. -- The `ROS 2 Entity manager` will aggregate found assets and will prepare a response that will contain: +A simulation interfaces user who calls the `GetSpawnables` service against GameLauncher will call the asset catalog to find all product assets of the type `.simulationinfo`. The `ROS 2 Entity manager` will aggregate found assets and will prepare a response that will contain: * `uri` as `spawnable://@cache@/robot/foorobot.spawnable` * the description copied from `Robots/FooRobot.SimulationInfo`, * the bound information copied from `Robots/FooRobot.SimulationInfo`, * tag list copied from `Robots/FooRobot.SimulationInfo`, * category copied from `Robots/FooRobot.SimulationInfo`. -- Prepared response will be returned to the ROS 2 user. +Prepared response will be returned to the ROS 2 user. ## SpawnEntity service -Service allows to spawn entities found previously with `GetSpawnables` service. +Service allows spawning entities previously found with `GetSpawnables` service. \ +Service definition: [SpawnEntity](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SpawnEntity.srv) -Service definition [SpawnEntity](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SpawnEntity.srv): +The ROS 2 user who wants to spawn a new object in their simulation has to have a valid URI e.g.,`spawnable://@cache@/robot/foorobot.spawnable`. `ROS 2 Entities Manager` will find respective Asset ID based on the URI. -``` -# Spawn an entity (a robot, other object) by name or URI - -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 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. -string uri # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc. - # Valid URIs can be determined by calling GetSpawnables first, and you can check - # the simulator format support by reading SimulatorFeatures spawn_formats field. - # If uri field is empty, resource_string must not be empty. -string resource_string # An entity definition file passed as a string. - # Simulators may support spawning from a file generated on the fly (e.g. XACRO). - # Check whether it is supported by your simulator through GetSimulatorFeatures. - # If uri field is not empty, resource_string field will be ignored. -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. - ---- - -# Additional result.result_code values for this service. Check result.error_message for further details. -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. -``` - -The ROS 2 user who wants to spawn a new object in their simulation has to have a valid URI e.g.,`spawnable://@cache@/robot/foorobot.spawnable`. - -**Note !** -Spawning assets from the file system e.g., `spawnable://home/michalpelka/robots/FooRobot.spawnables` will not be supported. - -With that URI `ROS 2 Entity Manager` will find respective Asset Id. Next, the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn entity. -During spawning the spawned O3DE entities will be modified: -- change the name of the root entity to that given by the `name` field, -- [Transform Component](https://docs.o3de.org/docs/user-guide/components/reference/transform/) of the root entity will modified to reflect the value of the `initial_pose` field, -- [ROS2 Frame](https://www.docs.o3de.org/docs/user-guide/components/reference/ros2/core/ros2-frame/) to set correct namespace. -- A component called `SimulationInfoComponent` will be created and attached to the root entity. - That component will be used to cache information from `simulationinfo` to be easily accessible in the future. -- [TagComponent](https://www.docs.o3de.org/docs/user-guide/components/reference/gameplay/tag/) from LmbrCentral gem at root entity will be created (if not present in prefab). -- TagComponent will be updated with a list of tags from 'simulationinfo'. +**Note !** Spawning assets from the file system e.g., `spawnable://home/username/robots/FooRobot.spawnables` will not be supported. +During spawning, the spawned O3DE entities will be modified as follows: +- The name of the root entity will reflect the name given by the `name` field, +- The [TransformComponent](https://docs.o3de.org/docs/user-guide/components/reference/transform/) of the root entity will reflect the value of the `initial_pose` field, +- The [ROS2FrameComponent](https://www.docs.o3de.org/docs/user-guide/components/reference/ros2/core/ros2-frame/) will reflect the namespace the value of the `entity_namespace` field. +- A component called `SimulationInfoComponent` will be created and attached to the root entity to cache the information from `simulationinfo` and to make it easily accessible in the future. +- [TagComponent](https://www.docs.o3de.org/docs/user-guide/components/reference/gameplay/tag/) from LmbrCentral Gem will be created at root entity (if not present) and updated with a list of tags from the `simulationinfo` sidecar. `SimulationInfoComponent` will be handling a `SimulationInfoComponentRequestBus`. `SimulationInfoComponentRequestBus` will have a unique string key that will come from the name of spawned entity. -This approach will result in a centralized aggregation of entities information, and will provide an API to i.a. find all spawned entities get their states. +This approach will result in a centralized aggregation of entities' information, and will provide an API to find all spawned entities and get their states. ## GetEntities service -This service provides an access to a list of all spawned entities. -Service definition : [GetEntities](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntities.srv ) +This service provides access to a list of all spawned entities. \ +Service definition: [GetEntities](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntities.srv ) -``` -# Get objects in the scene which can be interacted with, e.g. with using SetEntityState. -# You can get further information about entities through GetEntityInfo and GetEntityState services. -# There is also a GetEntitiesStates service if you would like to get state for each entity. - -EntityFilters filters # Optional filters for the query, including name, category, tags, - # and overlap filters. - ---- - -Result result -Entity[] entities # All entities matching the filters. -``` - -where [Entity](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Entity.msg) is defined: -``` -# Entity identified by its unique name. Entities are objects in the simulation such as models and links. -# Each simulator might define what an entity is in a (slightly) different way. - -string name # Entity unique name. -``` - -We will serve this by calling `SimulationInfoComponentRequestBus` with `AZ::EBusAggregateResults`. -With that, we will obtain a 'AZStd::Vector' of 'AZ::EntityId', that can be converted to a list of entity names. +We will serve this by calling `SimulationInfoComponentRequestBus` with `AZ::EBusAggregateResults` to obtain a list of `AZ::EntityId`, that can be converted to a list of entity names. ## GetEntitiesStates service -This service allows users to get the state (speed, location, acceleration) of chosen entities. +This service allows users to get the state (speed, location, acceleration) of chosen entities. \ +Service definition: [GetEntitiesStates.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntitiesStates.srv) +Individual entity state definition: [EntityState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityState.msg) -Service definition : [GetEntitiesStates.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntitiesStates.srv) -``` -# Get objects in the scene which can be interacted, e.g. with using SetEntityState. -# Use GetEntities service instead if EntityState information for all entities is not needed. +The service handling will be similar to [GetEntities](#GetEntities). Additional calls will be required to fill the state information: + - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) will be used to find the current twist, + - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) will be used to find the current pose, + - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) will be used to find the frame ID. -EntityFilters filters # Optional filters for the query, including name, category, tags, - # and overlap filters. - ---- - -Result result -Entity[] entities # All entities matching the filters. -EntityState[] states # States for these entities. -``` - -where [EntityState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityState.msg) is: -``` -# Entity current pose, twist and acceleration - -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 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. -``` - -The service handling will be similar to [GetEntities](#GetEntities). -There will be more calls to : - - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to find current twist, - - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) to find current pose, - - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) to find frame id. - -**Note !** Acceleration is will not be filled, and will not be supported. +**Note !** Acceleration will not be filled, and will not be supported. ## SetEntityState service -This service allows modifying the state of the chosen entity. +This service allows modifying the state of the chosen entity. \ +Service definition: [SetEntityState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SetEntityState.srv) -Service definition [SetEntityState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SetEntityState.srv) -``` -# Set a state of an object, which will result in an instant change in its pose and/or twist. - -Entity entity # Entity identified by its unique name as returned by GetEntities / SpawnEntity. -EntityState state # New state to set immediately. The timestamp in header is ignored. - # Note that the acceleration field may be ignored by simulators. - ---- - -Result `result`: -``` -where [EntityState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityState.msg) is: -``` -# Entity current pose, twist and acceleration - -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 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. -``` - -The O3DE EntityId will be discovered by calling `SimulationInfoComponentRequestBus` with the entity name provided in the service request. -Next, having the EntityId the corresponding API will be called to adjust the state: - - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) or - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to - adjust the position of the simulated entity. - - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) to eventually change frame id, - - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to - adjust speed or acceleration. +The `AZ::EntityId` will be discovered by calling `SimulationInfoComponentRequestBus` with the name provided in the request. Next, the corresponding API will be called to adjust the state of the entity: + - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) or [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to adjust the position of the simulated entity. + - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) to eventually change the frame ID, + - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to adjust the speed or the acceleration. Note that serving this service is a bit tricky in O3DE. Due to the modularity of O3DE, the entities can be moved around in several ways: @@ -382,15 +191,15 @@ Due to the modularity of O3DE, the entities can be moved around in several ways: - Potential 3rd physics engine. Some of those methods respect calls to `TranformComponentRequests`, but some of them need to call directly methods in the PhysX gem. -| Method | TransformComponentRequests API| RigidBodyRequestBus API | Custom API | -|----------------------------------------|--------------------------------|--------------------------|------------| -|Simulated PhysX Rigid Body | | supports | | -|Kinematic PhysX Rigid Body | supports | | | -|TransformComponent due to parent-child | supports | | | -|TransformComponent (custom calls) | | | | -|PhysX character component | | | ? | -|PhysX ragdoll | | | ? | -|PhysX articulations | | | supports | +| Method | TransformComponentRequests API | RigidBodyRequestBus API | Custom API | +| --------------------------------------- | ------------------------------ | ----------------------- | ---------- | +| Simulated PhysX Rigid Body | | supports | | +| Kinematic PhysX Rigid Body | supports | | | +| TransformComponent due to parent-child | supports | | | +| TransformComponent (custom calls) | | | | +| PhysX character component | | | ? | +| PhysX ragdoll | | | ? | +| PhysX articulations | | | supports | The correct API needs to be chosen to get the expected outcome it can be quite tricky. Let us investigate moving a `Simulated PhysX Rigid Body'. @@ -419,82 +228,38 @@ The alternative, approach would be to cycle through: - Use `TransformBus::Events::SetWorldTM` to change location, - enable simulation of [simulated body](https://docs.o3de.org/docs/user-guide/interactivity/physics/nvidia-physx/simulated-bodies/). -The velocity (twist) can be applied using `RigidBodyRequestBus::SetLinearVelocity` and `RigidBodyRequestBus::SetAngularVelocity`. -It will be effective against Simulated PhysX Rigid Body and Kinematic PhysX Rigid Body and should give a warning if it called against -unsupported type. - +The velocity (twist) can be applied using `RigidBodyRequestBus::SetLinearVelocity` and `RigidBodyRequestBus::SetAngularVelocity`. +It will be effective against Simulated PhysX Rigid Body and Kinematic PhysX Rigid Body and should give a warning if it called against unsupported type. The acceleration can be applied using `RigidBodyRequestBus::ApplyLinearImpulse` w.r.t object's mass. It will be effective against Simulated PhysX Rigid Body and should give a warning if it is called against unsupported type. -**Important :** Currently ROS2 Gem is heavily dependant on PhysX5 (due to SDF importer). The decoupling of those needs to be done in the future. +**Important :** Currently ROS2 Gem is heavily dependent on PhysX5 (due to SDF importer). The decoupling of those needs to be done in the future. ## DeleteEntity service - -Despawn previously spawned entity - -Service definition [DeleteEntity.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/DeleteEntity.srv) -``` -# Remove an entity (a robot, other object) from the simulation - -Entity entity # Entity identified by its unique name with a namespace, - # as returned by SpawnEntity or GetEntities. ---- - -Result result -``` +This service allows despawning the previously spawned entities. \ +Service definition: [DeleteEntity.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/DeleteEntity.srv) -The O3DE entity ID and their spawn ticket ID will be discovered by `SimulationInfoComponentRequestBus`. -Next the component `ROS 2 Entity manager` will be asked to despawn and remove the corresponding spawn ticket. +The `AZ::EntityId` will be discovered by calling `SimulationInfoComponentRequestBus` with the name provided in the request. Next, the corresponding API will be called to despawn and remove the corresponding spawn ticket. -**Important:** This mechanism will now allow to delete of entities that are part of the level prefab (e.g., prefab instantiated in Editor). +**Important:** This mechanism will allow to delete the entities that are part of the level prefab (e.g., prefab instantiated in Editor). ## GetEntityBounds service -Returns bounds of the spawned entity. - -Service definition [GetEntityBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityBounds.srv) -``` -# Get geometrical bounds for entity. This feature is available if GetSimulatorFeatures includes ENTITY_BOUNDS feature. - -Entity entity # Entity identified by its unique name as returned by GetEntities / SpawnEntity. - ---- - -Result result -Bounds bounds -``` +This service allows to get the bounds of the previously spawned entities. \ +Service definition: [GetEntityBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityBounds.srv) -The bounds for particular entities will be obtained by calling `SimulationInfoComponentRequestBus`. +The bound for the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. ## GetEntityInfo service -Returns category, description and tags for spawned entity. - -Service definition [GetEntityInfo.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityInfo.srv): -``` -# Get type and other information about an entity. - -Entity entity # Entity identified by its unique name as returned by GetEntities / SpawnEntity. - ---- - -Result result -EntityInfo info # Only valid if result.result_code is OK. -``` -where [EntityInfo.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityInfo.msg): -``` -# Entity type and additional information - -uint8 category # Major category for the entity. Extra entity type distinction can be made through tags. - # See EntityCategories for defined category values. -string description # optional: verbose, human-readable description of the entity. -string[] tags # optional: tags which are useful for filtering and categorizing entities further. -``` +This service allows to get the category, description and tags for the given entity. \ +Service definition: [GetEntityInfo.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityInfo.srv) \ +Particular entity info definition: [EntityInfo.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityInfo.msg) -This information will be obtained from `SimulationInfoComponentRequestBus`. +This information the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. ## GetNamedPoses service @@ -583,12 +348,12 @@ Result result This service will need to use multiple APIs to give results. -|Scope | Planned API and usage | -|----------------|-------------------- -|SCOPE_ALL | ConsoleRequestBus and `LoadLevel` command. -|SCOPE_SPAWNED | Internal gem API to destroy all spawn tickets in ROS 2 Entities manager. -|SCOPE_STATE | Move all spawned entities to initial poses cached in ROS 2 Entities manager. -|SCOPE_TIME | New ROS2Bus call +| Scope | Planned API and usage | +| ------------- | ---------------------------------------------------------------------------- | +| SCOPE_ALL | ConsoleRequestBus and `LoadLevel` command. | +| SCOPE_SPAWNED | Internal gem API to destroy all spawn tickets in ROS 2 Entities manager. | +| SCOPE_STATE | Move all spawned entities to initial poses cached in ROS 2 Entities manager. | +| SCOPE_TIME | New ROS2Bus call | ## SetSimulationState service @@ -738,4 +503,4 @@ The effort needs to be taken to adjust the existing code to the deprecation of G - Handling integration of physics engine. - Timing of implementation and release. -- Avoid coupling ROS2 Gem with PhysX5 Gem. \ No newline at end of file +- Avoid coupling ROS2 Gem with PhysX5 Gem. From 735bb3dcb49789ffc2a2aa784582ccae1efaa2e0 Mon Sep 17 00:00:00 2001 From: Jan Hanca Date: Mon, 10 Mar 2025 19:29:50 +0100 Subject: [PATCH 08/13] Code review changes after GetNamedPoses Signed-off-by: Jan Hanca --- rfcs/RFC Simulation Interfaces.md | 251 +++++++++--------------------- 1 file changed, 74 insertions(+), 177 deletions(-) diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md index 88a6cba..72eda90 100644 --- a/rfcs/RFC Simulation Interfaces.md +++ b/rfcs/RFC Simulation Interfaces.md @@ -45,18 +45,14 @@ The following terminology that was created in [RFC-410](https://github.com/ros-i The implementation will be split into three (or more) system components: -- ROS 2 Entities manager \ - It will be responsible for the lifetime of spawned objects, it will cache initial positions. -- ROS 2 Named poses manager \ - It will be responsible for aggregating information in the Named Pose Game Component. -- ROS 2 Simulator manager \ - It will be responsible for modifying the global state of the simulation (e.g., pausing, reloading). - -We will decouple the implementation of those features from their ROS 2 interfaces. -Every manager will expose public methods that: +- `ROS 2 Entities manager`: responsible for the lifetime of spawned objects, it will cache initial positions. +- `ROS 2 Named poses manager`: responsible for aggregating information in the Named Pose Game Component. +- `ROS 2 Simulator manager`: responsible for modifying the global state of the simulation (e.g., pausing, reloading). + +We will decouple the implementation of those features from their ROS 2 interfaces. Every manager will expose public methods that: - will be callable from C++, - will be handled through dedicated ROS 2 interface and exposed as service. -The purpose of that approach is to enable testability without the need for a ROS framework. +The purpose of that approach is to enable testability without the need for a ROS framework and ensure the whole system can be used with any middleware in the future. # ROS 2 API This section presents the detailed plan for implementation, including potential limitation. @@ -83,7 +79,7 @@ The following features are the subject of this RFC: - SIMULATION_PAUSE -The features ` SIMULATION_RESET_STATE, STEP_SIMULATION_SINGLE, STEP_SIMULATION_MULTIPLE, STEP_SIMULATION_ACTION` will be introduced in the next RFC since they require multiple changes in the *PhysX Gem* and *AzPhysics API*. Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. +The features *SIMULATION_RESET_STATE*, *STEP_SIMULATION_SINGLE*, *STEP_SIMULATION_MULTIPLE*, *STEP_SIMULATION_ACTION* will be introduced in the next RFC since they require multiple changes in the *PhysX Gem* and *AzPhysics API*. Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. Only `[.spawnable]` format will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)). Other formats, such as `URDF` and `SDF`, are supported only in the Editor mode in ROS 2 Gem. Spawning `SDF` and `URDF` would require support for the Game mode: - handling mesh importing in game mode and preparing it to use with the *Mesh Feature Processor*, @@ -136,7 +132,7 @@ The ROS 2 user who wants to spawn a new object in their simulation has to have a Next, the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn entity. -**Note !** Spawning assets from the file system e.g., `spawnable://home/username/robots/FooRobot.spawnables` will not be supported. +**Note:** Spawning assets from the file system e.g., `spawnable://home/username/robots/FooRobot.spawnables` will not be supported. During spawning, the spawned O3DE entities will be modified as follows: - The name of the root entity will reflect the name given by the `name` field, @@ -167,7 +163,7 @@ The service handling will be similar to [GetEntities](#GetEntities). Additional - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) will be used to find the current pose, - [ROS2FrameBus.h](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/Code/Include/ROS2/Frame/ROS2FrameBus.h) will be used to find the frame ID. -**Note !** Acceleration will not be filled, and will not be supported. +**Note:** Acceleration will not be filled, and will not be supported. ## SetEntityState service @@ -235,7 +231,7 @@ The acceleration can be applied using `RigidBodyRequestBus::ApplyLinearImpulse` It will be effective against Simulated PhysX Rigid Body and should give a warning if it is called against unsupported type. -**Important :** Currently ROS2 Gem is heavily dependent on PhysX5 (due to SDF importer). The decoupling of those needs to be done in the future. +**Note:** Currently ROS2 Gem is heavily dependent on PhysX5 (due to SDF importer). The decoupling of those needs to be done in the future. ## DeleteEntity service @@ -244,14 +240,14 @@ Service definition: [DeleteEntity.srv](https://github.com/adamdbrw/simulation_in The `AZ::EntityId` will be discovered by calling `SimulationInfoComponentRequestBus` with the name provided in the request. Next, the corresponding API will be called to despawn and remove the corresponding spawn ticket. -**Important:** This mechanism will allow to delete the entities that are part of the level prefab (e.g., prefab instantiated in Editor). +**Note:** This mechanism will allow to delete the entities that are part of the level prefab (e.g., prefab instantiated in Editor). ## GetEntityBounds service This service allows to get the bounds of the previously spawned entities. \ Service definition: [GetEntityBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityBounds.srv) -The bound for the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. +The bound for the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. The information about entity's bounds will be stored within the `.simulationinfo` product asset, and it will be generated based on the source asset data provided by the simulation engineer. ## GetEntityInfo service @@ -259,148 +255,53 @@ This service allows to get the category, description and tags for the given enti Service definition: [GetEntityInfo.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityInfo.srv) \ Particular entity info definition: [EntityInfo.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityInfo.msg) -This information the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. +This information will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. The information will be stored within the `.simulationinfo` product asset, and it will be generated based on the source asset data provided by the simulation engineer. ## GetNamedPoses service -Simulation expert using O3DE Editor can add entity with component from ROS2 gem called `Named Pose Editor Component`. -This component will require `TransformService` and dependent services `BoxShapeService` and `SphereShapeService` -The `Named Pose Component` will contain two configurable fields called `description` and `tags`. -During creation of game component (`CreateGameEntity`) the TagComponent from LmbrCentral gem will be created and fed with list of tags. -Creating the TagComponent is useful to make this feature compatible with O3DE's tag system. -The box or sphere shape component allows to definition of optional boundaries around the named pose. - -**Important** Convex hull bound shape will not be supported yet. - -Calling service `GetNamedPose` will discover those components and return their configuration. - -Service definition [GetNamedPoses.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoses.srv): -``` -# Get predefined poses which are convenient to for spawning, navigation goals etc. - -TagsFilter tags # Tags filter to apply. Only named poses with matching tags field - # will be returned. Can be empty (see TagsFilter). +This service allows to get the list of the predefined poses which are convenient to for spawning, navigation goals, etc. \ +Service definition: [GetNamedPoses.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoses.srv) \ +Individual named pose definition: [NamedPose.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/NamedPose.msg) ---- +This information will be obtained by calling a respective bus of `ROS 2 Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The poses will be predefined by a simulation expert using O3DE Editor. In particular, each entity with `NamedPoseComponent` from ROS 2 Gem will be registered in the poses manager. The `NamedPoseComponent` will contain two configurable fields called `description` and `tags`. During creation of game component (`CreateGameEntity`) the `TagComponent` from `LmbrCentral` Gem will be created and fed with the list of tags. -Result result -NamedPose[] poses # A list of predefined poses, which may be empty. -``` -where: [TagsFilter.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/TagsFilter.msg), -[NamedPose.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/NamedPose.msg): -``` -# 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. -``` - -During simulation entities with `Named Pose Component` will be discovered (e.g., using designated request bus or o3de tag system), -the aggregation will be filtered and returned to the caller. - -**Important** Since O3DE does not require those names to be unique, the ROS 2 gem needs to skip or extend the names of duplicates. +**Note:** `ROS 2 Named poses manager` will ensure the names are unique (O3DE does not check for the name's uniqueness). ## GetNamedPoseBounds service -Service allows to get boundaries defined in Named Pose. +This service allows to get the boundaries defined in the predefined pose object. \ +Service definition [GetNamedPoseBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoseBounds.srv) -Service definition [GetNamedPoseBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoseBounds.srv): -``` -# Get bounds for the named pose. This feature is available if GetSimulatorFeatures includes POSE_BOUNDS feature. +The information about the boundaries will be obtained by calling a respective bus of `ROS 2 Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The boundaries of the pose will be predefined by a simulation expert using O3DE Editor by adding `TransformService` and dependent services `BoxShapeService` and `SphereShapeService` alongside with the `NamedPoseComponent`. -string name # unique names (as returned from GetNamedPoses). - ---- - -Result result -Bounds bounds # bounds for the named pose. -``` - -It will expose data in the Named Pose Game Component and corresponding Shape Components. +**Note:** Convex hull bound shape will not be supported in this implementation. This subject will be cover by another RFC when necessary. ## Reset Simulation service -Allows ROS 2 user to reset the simulation. - -Service definition [ResetSimulation.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/ResetSimulation.srv) -``` -# Reset the simulation to the start, including the entire scene and the simulation time. -# Objects that were dynamically spawned are de-spawned. - -uint8 SCOPE_DEFAULT = 0 # same as ALL. -uint8 SCOPE_TIME = 1 # Reset simulation time to start. -uint8 SCOPE_STATE = 2 # Reset state such as poses and velocities. This may include state randomization - # if such feature is available and turned on. -uint8 SCOPE_SPAWNED = 4 # De-spawns all spawned entities. -uint8 SCOPE_ALL = 255 # Fully resets simulation to the start, as if it was closed and launched again. - -uint8 scope # Scope of the reset. Note that simulators might only support some scopes. - # This is a bit field which may be checked for each scope e.g. scope & TIME. - ---- - -Result result -``` +This service allows to reset the simulation via ROS 2 interface. \ +Service definition: [ResetSimulation.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/ResetSimulation.srv) -This service will need to use multiple APIs to give results. +This service will be handled by `ROS 2 Simulator manager`. It will use multiple APIs to give results. -| Scope | Planned API and usage | -| ------------- | ---------------------------------------------------------------------------- | -| SCOPE_ALL | ConsoleRequestBus and `LoadLevel` command. | -| SCOPE_SPAWNED | Internal gem API to destroy all spawn tickets in ROS 2 Entities manager. | -| SCOPE_STATE | Move all spawned entities to initial poses cached in ROS 2 Entities manager. | -| SCOPE_TIME | New ROS2Bus call | +| Scope | Planned API and usage | +| ------------- | ------------------------------------------------------------------------------ | +| SCOPE_ALL | `ConsoleRequestBus` and `LoadLevel` command. | +| SCOPE_SPAWNED | Internal API to destroy all spawn tickets using `ROS 2 Entities manager`. | +| SCOPE_STATE | Move all spawned entities to initial poses cached in `ROS 2 Entities manager`. | +| SCOPE_TIME | New call using `ROS2Bus` | ## SetSimulationState service -Allows ROS 2 user to set the state of the simulation (STOPPED, PAUSED, PLAYING, QUITTING) +This service allows to set the state of the simulation (*STOPPED*, *PAUSED*, *PLAYING*, *QUITTING*). \ +Service definition: [SimulationState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulationState.msg) -``` -# Change the simulation state - - -SimulationState state # Target state to set for the simulation. +This service will be handled by `ROS 2 Simulator manager`. ---- +The transition from *PLAYING* or *PAUSED* to *STOPPED* will trigger level reloading. -uint8 ALREADY_IN_TARGET_STATE = 101 # Additional result type for this call, which means simulation was already - # in the target state (e.g. was already stopped when STOP was requested). -uint8 STATE_TRANSITION_ERROR = 102 # The simulator failed to transition to the target state. This might happen - # especially with the transition to PLAYING from STOPPED. - # See result.error_message for details. -uint8 INCORRECT_TRANSITION = 103 # Incorrect transition (pausing when in stopped state). +The transition from *PLAYING* to *PAUSED* will ask the default physics scene to be disabled. It will stop movement of all PhysX articulations, rigid bodies (both kinematic and simulated), and characters, but some animations will be played. The transition from *PAUSED* to *PLAYING* will do the opposite. -Result result - -``` -where [SimulationState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulationState.msg) is defined as: -``` -# Simulation states used in SetSimulationState and returned in GetSimulationState - -uint8 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 PLAYING = 1 # Simulation is playing, can be either paused or stopped. -uint8 PAUSED = 2 # Simulation is paused, can be either stopped (which will reset it) or played. -uint8 QUITTING = 3 # Closing the simulator application. Switching from PLAYING or 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 -``` - -The transition from PLAYING to STOPPED will trigger level reloading. That will take a while to complete. \ -The transition from PLAYING to PAUSED will ask the default physics scene to be disabled. -It will stop movement of all PhysX articulations, rigid bodies (both kinematic and simulated), and characters, but some animations will be played. -The transition from PLAYING to QUITTING will simply call: +The transition from *PLAYING*, *PAUSED*, or *STOPPED* to *QUITTING* will call: ```cpp int* ptr = nullptr; *ptr= 99; @@ -415,48 +316,44 @@ The ROS 2 Simulator manager will contain the state of the simulation and perform ## GetSimulationState service -Allows ROS 2 user to get the current state of the simulation. +This service allows to get the current state of the simulation. \ +Service definition: [GetSimulationState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulationState.srv) -Service definition [GetSimulationState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulationState.srv) +This service will be handled by `ROS 2 Simulator manager`. If transition is in progress (e.g. reloading level or despawning), the old state will be returned. -``` -# Gets the simulation state (paused, playing, stopped) +# Deprecated components in ROS 2 Gem ---- +During this effort some components will be retired, and some moved outside of scope of supported and canonical repos. This is primarily caused by ROS 2 community retiring `gazebo_msgs`. -SimulationState state # Current state of the simulation. +### ROS2SpawnerComponent -Result result -``` -The ROS 2 Simulator manager will return current state. -If transition is in progress (e.g. reloading level or despawning), the old state will be returned. +The `ROS2SpawnerComponent` can co-exist with managers for *Simulation Interfaces* proposed in this RFC, but ROS 2 dependencies (namely `gazebo_msgs`) will be removed from upcoming ROS 2 distribution (`Kilted Kaiju`). The component will be marked deprecated (instead of completely removed from the codebase) to make the transition to Simulation Interfaces an easier experience. The component will be hidden away from users with the *CMake variable*. This variable will be first set to *enabled* by default, and toggled to *disabled* after the deprecation period into the retirement period. Finally, the component will be completely removed from ROS 2 Gem. +**Note:** Additional message during the *configure* step will be shown to the user if `gazebo_msgs` package is not detected, but the *variable* is set *true*. +Users of `Kilted Kaiju` (and newer) ROS 2 releases will be able to use the deprecated component by building the package manually in their custom ROS 2 workspace. This involves: +- cloning and building the latest [gazebo_ros_pkgs/gazebo_msgs](https://github.com/ros-simulation/gazebo_ros_pkgs/tree/3.9.0/gazebo_msgs) +- sourcing custom workspace +- setting CMake flag +- building ROS2 gem from source. -## Deprecated components in ROS 2 Gem +The deprecation period and the retirement period of the component are yet to be decided. -During this effort some components will be retired, and some moved outside of scope of supported and canonical repos. +### ROS2ContactSensorComponent -### ROS2SpawnerComponent +The `ROS2ContactSensorComponent` is independent of *Simulation Interfaces* proposed in this RFC, but ROS 2 dependencies (namely `gazebo_msgs`) will be removed from upcoming ROS 2 distribution (`Kilted Kaiju`). In particular, this component uses [`ContactState` message](https://github.com/ros-simulation/gazebo_ros_pkgs/blob/3.9.0/gazebo_msgs/msg/ContactState.msg). The component will be hidden away from users with the *CMake variable*. This variable will be first set to *enabled* by default, and toggled to *disabled* after the deprecation period into the retirement period. Finally, the component will be completely removed from ROS 2 Gem. -The ROS2Spawner component will be retired and hidden away from users with the CMake variable. -This component can co-exist with managers for Simulation Interfaces, but ROS 2 package that the ROS2Spawner requires will be removed from upcoming ROS 2 distribution (Kilted Kaiju). -The said package (`gazebo_msgs`) will be replaced by `simulation_interfaces`. -The component will be retired (instead of completely removed from the codebase) to make the transition to Simulation interfaces an easier experience. -However, using ROS2Spawner component will require a few extra steps (after the EOL of the `gazebo_msgs` package): +**Note:** Additional message during the *configure* step will be shown to the user if `gazebo_msgs` package is not detected, but the *variable* is set *true*. + +Users of `Kilted Kaiju` (and newer) ROS 2 releases will be able to use the deprecated component by building the package manually in their custom ROS 2 workspace. This involves: - cloning and building the latest [gazebo_ros_pkgs/gazebo_msgs](https://github.com/ros-simulation/gazebo_ros_pkgs/tree/3.9.0/gazebo_msgs) - sourcing custom workspace - setting CMake flag - building ROS2 gem from source. -### ROS2ContactSensorComponent - -This component's code also depends on [`gazebo_msgs`](https://github.com/ros-simulation/gazebo_ros_pkgs/blob/3.9.0/gazebo_msgs/msg/ContactState.msg). -Since there is no equivalent message in simulation_interfaces component will be retired and hidden from Users with CMakeVariable. -The steps to use this component will be the same as those in the ROS2SpawnerComponent. - -Note that the ROS 2 community probably propose suitable replacement messages in the future. +The deprecation period and the retirement period of the component are yet to be decided. +# Conclusions - -### What are the advantages of the feature? +## What are the advantages of the feature? - - Leading standardization of simulation in the robotics domain, - - easier usage of O3DE in robotics and ML pipelines, - - improve the testability of the ROS 2 features, - - adjustments to EOL of `gazebo_msgs` +- Adoption of the simulation standard in the robotics domain in O3DE. +- Improving the user experience of robotics and ML pipelines in O3DE. +- Improvement of the ROS 2 features' testability. +- Adjustments to the end-of-life of `gazebo_msgs`. -### What are the disadvantages of the feature? +## What are the disadvantages of the feature? -Significant increase in code base size for ROS2 Gem. +Significant increase in the code base size for ROS 2 Gem. ### How will this be implemented or integrated into the O3DE environment? -It was explained in great detail in the section [ROS 2 API](#ros-2-api). +The *Simulation Interfaces* feature will build over the ROS 2 Gem. In particular, three separate tools for managing the *spawnables*, the simulation and the named poses will be implemented as O3DE *System Components*. The tools will be callable using O3DE bus system and via ROS 2 middleware. The latter will be decoupled from the *Simulation Interfaces* implementation to ensure the system can be used with different frameworks in the future. More details about the design are given in section [ROS 2 API](#ros-2-api). ### Are there any alternatives to this feature? -The effort needs to be taken to adjust the existing code to the deprecation of Gazebo Classic and `gazebo_msgs`. +The effort needs to be taken to adjust the existing code to the deprecation of Gazebo Classic and `gazebo_msgs`. *ROS 2 Simulation Interfaces* are the upcoming simulation standard that was primarily designed by O3DE *sig-simulation* developers. It will be integrated into all simulation engines and, therefore, it makes no sense to ### How will users learn this feature? @@ -495,12 +391,13 @@ The effort needs to be taken to adjust the existing code to the deprecation of G - Explain how it would be taught to new and existing O3DE users. - Include any significant impacts to documentation such as; Required official video updates, required product screenshot updates (i.e. Editor UX changes), new documentation site sections. --> -- Posts by OpenRobotics and Robotec.AI in their social media -- documentation in [o3de.org](o3de.org) and [docs.ros.org](https://docs.ros.org/en/jazzy/Tutorials/Advanced/Simulators/Simulation-Main.html) -- tutorials, conferences +- Documentation in [o3de.org](o3de.org) and [docs.ros.org](https://docs.ros.org/en/jazzy/Tutorials/Advanced/Simulators/Simulation-Main.html). +- Discord social platform of O3DE. +- Posts by OpenRobotics and Robotec.ai in their social media. +- Tutorials, conferences. ### Are there any open questions? -- Handling integration of physics engine. -- Timing of implementation and release. -- Avoid coupling ROS2 Gem with PhysX5 Gem. +- Handling integration with the physics engine. +- Timing of the implementation and the release. +- Avoid coupling ROS 2 Gem with PhysX5 Gem. From 26d2361044f1d302455d5e0c1d47aaa2511d1bb3 Mon Sep 17 00:00:00 2001 From: Jan Hanca Date: Mon, 17 Mar 2025 15:25:18 +0100 Subject: [PATCH 09/13] External code review changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Hanca Co-authored-by: Michał Pełka Co-authored-by: Paweł Liberadzki Signed-off-by: Jan Hanca --- rfcs/RFC Simulation Interfaces.md | 39 +++++++++++++++++-------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/rfcs/RFC Simulation Interfaces.md b/rfcs/RFC Simulation Interfaces.md index 72eda90..2588056 100644 --- a/rfcs/RFC Simulation Interfaces.md +++ b/rfcs/RFC Simulation Interfaces.md @@ -14,7 +14,7 @@ As a rule of thumb, receiving encouraging feedback from long-standing project de ### Summary: -This RFC is a follow-up to an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardize simulation interfaces existing robotics simulators in [ROS 2](https://docs.ros.org/en/jazzy/index.html). Current implementation of similar interfaces is limited to `ROS2SpawnerComponent`, that utilizes *Gazebo* messages for ROS 2 communication. The messages were marked deprecated in the latest ROS 2 release and should be superseded. Proposed approach includes three new *Components* that will fulfill the design presented in [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1), and that are planned to be developed alongside updates to simulation interfaces. Backward compatibility will be ensured for `ROS2SpawnerComponent` and `ROS2ContactSensor` through CMake configuration with the deprecation information. +This RFC is a follow-up to an effort at [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1) to standardize [ROS 2](https://docs.ros.org/en/jazzy/index.html) simulation interfaces for robotics simulators. Current implementation of similar interfaces is limited to `ROS2SpawnerComponent`, that utilizes *Gazebo* messages for ROS 2 communication. The messages were marked deprecated in the latest ROS 2 release and should be superseded. Proposed approach includes three new *Components* that will fulfill the design presented in [ros-simulation/simulation_interfaces](https://github.com/ros-simulation/simulation_interfaces/pull/1), and that are planned to be developed alongside updates to simulation interfaces. Backward compatibility will be ensured for `ROS2SpawnerComponent` and `ROS2ContactSensor` through CMake configuration with the deprecation information. ### What is the relevance of this feature? @@ -39,7 +39,7 @@ The following terminology that was created in [RFC-410](https://github.com/ros-i | --------- | -------------------------------------------------------------------------------- | | Spawnable | Robot or other object that can be spawned in simulation runtime. | | Entity | Spawned spawnable, it has a unique name. | -| Bound | A region that is defined by an axis-aligned box shape, convex hull, or a sphere. | +| Bounds | A volume that is defined by an axis-aligned box shape, convex hull, or a sphere. | | NamedPose | SE3 (translation and rotation) transform with a unique name | | Tag | A string that allows filtering entities and named poses | @@ -52,6 +52,7 @@ The implementation will be split into three (or more) system components: We will decouple the implementation of those features from their ROS 2 interfaces. Every manager will expose public methods that: - will be callable from C++, - will be handled through dedicated ROS 2 interface and exposed as service. + The purpose of that approach is to enable testability without the need for a ROS framework and ensure the whole system can be used with any middleware in the future. # ROS 2 API @@ -68,6 +69,7 @@ The following features are the subject of this RFC: - NAMED_POSES - POSE_BOUNDS - ENTITY_BOUNDS + - ENTITY_TAGS - ENTITY_STATE_LISTING - ENTITY_STATE_SETTING @@ -75,11 +77,9 @@ The following features are the subject of this RFC: - SIMULATION_RESET - SIMULATION_RESET_TIME - SIMULATION_RESET_SPAWNED - - SIMULATION_RESET_STATE - - SIMULATION_PAUSE -The features *SIMULATION_RESET_STATE*, *STEP_SIMULATION_SINGLE*, *STEP_SIMULATION_MULTIPLE*, *STEP_SIMULATION_ACTION* will be introduced in the next RFC since they require multiple changes in the *PhysX Gem* and *AzPhysics API*. Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. +The features *STEP_SIMULATION_SINGLE*, *STEP_SIMULATION_MULTIPLE*, and *STEP_SIMULATION_ACTION* will be introduced in the next RFC since they require multiple changes in the *PhysX Gem* and *AzPhysics API*. Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. Only `[.spawnable]` format will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)). Other formats, such as `URDF` and `SDF`, are supported only in the Editor mode in ROS 2 Gem. Spawning `SDF` and `URDF` would require support for the Game mode: - handling mesh importing in game mode and preparing it to use with the *Mesh Feature Processor*, @@ -121,6 +121,7 @@ A simulation interfaces user who calls the `GetSpawnables` service against GameL * the bound information copied from `Robots/FooRobot.SimulationInfo`, * tag list copied from `Robots/FooRobot.SimulationInfo`, * category copied from `Robots/FooRobot.SimulationInfo`. + Prepared response will be returned to the ROS 2 user. ## SpawnEntity service @@ -193,8 +194,8 @@ Some of those methods respect calls to `TranformComponentRequests`, but some of | Kinematic PhysX Rigid Body | supports | | | | TransformComponent due to parent-child | supports | | | | TransformComponent (custom calls) | | | | -| PhysX character component | | | ? | -| PhysX ragdoll | | | ? | +| PhysX character component | | | TBD | +| PhysX ragdoll | | | TBD | | PhysX articulations | | | supports | The correct API needs to be chosen to get the expected outcome it can be quite tricky. @@ -240,14 +241,16 @@ Service definition: [DeleteEntity.srv](https://github.com/adamdbrw/simulation_in The `AZ::EntityId` will be discovered by calling `SimulationInfoComponentRequestBus` with the name provided in the request. Next, the corresponding API will be called to despawn and remove the corresponding spawn ticket. -**Note:** This mechanism will allow to delete the entities that are part of the level prefab (e.g., prefab instantiated in Editor). +**Note:** This mechanism will **not** allow to delete the entities that are the part of the level prefab (e.g., prefab instantiated in Editor). ## GetEntityBounds service This service allows to get the bounds of the previously spawned entities. \ Service definition: [GetEntityBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityBounds.srv) -The bound for the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. The information about entity's bounds will be stored within the `.simulationinfo` product asset, and it will be generated based on the source asset data provided by the simulation engineer. +The bounds for the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. The information about entity's bounds will be stored within the `.simulationinfo` product asset, and it will be generated based on the source asset data provided by the simulation engineer. + +**Note:** Convex hull bounds shape will not be supported in this implementation. This subject will be cover by another RFC when necessary. ## GetEntityInfo service @@ -269,12 +272,12 @@ This information will be obtained by calling a respective bus of `ROS 2 Named po ## GetNamedPoseBounds service -This service allows to get the boundaries defined in the predefined pose object. \ +This service allows to get the bounds defined in the predefined pose object. \ Service definition [GetNamedPoseBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoseBounds.srv) -The information about the boundaries will be obtained by calling a respective bus of `ROS 2 Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The boundaries of the pose will be predefined by a simulation expert using O3DE Editor by adding `TransformService` and dependent services `BoxShapeService` and `SphereShapeService` alongside with the `NamedPoseComponent`. +The information about the bounds will be obtained by calling a respective bus of `ROS 2 Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The bounds of the pose will be predefined by a simulation expert using O3DE Editor by adding `TransformService` and dependent services `BoxShapeService` and `SphereShapeService` alongside with the `NamedPoseComponent`. -**Note:** Convex hull bound shape will not be supported in this implementation. This subject will be cover by another RFC when necessary. +**Note:** Convex hull bounds shape will not be supported in this implementation. This subject will be cover by another RFC when necessary. ## Reset Simulation service @@ -329,12 +332,12 @@ During this effort some components will be retired, and some moved outside of sc The `ROS2SpawnerComponent` can co-exist with managers for *Simulation Interfaces* proposed in this RFC, but ROS 2 dependencies (namely `gazebo_msgs`) will be removed from upcoming ROS 2 distribution (`Kilted Kaiju`). The component will be marked deprecated (instead of completely removed from the codebase) to make the transition to Simulation Interfaces an easier experience. The component will be hidden away from users with the *CMake variable*. This variable will be first set to *enabled* by default, and toggled to *disabled* after the deprecation period into the retirement period. Finally, the component will be completely removed from ROS 2 Gem. -**Note:** Additional message during the *configure* step will be shown to the user if `gazebo_msgs` package is not detected, but the *variable* is set *true*. +**Note:** Additional message during the *configure* step will be shown to the user if `gazebo_msgs` package is not detected, but the *variable* is set *enabled*. Users of `Kilted Kaiju` (and newer) ROS 2 releases will be able to use the deprecated component by building the package manually in their custom ROS 2 workspace. This involves: - cloning and building the latest [gazebo_ros_pkgs/gazebo_msgs](https://github.com/ros-simulation/gazebo_ros_pkgs/tree/3.9.0/gazebo_msgs) - sourcing custom workspace -- setting CMake flag +- setting *CMake variable* (after deprecation period) - building ROS2 gem from source. The deprecation period and the retirement period of the component are yet to be decided. @@ -343,12 +346,12 @@ The deprecation period and the retirement period of the component are yet to be The `ROS2ContactSensorComponent` is independent of *Simulation Interfaces* proposed in this RFC, but ROS 2 dependencies (namely `gazebo_msgs`) will be removed from upcoming ROS 2 distribution (`Kilted Kaiju`). In particular, this component uses [`ContactState` message](https://github.com/ros-simulation/gazebo_ros_pkgs/blob/3.9.0/gazebo_msgs/msg/ContactState.msg). The component will be hidden away from users with the *CMake variable*. This variable will be first set to *enabled* by default, and toggled to *disabled* after the deprecation period into the retirement period. Finally, the component will be completely removed from ROS 2 Gem. -**Note:** Additional message during the *configure* step will be shown to the user if `gazebo_msgs` package is not detected, but the *variable* is set *true*. +**Note:** Additional message during the *configure* step will be shown to the user if `gazebo_msgs` package is not detected, but the *variable* is set to *enabled*. Users of `Kilted Kaiju` (and newer) ROS 2 releases will be able to use the deprecated component by building the package manually in their custom ROS 2 workspace. This involves: - cloning and building the latest [gazebo_ros_pkgs/gazebo_msgs](https://github.com/ros-simulation/gazebo_ros_pkgs/tree/3.9.0/gazebo_msgs) - sourcing custom workspace -- setting CMake flag +- setting *CMake variable* (after deprecation period) - building ROS2 gem from source. The deprecation period and the retirement period of the component are yet to be decided. @@ -382,7 +385,9 @@ The *Simulation Interfaces* feature will build over the ROS 2 Gem. In particular ### Are there any alternatives to this feature? -The effort needs to be taken to adjust the existing code to the deprecation of Gazebo Classic and `gazebo_msgs`. *ROS 2 Simulation Interfaces* are the upcoming simulation standard that was primarily designed by O3DE *sig-simulation* developers. It will be integrated into all simulation engines and, therefore, it makes no sense to +The effort needs to be taken to adjust the existing code to the deprecation of Gazebo Classic and `gazebo_msgs`. *ROS 2 Simulation Interfaces* are the upcoming simulation standard that was primarily designed by O3DE *sig-simulation* developers. It will be integrated into all major simulation engines and, therefore, should be integrated into O3DE. + +The proposed approach allows for a smooth transition from the previous implementation to the standard. We are open for suggestions on the architecture of the O3DE integration. ### How will users learn this feature? From ea295f1e77538bcd5dcbbe0b0e3de3ea6a6c4b3c Mon Sep 17 00:00:00 2001 From: Jan Hanca Date: Mon, 17 Mar 2025 15:32:11 +0100 Subject: [PATCH 10/13] Rename RFC file to keep consistent Signed-off-by: Jan Hanca --- ...faces.md => RFC Feature - Simulation Interfaces Integration.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rfcs/RFC Simulation Interfaces.md => RFC Feature - Simulation Interfaces Integration.md (100%) diff --git a/rfcs/RFC Simulation Interfaces.md b/RFC Feature - Simulation Interfaces Integration.md similarity index 100% rename from rfcs/RFC Simulation Interfaces.md rename to RFC Feature - Simulation Interfaces Integration.md From b0cebefa89f57f19759c0ea5fa3fc3dc9cd9a545 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Mon, 17 Mar 2025 15:53:05 +0100 Subject: [PATCH 11/13] move to RFCs dir MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Pełka --- .../RFC Feature - Simulation Interfaces Integration.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename RFC Feature - Simulation Interfaces Integration.md => rfcs/RFC Feature - Simulation Interfaces Integration.md (100%) diff --git a/RFC Feature - Simulation Interfaces Integration.md b/rfcs/RFC Feature - Simulation Interfaces Integration.md similarity index 100% rename from RFC Feature - Simulation Interfaces Integration.md rename to rfcs/RFC Feature - Simulation Interfaces Integration.md From b8cb61c4d99a3bb9d21cad1d29411fe7ce73762b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Mon, 17 Mar 2025 15:55:27 +0100 Subject: [PATCH 12/13] remove easter egg MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Pełka --- ...FC Feature - Simulation Interfaces Integration.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/rfcs/RFC Feature - Simulation Interfaces Integration.md b/rfcs/RFC Feature - Simulation Interfaces Integration.md index 2588056..7110e58 100644 --- a/rfcs/RFC Feature - Simulation Interfaces Integration.md +++ b/rfcs/RFC Feature - Simulation Interfaces Integration.md @@ -304,16 +304,8 @@ The transition from *PLAYING* or *PAUSED* to *STOPPED* will trigger level reload The transition from *PLAYING* to *PAUSED* will ask the default physics scene to be disabled. It will stop movement of all PhysX articulations, rigid bodies (both kinematic and simulated), and characters, but some animations will be played. The transition from *PAUSED* to *PLAYING* will do the opposite. -The transition from *PLAYING*, *PAUSED*, or *STOPPED* to *QUITTING* will call: -```cpp - int* ptr = nullptr; - *ptr= 99; -``` -alternatively: -```cpp -#pragma clang diagnostic ignored "-Winfinite-recursion" -auto exit = [&]() { exit(); }; exit(); -``` +The transition from *PLAYING*, *PAUSED*, or *STOPPED* to *QUITTING* will close simulator calling `ConsoleRequestBus` with `quit` command. + The ROS 2 Simulator manager will contain the state of the simulation and perform necessary transitions. From 6d046a74957f18b4e444cd1ca8cd265bb5e94145 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pe=C5=82ka?= Date: Mon, 31 Mar 2025 14:38:29 +0200 Subject: [PATCH 13/13] Adjust RFC to use AZPhysics (#3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Changes to entity definition Signed-off-by: Michał Pełka * Adjust RFC to utilzie AZPhysics Signed-off-by: Michał Pełka --------- Signed-off-by: Michał Pełka --- ...ure - Simulation Interfaces Integration.md | 184 ++++++++++++------ 1 file changed, 127 insertions(+), 57 deletions(-) diff --git a/rfcs/RFC Feature - Simulation Interfaces Integration.md b/rfcs/RFC Feature - Simulation Interfaces Integration.md index 7110e58..c37125d 100644 --- a/rfcs/RFC Feature - Simulation Interfaces Integration.md +++ b/rfcs/RFC Feature - Simulation Interfaces Integration.md @@ -38,16 +38,16 @@ The following terminology that was created in [RFC-410](https://github.com/ros-i | Term | Description | | --------- | -------------------------------------------------------------------------------- | | Spawnable | Robot or other object that can be spawned in simulation runtime. | -| Entity | Spawned spawnable, it has a unique name. | +| Entity | O3DE entity with sets of requirements specified in [Requirements for Simulation Entity]\(#requirements-for-simulation-entity)| | Bounds | A volume that is defined by an axis-aligned box shape, convex hull, or a sphere. | | NamedPose | SE3 (translation and rotation) transform with a unique name | | Tag | A string that allows filtering entities and named poses | The implementation will be split into three (or more) system components: -- `ROS 2 Entities manager`: responsible for the lifetime of spawned objects, it will cache initial positions. -- `ROS 2 Named poses manager`: responsible for aggregating information in the Named Pose Game Component. -- `ROS 2 Simulator manager`: responsible for modifying the global state of the simulation (e.g., pausing, reloading). +- `Simulation Entities manager`: responsible for the lifetime of spawned objects, it will cache initial positions. +- `Simulation Named poses manager`: responsible for aggregating information in the Named Pose Game Component. +- `Simulation manager`: responsible for modifying the global state of the simulation (e.g., pausing, reloading). We will decouple the implementation of those features from their ROS 2 interfaces. Every manager will expose public methods that: - will be callable from C++, @@ -55,46 +55,117 @@ We will decouple the implementation of those features from their ROS 2 interface The purpose of that approach is to enable testability without the need for a ROS framework and ensure the whole system can be used with any middleware in the future. +### Requirements for Simulation Entity + +In O3DE entity is fundamental block of building a spawnable or a prefab. It has different meaning to "entity" defined in [RFC-410](https://github.com/ros-infrastructure/rep/issues/410). + +| Aspect | Simulated Entity | O3DE entity | +|---------------|-----------------------------|--------------| +| Naming | Unique | Non-unique | +| Referencing | By name | By Id | +| Customization | Tags, description, category | Components | + +`Simulation Entities manager` will keep mapping between simulation entities and O3DE's entities. + +The O3DE entity will be picked by `Simulation Entities Manager` when following conditions are met: +- Entity is "physical" by containing one or more components: + - [PhysX Static Rigid Body Component](https://www.docs.o3de.org/docs/user-guide/components/reference/physx/static-rigid-body/) + - [PhysX Dynamic Rigid Body Component](https://www.docs.o3de.org/docs/user-guide/components/reference/physx/rigid-body/) + - PhysX Articulation + - Or others (e.g., from other physics engine) +- Other optional requirements (e.g. need for [ROS 2 Frame component ](https://www.docs.o3de.org/docs/user-guide/components/reference/ros2/core/ros2-frame/)) + +Utilizing `AzPhysics::SceneInterface` abstraction we will be independent from PhysX 5 implementation. +What is more, number of useful tools (e.g., [Overlap Scene Query](https://docs.o3de.org/docs/user-guide/interactivity/physics/nvidia-physx/scene-queries/#overlap) are available). + +**Note:** The Simulation Interface will be dependant on PhysX 5 gem dynamically during tests. To test implemented features, physics engine gem is needed. + # ROS 2 API This section presents the detailed plan for implementation, including potential limitation. ## GetSimulationFeatures service -The simulator needs to advertise supported features via the ROS 2 service [GetSimulatorFeatures.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulatorFeatures.srv) -That service in its response provides the caller with a list of features [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg) +The simulator needs to advertise supported features via the ROS 2 service [GetSimulatorFeatures.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetSimulatorFeatures.srv) +That service in its response provides the caller with a list of features [SimulatorFeatures.msg](https://github.com/ros-simulation/simulation_interfaces/tree/main/msg/SimulatorFeatures.msg) The following features are the subject of this RFC: - - SPAWNING - - DELETING - - NAMED_POSES - - POSE_BOUNDS - - ENTITY_BOUNDS - - ENTITY_TAGS - - - ENTITY_STATE_LISTING - - ENTITY_STATE_SETTING - - SIMULATION_RESET - - SIMULATION_RESET_TIME - - SIMULATION_RESET_SPAWNED - - SIMULATION_PAUSE - -The features *STEP_SIMULATION_SINGLE*, *STEP_SIMULATION_MULTIPLE*, and *STEP_SIMULATION_ACTION* will be introduced in the next RFC since they require multiple changes in the *PhysX Gem* and *AzPhysics API*. Action [SimulateSteps.action](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/action/SimulateSteps.action) will not be supported. - -Only `[.spawnable]` format will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulatorFeatures.msg)). Other formats, such as `URDF` and `SDF`, are supported only in the Editor mode in ROS 2 Gem. Spawning `SDF` and `URDF` would require support for the Game mode: +- SPAWNING +- DELETING +- NAMED_POSES +- POSE_BOUNDS +- ENTITY_TAGS +- ENTITY_BOUNDS +- ENTITY_BOUNDS_BOX +- ENTITY_BOUNDS_CONVEX +- ENTITY_CATEGORIES +- SPAWNING_RESOURCE_STRING +- ENTITY_STATE_GETTING +- ENTITY_STATE_SETTING +- ENTITY_INFO_GETTING +- ENTITY_INFO_SETTING +- SPAWNABLES +- SIMULATION_RESET +- SIMULATION_RESET_TIME +- SIMULATION_RESET_STATE +- SIMULATION_RESET_SPAWNED +- SIMULATION_STATE_GETTING +- SIMULATION_STATE_SETTING +- SIMULATION_STATE_PAUSE +- STEP_SIMULATION_SINGLE + +The features *STEP_SIMULATION_SINGLE*, *STEP_SIMULATION_MULTIPLE*, and *STEP_SIMULATION_ACTION* will be introduced in the next RFC since they require multiple changes in the *PhysX Gem* and *AzPhysics API*. Action [SimulateSteps.action](https://github.com/ros-simulation/simulation_interfaces/tree/main/action/SimulateSteps.action) will not be supported. + +Only `[.spawnable]` format will be supported for spawning (field `spawn_formats` of [SimulatorFeatures.msg](https://github.com/ros-simulation/simulation_interfaces/tree/main/msg/SimulatorFeatures.msg)). Other formats, such as `URDF` and `SDF`, are supported only in the Editor mode in ROS 2 Gem. Spawning `SDF` and `URDF` would require support for the Game mode: - handling mesh importing in game mode and preparing it to use with the *Mesh Feature Processor*, - creating materials and texture assets in runtime, - PhysX (or other Physics engine) collider mesh cooking with decomposition. Such a feature would be useful, but it is out of the scope of this RFC. + +### Priority of implementation + +Feature is large contribution that will be implemented by multiple developers over longer period. +We propose following priority. + +| Feature | Priority Tier | +|----------------------------|---------------| +|SPAWNING | A +|DELETING | A +|NAMED_POSES | B +|POSE_BOUNDS | B +|ENTITY_TAGS | C +|ENTITY_BOUNDS | B +|ENTITY_BOUNDS_BOX | C +|ENTITY_BOUNDS_CONVEX | C +|ENTITY_CATEGORIES | C +|SPAWNING_RESOURCE_STRING | D +|ENTITY_STATE_GETTING | A +|ENTITY_STATE_SETTING | A +|ENTITY_INFO_GETTING | B +|ENTITY_INFO_SETTING | B +|SPAWNABLES | A +|SIMULATION_RESET | A +|SIMULATION_RESET_TIME | A +|SIMULATION_RESET_STATE | A +|SIMULATION_RESET_SPAWNED | B +|SIMULATION_STATE_GETTING | A +|SIMULATION_STATE_SETTING | A +|SIMULATION_STATE_PAUSE | A +|STEP_SIMULATION_SINGLE | B +|STEP_SIMULATION_MULTIPLE | B ( Another RFC ) +|STEP_SIMULATION_ACTION | B ( Another RFC ) + ## GetSpawnables service This service allows users to find simulated *spawnables* to spawn (place) in the simulation. \ -Service definition: [GetSpawnables](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSpawnables.srv) \ -Individual *spawnables* definition: [Spawnable.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/Spawnable.msg) +Service definition: [GetSpawnables](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetSpawnables.srv) \ +Individual *spawnables* definition: [Spawnable.msg](https://github.com/ros-simulation/simulation_interfaces/tree/main/msg/Spawnable.msg) -We will utilize the asset catalog to find the available *spawnables*. The asset catalog contains product assets (such as `.spawnable`, `.azmodel`, `.azbuffer`). We will introduce another product asset called `.simulationinfo`. It will contain necessary data about *prefab* that can be spawned or adjusted by Simulation Interfaces. The Engine's API will be used to get product assets, namely `AZ::Data::AssetCatalogRequests::EnumerateAssets`. +We will utilize the asset catalog to find the available *spawnables*. The asset catalog contains product assets (such as `.spawnable`, `.azmodel`, `.azbuffer`). +We will introduce another product asset called `.simulationinfo`. +It will contain necessary data about *prefab* that can be spawned or adjusted by Simulation Interfaces. The Engine's API will be used to get product assets, namely `AZ::Data::AssetCatalogRequests::EnumerateAssets`. The `.simulationinfo` product asset will be an XML / JSON file (similar to other product assets like `.physxmaterial`) and will contain at least the following information: - a description (as a string), @@ -127,9 +198,9 @@ Prepared response will be returned to the ROS 2 user. ## SpawnEntity service Service allows spawning entities previously found with `GetSpawnables` service. \ -Service definition: [SpawnEntity](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SpawnEntity.srv) +Service definition: [SpawnEntity](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/SpawnEntity.srv) -The ROS 2 user who wants to spawn a new object in their simulation has to have a valid URI e.g.,`spawnable://@cache@/robot/foorobot.spawnable`. `ROS 2 Entities Manager` will find respective Asset ID based on the URI. +The ROS 2 user who wants to spawn a new object in their simulation has to have a valid URI e.g.,`spawnable://@cache@/robot/foorobot.spawnable`. `Simulation Entities Manager` will find respective Asset ID based on the URI. Next, the [SpawnableEntitiesDefinition](https://github.com/o3de/o3de/blob/152bc0a1851d881fe735adf54ec93e1ad7875b11/Code/Framework/AzFramework/AzFramework/Spawnable/SpawnableEntitiesInterface.h#L334-L333) interface will be utilized to create a spawn ticket and spawn entity. @@ -149,15 +220,18 @@ This approach will result in a centralized aggregation of entities' information, ## GetEntities service This service provides access to a list of all spawned entities. \ -Service definition: [GetEntities](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntities.srv ) +Service definition: [GetEntities](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetEntities.srv ) -We will serve this by calling `SimulationInfoComponentRequestBus` with `AZ::EBusAggregateResults` to obtain a list of `AZ::EntityId`, that can be converted to a list of entity names. +This will served by `Simulation Entities manager` in two ways: + - returning to the caller whole cache of entities (when no filter in the query) + - returning results of Overlap Scene Query (when Bounds where set the query) +The intermidiate result will be filtered by regular expression (given in filter string), category and tags. ## GetEntitiesStates service This service allows users to get the state (speed, location, acceleration) of chosen entities. \ -Service definition: [GetEntitiesStates.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntitiesStates.srv) -Individual entity state definition: [EntityState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityState.msg) +Service definition: [GetEntitiesStates.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetEntitiesStates.srv) +Individual entity state definition: [EntityState](https://github.com/ros-simulation/simulation_interfaces/tree/main/msg/EntityState.msg) The service handling will be similar to [GetEntities](#GetEntities). Additional calls will be required to fill the state information: - [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) will be used to find the current twist, @@ -169,7 +243,7 @@ The service handling will be similar to [GetEntities](#GetEntities). Additional ## SetEntityState service This service allows modifying the state of the chosen entity. \ -Service definition: [SetEntityState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/SetEntityState.srv) +Service definition: [SetEntityState.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/SetEntityState.srv) The `AZ::EntityId` will be discovered by calling `SimulationInfoComponentRequestBus` with the name provided in the request. Next, the corresponding API will be called to adjust the state of the entity: - [TransformComponentRequests](https://github.com/o3de/o3de/blob/42d375dd99b972400f9f26bfec7e3444088f3398/Code/Framework/AzCore/AzCore/Component/TransformBus.h) or [RigidBodyRequestBus](https://github.com/o3de/o3de/blob/79e1df3990c5554c454d68798a0f3ef94c8ae317/Code/Framework/AzFramework/AzFramework/Physics/RigidBodyBus.h) to adjust the position of the simulated entity. @@ -237,68 +311,64 @@ unsupported type. ## DeleteEntity service This service allows despawning the previously spawned entities. \ -Service definition: [DeleteEntity.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/DeleteEntity.srv) +Service definition: [DeleteEntity.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/DeleteEntity.srv) The `AZ::EntityId` will be discovered by calling `SimulationInfoComponentRequestBus` with the name provided in the request. Next, the corresponding API will be called to despawn and remove the corresponding spawn ticket. -**Note:** This mechanism will **not** allow to delete the entities that are the part of the level prefab (e.g., prefab instantiated in Editor). +**Note:** This mechanism will allow to delete the entities that are the part of the level prefab (e.g., prefab instantiated in Editor). ## GetEntityBounds service This service allows to get the bounds of the previously spawned entities. \ -Service definition: [GetEntityBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityBounds.srv) +Service definition: [GetEntityBounds.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetEntityBounds.srv) The bounds for the particular entity will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. The information about entity's bounds will be stored within the `.simulationinfo` product asset, and it will be generated based on the source asset data provided by the simulation engineer. -**Note:** Convex hull bounds shape will not be supported in this implementation. This subject will be cover by another RFC when necessary. - ## GetEntityInfo service This service allows to get the category, description and tags for the given entity. \ -Service definition: [GetEntityInfo.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetEntityInfo.srv) \ -Particular entity info definition: [EntityInfo.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/EntityInfo.msg) +Service definition: [GetEntityInfo.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetEntityInfo.srv) \ +Particular entity info definition: [EntityInfo.msg](https://github.com/ros-simulation/simulation_interfaces/tree/main/msg/EntityInfo.msg) This information will be obtained by calling `SimulationInfoComponentRequestBus` with the name of the entity provided in the request. The information will be stored within the `.simulationinfo` product asset, and it will be generated based on the source asset data provided by the simulation engineer. ## GetNamedPoses service This service allows to get the list of the predefined poses which are convenient to for spawning, navigation goals, etc. \ -Service definition: [GetNamedPoses.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoses.srv) \ -Individual named pose definition: [NamedPose.msg](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/NamedPose.msg) +Service definition: [GetNamedPoses.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetNamedPoses.srv) \ +Individual named pose definition: [NamedPose.msg](https://github.com/ros-simulation/simulation_interfaces/tree/main/msg/NamedPose.msg) -This information will be obtained by calling a respective bus of `ROS 2 Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The poses will be predefined by a simulation expert using O3DE Editor. In particular, each entity with `NamedPoseComponent` from ROS 2 Gem will be registered in the poses manager. The `NamedPoseComponent` will contain two configurable fields called `description` and `tags`. During creation of game component (`CreateGameEntity`) the `TagComponent` from `LmbrCentral` Gem will be created and fed with the list of tags. +This information will be obtained by calling a respective bus of `Simulation Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The poses will be predefined by a simulation expert using O3DE Editor. In particular, each entity with `NamedPoseComponent` from ROS 2 Gem will be registered in the poses manager. The `NamedPoseComponent` will contain two configurable fields called `description` and `tags`. During creation of game component (`CreateGameEntity`) the `TagComponent` from `LmbrCentral` Gem will be created and fed with the list of tags. -**Note:** `ROS 2 Named poses manager` will ensure the names are unique (O3DE does not check for the name's uniqueness). +**Note:** `Simulation Named poses manager` will ensure the names are unique (O3DE does not check for the name's uniqueness). ## GetNamedPoseBounds service This service allows to get the bounds defined in the predefined pose object. \ -Service definition [GetNamedPoseBounds.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetNamedPoseBounds.srv) - -The information about the bounds will be obtained by calling a respective bus of `ROS 2 Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The bounds of the pose will be predefined by a simulation expert using O3DE Editor by adding `TransformService` and dependent services `BoxShapeService` and `SphereShapeService` alongside with the `NamedPoseComponent`. +Service definition [GetNamedPoseBounds.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetNamedPoseBounds.srv) -**Note:** Convex hull bounds shape will not be supported in this implementation. This subject will be cover by another RFC when necessary. +The information about the bounds will be obtained by calling a respective bus of `Simulation Named poses manager`. Additionally, the aggregation will be filtered based on the parameters of the call. The bounds of the pose will be predefined by a simulation expert using O3DE Editor by adding `TransformService` and dependent services `BoxShapeService` and `SphereShapeService` alongside with the `NamedPoseComponent`. ## Reset Simulation service This service allows to reset the simulation via ROS 2 interface. \ -Service definition: [ResetSimulation.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/ResetSimulation.srv) +Service definition: [ResetSimulation.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/ResetSimulation.srv) -This service will be handled by `ROS 2 Simulator manager`. It will use multiple APIs to give results. +This service will be handled by `Simulation manager`. It will use multiple APIs to give results. | Scope | Planned API and usage | | ------------- | ------------------------------------------------------------------------------ | | SCOPE_ALL | `ConsoleRequestBus` and `LoadLevel` command. | -| SCOPE_SPAWNED | Internal API to destroy all spawn tickets using `ROS 2 Entities manager`. | -| SCOPE_STATE | Move all spawned entities to initial poses cached in `ROS 2 Entities manager`. | +| SCOPE_SPAWNED | Internal API to destroy all spawn tickets using `Simulation Entities manager`. | +| SCOPE_STATE | Move all spawned entities to initial poses cached in `Simulation Entities manager`. | | SCOPE_TIME | New call using `ROS2Bus` | ## SetSimulationState service This service allows to set the state of the simulation (*STOPPED*, *PAUSED*, *PLAYING*, *QUITTING*). \ -Service definition: [SimulationState](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/msg/SimulationState.msg) +Service definition: [SimulationState](https://github.com/ros-simulation/simulation_interfaces/tree/main/msg/SimulationState.msg) -This service will be handled by `ROS 2 Simulator manager`. +This service will be handled by `Simulation manager`. The transition from *PLAYING* or *PAUSED* to *STOPPED* will trigger level reloading. @@ -307,14 +377,14 @@ The transition from *PLAYING* to *PAUSED* will ask the default physics scene to The transition from *PLAYING*, *PAUSED*, or *STOPPED* to *QUITTING* will close simulator calling `ConsoleRequestBus` with `quit` command. -The ROS 2 Simulator manager will contain the state of the simulation and perform necessary transitions. +The Simulation manager will contain the state of the simulation and perform necessary transitions. ## GetSimulationState service This service allows to get the current state of the simulation. \ -Service definition: [GetSimulationState.srv](https://github.com/adamdbrw/simulation_interfaces/blob/simulation_interfaces/srv/GetSimulationState.srv) +Service definition: [GetSimulationState.srv](https://github.com/ros-simulation/simulation_interfaces/tree/main/srv/GetSimulationState.srv) -This service will be handled by `ROS 2 Simulator manager`. If transition is in progress (e.g. reloading level or despawning), the old state will be returned. +This service will be handled by `Simulation manager`. If transition is in progress (e.g. reloading level or despawning), the old state will be returned. # Deprecated components in ROS 2 Gem