doc: More concise sim/real-interface description

docs/index.rst

@@ -24,10 +24,9 @@ To learn more about the TriFinger robots, check out our paper_ (and the correspo
 
 .. toctree::
    :maxdepth: 1
-   :caption: Ease of Use with a Real Robot
+   :caption: Guides
 
    simreal/simwithreal
-   simreal/realwithsim
    simreal/simvsreal
    simreal/timesteplogic
 

docs/simreal/simvsreal.rst

@@ -1,20 +1,22 @@
 .. _sec-simulation-vs-real-robot:
 
-*********************************************
-Differences between Simulation and Real Robot
-*********************************************
+************************
+Simulation vs Real Robot
+************************
 
-The ``SimFinger`` class provides us with an API to control the TriFinger robots in
-simulation. Similarly, the `robot_interfaces::RobotFrontend`_ class provides an
-API to interact with these robots in real life.
+The :class:`~trifinger_simulation.sim_finger.SimFinger` class provides an API to control
+the TriFinger robots in simulation. Similarly, the
+:cpp:class:`robot_interfaces::RobotFrontend` class provides an API to interact with
+these robots in real life.
 
-It is extremely easy to switch between these two. However, there are some subtle
-differences one should keep in mind, which arise due to the accompanying switch
-between non-real time behaviour (in simulation), and real-time behaviour (in real life).
+It is easy to switch between these two (see :doc:`simwithreal`). However, there are some
+subtle differences one should keep in mind, which arise due to the accompanying switch
+between non-real-time behaviour (in simulation), and real-time behaviour (with real
+robots).
 
 
-Simulation is stepped in ``append_desired_action()``
-========================================================
+Simulation is Stepped in ``append_desired_action()``
+====================================================
 
 The simulation is explicitly stepped in the ``append_desired_action()``
 method: this is because the simulation doesn't exhibit real-time
@@ -26,43 +28,44 @@ continue to move and will repeat the last action if no new action is provided in
 
 .. _`No waiting for future time steps`:
 
-No waiting for future time steps
-======================================
+No Waiting for Future Time Steps
+================================
 
 On the real robot, it is possible to pass a time index that lies in the future
-and most methods of the `robot_interfaces::RobotFrontend`_ will simply block and wait until this
-time step is reached.  The simulation, however, is not running asynchronously
-but is actively stepped every time ``append_desired_action()`` is called.
-Therefore the behaviour of waiting for a time step is not supported.  Instead,
-passing a time index that lies in the future will result in an error.
+and most methods of the :cpp:class:`robot_interfaces::RobotFrontend` will simply block
+and wait until this time step is reached.  The simulation, however, is not running
+asynchronously but is actively stepped every time ``append_desired_action()`` is called.
+Therefore the behaviour of waiting for a time step is not supported.  Instead, passing a
+time index that lies in the future will result in an error.
 
 
 No Time Series in SimFinger
-==============================
+===========================
 
-The `robot_interfaces`_ package makes use of time series for observations,
-actions, etc.  This means all data of the last few time steps is available.  One
-could, for example do the following to determine how the state of the robot
-changed:
+The :doc:`robot_interfaces <robot_interfaces:index>` package makes use of time series
+for observations, actions, etc.  This means all data of the last few time steps is
+available.  One could, for example do the following to determine how the state of the
+robot changed:
 
 .. code-block:: python
 
     previous_observation = frontend.get_observation(t - 1)
     current_observation = frontend.get_observation(t)
 
-The ``SimFinger`` class does not implement a time series, so it only provides
-the observation of the current time step ``t``.  Passing any other value for
-``t`` will result in an error.
+The ``SimFinger``:class:`~trifinger_simulation.sim_finger.SimFinger` class does not
+implement a time series, so it only provides the observation of the current time step
+``t``.  Passing any other value for ``t`` will result in an error.
 
 
-API-differences with `robot_interfaces::RobotFrontend`_
-=========================================================
+API-differences with robot_interfaces::RobotFrontend
+====================================================
 
-Our goal is to provide the same API in ``SimFinger`` as in ``RobotFrontend`` to
-make transition between simulation and real robot easy.  There are a few
-differences, though.
+Our goal is to provide the same API in
+:class:`~trifinger_simulation.sim_finger.SimFinger` as in ``RobotFrontend`` to make
+transition between simulation and real robot easy.  There are a few differences, though.
 
-Currently ``SimFinger`` supports the following methods:
+Currently :class:`~trifinger_simulation.sim_finger.SimFinger` supports the following
+methods:
 
 - ``append_desired_action()``
 - ``get_observation()``
@@ -77,6 +80,3 @@ The following methods are not supported:
   simulation, so this method is omitted to avoid confusion.
 - ``wait_until_timeindex()``:  In general the process of waiting for a specific
   time step is not supported, see :ref:`No waiting for future time steps`.
-
-.. _`robot_interfaces::RobotFrontend`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/include/robot_interfaces/robot_frontend.hpp
-.. _`robot_interfaces`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/include/robot_interfaces/

docs/simreal/simwithreal.rst

@@ -1,72 +1,63 @@
-************************************************
-Simulation vs Real Robot in trifinger_simulation
-************************************************
+********************
+Real Robot Interface
+********************
 
-We have designed the entire `trifinger_simulation` package with the
-aim of making it possible to seamlessly transition to our software for
-interfacing with these robots in the real world, to the extent of making
-this transition pretty much plug and play: depending on whether you want
-to create an instance of a simulated robot or a
-real robot, which you would like to use in a gym environment for learning, or for
-optimal control, or just to play around in by sending some crazy random commands.
+The simulation API is designed with the aim of making it easy to transition to the
+interface of the real robots.
+Below, we describe two different ways of switching between simulated and real robot:
 
-To give a very simple example of this, consider sending some control commands to
-the TriFinger,
+1. Switching between :class:`~trifinger_simulation.sim_finger.SimFinger` and
+   :class:`~trifinger_simulation.real_finger.RealFinger`
+2. Using the real-robot interface and replacing the hardware back end with the
+   simulation.
+
+Note also, that the interface of :class:`~trifinger_simulation.sim_finger.SimFinger` is
+designed to be as similar as possible to the real-robot front end, so even switching
+between the two should be relatively easy.
+
+
+RealRobot Wrapper
+=================
+
+The :class:`~trifinger_simulation.real_finger.RealFinger` class provides a wrapper
+around the real-robot interface which can be used as a drop-in replacement for
+:class:`~trifinger_simulation.sim_finger.SimFinger`.
+
+Simple example, sending control commands to the TriFinger:
 
 .. code-block:: python
 
     from trifinger_simulation import sim_finger, real_finger
 
     if use_real == True:
-        # to know what this robot is, look at the example below
-        robot = sim_finger.RealFinger(finger_type)
+        robot = real_finger.RealFinger(finger_type)
     else:
-        robot = real_finger.SimFinger(finger_type)
+        robot = sim_finger.SimFinger(finger_type)
 
     def step(action):
         for _ in range(steps_per_control):
             t = robot.append_desired_action(action)
             observation = robot.get_observation()
 
-As you can see from the example above, you can control the TriFinger in the
-same way irrespective of whether its a simulated or real. You can see an example
-of this usage in our `TriFingerReach environment <https://github.com/open-dynamic-robot-initiative/trifinger_simulation/blob/master/trifinger_simulation/gym_wrapper/envs/trifinger_reach.py>`_.
-
-The ``RealFinger`` class exposes analogous methods to interact with the real robot as the ones
-for ``SimFinger``. Inside ``RealFinger``, the robot actually gets created like this:
-
-.. code-block:: python
-
-    import robot_interfaces
-    import robot_fingers
-
-    robot_config_path = "path_to_the_config_yml_of_the_desired_robot_type"
-
-    robot_data = robot_interfaces.trifinger.SingleProcessData()
+You can see an example of this usage in our :doc:`TriFingerReach environment
+<src_trifinger_reach-py>`.
 
-    robot_backend = robot_fingers.create_trifinger_backend(
-                robot_data, robot_config_path)
-    robot = robot_interfaces.trifinger.Frontend(robot_data)
 
 .. note::
 
-    In order to use the ``RealFinger`` class, you would need to install additional packages like
-    `robot_interfaces`_ and `robot_fingers`_ as you can see in the example above. These packages are
-    not a part of the `trifinger_simulation conda environment`_. Instructions on how to install
-    these packages will follow soon in the :ref:`colcon` section.
+    In order to use the ``RealFinger`` class, you would need additional packages from
+    the TriFinger software bundle.  See :ref:`colcon`.
 
-.. note:: 
 
-    If at this point, you are interested in exploring our software interface for the
-    real robot, you can head over to the frontend of this interface to check out
-    the exposed methods in the `RobotFrontend`_,
-    and check out some demos for controlling a real robot in `here <https://github.com/open-dynamic-robot-initiative/robot_fingers/tree/master/demos>`_.
 
-In addition, you can also access the complete API of interacting with the real robot (the `RobotFrontend`_ mentioned
-in the note above) with this simulation. Head over to the next section, :ref:`robot_interfaces with Simulation` to know how to do this.
+Real Robot Front End with Simulation Back End
+=============================================
 
+The :doc:`robot_fingers <robot_fingers:index>` package provides an
+:doc:`robot_interfaces <robot_interfaces:index>`-based interface to the hardware of the
+real TriFinger robots.
 
-.. _`RobotFrontend`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/include/robot_interfaces/robot_frontend.hpp
-.. _`robot_interfaces`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/
-.. _`robot_fingers`: https://github.com/open-dynamic-robot-initiative/robot_fingers
-.. _`trifinger_simulation conda environment`: https://github.com/open-dynamic-robot-initiative/trifinger_simulation/blob/master/environment.yml
+It is possible to use the front end of the real-robot interface but with the simulation
+plugged in as back end.  This allows using the exact same code for simulation and real
+robot.  For more information on this, see :ref:`robot_fingers:simulation_backend` in the
+``robot_fingers`` documentation.

docs/simreal/src_trifinger_reach-py.rst

@@ -0,0 +1,7 @@
+:orphan:
+
+***************************************
+Example: TriFingerReach Gym Environment
+***************************************
+
+.. literalinclude:: ../../trifinger_simulation/gym_wrapper/envs/trifinger_reach.py