[Example 2] Moving and Restructuring (#233)

Co-authored-by: Dr. Denis <[email protected]>

Author: christophfroehlich

README.md

@@ -69,7 +69,8 @@ Check README file inside each example folder for detailed description.
 
 ##### Example 2
 
-....
+*DiffBot*, or ''Differential Mobile Robot'', is a simple mobile base with differential drive.
+The robot is basically a box moving according to differential drive kinematics.
 
 
 ## Quick Hints
@@ -144,89 +145,6 @@ This repository provides the following simple example robots: a 2 degrees of fre
 The first two examples demonstrate the minimal setup for those two robots to run.
 Later examples show more details about `ros2_control`-concepts and some more advanced use-cases.
 
-
-## *DiffBot*
-
-*DiffBot*, or ''Differential Mobile Robot'', is a simple mobile base with differential drive.
-The robot is basically a box moving according to differential drive kinematics.
-The *DiffBot* URDF files can be found in `urdf` folder of `diffbot_description` package.
-
-1. To check that *DiffBot* description is working properly use following launch commands:
-   ```
-   ros2 launch diffbot_description view_robot.launch.py
-   ```
-   **NOTE**: Getting the following output in terminal is OK: `Warning: Invalid frame ID "odom" passed to canTransform argument target_frame - frame does not exist`.
-             This happens because `joint_state_publisher_gui` node need some time to start.
-
-1. To start *DiffBot* example open a terminal, source your ROS2-workspace and execute its launch file with:
-   ```
-   ros2 launch ros2_control_demo_bringup diffbot.launch.py
-   ```
-   The launch file loads and starts the robot hardware, controllers and opens `RViz`.
-   In the starting terminal you will see a lot of output from the hardware implementation showing its internal states.
-   This excessive printing is only added for demonstration. In general, printing to the terminal should be avoided as much as possible in a hardware interface implementation.
-
-   If you can see an orange box in `RViz` everything has started properly.
-   Still, to be sure, let's introspect the control system before moving *DiffBot*.
-
-1. Check if the hardware interface loaded properly, by opening another terminal and executing:
-   ```
-   ros2 control list_hardware_interfaces
-   ```
-   You should get:
-   ```
-   command interfaces
-        left_wheel_joint/velocity [claimed]
-        right_wheel_joint/velocity [claimed]
-   state interfaces
-         left_wheel_joint/position
-         left_wheel_joint/velocity
-         right_wheel_joint/position
-         right_wheel_joint/velocity
-   ```
-   The `[claimed]` marker on command interfaces means that a controller has access to command *DiffBot*.
-
-1. Check if controllers are running:
-   ```
-   ros2 control list_controllers
-   ```
-   You should get:
-   ```
-   diffbot_base_controller[diff_drive_controller/DiffDriveController] active
-   joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active
-   ```
-
-1. If everything is fine, now you can send a command to *Diff Drive Controller* using ros2 cli interface:
-   ```
-   ros2 topic pub --rate 30 /diffbot_base_controller/cmd_vel_unstamped geometry_msgs/msg/Twist "linear:
-    x: 0.7
-    y: 0.0
-    z: 0.0
-   angular:
-    x: 0.0
-    y: 0.0
-    z: 1.0"
-    ```
-   You should now see an orange box circling in `RViz`.
-   Also, you should see changing states in the terminal where launch file is started.
-
-
-Files used for this demos:
-  - Launch file: [diffbot.launch.py](ros2_control_demo_bringup/launch/diffbot.launch.py)
-  - Controllers yaml: [diffbot_controllers.yaml](ros2_control_demo_bringup/config/diffbot_controllers.yaml)
-  - URDF file: [diffbot.urdf.xacro](ros2_control_demo_description/diffbot_description/urdf/diffbot.urdf.xacro)
-    - Description: [diffbot_description.urdf.xacro](ros2_control_demo_description/diffbot_description/urdf/diffbot_description.urdf.xacro)
-    - `ros2_control` tag: [diffbot.ros2_control.xacro](ros2_control_demo_description/diffbot_description/ros2_control/diffbot.ros2_control.xacro)
-  - RViz configuration: [diffbot.rviz](ros2_control_demo_description/diffbot_description/config/diffbot.rviz)
-
-  - Hardware interface plugin: [diffbot_system.cpp](ros2_control_demo_hardware/src/diffbot_system.cpp)
-
-
-Controllers from this demo:
-  - `Joint State Broadcaster` ([`ros2_controllers` repository](https://github.com/ros-controls/ros2_controllers)): [doc](https://ros-controls.github.io/control.ros.org/ros2_controllers/joint_state_broadcaster/doc/userdoc.html)
-  - `Diff Drive Controller` ([`ros2_controllers` repository](https://github.com/ros-controls/ros2_controllers)): [doc](https://ros-controls.github.io/control.ros.org/ros2_controllers/diff_drive_controller/doc/userdoc.html)
-
-
 # Examples of ros2_control concepts
 
 Each of the described example cases from the [roadmap](https://github.com/ros-controls/roadmap/blob/master/design_drafts/components_architecture_and_urdf_examples.md) has its own launch and URDF file.

example_2/CMakeLists.txt

@@ -0,0 +1,83 @@
+cmake_minimum_required(VERSION 3.5)
+project(ros2_control_demo_example_2)
+
+# Default to C++14
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 14)
+endif()
+
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra)
+endif()
+
+# find dependencies
+set(THIS_PACKAGE_INCLUDE_DEPENDS
+  hardware_interface
+  pluginlib
+  rclcpp
+  rclcpp_lifecycle
+)
+
+# find dependencies
+find_package(ament_cmake REQUIRED)
+foreach(Dependency IN ITEMS ${THIS_PACKAGE_INCLUDE_DEPENDS})
+  find_package(${Dependency} REQUIRED)
+endforeach()
+
+
+## COMPILE
+add_library(
+  ${PROJECT_NAME}
+  SHARED
+  hardware/diffbot_system.cpp
+)
+target_include_directories(
+  ${PROJECT_NAME}
+  PRIVATE
+  hardware/include
+)
+ament_target_dependencies(
+  ${PROJECT_NAME}
+  ${THIS_PACKAGE_INCLUDE_DEPENDS}
+)
+
+# Causes the visibility macros to use dllexport rather than dllimport,
+# which is appropriate when building the dll but not consuming it.
+target_compile_definitions(${PROJECT_NAME} PRIVATE "ROS2_CONTROL_DEMO_EXAMPLE_2_BUILDING_DLL")
+
+# Export hardware plugins
+pluginlib_export_plugin_description_file(hardware_interface ros2_control_demo_example_2.xml)
+
+# INSTALL
+install(
+  TARGETS ${PROJECT_NAME}
+  DESTINATION lib
+)
+install(
+  DIRECTORY hardware/include/
+  DESTINATION include
+)
+install(
+  DIRECTORY description/launch description/ros2_control description/urdf description/rviz
+  DESTINATION share/${PROJECT_NAME}
+)
+install(
+  DIRECTORY bringup/launch bringup/config
+  DESTINATION share/${PROJECT_NAME}
+)
+
+if(BUILD_TESTING)
+  find_package(ament_cmake_gtest REQUIRED)
+endif()
+
+## EXPORTS
+ament_export_include_directories(
+  include
+)
+ament_export_libraries(
+  ${PROJECT_NAME}
+)
+ament_export_dependencies(
+  ${THIS_PACKAGE_INCLUDE_DEPENDS}
+)
+ament_package()

example_2/README.rst

@@ -0,0 +1,110 @@
+*********
+DiffBot
+*********
+
+*DiffBot*, or ''Differential Mobile Robot'', is a simple mobile base with differential drive.
+The robot is basically a box moving according to differential drive kinematics.
+The *DiffBot* URDF files can be found in ``description/urdf`` folder.
+
+1. To check that *DiffBot* description is working properly use following launch commands
+
+   .. code-block:: shell
+
+    ros2 launch ros2_control_demo_example_2 view_robot.launch.py
+
+   .. warning::
+    Getting the following output in terminal is OK: ``Warning: Invalid frame ID "odom" passed to canTransform argument target_frame - frame does not exist``.
+    This happens because ``joint_state_publisher_gui`` node need some time to start.
+
+   .. image:: doc/diffbot.png
+    :width: 400
+    :alt: Differential Mobile Robot
+
+2. To start *DiffBot* example open a terminal, source your ROS2-workspace and execute its launch file with
+
+   .. code-block:: shell
+
+    ros2 launch ros2_control_demo_example_2 diffbot.launch.py
+
+   The launch file loads and starts the robot hardware, controllers and opens *RViz*.
+   In the starting terminal you will see a lot of output from the hardware implementation showing its internal states.
+   This excessive printing is only added for demonstration. In general, printing to the terminal should be avoided as much as possible in a hardware interface implementation.
+
+   If you can see an orange box in *RViz* everything has started properly.
+   Still, to be sure, let's introspect the control system before moving *DiffBot*.
+
+3. Check if the hardware interface loaded properly, by opening another terminal and executing
+
+   .. code-block:: shell
+
+    ros2 control list_hardware_interfaces
+
+   You should get
+
+   .. code-block:: shell
+
+    command interfaces
+          left_wheel_joint/velocity [claimed]
+          right_wheel_joint/velocity [claimed]
+    state interfaces
+          left_wheel_joint/position
+          left_wheel_joint/velocity
+          right_wheel_joint/position
+          right_wheel_joint/velocity
+
+   The ``[claimed]`` marker on command interfaces means that a controller has access to command *DiffBot*.
+
+4. Check if controllers are running
+
+   .. code-block:: shell
+
+    ros2 control list_controllers
+
+   You should get
+
+   .. code-block:: shell
+
+    diffbot_base_controller[diff_drive_controller/DiffDriveController] active
+    joint_state_broadcaster[joint_state_broadcaster/JointStateBroadcaster] active
+
+5. If everything is fine, now you can send a command to *Diff Drive Controller* using ros2 cli interface:
+
+   .. code-block:: shell
+
+    ros2 topic pub --rate 30 /diffbot_base_controller/cmd_vel_unstamped geometry_msgs/msg/Twist "linear:
+      x: 0.7
+      y: 0.0
+      z: 0.0
+    angular:
+      x: 0.0
+      y: 0.0
+      z: 1.0"
+
+   You should now see an orange box circling in *RViz*.
+   Also, you should see changing states in the terminal where launch file is started.
+
+   .. code-block:: shell
+
+    [DiffBotSystemHardware]: Got command 43.33333 for 'left_wheel_joint'!
+    [DiffBotSystemHardware]: Got command 50.00000 for 'right_wheel_joint'!
+
+Files used for this demos
+#########################
+
+  - Launch file: `diffbot.launch.py <bringup/launch/diffbot.launch.py>`__
+  - Controllers yaml: `diffbot_controllers.yaml <bringup/config/diffbot_controllers.yaml>`__
+  - URDF file: `diffbot.urdf.xacro <description/urdf/diffbot.urdf.xacro>`__
+
+    + Description: `diffbot_description.urdf.xacro <description/urdf/diffbot_description.urdf.xacro>`__
+    + ``ros2_control`` tag: `diffbot.ros2_control.xacro <description/ros2_control/diffbot.ros2_control.xacro>`__
+
+  - RViz configuration: `diffbot.rviz <description/rviz/diffbot.rviz>`__
+
+  - Hardware interface plugin: `diffbot_system.cpp <hardware/diffbot_system.cpp>`__
+
+
+Controllers from this demo
+##########################
+
+  - ``Joint State Broadcaster`` (`*ros2_controllers* repository <https://github.com/ros-controls/ros2_controllers>`__): `doc <https://control.ros.org/master/doc/ros2_controllers/joint_state_broadcaster/doc/userdoc.html>`__
+  - ``Diff Drive Controller`` (`*ros2_controllers* repository <https://github.com/ros-controls/ros2_controllers>`__): `doc <https://control.ros.org/master/doc/ros2_controllers/diff_drive_controller/doc/userdoc.html>`__

ros2_control_demo_bringup/config/diffbot_controllers.yaml renamed to example_2/bringup/config/diffbot_controllers.yaml

@@ -28,21 +28,21 @@ def generate_launch_description():
             PathJoinSubstitution([FindExecutable(name="xacro")]),
             " ",
             PathJoinSubstitution(
-                [FindPackageShare("diffbot_description"), "urdf", "diffbot.urdf.xacro"]
+                [FindPackageShare("ros2_control_demo_example_2"), "urdf", "diffbot.urdf.xacro"]
             ),
         ]
     )
     robot_description = {"robot_description": robot_description_content}
 
     robot_controllers = PathJoinSubstitution(
         [
-            FindPackageShare("ros2_control_demo_bringup"),
+            FindPackageShare("ros2_control_demo_example_2"),
             "config",
             "diffbot_controllers.yaml",
         ]
     )
     rviz_config_file = PathJoinSubstitution(
-        [FindPackageShare("diffbot_description"), "config", "diffbot.rviz"]
+        [FindPackageShare("ros2_control_demo_example_2"), "rviz", "diffbot.rviz"]
     )
 
     control_node = Node(

ros2_control_demo_bringup/launch/diffbot.launch.py renamed to example_2/bringup/launch/diffbot.launch.py

@@ -26,7 +26,7 @@ def generate_launch_description():
     declared_arguments.append(
         DeclareLaunchArgument(
             "description_package",
-            default_value="diffbot_description",
+            default_value="ros2_control_demo_example_2",
             description="Description package with robot URDF/xacro files. Usually the argument \
         is not set, it enables use of a custom description.",
         )
@@ -69,7 +69,7 @@ def generate_launch_description():
     robot_description = {"robot_description": robot_description_content}
 
     rviz_config_file = PathJoinSubstitution(
-        [FindPackageShare(description_package), "config", "diffbot_view.rviz"]
+        [FindPackageShare(description_package), "rviz", "diffbot_view.rviz"]
     )
 
     joint_state_publisher_node = Node(

ros2_control_demo_description/diffbot_description/launch/view_robot.launch.py renamed to example_2/description/launch/view_robot.launch.py

@@ -5,7 +5,7 @@
 
     <ros2_control name="${name}" type="system">
       <hardware>
-        <plugin>ros2_control_demo_hardware/DiffBotSystemHardware</plugin>
+        <plugin>ros2_control_demo_example_2/DiffBotSystemHardware</plugin>
         <param name="example_param_hw_start_duration_sec">0</param>
         <param name="example_param_hw_stop_duration_sec">3.0</param>
       </hardware>