From 77ff751a2029cfb92a477b7280b8cc9b22d3ba69 Mon Sep 17 00:00:00 2001 From: Saurabh Kamat Date: Wed, 6 Aug 2025 00:27:37 +0800 Subject: [PATCH 1/2] Added initial simulation interfaces docs Signed-off-by: Saurabh Kamat --- jetty/ros2_integration.md | 169 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) diff --git a/jetty/ros2_integration.md b/jetty/ros2_integration.md index 50d8c1b83..f72367bef 100644 --- a/jetty/ros2_integration.md +++ b/jetty/ros2_integration.md @@ -227,3 +227,172 @@ And verify the vehicle matching its trajectory in Gazebo and RViz. ![gz_rviz](tutorials/ros2_integration/gz_rviz.gif) For more details on implementation of this demo see [ROS 2 Interoperability](ros2_interop). + +## Using ROS 2 Simulation Interfaces + +The [ROS 2 Simulation Interfaces](https://github.com/ros-simulation/simulation_interfaces) +define a standard set of ROS 2 service, message and action definitions or controlling and +interacting with simulation environments. These interfaces are simulator-agnostic and aim to +provide a unified way to control and observe simulation using ROS 2. + +Gazebo has implemented these interfaces, enabling tasks like spawning entities, stepping +simulation, querying world state, etc. through standard ROS 2 calls. In this tutorial we +will learn how to interact with a running Gazebo simulation. + +### Simulation Control + +The following services and actions are available to control the flow of simulation time. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `ResetSimulation` | `/reset_simulaiton` | Service | Reset the simulation to its initial state | +| `StepSimulation` | `/step_simulation` | Service | Step the simulation forward by a specified number of steps | +| `GetSimulationState` | `/get_simulation_state` | Service | Get the current simulation state (playing/paused/stopped) | +| `SetSimulationState` | `/set_simulation_state` | Service | Set the simulation state (play/pause/stop) | +| `SimulateSteps` | `/simulate_steps` | Action | Step the simulation forward by a specified number of steps with feedback and cancellation support | + +**ResetSimulation Service** + +Reset the simulation to its initial state. + +```bash +ros2 service call /reset_simulation simulation_interfaces/srv/ResetSimulation "{}" +``` + +**StepSimulation Service** + +Step the simulation forward by a specified number of steps. + +```bash +ros2 service call /step_simulation simulation_interfaces/srv/StepSimulation "{steps: 10}" +``` + +**GetSimulationState Service** + +Get the current simulation state (playing/paused/stopped). + +```bash +ros2 service call /get_simulation_state simulation_interfaces/srv/GetSimulationState "{}" +``` + +**SetSimulationState Service** + +Set the simulation state (play/pause/stop). + +- Set simulation state to stop. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 0}}" + ``` + +- Set simulation state to playing. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 1}}" + ``` + +- Set simulation state to paused. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 2}}" + ``` + +- Set simulation state to quitting. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 3}}" + ``` + +**SimulateSteps Action** + +Step the simulation forward by a specified number of steps with feedback and cancellation support. + +```bash +ros2 action send_goal /simulate_steps simulation_interfaces/action/SimulateSteps "{steps: 10}" --feedback +``` + +### Entity Management + +The following interfaces are used to create or remove entities in the simulation at runtime. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `SpawnEntity` | `/spawn_entity` | Service | Spawn a new entity in the simulation at a specific location | +| `DeleteEntity` | `/delete_entity` | Service | Delete an existing entity by name | + +**SpawnEntity Service** + +Spawn a new entity in the simulation at a specific location. + +```bash +ros2 service call /spawn_entity simulation_interfaces/srv/SpawnEntity "{ + name: 'my_model', + uri: '/path/to/model.sdf', + allow_renaming: false, + initial_pose: { + pose: { + position: {x: 0.0, y: 0.0, z: 0.0}, + orientation: {w: 1.0, x: 0.0, y: 0.0, z: 0.0} + } + } +}" +``` + +**DeleteEntity Service** + +Delete an existing entity by name. + +```bash +ros2 service call /delete_entity simulation_interfaces/srv/DeleteEntity "{entity: 'my_model'}" +``` + +### State Queries + +The following interfaces are used to introspect simulation world and entity state. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `GetEntityState` | `/get_entity_state` | Service | Get the pose and twist of a specific entity | +| `GetEntitiesStates` | `/get_entities_states` | Service | Get the state for multiple entities (optionally filtered) | +| `GetEntities` | `/get_entities` | Service | Get a list of entities (optionally filtered) | + +**GetEntityState Service** + +Get the pose and twist of a specific entity. + +```bash +ros2 service call /get_entity_state simulation_interfaces/srv/GetEntityState "{entity: 'my_model'}" +``` + +**GetEntitiesStates Service** + +Get the state of multiple entities (optionally filtered). + +```bash +ros2 service call /get_entities_states simulation_interfaces/srv/GetEntitiesStates "{filters: {filter: ''}}" +``` + +**GetEntites Service** + +Get the list of entities (optionally filtered). + +```bash +ros2 service call /get_entities simulation_interfaces/src/GetEntities "{filters: {filter: ''}}" +``` + +### Simulator Information + +Some simulators may only support a subset of interfaces. The following services can be used to inspect +supported features. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `GetSimulatorFeatures` | `/get_simulator_features` | Service | Query which interface features are supported | + +**GetSimulatorFeatures Service** + +Query which interface features are supported. + +```bash +ros2 service call /get_simulator_features simulation_interfaces/srv/GetSimulationFeatures "{}" +``` From d81777f6f7e21bf69a745b6cc57bd3114b965714 Mon Sep 17 00:00:00 2001 From: Saurabh Kamat Date: Mon, 11 Aug 2025 22:13:21 +0800 Subject: [PATCH 2/2] Added ros2 sim interfaces as a new section Signed-off-by: Saurabh Kamat --- jetty/ros2_integration.md | 178 +++-------------------------------- jetty/ros2_sim_interfaces.md | 172 +++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+), 165 deletions(-) create mode 100644 jetty/ros2_sim_interfaces.md diff --git a/jetty/ros2_integration.md b/jetty/ros2_integration.md index f72367bef..48f7e171b 100644 --- a/jetty/ros2_integration.md +++ b/jetty/ros2_integration.md @@ -231,168 +231,16 @@ For more details on implementation of this demo see [ROS 2 Interoperability](ros ## Using ROS 2 Simulation Interfaces The [ROS 2 Simulation Interfaces](https://github.com/ros-simulation/simulation_interfaces) -define a standard set of ROS 2 service, message and action definitions or controlling and -interacting with simulation environments. These interfaces are simulator-agnostic and aim to -provide a unified way to control and observe simulation using ROS 2. - -Gazebo has implemented these interfaces, enabling tasks like spawning entities, stepping -simulation, querying world state, etc. through standard ROS 2 calls. In this tutorial we -will learn how to interact with a running Gazebo simulation. - -### Simulation Control - -The following services and actions are available to control the flow of simulation time. - -| Interface Name | Topic Name | Type | Description | -|----------------|------------|------|-------------| -| `ResetSimulation` | `/reset_simulaiton` | Service | Reset the simulation to its initial state | -| `StepSimulation` | `/step_simulation` | Service | Step the simulation forward by a specified number of steps | -| `GetSimulationState` | `/get_simulation_state` | Service | Get the current simulation state (playing/paused/stopped) | -| `SetSimulationState` | `/set_simulation_state` | Service | Set the simulation state (play/pause/stop) | -| `SimulateSteps` | `/simulate_steps` | Action | Step the simulation forward by a specified number of steps with feedback and cancellation support | - -**ResetSimulation Service** - -Reset the simulation to its initial state. - -```bash -ros2 service call /reset_simulation simulation_interfaces/srv/ResetSimulation "{}" -``` - -**StepSimulation Service** - -Step the simulation forward by a specified number of steps. - -```bash -ros2 service call /step_simulation simulation_interfaces/srv/StepSimulation "{steps: 10}" -``` - -**GetSimulationState Service** - -Get the current simulation state (playing/paused/stopped). - -```bash -ros2 service call /get_simulation_state simulation_interfaces/srv/GetSimulationState "{}" -``` - -**SetSimulationState Service** - -Set the simulation state (play/pause/stop). - -- Set simulation state to stop. - - ```bash - ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 0}}" - ``` - -- Set simulation state to playing. - - ```bash - ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 1}}" - ``` - -- Set simulation state to paused. - - ```bash - ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 2}}" - ``` - -- Set simulation state to quitting. - - ```bash - ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 3}}" - ``` - -**SimulateSteps Action** - -Step the simulation forward by a specified number of steps with feedback and cancellation support. - -```bash -ros2 action send_goal /simulate_steps simulation_interfaces/action/SimulateSteps "{steps: 10}" --feedback -``` - -### Entity Management - -The following interfaces are used to create or remove entities in the simulation at runtime. - -| Interface Name | Topic Name | Type | Description | -|----------------|------------|------|-------------| -| `SpawnEntity` | `/spawn_entity` | Service | Spawn a new entity in the simulation at a specific location | -| `DeleteEntity` | `/delete_entity` | Service | Delete an existing entity by name | - -**SpawnEntity Service** - -Spawn a new entity in the simulation at a specific location. - -```bash -ros2 service call /spawn_entity simulation_interfaces/srv/SpawnEntity "{ - name: 'my_model', - uri: '/path/to/model.sdf', - allow_renaming: false, - initial_pose: { - pose: { - position: {x: 0.0, y: 0.0, z: 0.0}, - orientation: {w: 1.0, x: 0.0, y: 0.0, z: 0.0} - } - } -}" -``` - -**DeleteEntity Service** - -Delete an existing entity by name. - -```bash -ros2 service call /delete_entity simulation_interfaces/srv/DeleteEntity "{entity: 'my_model'}" -``` - -### State Queries - -The following interfaces are used to introspect simulation world and entity state. - -| Interface Name | Topic Name | Type | Description | -|----------------|------------|------|-------------| -| `GetEntityState` | `/get_entity_state` | Service | Get the pose and twist of a specific entity | -| `GetEntitiesStates` | `/get_entities_states` | Service | Get the state for multiple entities (optionally filtered) | -| `GetEntities` | `/get_entities` | Service | Get a list of entities (optionally filtered) | - -**GetEntityState Service** - -Get the pose and twist of a specific entity. - -```bash -ros2 service call /get_entity_state simulation_interfaces/srv/GetEntityState "{entity: 'my_model'}" -``` - -**GetEntitiesStates Service** - -Get the state of multiple entities (optionally filtered). - -```bash -ros2 service call /get_entities_states simulation_interfaces/srv/GetEntitiesStates "{filters: {filter: ''}}" -``` - -**GetEntites Service** - -Get the list of entities (optionally filtered). - -```bash -ros2 service call /get_entities simulation_interfaces/src/GetEntities "{filters: {filter: ''}}" -``` - -### Simulator Information - -Some simulators may only support a subset of interfaces. The following services can be used to inspect -supported features. - -| Interface Name | Topic Name | Type | Description | -|----------------|------------|------|-------------| -| `GetSimulatorFeatures` | `/get_simulator_features` | Service | Query which interface features are supported | - -**GetSimulatorFeatures Service** - -Query which interface features are supported. - -```bash -ros2 service call /get_simulator_features simulation_interfaces/srv/GetSimulationFeatures "{}" -``` +are a set of standard ROS 2 service, message and action +definitions for controlling and interacting with simulation environments. They are +simulator agnostic, which means the same interfacs can be implemented in different +simulators while keeping the API consistent. + +Gazebo implements these interfaces, enabling you to, +- Spawn and delete entities +- Control simulation state and time stepping +- Query entity and world state +- Retrieve simulator information + +For a full tutorial, including usage examples for each interface see +[Use ROS 2 Simulation Interfaces with Gazebo](ros2_sim_interfaces). \ No newline at end of file diff --git a/jetty/ros2_sim_interfaces.md b/jetty/ros2_sim_interfaces.md new file mode 100644 index 000000000..928ed3748 --- /dev/null +++ b/jetty/ros2_sim_interfaces.md @@ -0,0 +1,172 @@ +# Use ROS 2 Simulation Interfaces to Interact with Gazebo + +The [ROS 2 Simulation Interfaces](https://github.com/ros-simulation/simulation_interfaces) +define a standard set of ROS 2 service, message and action definitions for controlling and +interacting with simulation environments. These interfaces are simulator-agnostic and aim to +provide a unified way to control and observe simulation using ROS 2. + +Gazebo has implemented these interfaces, enabling tasks like spawning entities, stepping +simulation, querying world state, etc. through standard ROS 2 calls. In this tutorial we +will learn how to interact with a running Gazebo simulation for the following tasks, +- [Simulation Control](#simulation-control) +- [Entity Management](#entity-management) +- [State Query](#state-query) +- [Simulator Information](#simulator-information) + +## Simulation Control + +The following services and actions are available to control the flow of simulation time. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `ResetSimulation` | `/reset_simulaiton` | Service | Reset the simulation to its initial state | +| `StepSimulation` | `/step_simulation` | Service | Step the simulation forward by a specified number of steps | +| `GetSimulationState` | `/get_simulation_state` | Service | Get the current simulation state (playing/paused/stopped) | +| `SetSimulationState` | `/set_simulation_state` | Service | Set the simulation state (play/pause/stop) | +| `SimulateSteps` | `/simulate_steps` | Action | Step the simulation forward by a specified number of steps with feedback and cancellation support | + +**ResetSimulation Service** + +Reset the simulation to its initial state. + +```bash +ros2 service call /reset_simulation simulation_interfaces/srv/ResetSimulation "{}" +``` + +**StepSimulation Service** + +Step the simulation forward by a specified number of steps. + +```bash +ros2 service call /step_simulation simulation_interfaces/srv/StepSimulation "{steps: 10}" +``` + +**GetSimulationState Service** + +Get the current simulation state (playing/paused/stopped). + +```bash +ros2 service call /get_simulation_state simulation_interfaces/srv/GetSimulationState "{}" +``` + +**SetSimulationState Service** + +Set the simulation state (play/pause/stop). + +- Set simulation state to stop. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 0}}" + ``` + +- Set simulation state to playing. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 1}}" + ``` + +- Set simulation state to paused. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 2}}" + ``` + +- Set simulation state to quitting. + + ```bash + ros2 service call /set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 3}}" + ``` + +**SimulateSteps Action** + +Step the simulation forward by a specified number of steps with feedback and cancellation support. + +```bash +ros2 action send_goal /simulate_steps simulation_interfaces/action/SimulateSteps "{steps: 10}" --feedback +``` + +## Entity Management + +The following interfaces are used to create or remove entities in the simulation at runtime. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `SpawnEntity` | `/spawn_entity` | Service | Spawn a new entity in the simulation at a specific location | +| `DeleteEntity` | `/delete_entity` | Service | Delete an existing entity by name | + +**SpawnEntity Service** + +Spawn a new entity in the simulation at a specific location. + +```bash +ros2 service call /spawn_entity simulation_interfaces/srv/SpawnEntity "{ + name: 'my_model', + uri: '/path/to/model.sdf', + allow_renaming: false, + initial_pose: { + pose: { + position: {x: 0.0, y: 0.0, z: 0.0}, + orientation: {w: 1.0, x: 0.0, y: 0.0, z: 0.0} + } + } +}" +``` + +**DeleteEntity Service** + +Delete an existing entity by name. + +```bash +ros2 service call /delete_entity simulation_interfaces/srv/DeleteEntity "{entity: 'my_model'}" +``` + +## State Query + +The following interfaces are used to introspect simulation world and entity state. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `GetEntityState` | `/get_entity_state` | Service | Get the pose and twist of a specific entity | +| `GetEntitiesStates` | `/get_entities_states` | Service | Get the state for multiple entities (optionally filtered) | +| `GetEntities` | `/get_entities` | Service | Get a list of entities (optionally filtered) | + +**GetEntityState Service** + +Get the pose and twist of a specific entity. + +```bash +ros2 service call /get_entity_state simulation_interfaces/srv/GetEntityState "{entity: 'my_model'}" +``` + +**GetEntitiesStates Service** + +Get the state of multiple entities (optionally filtered). + +```bash +ros2 service call /get_entities_states simulation_interfaces/srv/GetEntitiesStates "{filters: {filter: ''}}" +``` + +**GetEntites Service** + +Get the list of entities (optionally filtered). + +```bash +ros2 service call /get_entities simulation_interfaces/src/GetEntities "{filters: {filter: ''}}" +``` + +## Simulator Information + +Some simulators may only support a subset of interfaces. The following services can be used to inspect +supported features. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `GetSimulatorFeatures` | `/get_simulator_features` | Service | Query which interface features are supported | + +**GetSimulatorFeatures Service** + +Query which interface features are supported. + +```bash +ros2 service call /get_simulator_features simulation_interfaces/srv/GetSimulationFeatures "{}" +``` \ No newline at end of file