Add pause run tutorial (gazebosim#2383)

Add a tutorial to start/stop the simulation with either the GUI or CLI. This mirrors the reset simulation tutorial.


---------

Signed-off-by: Ryan Friedman <[email protected]>
Signed-off-by: Ryan <[email protected]>
Signed-off-by: Addisu Z. Taddese <[email protected]>
Co-authored-by: Addisu Z. Taddese <[email protected]>

tutorials.md.in

@@ -11,6 +11,7 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively.
 * \subpage gui_config "GUI configuration": Customizing your layout.
 * \subpage server_config "Server configuration": Customizing what system plugins are loaded.
 * \subpage model_command "Model Command": Use the CLI to get information about the models in a simulation.
+* \subpage pause_run_simulation "Pause and Run simulation": Use Gazebo transport API to pause and run simulation.
 * \subpage reset_simulation Reset simulation
 * \subpage resources "Finding resources": The different ways in which Gazebo looks for files.
 * \subpage debugging "Debugging": Information about debugging Gazebo.

tutorials/pause_run_simulation.md

@@ -0,0 +1,57 @@
+\page pause_run_simulation Pause and Run simulation
+
+A Gazebo transport API is exposed to allow starting and stopping the simulation.
+It's possible to call this API using the command line or through the GUI.
+
+To repeat this demo, run the `default` world:
+```bash
+gz sim default.sdf
+```
+
+## Transport API
+
+When Gazebo is run headless, this is an easy way to start the simulation.
+
+To pause and play over the transport API, we should call the service `/world/<world_name>/control` and fill the request message type
+`gz.msgs.WorldControl`. This service returns a `gz.msgs.Boolean` with the status of the request (true means everything was fine, false otherwise).
+
+The `WorldControl` message contains a `pause` field for starting and stopping the simulation.
+
+To start the simulation:
+
+```bash
+gz service -s /world/default/control --reqtype gz.msgs.WorldControl --reptype gz.msgs.Boolean --timeout 3000 --req 'pause: false'
+```
+
+To pause the simulation:
+
+```bash
+gz service -s /world/default/control --reqtype gz.msgs.WorldControl --reptype gz.msgs.Boolean --timeout 3000 --req 'pause: true'
+```
+
+When paused, time will stop in Gazebo, and the physics will not be running.
+
+To check the current state of the simulator, check the `paused` field in `/stats` like so:
+```bash
+gz topic --echo --topic /stats -n 1
+```
+If the simulator is currently paused but was running before, we would see something similar to this:
+```text
+sim_time {
+  sec: 8
+  nsec: 707000000
+}
+real_time {
+  sec: 8
+  nsec: 824323281
+}
+iterations: 8707
+real_time_factor: 0.998022916602211
+```
+
+
+## GUI
+
+We included a button in the `World Control` plugin allowing to start and stop the simulation from the GUI.
+
+@image html files/pause_run_simulation/gui_pause_run.png

tutorials/reset_simulation.md

@@ -4,6 +4,11 @@ The Reset Gazebo transport API is exposed to allow resetting simulation to time
 It's possible to call this API using the command line or through the GUI.
 In addition to the API, we have also expanded the simulation system API with a Reset interface.
 
+To repeat this demo, run the `rolling_shapes.sdf` file:
+```bash
+gz sim rolling_shapes.sdf
+```
+
 ## Reset interface
 
 System authors may now choose to implement the Reset interface to have a more intelligent
@@ -16,7 +21,7 @@ Follow the tutorial \subpage createsystemplugins to see how to support Reset by
 ## Transport API
 
 To invoke reset over transport API, we should call the service `/world/<world_name>/control` and fill the request message type
-`gz.msgs.WorldControl`. This service returns a `gz.msgs.Boolean` with the status of the reset (true means everything was fine, false otherwise)
+`gz.msgs.WorldControl`. This service returns a `gz.msgs.Boolean` with the status of the reset (true means everything was fine, false otherwise).
 
 The `WorldControl` message now contains a `reset` field for resetting the world: