diff --git a/docs/index.rst b/docs/index.rst index b3fa479..3c6dbb0 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/simreal/realwithsim.rst b/docs/simreal/realwithsim.rst deleted file mode 100644 index 4101b9c..0000000 --- a/docs/simreal/realwithsim.rst +++ /dev/null @@ -1,51 +0,0 @@ -********************************************** -Simulation vs Real Robot in the Real Robot API -********************************************** - -It is also possible to use this simulation through our software for interfacing with the -real robot. So, you could -access the real TriFinger with the simulation as seen in :doc:`simwithreal`. -You can also access the simulated TriFinger through the real interface, as seen here below. - -The Real Robot API -====================== - -The `robot_interfaces`_ sotware package provides an interface to the hardware -of the real TriFinger robots. See the documentation there fore more details. - - -.. _`robot_interfaces with Simulation`: - -Using the Simulation through the `robot_interfaces`_ API -=========================================================== - -It is possible to create a backend of this simulation and have access to all the methods -provided by `robot_interfaces`_ in addition to all the methods provided by ``SimFinger``. -This is done by using the pyBullet -driver in the backend. By doing this, you only need to replace the backend of the robot -when switching between simulation and real, while all the rest of your code can -remain **exactly** the same. - - -To create a TriFinger backend using simulation: - -.. code-block:: python - - import trifinger_simulation.drivers - - backend = trifinger_simulation.drivers.create_trifinger_backend( - robot_data, real_time_mode=True, visualize=True - ) - -If ``real_time_mode`` is ``True``, the backend will expect a new action every -millisecond and repeat the previous action if it is not provided in time (like -on the real robot). If set to ``False``, it will run as fast as possible and -wait for new actions. - -Set ``visualize=True`` to run the pyBullet GUI for visualization. - - -For a complete example, see `demo_robot_interface.py`_ - -.. _`demo_robot_interface.py`: https://github.com/open-dynamic-robot-initiative/trifinger_simulation/blob/master/demos/catkin/demo_robot_interface.py -.. _`robot_interfaces`: https://github.com/open-dynamic-robot-initiative/robot_interfaces diff --git a/docs/simreal/simvsreal.rst b/docs/simreal/simvsreal.rst index 9ded4d5..47748c3 100644 --- a/docs/simreal/simvsreal.rst +++ b/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 ` 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/ diff --git a/docs/simreal/simwithreal.rst b/docs/simreal/simwithreal.rst index 282af67..40b7081 100644 --- a/docs/simreal/simwithreal.rst +++ b/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 `_. - -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 +`. - 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 `_. -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 ` package provides an +:doc:`robot_interfaces `-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. diff --git a/docs/simreal/src_trifinger_reach-py.rst b/docs/simreal/src_trifinger_reach-py.rst new file mode 100644 index 0000000..2d5ba99 --- /dev/null +++ b/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