diff --git a/demos/demo_simulation_driver.py b/demos/demo_simulation_driver.py index b0bc6c4..7cb42ab 100644 --- a/demos/demo_simulation_driver.py +++ b/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() diff --git a/doc/breathing_cat.toml b/doc/breathing_cat.toml index b3e3626..3c65b1b 100644 --- a/doc/breathing_cat.toml +++ b/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" diff --git a/doc/simulation_backend.rst b/doc/simulation_backend.rst new file mode 100644 index 0000000..2d0e863 --- /dev/null +++ b/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 +`), 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 diff --git a/doc_mainpage.rst b/doc_mainpage.rst index d63147b..8cf2dbb 100644 --- a/doc_mainpage.rst +++ b/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 diff --git a/scripts/pybullet_backend.py b/scripts/pybullet_backend.py index c58964d..642f950 100644 --- a/scripts/pybullet_backend.py +++ b/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. diff --git a/srcpy/pybullet_drivers.cpp b/srcpy/pybullet_drivers.cpp index a3036a8..ce43685 100644 --- a/srcpy/pybullet_drivers.cpp +++ b/srcpy/pybullet_drivers.cpp @@ -19,14 +19,14 @@ PYBIND11_MODULE(pybullet_drivers, m) "first_action_timeout"_a = std::numeric_limits::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::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