Skip to content

Commit

Permalink
Unfinished doc migration
Browse files Browse the repository at this point in the history
  • Loading branch information
@yck011522
yck011522 committed Nov 19, 2024
1 parent 197b3fc commit 57c04d7
Show file tree
Hide file tree
Showing 137 changed files with 584 additions and 12,619 deletions.
6 changes: 6 additions & 0 deletions docs/backends/analytical_kinematics.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.. _backends_analytical_kinematics:

********************************************************************************
Using Analytical Kinematics Planner
********************************************************************************

5 changes: 5 additions & 0 deletions docs/backends/analytical_pybullet.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
.. _backends_analytical_pybullet:

********************************************************************************
Using Analytical PyBullet Planner
********************************************************************************
26 changes: 18 additions & 8 deletions docs/backends/pybullet.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.. _pybullet_backend:
.. _backends_pybullet:

****************
PyBullet
****************
********************************************************************************
Using PyBullet Planner
********************************************************************************

.. highlight:: bash

Expand All @@ -13,10 +13,20 @@ robotics simulation and machine learning." It also provides bindings for render
and visualization, and support for virtual reality headsets. While PyBullet
is based on a client-server architecture, there is no need to spin up any Docker
containers to run the server. This, along with its speed, may make PyBullet a
preferable backend for COMPAS_FAB. However, it, alone, does not provide motion
planning functionality. PyBullet is also not compatible with IronPython. Hence to use
it with Rhinoceros and Grasshopper it must be invoked through the
:mod:`compas.rpc` module.
preferable backend for COMPAS_FAB.

PyBullet is able to import Robot Models as URDF packages and provides forward
and inverse kinematics functions. Unlike ROS, the robot models can be loaded
dynamically and multiple robots can be loaded in the same environment. This allows
for the simulation of kinematic tools.

The **COMPAS FAB** PyBullet backend provides the :class:`PyBulletClient` and the
:class:`PyBulletPlanner` classes to interact with PyBullet. The motion planning
functions are implemented by **COMPAS FAB**, building on top of the inverse
kinematics and collision checking functions offered by PyBullet.

PyBullet is not compatible with IronPython. Therefor, it is not possible to use
it with Rhino 7 or its associated Grasshopper.

Next Steps
==========
Expand Down
179 changes: 33 additions & 146 deletions docs/backends/ros.rst
View file
Original file line number Diff line number Diff line change
@@ -1,160 +1,47 @@
.. _ros_backend:
.. _backends_ros_moveit:

****************
ROS
****************
********************************************************************************
Using ROS MoveIt Planner
********************************************************************************

.. highlight:: bash
.. currentmodule:: compas_fab

The `Robot Operating System <https://www.ros.org>`_ (ROS) is a flexible framework
for writing robot software. It is a collection of tools, libraries, and
conventions that aim to simplify the task of creating complex and robust
robot behavior across a wide variety of robotic platforms.
The ROS MoveIt planner is a wrapper that allows you to use the MoveIt motion
planning framework in a running ROS environment. The ROS and MoveIt environment
must be properly set up and running for this planner to work.

Running a ROS system usually involves multiple nodes (i.e. computers, real or
virtual), interconnected through a master controller.
The robot definition used by the planner must be installed in the ROS workspace
and launched together with the MoveIt configuration. Contrary to other backends,
the RobotModel cannot be changed after MoveIt is launched.

There are at least 3 different ways to run ROS: using Docker, using Linux, and
using WSL on Windows. In recent times, it became possible to install ROS using
Conda on Windows as well.
The user can only modify the initial robot cell, which is retrieved by calling
:meth:`compas_fab.backends.RosClient.load_robot_cell`. It contains
the :class:`compas_robots.RobotModel` and :class:`compas_fab.robots.RobotSemantics`
but have no tools and rigid bodies in it.
Users can customize this robot cell by adding tools and rigid bodies as needed.

The typical code snippet to use the MoveIt planner is as follows:

ROS on Docker
=============
.. code-block:: python
To massively simplify the use of these tools, we package complete ROS systems
into bundles of `Docker`_ containers. Each of these bundles runs in a
virtualized network within your computer.
from compas_fab.backends import RosClient
from compas_fab.backends import MoveItPlanner
with RosClient() as client:
planner = MoveItPlanner(client)
robot_cell = client.load_robot_cell()
Besides easing deployment, containers have the added benefit of ensuring
repeatability.
.. note::

Once you made sure `Docker`_ is running, you can run ROS nodes as containers.
Gramazio Kohler Research publishes ROS images on `Docker Hub`_ but there are
many more to be found online.
The following examples use the `ROS <https://www.ros.org/>`_ backend.
Before running them, please make sure you have the :ref:`ROS backend <ros_backend>`
installed and the :ref:`UR5 Demo <ros_bundles_list>` started.
It maybe beneficial to :ref:`enable GUI <docker_gui>`.

You can start a minimally functional ROS system, containing a ROS master and
the `ROS Bridge`_ with the following command::
.. toctree::
:maxdepth: 2
:titlesonly:
:glob:

