From c0282b66d8e9657854916fb18326d506e2e459a1 Mon Sep 17 00:00:00 2001
From: Felix Durchdewald <durchdewald@fzi.de>
Date: Thu, 18 Jan 2024 14:04:43 +0100
Subject: [PATCH] adapted documentation to new package

---
 .vscode/c_cpp_properties.json                 | 20 ++++++++++
 .vscode/settings.json                         | 10 +++++
 .../examples/my_robot_cell/assemble_urdf.rst  | 36 +++++++++++++-----
 .../my_robot_cell/build_moveit_config.rst     | 20 +++++++++-
 .../my_robot_cell/start_ur_driver.rst         | 37 +++++++++++++++++++
 5 files changed, 111 insertions(+), 12 deletions(-)
 create mode 100644 .vscode/c_cpp_properties.json
 create mode 100644 .vscode/settings.json

diff --git a/.vscode/c_cpp_properties.json b/.vscode/c_cpp_properties.json
new file mode 100644
index 0000000..920fd51
--- /dev/null
+++ b/.vscode/c_cpp_properties.json
@@ -0,0 +1,20 @@
+{
+  "configurations": [
+    {
+      "browse": {
+        "databaseFilename": "${default}",
+        "limitSymbolsToIncludedHeaders": false
+      },
+      "includePath": [
+        "/opt/ros/foxy/include/**",
+        "/usr/include/**"
+      ],
+      "name": "ROS",
+      "intelliSenseMode": "gcc-x64",
+      "compilerPath": "/usr/bin/gcc",
+      "cStandard": "gnu11",
+      "cppStandard": "c++14"
+    }
+  ],
+  "version": 4
+}
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..e28b16c
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,10 @@
+{
+    "python.autoComplete.extraPaths": [
+        "/opt/ros/foxy/lib/python3.8/site-packages",
+        ""
+    ],
+    "python.analysis.extraPaths": [
+        "/opt/ros/foxy/lib/python3.8/site-packages",
+        ""
+    ]
+}
\ No newline at end of file
diff --git a/ur_documentation/docs/source/examples/my_robot_cell/assemble_urdf.rst b/ur_documentation/docs/source/examples/my_robot_cell/assemble_urdf.rst
index b83995f..a11f22f 100644
--- a/ur_documentation/docs/source/examples/my_robot_cell/assemble_urdf.rst
+++ b/ur_documentation/docs/source/examples/my_robot_cell/assemble_urdf.rst
@@ -21,34 +21,50 @@ First, we'll have to **include** the macro to generate the robot arm:
     :linenos:
     :caption: my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
 
-This line only loaded the macro for generating the robot.
+The second **include** contains our costum workspace:
+
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
+    :language: xml
+    :start-at:     <xacro:include filename="$(find my_robot_cell_description)/urdf/my_robot_cell_macro.xacro"/>
+    :end-at:     <xacro:include filename="$(find my_robot_cell_description)/urdf/my_robot_cell_macro.xacro"/>
+    :linenos:
+    :caption: my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
+
+Those lines only loadeded the macros for generating the robot and the workcell.
 
 Later, we will call the macro to create the arm. Therefore, we need to declare certain arguments that must be passed to the macro.
 
 .. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
     :language: xml
     :start-at:   <xacro:arg name="ur_type" default="ur20"/>
-    :end-at:   <xacro:arg name="ur_input_recipe_filename" default="$(find ur_robot_driver)/resources/rtde_output_recipe.txt"/>
+    :end-at:     <xacro:arg name="visual_params" default="$(find ur_description)/config/$(arg ur_type)/visual_parameters.yaml"/>
     :linenos:
     :caption: my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
     
-The following section contains all items within the workcell that are not part of the robot arm. If you are not experienced in writing URDFs, you may want to refer to this  `tutorial <https://docs.ros.org/en/rolling/Tutorials/Intermediate/URDF/URDF-Main.html>`_.
+The macro we are calling now contains all items within the workcell that are not part of the robot arm. If you are not experienced in writing URDFs, you may want to refer to this  `tutorial <https://docs.ros.org/en/rolling/Tutorials/Intermediate/URDF/URDF-Main.html>`_.
 
 .. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
     :language: xml
-    :start-at:   <link name="world"/>
-    :end-before:   <link name="robot_mount"/>
-    :linenos: 
+    :start-at:     <xacro:my_robot_cell/>
+    :end-at:       <xacro:my_robot_cell/>
+    :linenos:
     :caption: my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
 
-This section of the URDF provides an example of what a custom workcell could resemble. Your workspace will likely vary from this one. Please feel free to modify this portion of the URDF to match your own setup. In this instance, our workspace comprises a table in front of a wall, featuring a monitor, and the **ur20** robot arm mounted on top.
+The loaded macro is defined in the following manner:
+
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_description/urdf/my_robot_cell_macro.xacro
+    :language: xml
+    :linenos: 
+    :caption: my_robot_cell_description/urdf/my_robot_cell_macro.urdf.xacro
+
+This macro provides an example of what a custom workcell could resemble. Your workspace will likely vary from this one. Please feel free to modify this portion of the URDF to match your own setup. In this instance, our workspace comprises a table in front of a wall, featuring a monitor, and the **ur20** robot arm mounted on top.
 
-The final step before generating the robot is to create its parent link.
+Ensure that your custom workcell includes the parent link, which must be passed to the **ur_robot** macro. In this example, we chose to create a link named **robot_mount**.
 
