Skip to content

Commit b0e8ef0

Browse files
sauk2azeey
sauk2
and
azeey
authored
Added initial documentation for ROS 2 simulation interfaces (#601)
* Added initial simulation interfaces docs Signed-off-by: Saurabh Kamat <[email protected]> * Added ros2 sim interfaces as a new section Signed-off-by: Saurabh Kamat <[email protected]> * Fixed typo Signed-off-by: Saurabh Kamat <[email protected]> * Added namespace to all sim interface topics Signed-off-by: Saurabh Kamat <[email protected]> * Added sim interfaces as an index entry Signed-off-by: Saurabh Kamat <[email protected]> * Add known limitations Signed-off-by: Addisu Z. Taddese <[email protected]> --------- Signed-off-by: Saurabh Kamat <[email protected]> Signed-off-by: Addisu Z. Taddese <[email protected]> Co-authored-by: Addisu Z. Taddese <[email protected]>
1 parent 89547d2 commit b0e8ef0

File tree

3 files changed

+198
-0
lines changed

3 files changed

+198
-0
lines changed

‎jetty/index.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,9 @@ pages:
9797
- name: ros2_integration
9898
title: Use ROS 2 to interact with Gazebo
9999
file: ros2_integration.md
100+
- name: ros2_sim_interfaces
101+
title: Use ROS 2 Simulation Interfaces to Interact with Gazebo
102+
file: ros2_sim_interfaces.md
100103
- name: ros2_spawn_model
101104
title: Use ROS 2 to spawn a Gazebo model
102105
file: ros2_spawn_model.md

‎jetty/ros2_integration.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,3 +227,20 @@ And verify the vehicle matching its trajectory in Gazebo and RViz.
227227
![gz_rviz](tutorials/ros2_integration/gz_rviz.gif)
228228
229229
For more details on implementation of this demo see [ROS 2 Interoperability](ros2_interop).
230+
231+
## Using ROS 2 Simulation Interfaces
232+
233+
The [ROS 2 Simulation Interfaces](https://github.com/ros-simulation/simulation_interfaces)
234+
are a set of standard ROS 2 service, message and action
235+
definitions for controlling and interacting with simulation environments. They are
236+
simulator agnostic, which means the same interfacs can be implemented in different
237+
simulators while keeping the API consistent.
238+
239+
Gazebo implements these interfaces, enabling you to,
240+
- Spawn and delete entities
241+
- Control simulation state and time stepping
242+
- Query entity and world state
243+
- Retrieve simulator information
244+
245+
For a full tutorial, including usage examples for each interface see
246+
[Use ROS 2 Simulation Interfaces with Gazebo](ros2_sim_interfaces).

‎jetty/ros2_sim_interfaces.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Use ROS 2 Simulation Interfaces to Interact with Gazebo
2+
3+
The [ROS 2 Simulation Interfaces](https://github.com/ros-simulation/simulation_interfaces)
4+
define a standard set of ROS 2 service, message and action definitions for controlling and
5+
interacting with simulation environments. These interfaces are simulator-agnostic and aim to
6+
provide a unified way to control and observe simulation using ROS 2.
7+
8+
Gazebo has implemented these interfaces, enabling tasks like spawning entities, stepping
9+
simulation, querying world state, etc. through standard ROS 2 calls. In this tutorial we
10+
will learn how to interact with a running Gazebo simulation for the following tasks,
11+
- [Simulation Control](#simulation-control)
12+
- [Entity Management](#entity-management)
13+
- [State Query](#state-query)
14+
- [Simulator Information](#simulator-information)
15+
16+
## Simulation Control
17+
18+
The following services and actions are available to control the flow of simulation time.
19+
20+
| Interface Name | Topic Name | Type | Description |
21+
|----------------|------------|------|-------------|
22+
| `ResetSimulation` | `/gzserver/reset_simulation` | Service | Reset the simulation to its initial state |
23+
| `StepSimulation` | `/gzserver/step_simulation` | Service | Step the simulation forward by a specified number of steps |
24+
| `GetSimulationState` | `/gzserver/get_simulation_state` | Service | Get the current simulation state (playing/paused/stopped) |
25+
| `SetSimulationState` | `/gzserver/set_simulation_state` | Service | Set the simulation state (play/pause/stop) |
26+
| `SimulateSteps` | `/gzserver/simulate_steps` | Action | Step the simulation forward by a specified number of steps with feedback and cancellation support |
27+
28+
**ResetSimulation Service**
29+
30+
Reset the simulation to its initial state.
31+
32+
```bash
33+
ros2 service call /gzserver/reset_simulation simulation_interfaces/srv/ResetSimulation "{}"
34+
```
35+
36+
**StepSimulation Service**
37+
38+
Step the simulation forward by a specified number of steps.
39+
40+
```bash
41+
ros2 service call /gzserver/step_simulation simulation_interfaces/srv/StepSimulation "{steps: 10}"
42+
```
43+
44+
**GetSimulationState Service**
45+
46+
Get the current simulation state (playing/paused/stopped).
47+
48+
```bash
49+
ros2 service call /gzserver/get_simulation_state simulation_interfaces/srv/GetSimulationState "{}"
50+
```
51+
52+
**SetSimulationState Service**
53+
54+
Set the simulation state (play/pause/stop).
55+
56+
- Set simulation state to stop.
57+
58+
```bash
59+
ros2 service call /gzserver/set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 0}}"
60+
```
61+
62+
- Set simulation state to playing.
63+
64+
```bash
65+
ros2 service call /gzserver/set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 1}}"
66+
```
67+
68+
- Set simulation state to paused.
69+
70+
```bash
71+
ros2 service call /gzserver/set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 2}}"
72+
```
73+
74+
- Set simulation state to quitting.
75+
76+
```bash
77+
ros2 service call /gzserver/set_simulation_state simulation_interfaces/srv/SetSimulationState "{state: {state: 3}}"
78+
```
79+
80+
**SimulateSteps Action**
81+
82+
Step the simulation forward by a specified number of steps with feedback and cancellation support.
83+
84+
```bash
85+
ros2 action send_goal /gzserver/simulate_steps simulation_interfaces/action/SimulateSteps "{steps: 10}" --feedback
86+
```
87+
88+
## Entity Management
89+
90+
The following interfaces are used to create or remove entities in the simulation at runtime.
91+
92+
| Interface Name | Topic Name | Type | Description |
93+
|----------------|------------|------|-------------|
94+
| `SpawnEntity` | `/gzserver/spawn_entity` | Service | Spawn a new entity in the simulation at a specific location |
95+
| `DeleteEntity` | `/gzserver/delete_entity` | Service | Delete an existing entity by name |
96+
97+
**SpawnEntity Service**
98+
99+
Spawn a new entity in the simulation at a specific location.
100+
101+
```bash
102+
ros2 service call /gzserver/spawn_entity simulation_interfaces/srv/SpawnEntity "{
103+
name: 'my_model',
104+
uri: '/path/to/model.sdf',
105+
allow_renaming: false,
106+
initial_pose: {
107+
pose: {
108+
position: {x: 0.0, y: 0.0, z: 0.0},
109+
orientation: {w: 1.0, x: 0.0, y: 0.0, z: 0.0}
110+
}
111+
}
112+
}"
113+
```
114+
115+
**DeleteEntity Service**
116+
117+
Delete an existing entity by name.
118+
119+
```bash
120+
ros2 service call /gzserver/delete_entity simulation_interfaces/srv/DeleteEntity "{entity: 'my_model'}"
121+
```
122+
123+
## State Query
124+
125+
The following interfaces are used to introspect simulation world and entity state.
126+
127+
| Interface Name | Topic Name | Type | Description |
128+
|----------------|------------|------|-------------|
129+
| `GetEntityState` | `/gzserver/get_entity_state` | Service | Get the pose and twist of a specific entity |
130+
| `GetEntitiesStates` | `/gzserver/get_entities_states` | Service | Get the state for multiple entities (optionally filtered) |
131+
| `GetEntities` | `/gzserver/get_entities` | Service | Get a list of entities (optionally filtered) |
132+
133+
**GetEntityState Service**
134+
135+
Get the pose and twist of a specific entity.
136+
137+
```bash
138+
ros2 service call /gzserver/get_entity_state simulation_interfaces/srv/GetEntityState "{entity: 'my_model'}"
139+
```
140+
141+
**GetEntitiesStates Service**
142+
143+
Get the state of multiple entities (optionally filtered).
144+
145+
```bash
146+
ros2 service call /gzserver/get_entities_states simulation_interfaces/srv/GetEntitiesStates "{filters: {filter: ''}}"
147+
```
148+
149+
**GetEntites Service**
150+
151+
Get the list of entities (optionally filtered).
152+
153+
```bash
154+
ros2 service call /gzserver/get_entities simulation_interfaces/src/GetEntities "{filters: {filter: ''}}"
155+
```
156+
157+
## Simulator Information
158+
159+
Some simulators may only support a subset of interfaces. The following services can be used to inspect
160+
supported features.
161+
162+
| Interface Name | Topic Name | Type | Description |
163+
|----------------|------------|------|-------------|
164+
| `GetSimulatorFeatures` | `/gzserver/get_simulator_features` | Service | Query which interface features are supported |
165+
166+
**GetSimulatorFeatures Service**
167+
168+
Query which interface features are supported.
169+
170+
```bash
171+
ros2 service call /gzserver/get_simulator_features simulation_interfaces/srv/GetSimulationFeatures "{}"
172+
```
173+
174+
## Known Limitations
175+
176+
- Only an empty string or "world" can be used in the `frame_id` field of `PoseStamped` messages. We plan to add support for using frames known to `Tf` in the future.
177+
- Entity namespaces are not supported by the `SpawnEntity` service.
178+
- When spawning an entity, if `SpawnEntity.allow_renaming` is set to `true` and a rename occurs in Gazebo, the new name is not returned in the `Result` object return by the `SpawnEntity` service.

0 commit comments

Comments
 (0)