Move installation instructions to RST and update docker usage instruc…

…tions (backport #309) (#322) * Move installation instructions to RST and update docker usage instructions (#309) Co-authored-by: Reza Kermani <kermani.areza@gmail.com> (cherry picked from commit 815e05e) * Use humble instead of rolling branch in docs --------- Co-authored-by: Christoph Fröhlich <christophfroehlich@users.noreply.github.com> Co-authored-by: Christoph Froehlich <christoph.froehlich@ait.ac.at>
ros-controls · Jun 28, 2023 · ba54f20 · ba54f20
1 parent b3b5ced
commit ba54f20
Show file tree

Hide file tree

Showing 28 changed files with 378 additions and 88 deletions.
diff --git a/README.md b/README.md
@@ -78,34 +78,6 @@ The important files to check in each example are:
 The concepts in this package are demonstrated on the examples of *RRBot* and *DiffBot*.
 Those two world-known imaginary robots are trivial simulations to demonstrate and test `ros2_control` concepts.
 
-## Usage
-### Using Docker
-**Building your own**
-
-```bash
-mkdir -p ~/ros2_ws/src
-cd ~/ros2_ws/src
-git clone https://github.com/ros-controls/ros2_control_demos
-cd ros2_control_demos
-docker build . -t ros2_control_demos -f Dockerfile/Dockerfile
-```
-
-**To run the demo**
-
-Docker allows us to run the demo without the GUI if configured properly. The following command runs the demo without the GUI:
-```bash
-docker run -it --rm ros2_control_demos
-```
-
-Then on your local machine, you can run rviz with the config file specified:
-
-```bash
-cd ~/ros2_ws
-source /opt/ros/rolling/setup.sh
-rviz2 -d src/ros2_control_demos/example_2/description/rviz/diffbot.rviz
-```
-
-
 ## Build status
 
 ROS 2 Distro | Branch | Build status | Documentation
@@ -129,27 +101,3 @@ ROS 2 Distro | Branch | Build status | Documentation
    Uses repos file: `src/$NAME$/$NAME$.repos`
 
 1. Source build - also core ROS packages are build from source. It shows potential issues in the mid future.
-
-
-# Build from source
-```
-git clone https://github.com/ros-controls/ros2_control
-git clone https://github.com/ros-controls/ros2_controllers
-git clone https://github.com/ros-controls/ros2_control_demos
-```
-
-**NOTE**: `ros2_control` and `ros2_controllers` packages are released and can be installed using a package manager.
-We provide officially released and maintained debian packages, which can easily be installed via aptitude.
-However, there might be cases in which not-yet released demos or features are only available through a source build in your own workspace.
-
-* Install dependencies:
-  ```
-  rosdep install --from-paths src --ignore-src -r -y
-  ```
-
-* Build everything, e.g. with:
-  ```
-  colcon build --symlink-install
-  ```
-
-* Do not forget to source `setup.bash` from the `install` folder!
diff --git a/doc/index.rst b/doc/index.rst
@@ -70,6 +70,160 @@ Example 8: "Using transmissions"
 Example 9: "Gazebo Classic"
    Demonstrates how to switch between simulation and hardware.
 
+
+.. _ros2_control_demos_install:
+
+=====================
+Installation
+=====================
+
+You can install the demos manually or use the provided docker file.
+
+Manual Install
+---------------
+
+First, you have to install `ROS 2 on your computer <https://docs.ros.org/en/humble/Installation.html>`__.
+
+.. note::
+
+  ``ros2_control`` and ``ros2_controllers`` packages are released and can be installed using a package manager.
+  We provide officially released and maintained debian packages, which can easily be installed via aptitude.
+  However, there might be cases in which not-yet released demos or features are only available through a source build in your own workspace.
+
+Build from debian packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Download the ``ros2_control_demos`` repository and install its dependencies with
+
+.. code-block:: shell
+
+  mkdir -p ~/ros2_ws/src
+  cd ~/ros2_ws/src
+  git clone https://github.com/ros-controls/ros2_control_demos
+  cd ~/ros2_ws/
+  rosdep update --rosdistro=$ROS_DISTRO
+  sudo apt-get update
+  sudo rosdep install --from-paths ./ -i -y --rosdistro ${ROS_DISTRO}
+
+Now you can build the repository (source your ROS 2 installation first)
+
+.. code-block:: shell
+
+  cd ~/ros2_ws/
+  . /opt/ros/${ROS_DISTRO}/setup.sh
+  colcon build --merge-install
+
+
+Build from source
+^^^^^^^^^^^^^^^^^
+
+* Download all repositories
+
+  .. code-block:: shell
+
+    mkdir -p ~/ros2_ws/src
+    cd ~/ros2_ws/src
+    git clone https://github.com/ros-controls/ros2_control_demos
+    cd ~/ros2_ws/
+    vcs import src < src/ros2_control_demos/ros2_control_demos.$ROS_DISTRO.repos
+    rosdep update --rosdistro=$ROS_DISTRO
+    sudo apt-get update
+
+* Install dependencies:
+
+  .. code-block:: shell
+
+    rosdep install --from-paths src --ignore-src -r -y
+
+* Build everything, e.g. with:
+
+  .. code-block:: shell
+
+    . /opt/ros/${ROS_DISTRO}/setup.sh
+    colcon build --symlink-install
+
+* Do not forget to source ``setup.bash`` from the ``install`` folder!
+
+Using Docker
+---------------
+
+First, build the dockerfile with
+
+.. code-block:: shell
+
+  mkdir -p ~/ros2_ws/src
+  cd ~/ros2_ws/src
+  git clone https://github.com/ros-controls/ros2_control_demos
+  cd ros2_control_demos
+  docker build . -t ros2_control_demos -f Dockerfile/Dockerfile
+
+To view the robot
+^^^^^^^^^^^^^^^^^
+
+Docker now allows us to run the demo without the GUI if configured properly. Now we can view the robot by the following procedure:
+
+After having `ROS 2 installed <https://docs.ros.org/en/humble/Installation.html>`__ on your local system (not inside the docker),  we can use ``rviz2`` to visualize the robot state and ``joint_state_publisher_gui`` package to give manual joint values to the robot. To install the package you can run:
+
+.. code-block:: shell
+
+  sudo apt-get install -y ros-${ROS_DISTRO}-joint-state-publisher-gui ros-${ROS_DISTRO}-rviz2
+
+Then we are ready to bring up all the components to view the robot. Let's start with the docker container by running the following command:
+
+.. code-block:: shell
+
+  docker run -it --rm --name ros2_control_demos --net host ros2_control_demos ros2 launch ros2_control_demos_example_1 view_robot.launch.py gui:=false
+
+.. note::
+
+  Depending on your machine settings, it might be possible that you have to omit ``--net host``.
+
+Now, we need to start ``rviz2`` to view the robot as well as ``joint_state_publisher_gui``, each in their own terminals after sourcing our ROS 2  installation.
+
+Terminal 1:
+
+.. code-block:: shell
+
+  source /opt/ros/${ROS_DISTRO}/setup.bash
+  ros2 run joint_state_publisher_gui joint_state_publisher_gui
+
+Terminal 2:
+
+.. code-block:: shell
+
+  source /opt/ros/${ROS_DISTRO}/setup.bash
+  cd ~/ros2_ws
+  rviz2 -d src/ros2_control_demos/example_1/description/rviz/rrbot.rviz
+
+Now, you can see the robot moving by changing the values of the joints by moving the sliders around in the ``joint_state_publisher_gui``.
+
+To run the ros2_control demos
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following command runs the demo without the GUI:
+
+.. code-block:: shell
+
+  docker run -it --rm --name ros2_control_demos --net host ros2_control_demos
+
+.. note::
+
+  Depending on your machine settings, it might be possible that you have to omit ``--net host``.
+
+Then on your local machine, you can run rviz2 with the config file specified:
+
+.. code-block:: shell
+
+  cd ~/ros2_ws
+  source /opt/ros/${ROS_DISTRO}/setup.sh
+  rviz2 -d src/ros2_control_demos/example_1/description/rviz/rrbot.rviz
+
+You can also run other commands or launch files from the docker, e.g.
+
+.. code-block:: shell
+
+  docker run -it --rm --name ros2_control_demos --net host ros2_control_demos ros2 launch ros2_control_demo_example_2 diffbot.launch.py
+
 =====================
 Quick Hints
 =====================

diff --git a/doc/run_from_docker.rst b/doc/run_from_docker.rst
@@ -0,0 +1,9 @@
+.. note::
+
+   The commands below are given for a local installation of this repository and its dependencies. If you use the provided docker container, add the prefix
+
+   .. code::
+
+      docker run -it --rm --name ros2_control_demos --net host ros2_control_demos
+
+   to every command followed by a ``gui:=false``. For more information on the docker usage see :ref:`ros2_control_demos_install`.
diff --git a/example_1/bringup/launch/rrbot.launch.py b/example_1/bringup/launch/rrbot.launch.py
@@ -28,14 +28,14 @@ def generate_launch_description():
     declared_arguments = []
     declared_arguments.append(
         DeclareLaunchArgument(
-            "start_rviz",
+            "gui",
             default_value="true",
             description="Start RViz2 automatically with this launch file.",
         )
     )
 
     # Initialize Arguments
-    start_rviz = LaunchConfiguration("start_rviz")
+    gui = LaunchConfiguration("gui")
 
     # Get URDF via xacro
     robot_description_content = Command(
@@ -82,7 +82,7 @@ def generate_launch_description():
         name="rviz2",
         output="log",
         arguments=["-d", rviz_config_file],
-        condition=IfCondition(start_rviz),
+        condition=IfCondition(gui),
     )
 
     joint_state_broadcaster_spawner = Node(

diff --git a/example_1/description/launch/view_robot.launch.py b/example_1/description/launch/view_robot.launch.py
@@ -14,6 +14,7 @@
 
 from launch import LaunchDescription
 from launch.actions import DeclareLaunchArgument
+from launch.conditions import IfCondition
 from launch.substitutions import Command, FindExecutable, LaunchConfiguration, PathJoinSubstitution
 
 from launch_ros.actions import Node
@@ -38,6 +39,14 @@ def generate_launch_description():
             description="URDF/XACRO description file with the robot.",
         )
     )