docker run -p 9090:9090 -t gramaziokohler/ros-noetic-base roslaunch rosbridge_server rosbridge_websocket.launch
ros/*

Complete ROS systems
--------------------

It is usually not enough to run single ROS nodes. ROS systems are networks of
multiple interconnected nodes. Docker provides a way to compose virtualized
networks using the ``docker-compose`` command. These commands take one simple
configuration file as input, and handle all tasks required to run and connect
all the nodes.

As an example, download :download:`this file <files/base/docker-compose.yml>`,
open the command prompt, go to the folder where the file was downloaded,
and run the following command::

docker-compose up -d

You now have a ROS system with two nodes running: a ROS master and
the `ROS Bridge`_ which adds a web socket channel to communicate with ROS.

Creating new ROS bundles using containers is usually only a matter of combining
them into a new ``docker-compose.yml`` file, which is relatively simple but we
prepared some very common ones as examples.

.. _ros_bundles_list:

**Complete ROS system examples**

* ROS Noetic Base setup: :download:`Link <files/base/docker-compose.yml>`
* ABB IRB120: :download:`Link <files/abb-irb120-demo/docker-compose.yml>`
* ABB IRB120T: :download:`Link <files/abb-irb120t-demo/docker-compose.yml>`
* ABB IRB1600: :download:`Link <files/abb-irb1600-demo/docker-compose.yml>`
* ABB IRB4600 40/255: :download:`Link <files/abb-irb4600_40_255-demo/docker-compose.yml>`
* ABB IRB4600 60/205: :download:`Link <files/abb-irb4600_60_205-demo/docker-compose.yml>`
* Panda: :download:`Link <files/panda-demo/docker-compose.yml>`
* RFL: :download:`Link <files/rfl-demo/docker-compose.yml>`
* UR3: :download:`Link <files/ur3-demo/docker-compose.yml>`
* UR3e: :download:`Link <files/ur3e-demo/docker-compose.yml>`
* UR5: :download:`Link <files/ur5-demo/docker-compose.yml>`
* UR5e: :download:`Link <files/ur5e-demo/docker-compose.yml>`
* UR10: :download:`Link <files/ur10-demo/docker-compose.yml>`
* UR10e: :download:`Link <files/ur10e-demo/docker-compose.yml>`

Once the containers are running, it is possible to access the graphic user interface.
Check :ref:`the following page <backends_gui>` for more details.

ROS on Linux
============

The usual but most involved way to install ROS is on a Linux machine,
either virtual or real. The machine should have an IP address reachable
from your computer.

Follow the `ROS installation instructions`_ for all the details, or
alternatively, use the following commands as a brief outline of the steps
required to install ROS on **Ubuntu 20.04**:

::

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt update
sudo apt install ros-noetic-desktop-full ros-noetic-rosbridge-server python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential

sudo rosdep init && rosdep update
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/
catkin_make

echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

Once ROS is installed, you can start a minimally functional ROS system,
containing a ROS master and the `ROS Bridge`_ with the following command::

roslaunch rosbridge_server rosbridge_websocket.launch


ROS on WSL
==========

For Windows 10 users, an alternative is to install the
`Windows Subsystem for Linux`_ (WSL). WSL allows to run Linux within
Windows without the need for an additional virtual machine.

To install WSL, open PowerShell as administrator and run:

::

wsl --install

This command will enable the required optional components, download the latest Linux kernel,
set WSL 2 as your default, and install a Linux distribution for you.
Once the installation is completed, run ``bash`` and follow the instructions
above to install ROS on Linux.

After installation, it is possible to access the graphic user interface.
Check :ref:`the following page <backends_gui>` for more details.

.. seealso::

For additional details, see `Microsoft WSL documentation`_.



.. _ROS installation instructions: https://wiki.ros.org/ROS/Installation
.. _Windows Subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/about
.. _Microsoft WSL documentation: https://docs.microsoft.com/en-us/windows/wsl/install-win10
.. _Docker: https://www.docker.com/
.. _Docker Hub: https://hub.docker.com/u/gramaziokohler/
.. _ROS Bridge: https://wiki.ros.org/rosbridge_suite

Next Steps
==========

* :doc:`Tutorial: COMPAS Robots <compas_robots:tutorial>`
* :ref:`Examples: Description models <examples_description_models>`
* :ref:`Examples: ROS Backend <examples_ros>`
* :ref:`COMPAS FAB API Reference <reference>`
2 changes: 1 addition & 1 deletion ...03_backends_ros/06_ros_in_grasshopper.rst → docs/backends/ros/06_ros_in_grasshopper.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Many of the features of the Grasshopper playground have been packaged into Grass
components for simplicity of use. Below is a screenshot of a canvas which loads a
robot from ROS and visualizes it using the Grasshopper components of **COMPAS FAB**.

.. figure:: files/06_ros_in_grasshopper.jpg
.. figure:: images/06_ros_in_grasshopper.jpg
:figclass: figure
:class: figure-img img-fluid

6 changes: 3 additions & 3 deletions ...create_urdf_ur5_with_measurement_tool.rst → ...create_urdf_ur5_with_measurement_tool.rst
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _ros_examples_create_urdf_ur5_with_measurement_tool:

********************************************************************************
Creating a URDF with an UR5 robot and a custom end-effector
Advanced: Creating a URDF with an UR5 robot and a custom end-effector
********************************************************************************

Export your meshes
Expand All @@ -20,7 +20,7 @@ point to the flange (tool0) is in (0,0,0). The geometry of your end-effector has
to be defined in *meters*. Then export both visual and a collision meshes of
your end-effector in a ROS-friendly format, like .stl or .obj (see below).

.. figure:: files/07_urdf_tool_00.jpg
.. figure:: images/07_urdf_tool_00.jpg
:figclass: figure
:class: figure-img img-fluid

Expand Down Expand Up @@ -276,7 +276,7 @@ And then run::

roslaunch ur5_with_measurement_tool display.launch

.. figure:: files/07_urdf_tool_01.jpg
.. figure:: images/07_urdf_tool_01.jpg
:figclass: figure
:class: figure-img img-fluid

Expand Down
24 changes: 12 additions & 12 deletions ...reate_moveit_package_from_custom_urdf.rst → ...reate_moveit_package_from_custom_urdf.rst
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _ros_examples_create_moveit_package_from_custom_urdf:

********************************************************************************
Creating a MoveIt! package from the custom created URDF
Advanced: Using custom URDF in MoveIt!
********************************************************************************

This example is mainly copied from `MoveIt! Setup Assistant Tutorial <https://docs.ros.org/kinetic/api/moveit_tutorials/html/doc/setup_assistant/setup_assistant_tutorial.html>`_
Expand All @@ -27,7 +27,7 @@ and to define the planning groups.
*Load Files.* The Setup Assistant will load the files (this might take a few
seconds) and present you with this screen:

.. figure:: files/08_ros_create_moveit_package_00.jpg
.. figure:: images/08_ros_create_moveit_package_00.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -42,7 +42,7 @@ Note:
The sampling density specifies how many random robot positions to check for self
collision. The default value of 10'000 collision checks should be fine.

.. figure:: files/08_ros_create_moveit_package_01.jpg
.. figure:: images/08_ros_create_moveit_package_01.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -60,7 +60,7 @@ frame. We will define only one virtual joint, attaching the
* Set the Joint Type as "fixed".
* Click *Save*.

.. figure:: files/08_ros_create_moveit_package_02.jpg
.. figure:: images/08_ros_create_moveit_package_02.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -75,7 +75,7 @@ is later used for path- and motion planning.
* Click on the *Planning Groups* pane selector.
* Click on *Add Group* and you should see the following screen:

.. figure:: files/08_ros_create_moveit_package_03.jpg
.. figure:: images/08_ros_create_moveit_package_03.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -87,13 +87,13 @@ Add the arm
* Let *Kin. Search Resolution*, *Kin. Search Timeout (sec)*, *Kin. Solver Attempts* and
*Group Default Planner* stay at their default values.

.. figure:: files/08_ros_create_moveit_package_04.jpg
.. figure:: images/08_ros_create_moveit_package_04.jpg
:figclass: figure
:class: figure-img img-fluid

* Click on the *Add Kin. Chain* button. Press *Expand All*

.. figure:: files/08_ros_create_moveit_package_05.jpg
.. figure:: images/08_ros_create_moveit_package_05.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -118,7 +118,7 @@ We will also add a group for the end-effector.
* Choose measurment_tool and tcp (The links you defined in the measurement_tool.xacro) and add them to the list of *Selected Links* on the right hand side.
* Click *Save*

.. figure:: files/08_ros_create_moveit_package_06.jpg
.. figure:: images/08_ros_create_moveit_package_06.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -140,7 +140,7 @@ Tip:
Try to move all the joints around. If there is something wrong
with the joint limits in your URDF, you should be able to see it immediately here.

.. figure:: files/08_ros_create_moveit_package_07.jpg
.. figure:: images/08_ros_create_moveit_package_07.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -158,7 +158,7 @@ this group as a special group: end effectors.
* Leave *Parent Group* empty.
* Press *Save*.

.. figure:: files/08_ros_create_moveit_package_08.jpg
.. figure:: images/08_ros_create_moveit_package_08.jpg
:figclass: figure
:class: figure-img img-fluid

Expand Down Expand Up @@ -187,7 +187,7 @@ You are almost there. One last step!
All the generated files will appear in the Generated Files/Folders tab and you
can click on each of them for a description of what they contain.

.. figure:: files/08_ros_create_moveit_package_09.jpg
.. figure:: images/08_ros_create_moveit_package_09.jpg
:figclass: figure
:class: figure-img img-fluid

Expand All @@ -203,7 +203,7 @@ Now, optionally, you can already start the MoveIt! Demo and play::
roslaunch ur5_with_measurement_tool_moveit_config demo.launch rviz_tutorial:=true


.. figure:: files/08_ros_create_moveit_package_10.jpg
.. figure:: images/08_ros_create_moveit_package_10.jpg
:figclass: figure
:class: figure-img img-fluid

Expand Down
Loading

0 comments on commit 57c04d7

Please sign in to comment.