From 86b2c2569ed6e5dc4e934730aa85da2bea16c575 Mon Sep 17 00:00:00 2001 From: "Addisu Z. Taddese" Date: Tue, 2 Dec 2025 16:12:01 -0600 Subject: [PATCH] Add documentation on the SetEntityState service Signed-off-by: Addisu Z. Taddese --- harmonic/ros2_sim_interfaces.md | 32 ++++++++++++++++++++++++++++++++ ionic/ros2_sim_interfaces.md | 24 ++++++++++++++++++++++++ jetty/ros2_sim_interfaces.md | 24 ++++++++++++++++++++++++ 3 files changed, 80 insertions(+) diff --git a/harmonic/ros2_sim_interfaces.md b/harmonic/ros2_sim_interfaces.md index 8296356fc..4c59b1b8d 100644 --- a/harmonic/ros2_sim_interfaces.md +++ b/harmonic/ros2_sim_interfaces.md @@ -12,6 +12,7 @@ will learn how to interact with a running Gazebo simulation for the following ta - [Simulation Control](#simulation-control) - [Entity Management](#entity-management) - [State Query](#state-query) +- [State Update](#state-update) - [Simulator Information](#simulator-information) ## Simulation Control @@ -155,6 +156,37 @@ Get the list of entities (optionally filtered). ros2 service call /gzserver/get_entities simulation_interfaces/src/GetEntities "{filters: {filter: ''}}" ``` +## State Update + +The following interfaces are used to set entity states. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `SetEntityState` | `/gzserver/set_entity_state` | Service | Set the pose and twist of a specific entity | + +### SetEntityState Service + +Set the pose and twist of a specific entity. + +```bash +ros2 service call /gzserver/set_entity_state simulation_interfaces/srv/SetEntityState "{ entity: 'my_model', state: {pose: { position: { x: -2.0, z: 0.5 }}, twist: {linear: {x: 0.5}}}}" +``` + +:::{caution} +When using `SetEntityState`, it is currently not possible to set just the `pose` or the `twist` of an entity. +Both components of the entity will be assigned based on the value of the provided message. For example, of `pose` is left empty, the pose of the entity will be set to the origin. + +This might be resolved in the future. See https://github.com/ros-simulation/simulation_interfaces/issues/18 +::: + +:::{warning} +In Gazebo Harmonic, the twist of an entity is reset back to zero +after each time step. This is like applying a brake on the entity (see https://github.com/gazebosim/gz-sim/issues/1926). +Thus, we do not recommend using `SetEntityState` to control the twist. Later versions of +Gazebo do not have this problem. If you need to control the twist, consider +using the [VelocityControl](https://gazebosim.org/api/sim/8/classgz_1_1sim_1_1systems_1_1VelocityControl.html) system. +::: + ## Simulator Information Some simulators may only support a subset of interfaces. The following services can be used to inspect diff --git a/ionic/ros2_sim_interfaces.md b/ionic/ros2_sim_interfaces.md index 8296356fc..dea5e224f 100644 --- a/ionic/ros2_sim_interfaces.md +++ b/ionic/ros2_sim_interfaces.md @@ -12,6 +12,7 @@ will learn how to interact with a running Gazebo simulation for the following ta - [Simulation Control](#simulation-control) - [Entity Management](#entity-management) - [State Query](#state-query) +- [State Update](#state-update) - [Simulator Information](#simulator-information) ## Simulation Control @@ -155,6 +156,29 @@ Get the list of entities (optionally filtered). ros2 service call /gzserver/get_entities simulation_interfaces/src/GetEntities "{filters: {filter: ''}}" ``` +## State Update + +The following interfaces are used to set entity states. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `SetEntityState` | `/gzserver/set_entity_state` | Service | Set the pose and twist of a specific entity | + +### SetEntityState Service + +Set the pose and twist of a specific entity. + +```bash +ros2 service call /gzserver/set_entity_state simulation_interfaces/srv/SetEntityState "{ entity: 'my_model', state: {pose: { position: { x: -2.0, z: 0.5 }}, twist: {linear: {x: 0.5}}}}" +``` + +:::{caution} +When using `SetEntityState`, it is currently not possible to set just the `pose` or the `twist` of an entity. +Both components of the entity will be assigned based on the value of the provided message. For example, of `pose` is left empty, the pose of the entity will be set to the origin. + +This might be resolved in the future. See https://github.com/ros-simulation/simulation_interfaces/issues/18 +::: + ## Simulator Information Some simulators may only support a subset of interfaces. The following services can be used to inspect diff --git a/jetty/ros2_sim_interfaces.md b/jetty/ros2_sim_interfaces.md index 8296356fc..dea5e224f 100644 --- a/jetty/ros2_sim_interfaces.md +++ b/jetty/ros2_sim_interfaces.md @@ -12,6 +12,7 @@ will learn how to interact with a running Gazebo simulation for the following ta - [Simulation Control](#simulation-control) - [Entity Management](#entity-management) - [State Query](#state-query) +- [State Update](#state-update) - [Simulator Information](#simulator-information) ## Simulation Control @@ -155,6 +156,29 @@ Get the list of entities (optionally filtered). ros2 service call /gzserver/get_entities simulation_interfaces/src/GetEntities "{filters: {filter: ''}}" ``` +## State Update + +The following interfaces are used to set entity states. + +| Interface Name | Topic Name | Type | Description | +|----------------|------------|------|-------------| +| `SetEntityState` | `/gzserver/set_entity_state` | Service | Set the pose and twist of a specific entity | + +### SetEntityState Service + +Set the pose and twist of a specific entity. + +```bash +ros2 service call /gzserver/set_entity_state simulation_interfaces/srv/SetEntityState "{ entity: 'my_model', state: {pose: { position: { x: -2.0, z: 0.5 }}, twist: {linear: {x: 0.5}}}}" +``` + +:::{caution} +When using `SetEntityState`, it is currently not possible to set just the `pose` or the `twist` of an entity. +Both components of the entity will be assigned based on the value of the provided message. For example, of `pose` is left empty, the pose of the entity will be set to the origin. + +This might be resolved in the future. See https://github.com/ros-simulation/simulation_interfaces/issues/18 +::: + ## Simulator Information Some simulators may only support a subset of interfaces. The following services can be used to inspect