+    declared_arguments.append(
+        DeclareLaunchArgument(
+            "gui",
+            default_value="true",
+            description="Start Rviz2 and Joint State Publisher gui automatically \
+        with this launch file.",
+        )
+    )
     declared_arguments.append(
         DeclareLaunchArgument(
             "prefix",
@@ -51,6 +60,7 @@ def generate_launch_description():
     # Initialize Arguments
     description_package = LaunchConfiguration("description_package")
     description_file = LaunchConfiguration("description_file")
+    gui = LaunchConfiguration("gui")
     prefix = LaunchConfiguration("prefix")
 
     # Get URDF via xacro
@@ -75,6 +85,7 @@ def generate_launch_description():
     joint_state_publisher_node = Node(
         package="joint_state_publisher_gui",
         executable="joint_state_publisher_gui",
+        condition=IfCondition(gui),
     )
     robot_state_publisher_node = Node(
         package="robot_state_publisher",
@@ -88,6 +99,7 @@ def generate_launch_description():
         name="rviz2",
         output="log",
         arguments=["-d", rviz_config_file],
+        condition=IfCondition(gui),
     )
 
     nodes = [

diff --git a/example_1/doc/userdoc.rst b/example_1/doc/userdoc.rst
@@ -19,6 +19,8 @@ For *example_1*, the hardware interface plugin is implemented having only one in
 
 The *RRBot* URDF files can be found in the ``description/urdf`` folder.
 
+.. include:: ../../doc/run_from_docker.rst
+
 Tutorial steps
 --------------------------
 

diff --git a/example_2/bringup/launch/diffbot.launch.py b/example_2/bringup/launch/diffbot.launch.py
@@ -27,14 +27,14 @@ def generate_launch_description():
     declared_arguments = []
     declared_arguments.append(
         DeclareLaunchArgument(
-            "start_rviz",
+            "gui",
             default_value="true",
             description="Start RViz2 automatically with this launch file.",
         )
     )
 
     # Initialize Arguments
-    start_rviz = LaunchConfiguration("start_rviz")
+    gui = LaunchConfiguration("gui")
 
     # Get URDF via xacro
     robot_description_content = Command(
@@ -80,7 +80,7 @@ def generate_launch_description():
         name="rviz2",
         output="log",
         arguments=["-d", rviz_config_file],
-        condition=IfCondition(start_rviz),
+        condition=IfCondition(gui),
     )
 
     joint_state_broadcaster_spawner = Node(

diff --git a/example_2/description/launch/view_robot.launch.py b/example_2/description/launch/view_robot.launch.py
@@ -14,6 +14,7 @@
 
 from launch import LaunchDescription
 from launch.actions import DeclareLaunchArgument
+from launch.conditions import IfCondition
 from launch.substitutions import Command, FindExecutable, LaunchConfiguration, PathJoinSubstitution
 
 from launch_ros.actions import Node
@@ -38,6 +39,14 @@ def generate_launch_description():
             description="URDF/XACRO description file with the robot.",
         )
     )
+    declared_arguments.append(
+        DeclareLaunchArgument(
+            "gui",
+            default_value="true",
+            description="Start Rviz2 and Joint State Publisher gui automatically \
+        with this launch file.",
+        )
+    )
     declared_arguments.append(
         DeclareLaunchArgument(
             "prefix",
@@ -51,6 +60,7 @@ def generate_launch_description():
     # Initialize Arguments
     description_package = LaunchConfiguration("description_package")
     description_file = LaunchConfiguration("description_file")
+    gui = LaunchConfiguration("gui")
     prefix = LaunchConfiguration("prefix")
 
     # Get URDF via xacro
@@ -75,6 +85,7 @@ def generate_launch_description():
     joint_state_publisher_node = Node(
         package="joint_state_publisher_gui",
         executable="joint_state_publisher_gui",
+        condition=IfCondition(gui),
     )
     robot_state_publisher_node = Node(
         package="robot_state_publisher",
@@ -88,6 +99,7 @@ def generate_launch_description():
         name="rviz2",
         output="log",
         arguments=["-d", rviz_config_file],
+        condition=IfCondition(gui),
     )
 
     nodes = [

diff --git a/example_2/doc/userdoc.rst b/example_2/doc/userdoc.rst
@@ -16,6 +16,8 @@ For *example_2*, the hardware interface plugin is implemented having only one in
 
 The *DiffBot* URDF files can be found in ``description/urdf`` folder.
 
+.. include:: ../../doc/run_from_docker.rst
+
 Tutorial steps
 --------------------------