-.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_description/urdf/my_robot_cell_macro.xacro
     :language: xml
     :start-at: <link name="robot_mount"/>
-    :end-before:   <xacro:ur_robot
+    :end-before:   </xacro:macro>
     :linenos: 
     :caption: my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
 
diff --git a/ur_documentation/docs/source/examples/my_robot_cell/build_moveit_config.rst b/ur_documentation/docs/source/examples/my_robot_cell/build_moveit_config.rst
index 6f9bc6b..f4f454a 100644
--- a/ur_documentation/docs/source/examples/my_robot_cell/build_moveit_config.rst
+++ b/ur_documentation/docs/source/examples/my_robot_cell/build_moveit_config.rst
@@ -18,7 +18,7 @@ Please note that MoveIt itself provides a detailed `tutorial <https://moveit.pic
 Although the Setup Assistant is very straightforward, there are some tips and tricks we want to discuss in the following sections.
 
 The first task the MoveIt Setup Assistant asks us to do is to load the URDF with the optional xacro arguments. Most of the arguments we declared already have the correct default values and can be ignored at this stage. 
-However, two arguments you might want to change from their default values are **ur_type** and **robot_ip**. So, **Step 1** might look something like this:
+However, one argument you might want to change from their default values is **ur_type**. So, **Step 1** might look something like this:
 
 .. image:: arguments.png
     :alt: Load a URDF
@@ -34,7 +34,6 @@ We can add the end effector planning group in the same way the tutorial recommen
 .. image:: planning_groups.png
     :alt: Planning Groups
 
-
 Since we've already determined which ROS 2 controllers we want to use to start the ``ur_robot_driver``, we don't need the Setup Assistant to generate a ros2_control.yaml file. Therefore, we can skip **Step 9: ROS 2 Controllers** and **Step 10: MoveIt Controllers** for now. 
 
 In **Step 12**, the Setup Assistant asks us to select which launch files we need. To maintain clarity, we should only generate those that are essential for our purpose.
@@ -50,6 +49,17 @@ The file specifies which controller MoveIt uses for its trajectory planning and
 
 In our example MoveIt uses the scaled_joint_trajectory_controller.
 
+Now you are ready to use moveit with an actual **ur20**, moveit itself also provides you with the oportunity to start a robot with mock hardware. To do that our **moveit config** needs some adjustments.
+First you need to create a few more launch Files in **Step 12**. To start mock hardware we also need the **Robot State Publisher Launch**, the **Spwan Controllers Launch** and the **Demo Launch**.
+
+When using real hardware, the ``ur_robot_driver`` spawns the ros2 controllers for us. However, if we want MoveIt to initiate a mock hardware setup, MoveIt needs to launch the ROS 2 controllers instead.
+Consequently, we must generate a "ros2_controllers.yaml" file for this purpose. Such a **ros2_controllers.yaml** could look something like this:
+
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_moveit_config/config/ros2_controllers.yaml
+    :language: yaml
+    :linenos:
+    :caption: my_robot_cell_moveit_config/config/ros2_controllers.yaml
+
 Before we can test our code, it's essential to build and source our Colcon workspace:
 
 .. code-block:: bash
@@ -76,3 +86,9 @@ You can simply try it out by launching the RViz node and planning some trajector
 
     ros2 launch my_robot_cell_moveit_config moveit_rviz.launch.py
 
+To start moveit with mock hardware you can simply use:
+
+.. code-block:: bash
+
+    ros2 launch my_robot_cell_moveit_config demo.launch.py
+
diff --git a/ur_documentation/docs/source/examples/my_robot_cell/start_ur_driver.rst b/ur_documentation/docs/source/examples/my_robot_cell/start_ur_driver.rst
index 573f7df..5571b07 100644
--- a/ur_documentation/docs/source/examples/my_robot_cell/start_ur_driver.rst
+++ b/ur_documentation/docs/source/examples/my_robot_cell/start_ur_driver.rst
@@ -2,6 +2,43 @@
 Start the ur_robot_driver
 =========================
 
+Before starting the ``ur_robot_driver``, it is necessary to add a **ros2_control** tag to our URDF. Luckily, the ``ur_robot_driver`` already provides us with a macro for that. We can simply include the macro in our assembled URDF.
+
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+    :language: py
+    :linenos:
+    :caption: my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+
+This URDF is very similar to the one we have already assembled. We simply need to include the ros2_control macro, 
+
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+    :language: py
+    :start-at:   <xacro:include filename="$(find ur_robot_driver)/urdf/ur.ros2_control.xacro"/>
+    :end-at:   <xacro:include filename="$(find ur_robot_driver)/urdf/ur.ros2_control.xacro"/>
+    :linenos: 
+    :caption: my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+
+
+define the necessary arguments that need to be passed to the macro,
+
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+    :language: py
+    :start-at:     <xacro:arg name="robot_ip" default="0.0.0.0"/>
+    :end-at:   <xacro:my_robot_cell/>
+    :linenos: 
+    :caption: my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+
+
+and then call the macro by providing all the specified arguments.
+
+.. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+    :language: py
+    :start-at:    <xacro:ur_ros2_control
+    :end-at:   </robot>
+    :linenos: 
+    :caption: my_robot_cell_control/urdf/my_robot_cell_control.urdf.xacro
+
+
 Now that everything is in place, we can proceed to start up a driver instance. To initialize the ``ur_robot_driver`` using our customized workcell description, we need to create a launch file.
 
 .. literalinclude:: ../../../../../my_robot_cell/my_robot_cell_control/launch/start_robot.launch.py