Skip to content

Commit e3fca83

Browse files
azeeyazeey
authored
Backport ROS 2 Simulation Interfaces to Ionic and Harmonic (#652)
* Copy ros2_sim_interfaces to ionic and harmonic * Use headings instead of emphasis This allows each service to be listed on the secondary navigation bar on the right side. --------- Signed-off-by: Addisu Z. Taddese <[email protected]>
1 parent 5415f01 commit e3fca83

File tree

7 files changed

+411
-12
lines changed

7 files changed

+411
-12
lines changed

‎harmonic/index.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,9 @@ pages:
9494
- name: ros2_integration
9595
title: Use ROS 2 to interact with Gazebo
9696
file: ros2_integration.md
97+
- name: ros2_sim_interfaces
98+
title: Use ROS 2 Simulation Interfaces to Interact with Gazebo
99+
file: ros2_sim_interfaces.md
97100
- name: ros2_spawn_model
98101
title: Use ROS 2 to spawn a Gazebo model
99102
file: ros2_spawn_model.md

‎harmonic/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).

‎harmonic/ros2_sim_interfaces.md‎

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

‎ionic/index.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,9 @@ pages:
9494
- name: ros2_integration
9595
title: Use ROS 2 to interact with Gazebo
9696
file: ros2_integration.md
97+
- name: ros2_sim_interfaces
98+
title: Use ROS 2 Simulation Interfaces to Interact with Gazebo
99+
file: ros2_sim_interfaces.md
97100
- name: ros2_spawn_model
98101
title: Use ROS 2 to spawn a Gazebo model
99102
file: ros2_spawn_model.md

‎ionic/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).

0 commit comments

Comments
 (0)