Merge pull request #171 from open-dynamic-robot-initiative/fkloss/doc…

…_sim

doc: Add How-to for simulation backend

demos/demo_simulation_driver.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-"""Basic demo on how to use pyBullet through the robot_interfaces pipeline.
+"""Basic demo on how to use PyBullet through the robot_interfaces pipeline.
 
-This demo illustrates how to use the pyBullet simulation in the backend of the
+This demo illustrates how to use the PyBullet simulation in the backend of the
 robot_interfaces pipeline.  When used like this, the same code can be executed
 in simulation and on the real robot with only changing a single line, namely
 the one for creating the backend.
@@ -36,9 +36,9 @@ def main():
         "--real-time-mode",
         "-r",
         action="store_true",
-        help="""Run simulation in real time.  If not set,
-                        the simulation runs as fast as possible.
-                        """,
+        help="""Run simulation in real time.  If not set, the simulation runs as fast as
+            possible.
+            """,
     )
     args = parser.parse_args()
 

doc/breathing_cat.toml

@@ -1,6 +1,7 @@
 [intersphinx.mapping]
 trifinger_docs = "https://open-dynamic-robot-initiative.github.io/trifinger_docs"
 robot_interfaces = "https://open-dynamic-robot-initiative.github.io/robot_interfaces"
+trifinger_simulation = "https://open-dynamic-robot-initiative.github.io/trifinger_simulation"
 
 [mainpage]
 title = "robot_fingers: (Tri-)Finger Robot Driver and Tools"

doc/simulation_backend.rst

@@ -0,0 +1,55 @@
+.. _simulation_backend:
+
+*********************************
+How to use the Simulation Backend
+*********************************
+
+In addition to the real-robot driver, ``robot_fingers`` also implements a
+simulation driver (based on :doc:`trifinger_simulation
+<trifinger_simulation:index>`), which can be used as a drop-in replacement for
+the real-robot.  This allows testing code in simulation and then moving to the
+real robot without the need for code changes (beyond replacing the backend).
+
+
+Multi-process Applications
+==========================
+
+**TriFingerPro only!**
+
+When running front end and back end in separate processes, all that needs to be
+done is to replace the back end with
+
+.. code-block:: sh
+
+   $ ros2 run robot_fingers pybullet_backend
+
+See ``--help`` for available options.
+
+This also requires the ``trifinger_data_backend`` to be running.  Minimal usage
+example (run each command in a separate terminal):
+
+.. code-block:: sh
+
+   $ ros2 run robot_fingers trifinger_data_backend -a 10000
+   $ ros2 run robot_fingers pybullet_backend --visualize
+   $ ros2 run robot_fingers demo_trifingerpro --multi-process
+
+
+Single-process Applications
+===========================
+
+When creating front end and back end in the same script, the only necessary
+change is to replace the function for creating the back end
+(:func:`robot_fingers.create_trifinger_backend` /
+:func:`robot_fingers.create_single_finger_backend`) with its counterpart from
+:mod:`robot_fingers.pybullet_drivers`.
+
+
+**Example: demo_simulation_driver**
+
+``demo_simulation_driver.py`` shows an example how to use the simulation backend
+(note that this example is a bit more complex as it covers all (Tri-)Finger
+types).  The only relevant difference to using the real robot is the choice of
+the "create backend" function.
+
+.. literalinclude:: /PKG/demos/demo_simulation_driver.py

doc_mainpage.rst

@@ -16,9 +16,10 @@ software, see also our paper_ on the open-source version of the TriFinger robot.
    :maxdepth: 1
 
    doc/installation.rst
-   doc/singularity.rst
    doc/getting_started.rst
+   doc/singularity.rst
    doc/homing.rst
+   doc/simulation_backend.rst
    doc/hardware_testing.rst
 
 

scripts/pybullet_backend.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Run robot_interfaces Backend for pyBullet using multi-process robot data.
+"""Run robot_interfaces Backend for PyBullet using multi-process robot data.
 
 This is intended to be used together with trifinger_data_backend.py and can
 serve as a replacement for the real robot backend.

srcpy/pybullet_drivers.cpp

@@ -19,14 +19,14 @@ PYBIND11_MODULE(pybullet_drivers, m)
           "first_action_timeout"_a = std::numeric_limits<double>::infinity(),
           "max_number_of_actions"_a = 0,
           R"XXX(
-            Create backend for the Single Finger robot using pyBullet simulation.
+            Create backend for the Single Finger robot using PyBullet simulation.
 
             Args:
                 robot_data (robot_interfaces.finger.Data):  Robot data instance
                     for the Finger robot.
                 real_time_mode (bool):  If True, step the simulation in real
                     time, otherwise as fast as possible.
-                visualize (bool):  If True, the pyBullet GUI is started for
+                visualize (bool):  If True, the PyBullet GUI is started for
                     visualization.
                 first_action_timeout (float): Timeout for the first action to
                     arrive.  If exceeded, the backend shuts down.  Set to
@@ -50,14 +50,14 @@ PYBIND11_MODULE(pybullet_drivers, m)
           "first_action_timeout"_a = std::numeric_limits<double>::infinity(),
           "max_number_of_actions"_a = 0,
           R"XXX(
-            Create a backend for the TriFinger robot using pyBullet simulation.
+            Create a backend for the TriFinger robot using PyBullet simulation.
 
             Args:
                 robot_data (robot_interfaces.trifinger.Data):  Robot data instance
                     for the TriFinger robot.
                 real_time_mode (bool):  If True, step the simulation in real
                     time, otherwise as fast as possible.
-                visualize (bool):  If True, the pyBullet GUI is started for
+                visualize (bool):  If True, the PyBullet GUI is started for
                     visualization.
                 first_action_timeout (float): Timeout for the first action to
                     arrive.  If exceeded, the backend shuts down.  Set to