Move installation instructions to RST and update docker usage instruc…

…tions (#309)

Co-authored-by: Reza Kermani <kermani.areza@gmail.com>

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!

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/rolling/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/rolling/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
 =====================

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`.

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(

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 = [

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
 --------------------------
 

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(

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 = [

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
 --------------------------