update docs

This commit is contained in:
Brian Delhaisse
2019-06-26 03:37:23 +02:00
parent 542284fdde
commit 52020bceb5
34 changed files with 418 additions and 130 deletions
+124 -89
View File
@@ -9,6 +9,37 @@ More than 64 robots have been implemented in PRL and include various kind of rob
GIF
.. image:: ../figures/coman.png
:width: 9%
:alt: coman
.. image:: ../figures/wam.png
:width: 9%
:alt: wam
.. image:: ../figures/fetch.png
:width: 9%
:alt: fetch
.. image:: ../figures/cassie.png
:width: 9%
:alt: cassie
.. image:: ../figures/hyq2max.png
:width: 9%
:alt: hyq2max
.. image:: ../figures/phantomx.png
:width: 9%
:alt: phantomx
.. image:: ../figures/pleurobot.png
:width: 9%
:alt: pleurobot
.. image:: ../figures/softhand.png
:width: 9%
:alt: softhand
.. image:: ../figures/centauro.png
:width: 9%
:alt: baxter
.. image:: ../figures/walkman.png
:width: 9%
:alt: walkman
Note that for few of them such as the ones that require the simulation of fluids such as quadcopters. The corresponding class implements the dynamical simulation. For such classes, as I did not spend too much time one it, some improvements might be needed for better realism.
@@ -16,6 +47,7 @@ How to use a robot in PRL?
--------------------------
.. code-block:: python
:linenos:
from itertools import count
import pyrobolearn as prl
@@ -45,35 +77,35 @@ How to use a robot in PRL?
world.step(sim.dt)
You can check for more examples in the [`examples/robots`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/robots) folder. You can also check for [`examples/kinematics`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/kinematics) and [`examples/dynamics`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/dynamics).
You can check for more examples in the `examples/robots <https://github.com/robotlearn/pyrobolearn/tree/master/examples/robots>`_ folder. You can also check for `examples/kinematics <https://github.com/robotlearn/pyrobolearn/tree/master/examples/kinematics>`_ and `examples/dynamics <https://github.com/robotlearn/pyrobolearn/tree/master/examples/dynamics>`_.
Design
------
The most abstract class is the `Body` class which is described in `pyrobolearn/robots/base.py`. From it, you can already access to multiple functionalities/attributes, such as its position and orientation. It only depends on the simulator.
The most abstract class is the ``Body`` class which is described in `pyrobolearn/robots/base.py <https://github.com/robotlearn/pyrobolearn/blob/master/pyrobolearn/robots/base.py>`_. From it, you can already access to multiple functionalities/attributes, such as its position and orientation. It only depends on the simulator.
Inheriting from one of its child classes is the most interesting (for our purpose) `Robot` class, described in `robot.py`. It is the parent class of several classes such as:
.. image:: ../UML/robots.png
:alt: UML diagram for Robot
:align: center
- `Manipulator` defined in `pyrobolearn/robots/manipulator.py`
- `LeggedRobot` defined in `pyrobolearn/robots/legged_robot.py`
- `WheeledRobot` defined in `pyrobolearn/robots/wheeled_robot.py`
- `Hand` defined in `pyrobolearn/robots/hand.py`
Inheriting from one of its child classes is the most interesting (for our purpose) ``Robot`` class, described in `robot.py <https://github.com/robotlearn/pyrobolearn/blob/master/pyrobolearn/robots/robot.py>`_. It is the parent class of several classes such as:
- ``Manipulator`` defined in `manipulator.py <https://github.com/robotlearn/pyrobolearn/blob/master/pyrobolearn/robots/manipulator.py>`_
- ``LeggedRobot`` defined in `legged_robot.py <https://github.com/robotlearn/pyrobolearn/blob/master/pyrobolearn/robots/legged_robot.py>`_
- ``WheeledRobot`` defined in `wheeled_robot.py <https://github.com/robotlearn/pyrobolearn/blob/master/pyrobolearn/robots/wheeled_robot.py>`_
- ``Hand`` defined in `hand.py <https://github.com/robotlearn/pyrobolearn/blob/master/pyrobolearn/robots/hand.py>`_
- etc.
UML picture
Note that `Robot` only depends on the simulator interface, and is independent of other modules in PRL (at the exception of some utils method that are useful to perform some transformations).
Note that ``Robot`` only depends on the simulator interface (aggregation relationship), and is independent of other modules in PRL (at the exception of some util methods that are useful to perform some transformations).
How to create your own robot?
-----------------------------
To illustrate how to create your own robot, let's assume you want to create a humanoid robot (biped and bi-manipulator) called `Asimov`.
To illustrate how to create your own robot, let's assume you want to create a humanoid robot (biped and bi-manipulator) called ``Asimov``.
1. First, you have to get (or create) its URDF file and the associated meshes. Let's put them in a directory called `asimov`, and move it in the `pyrobolearn/robots/urdfs/` folder where all the other URDFs are.
1. First, you have to get (or create) its URDF file and the associated meshes. Let's put them in a directory called ``asimov``, and move it in the ``pyrobolearn/robots/urdfs/`` folder where all the other URDFs are.
2. If you want to use it directly and to not create a specific class, you can just call:
@@ -102,10 +134,11 @@ To illustrate how to create your own robot, let's assume you want to create a hu
# perform a step in the world and pause for `sim.dt`
world.step(sim.dt)
3. Instead of the second point, let's create a proper class `Asimov` that inherits from the `BipedRobot` and `BiManipulator` (and thus inherits their functionalities) in a Python file `asimov.py`:
3. Instead of the second point, let's create a proper class ``Asimov`` that inherits from the ``BipedRobot`` and ``BiManipulator`` (and thus inherits their functionalities) in a Python file ``asimov.py``:
.. code-block:: python
:linenos:
#!/usr/bin/env python
"""Short description about your robot
@@ -168,7 +201,7 @@ To illustrate how to create your own robot, let's assume you want to create a hu
...
3. If you want to be able to load your robot from the world using its name (by calling `world.load_robot('asimov')`), add the Python file `asimov.py` in the `pyrobolearn/robots/` folder. The `__init__.py` inside that folder will automatically go through all the files and add the robots inside the `implemented_robots` list which is accessed by `World`. Note that you can also accessed to this list by calling `pyrobolearn.robots.implemented_robots`. If you also want to be able to call your robot using `from pyrobolearn.robots import Asimov`, you will have to add the line `from .asimov import Asimov` in the `pyrobolearn/robots/__init__.py`.
3. If you want to be able to load your robot from the world using its name (by calling ``world.load_robot('asimov')``), add the Python file ``asimov.py`` in the `pyrobolearn/robots/ <https://github.com/robotlearn/pyrobolearn/tree/master/pyrobolearn/robots>`_ folder. The ``__init__.py`` inside that folder will automatically go through all the files and add the robots inside the ``implemented_robots`` list which is accessed by ``World``. Note that you can also accessed to this list by calling ``pyrobolearn.robots.implemented_robots``. If you also want to be able to call your robot using ``from pyrobolearn.robots import Asimov``, you will have to add the line ``from .asimov import Asimov`` in the `pyrobolearn/robots/__init__.py <https://github.com/robotlearn/pyrobolearn/blob/master/pyrobolearn/robots/__init__.py>`_.
4. Now, you can call your robot in the framework.
@@ -203,91 +236,93 @@ Sensors and Actuators
FAQs and Troubleshootings
-------------------------
* The mass/inertia matrix of some links are not correct in the simulator, what should I do?
* If you use the Bullet simulator (which uses `pybullet`), you have to specify the mass and inertia matrix for each link. If a link doesn't have these attributes defined, pybullet automatically attribute a mass of 1kg and an identity inertia matrix (which is ridiculous huge). Normally, links without a mass and inertia matrices defined in a URDF file are dummy links that are used to represent a reference frame. To set a reasonable inertia matrix, please refer to ["Adding Physical and Collision Properties to a URDF Model"](http://wiki.ros.org/urdf/Tutorials/Adding%20Physical%20and%20Collision%20Properties%20to%20a%20URDF%20Model) and ["Inertial parameters of triangle meshes"](http://gazebosim.org/tutorials?tut=inertia&cat=build_robot).
* It is possible that some masses / inertia matrices have not been correctly set in the original URDF. I cleaned most of the URDF files but some links might have escaped my attention. Please open an issue on [Github](https://github.com/robotlearn/pyrobolearn), or check the 2 [links](http://wiki.ros.org/urdf/Tutorials/Adding%20Physical%20and%20Collision%20Properties%20to%20a%20URDF%20Model) [above](http://gazebosim.org/tutorials?tut=inertia&cat=build_robot) on how to set reasonable inertia values.
- The mass/inertia matrix of some links are not correct in the simulator, what should I do?
* If you use the Bullet simulator (which uses ``pybullet``), you have to specify the mass and inertia matrix for each link. If a link doesn't have these attributes defined, pybullet automatically attribute a mass of 1kg and an identity inertia matrix (which is ridiculous huge). Normally, links without a mass and inertia matrices defined in a URDF file are dummy links that are used to represent a reference frame. To set a reasonable inertia matrix, please refer to `"Adding Physical and Collision Properties to a URDF Model" <http://wiki.ros.org/urdf/Tutorials/Adding%20Physical%20and%20Collision%20Properties%20to%20a%20URDF%20Model>`_ and `"Inertial parameters of triangle meshes" <http://gazebosim.org/tutorials?tut=inertia&cat=build_robot>`_.
* It is possible that some masses / inertia matrices have not been correctly set in the original URDF. I cleaned most of the URDF files but some links might have escaped my attention. Please open an issue on `Github <https://github.com/robotlearn/pyrobolearn>`_, or check the 2 `links <http://wiki.ros.org/urdf/Tutorials/Adding%20Physical%20and%20Collision%20Properties%20to%20a%20URDF%20Model>`_ `above <http://gazebosim.org/tutorials?tut=inertia&cat=build_robot>`_ on how to set reasonable inertia values.
* How to convert a xacro file to a URDF file? Type `rosrun xacro xacro --inorder path/to/<robot>.urdf.xacro > <robot>.urdf` or `rosrun xacro xacro.py --inorder path/to/<robot>.urdf.xacro > <robot>.urdf`
- How to convert a xacro file to a URDF file? Type ``rosrun xacro xacro --inorder path/to/<robot>.urdf.xacro > <robot>.urdf`` or ``rosrun xacro xacro.py --inorder path/to/<robot>.urdf.xacro > <robot>.urdf``
* When I set the `fixed_base` to `False`, the robot has still a fixed base, what is happening? The first link (often called base_link or world_link in most URDF files) shouldn't have a mass/inertia of zero, this causes the robot to have a fixed base. Remove the corresponding tag from the urdf.
- When I set the ``fixed_base`` to ``False``, the robot has still a fixed base, what is happening? The first link (often called base_link or world_link in most URDF files) shouldn't have a mass/inertia of zero, this causes the robot to have a fixed base. Remove the corresponding tag from the urdf.
* I noticed that some functionalities are missing in one of the robot class? I probably forgot to implement it. Please open an issue on [Github](https://github.com/robotlearn/pyrobolearn) or create a pull request.
- I noticed that some functionalities are missing in one of the robot class? I probably forgot to implement it. Please open an issue on `Github <https://github.com/robotlearn/pyrobolearn>`_ or create a pull request.
* There is an error in one of the functionalities? Or, I have another question or want to suggest an improvement? Please open an issue on [Github](https://github.com/robotlearn/pyrobolearn) or a create a pull request.
- There is an error in one of the functionalities? Or, I have another question or want to suggest an improvement? Please open an issue on `Github <https://github.com/robotlearn/pyrobolearn>`_ or a create a pull request.
Future works
------------
* add more robots
* [hexapods](https://github.com/resibots/hexapod_ros/tree/master/hexapod_description)
* improve the flexibility/modularity by allowing to remove/add/replace links to/from the main robot. For instance:
* add a gripper to a manipulator robot, or replace a gripper with another
* remove a leg to a legged robot (which is interesting to simulate damage recovery scenarios)
* might need to define different URDFs for different simulators
- add more robots. Here are few other robots that might interest the users:
- `hexapods <https://github.com/resibots/hexapod_ros/tree/master/hexapod_description>`_
- `ROS robots <https://robots.ros.org/>`_
- `Universal robots <https://github.com/ros-industrial/universal_robot>`_
- improve the flexibility/modularity by allowing to remove/add/replace links to/from the main robot. For instance:
- add a gripper to a manipulator robot, or replace a gripper with another
- remove a leg from a legged robot (which is interesting to simulate damage recovery scenarios)
- might need to define different URDFs for different simulators
References
----------
All the robots were found in the following github repositories (and several were cleaned by me):
- [Aibo](https://github.com/dkotfis/aibo_ros)
- [Allegrohand](https://github.com/simlabrobotics/allegro_hand_ros)
- [Ant](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf)
- Atlas: [1](https://github.com/openai/roboschool), [2](https://github.com/erwincoumans/pybullet_robots)
- [Ballbot](https://github.com/CesMak/bb)
- [Baxter](https://github.com/RethinkRobotics/baxter_common)
- BB8: [1](http://www.theconstructsim.com/bb-8-gazebo-model/), [2](https://github.com/eborghi10/BB-8-ROS)
- [Blackbird](https://hackaday.io/project/160882-blackbird-bipedal-robot)
- [Cartpole](https://github.com/bulletphysics/bullet3/blob/master/data/cartpole.urdf) but modified to be able to have multiple links specified at runtime
- Cassie: [1](https://github.com/UMich-BipedLab/Cassie_Model), [2](https://github.com/agilityrobotics/cassie-gazebo-sim), [3](https://github.com/erwincoumans/pybullet_robots)
- [Centauro](https://github.com/ADVRHumanoids/centauro-simulator)
- [Cogimon](https://github.com/ADVRHumanoids/iit-cogimon-ros-pkg)
- [Coman](https://github.com/ADVRHumanoids/iit-coman-ros-pkg)
- [Crab](https://github.com/tuuzdu/crab_project)
- [Cubli](https://github.com/xinsongyan/cubli)
- [Darwin](https://github.com/HumaRobotics/darwin_description)
- [e.Do](https://github.com/Comau/eDO_description)
- [E-puck](https://github.com/gctronic/epuck_driver_cpp)
- [F10 racecar](https://github.com/erwincoumans/pybullet_robots/tree/master/data/f10_racecar)
- [Fetch](https://github.com/fetchrobotics/fetch_ros)
- [Flappy]()
- [Franka Emika](https://github.com/frankaemika/franka_ros)
- [Half Cheetah](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf)
- [Hopper](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf)
- [Hubo](https://github.com/robEllenberg/hubo-urdf)
- [Humanoid](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf)
- [Husky](https://github.com/husky/husky)
- [HyQ](https://github.com/iit-DLSLab/hyq-description)
- [HyQ2Max](https://github.com/iit-DLSLab/hyq2max-description)
- ICub: [1](https://github.com/robotology-playground/icub-models), [2](https://github.com/robotology-playground/icub-model-generator). There are currently few problems with this robot.
- [Jaco](https://github.com/JenniferBuehler/jaco-arm-pkgs)
- KR5: [1](https://github.com/a-price/KR5sixxR650WP_description), [2](https://github.com/ros-industrial/kuka_experimental)
- Kuka IIWA: [1](https://github.com/IFL-CAMP/iiwa_stack), [2](https://github.com/bulletphysics/bullet3/tree/master/data/kuka_iiwa)
- Kuka LWR: [1](https://github.com/CentroEPiaggio/kuka-lwr), [2](https://github.com/bulletphysics/bullet3/tree/master/data/kuka_lwr)
- [Laikago](https://github.com/erwincoumans/pybullet_robots)
- [Little Dog](https://github.com/RobotLocomotion/LittleDog)
- [Manipulator2D](https://github.com/domingoesteban/robolearn_robots_ros)
- [Minitaur](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/quadruped)
- [Lincoln MKZ car](https://bitbucket.org/DataspeedInc/dbw_mkz_ros)
- [Morphex](https://gist.github.com/lanius/cb8b5e0ede9ff3b2b2c1bc68b95066fb)
- Nao: [1](https://github.com/ros-naoqi/nao_robot), and [2](https://github.com/ros-naoqi/nao_meshes)
- OpenDog: [1](https://github.com/XRobots/openDog), and [2](https://github.com/wiccopruebas/opendog_project)
- [Pepper](https://github.com/ros-naoqi/pepper_robot)
- [Phantom X](https://github.com/HumaRobotics/phantomx_description)
- [Pleurobot](https://github.com/KM-RoBoTa/pleurobot_ros_pkg)
- [PR2](https://github.com/pr2/pr2_common)
- [Quadcopter](https://github.com/wilselby/ROS_quadrotor_simulator)
- [Rhex](https://github.com/grafoteka/rhex)
- [RRbot](https://github.com/ros-simulation/gazebo_ros_demos)
- Sawyer: [1](https://github.com/RethinkRobotics/sawyer_robot), [2](https://github.com/erwincoumans/pybullet_robots)
- [SEA hexapod](https://github.com/alexansari101/snake_ws)
- [SEA snake]( https://github.com/alexansari101/snake_ws)
- [Shadow hand](https://github.com/shadow-robot/sr_common)
- [Soft hand](https://github.com/CentroEPiaggio/pisa-iit-soft-hand)
- [Swimmer](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf)
- [Valkyrie](https://github.com/openhumanoids/val_description)
- [Walker 2D](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf)
- [Walk-man](https://github.com/ADVRHumanoids/iit-walkman-ros-pkg)
- [Wam](https://github.com/jhu-lcsr/barrett_model)
- [Youbot](https://github.com/youbot): this includes the youbot base without any arms, one kuka arm, 2 kuka arms, and the kuka arm without the wheeled base.
- `Aibo <https://github.com/dkotfis/aibo_ros>`_
- `Allegrohand <https://github.com/simlabrobotics/allegro_hand_ros>`_
- `Ant <https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf>`_
- Atlas: `1 <https://github.com/openai/roboschool>`_, `2 <https://github.com/erwincoumans/pybullet_robots>`_
- `Ballbot <https://github.com/CesMak/bb>`_
- `Baxter <https://github.com/RethinkRobotics/baxter_common>`_
- BB8: `1 <http://www.theconstructsim.com/bb-8-gazebo-model/>`_, `2 <https://github.com/eborghi10/BB-8-ROS>`_
- `Blackbird <https://hackaday.io/project/160882-blackbird-bipedal-robot>`_
- `Cartpole <https://github.com/bulletphysics/bullet3/blob/master/data/cartpole.urdf>`_ but modified to be able to have multiple links specified at runtime
- Cassie: `1 <https://github.com/UMich-BipedLab/Cassie_Model>`_, `2 <https://github.com/agilityrobotics/cassie-gazebo-sim>`_, `3 <https://github.com/erwincoumans/pybullet_robots>`_
- `Centauro <https://github.com/ADVRHumanoids/centauro-simulator>`_
- `Cogimon <https://github.com/ADVRHumanoids/iit-cogimon-ros-pkg>`_
- `Coman <https://github.com/ADVRHumanoids/iit-coman-ros-pkg>`_
- `Crab <https://github.com/tuuzdu/crab_project>`_
- `Cubli <https://github.com/xinsongyan/cubli>`_
- `Darwin <https://github.com/HumaRobotics/darwin_description>`_
- `e.Do <https://github.com/Comau/eDO_description>`_
- `E-puck <https://github.com/gctronic/epuck_driver_cpp>`_
- `F10 racecar <https://github.com/erwincoumans/pybullet_robots/tree/master/data/f10_racecar>`_
- `Fetch <https://github.com/fetchrobotics/fetch_ros>`_
- `Franka Emika <https://github.com/frankaemika/franka_ros>`_
- `Half Cheetah <https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf>`_
- `Hopper <https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf>`_
- `Hubo <https://github.com/robEllenberg/hubo-urdf>`_
- `Humanoid <https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf>`_
- `Husky <https://github.com/husky/husky>`_
- `HyQ <https://github.com/iit-DLSLab/hyq-description>`_
- `HyQ2Max <https://github.com/iit-DLSLab/hyq2max-description>`_
- ICub: `1 <https://github.com/robotology-playground/icub-models>`_, `2 <https://github.com/robotology-playground/icub-model-generator>`_. There are currently few problems with this robot.
- `Jaco <https://github.com/JenniferBuehler/jaco-arm-pkgs>`_
- KR5: `1 <https://github.com/a-price/KR5sixxR650WP_description>`_, `2 <https://github.com/ros-industrial/kuka_experimental>`_
- Kuka IIWA: `1 <https://github.com/IFL-CAMP/iiwa_stack>`_, `2 <https://github.com/bulletphysics/bullet3/tree/master/data/kuka_iiwa>`_
- Kuka LWR: `1 <https://github.com/CentroEPiaggio/kuka-lwr>`_, `2 <https://github.com/bulletphysics/bullet3/tree/master/data/kuka_lwr>`_
- `Laikago <https://github.com/erwincoumans/pybullet_robots>`_
- `Little Dog <https://github.com/RobotLocomotion/LittleDog>`_
- `Manipulator2D <https://github.com/domingoesteban/robolearn_robots_ros>`_
- `Minitaur <https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/quadruped>`_
- `Lincoln MKZ car <https://bitbucket.org/DataspeedInc/dbw_mkz_ros>`_
- `Morphex <https://gist.github.com/lanius/cb8b5e0ede9ff3b2b2c1bc68b95066fb>`_
- Nao: `1 <https://github.com/ros-naoqi/nao_robot>`_, and `2 <https://github.com/ros-naoqi/nao_meshes>`_
- OpenDog: `1 <https://github.com/XRobots/openDog>`_, and `2 <https://github.com/wiccopruebas/opendog_project>`_
- `Pepper <https://github.com/ros-naoqi/pepper_robot>`_
- `Phantom X <https://github.com/HumaRobotics/phantomx_description>`_
- `Pleurobot <https://github.com/KM-RoBoTa/pleurobot_ros_pkg>`_
- `PR2 <https://github.com/pr2/pr2_common>`_
- `Quadcopter <https://github.com/wilselby/ROS_quadrotor_simulator>`_
- `Rhex <https://github.com/grafoteka/rhex>`_
- `RRbot <https://github.com/ros-simulation/gazebo_ros_demos>`_
- Sawyer: `1 <https://github.com/RethinkRobotics/sawyer_robot>`_, `2 <https://github.com/erwincoumans/pybullet_robots>`_
- `SEA hexapod <https://github.com/alexansari101/snake_ws>`_
- `SEA snake <https://github.com/alexansari101/snake_ws>`_
- `Shadow hand <https://github.com/shadow-robot/sr_common>`_
- `Soft hand <https://github.com/CentroEPiaggio/pisa-iit-soft-hand>`_
- `Swimmer <https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf>`_
- `Valkyrie <https://github.com/openhumanoids/val_description>`_
- `Walker 2D <https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf>`_
- `Walk-man <https://github.com/ADVRHumanoids/iit-walkman-ros-pkg>`_
- `Wam <https://github.com/jhu-lcsr/barrett_model>`_
- `Youbot <https://github.com/youbot>`_: this includes the youbot base without any arms, one kuka arm, 2 kuka arms, and the kuka arm without the wheeled base.