Merge pull request #287 from UHHRobotics22-23/doc/description

Doc/description

marimbabot_description/README.md

@@ -1,30 +1,74 @@
-## Marimbabot Simulation package
+# Marimbabot Description package
 
+The description package contains all the models used in the control of the physical robot and the simulation.
 
-### URDF/Xacro Model
+## URDF/Xacro Model
 
-The URDF model is generated using `xacro`, with the template `urdf/marimba.urdf.xacro`. See `marimba_display.launch` to see how it's run for RViz.
+The URDF models are generated using `xacro`, for example with the template `urdf/marimba.urdf.xacro` for the marimba.
+See `marimba_display.launch` to see how it's run for RViz.
+The main files are found in the [urdf](urdf/) folder.
+Associated meshes are stored in the [mesh](mesh/) folder using the stl format (normally binary flavour).
 
+<!-- TODO What is with the gazebo_gripper_transmissions.xacro file? -->
+### Main Xacro Files
 
-### RViz
+The central xacro file is [marimbabot_ur5.urdf.xacro](urdf/marimbabot_ur5.urdf.xacro).
+The robot, marimba and mallet holder models are all loaded from this file.
 
-To see the model in RViz, [prepare your environment for the project](../README.md#setup) and run:
+Further configurations for the joints and ur5 controllers are imported from the [config](config/) folder.
 
+When running the marimbabot ur5 launch file, a parameter for the mallet mount can be specified. By default this remains the fixed mount for now  
+- fixed - the standard one mallet fixed mount
+- flex - the one mallet flexible mount
+- flex_double - the two mallet flexible mount with the integrated servo
 ```bash
-roslaunch marimbabot_description marimba_display.launch
+roslaunch marimbabot_description marimbobot_ur5_display.launch mallet_holder_type:="flex_double"
 ```
 
-![Marimba](extra/marimba_sim.png)
+#### Marimba
 
+The marimba is modeled by the [marimba.urdf.xacro](urdf/marimba.urdf.xacro) file.
+Each bar is modelled on its own to allow for automatic targeting based on the tone and midi output generation in the simulation.
 
-### double_flex_mallet
- This model has a flexibility in two sides. It serves to make the sound on the marimba louder and at the same time ensure that the mallet does not break.
+<!-- Please expand if there is more to say here -->
+
+#### Mallet Holder
+Multiple versions of the mallet holder were used in the development phase of the project.
+
+The final version is the [two_mallet_compliance_holder.urdf.xacro](urdf/two_mallet_compliance_holder.urdf.xacro). It contains two mallets on flexible holders with one being controlled by a servo.
+It is selected with the "flex_double" option.
+
+For one mallet implementations a static, single mallet was used.
+The model [static_mallet_holder.urdf](urdf/static_mallet_holder.urdf) is selected with the "fixed" option
+
+The [flex_mallet_holder.urdf](urdf/flex_mallet_holder.urdf) was rarely used in the development phase.
+It is a single mallet on a flexible mount. The "flex" option selects this version.
+
+### Secondary
+The marimba model used to helper files in its xacro definition.
+The [materials.xacro](urdf/materials.xacro) defines the used materials in the model.
+[utilities.xacro](urdf/utilities.xacro) contains various helper functions to create urdf objects and shapes with many defaults applied.
+
+## Launch files
+The launch file can be found in the [launch](launch/) folder and are used in the launch files of the [bringup package](../marimbabot_bringup/) or for rviz based debugging or inspection.
+### Main
+
+The main launch file for the description package is [marimbabot_ur5_upload.launch](launch/marimbabot_ur5_upload.launch)
+### RViz (Testing)
+
+The testing is setup for mostly inspecting models in rviz. The testing environments can be loaded with the launch files in the [launch](launch/) folder.
+
+Further rviz config files used in some of the testing launch files are found in the [config](config/) folder.
+
+To see the a model in RViz, [prepare your environment for the project](../README.md#setup) and run:
 
-### Exchangable mallet mount
-when running the marimbabot ur5 launch file, a parameter for the mallet mount can be specified. By default this remains the fixed mount for now  
-- fixed - the standard one mallet fixed mount
-- flex - the one mallet flexible mount
-- flex_double - the two mallet flexible mount with the integrated servo
 ```bash
-roslaunch marimbabot_description marimbobot_ur5_display.launch mallet_holder_type:="flex_double"
-```
+roslaunch marimbabot_description marimba_display.launch
+```
+The marimba model will be displayed. Other files can be used in a similar fasion.
+
+![Marimba](extra/marimba_sim.png)
+
+One further RViz launch file is the [marimbabot_ur5_display.launch](launch/ marimbabot_ur5_display.launch) which shows whole setup of the scene.
+
+The [flex_mallet_holder.launch](launch/flex_mallet_holder.launch) and [two_mallet_display.launch](launch/two_mallet_display.launch) are used to develop and debug the mallet holder models.

marimbabot_description/launch/two_mallet_display.launch

@@ -1,6 +1,6 @@
 <launch>
     <arg name="gui" default="true" />
-    <arg name="rvizconfig" default="$(find marimbabot_description)/rviz/urdf_inspection.rviz" />
+    <arg name="rvizconfig" default="$(find marimbabot_description)/config/urdf_inspection.rviz" />
 
     <param name="robot_description" command="xacro '$(find marimbabot_description)/urdf/two_mallet_compliance_holder.urdf.xacro'" />
 

marimbabot_description/urdf/flex_mallet_holder.urdf

@@ -1,7 +1,13 @@
 <?xml version="1.0"?>
+
+<!-- URDF definition for the flexible mallet holder -->
+
 <robot name="double_flex_mallet">
 
-      <link name="mallet_head">
+    <!-- Link definitions -->
+
+    <!-- Mallet Top Part --> 
+    <link name="mallet_head">
         <collision>
             <origin xyz="0.0 0.0 0" rpy="0.0 0.0 0.0"/>
             <!-- 0.018375 -->
@@ -11,6 +17,7 @@
         </collision>
     </link>
 
+    <!-- Rod Part of the Mallet -->
     <link name="mallet_neck">
         <collision>
             <origin xyz="0.0 0.0 0.2095" rpy="0.0 0.0 0.0"/>
@@ -20,6 +27,7 @@
         </collision>
     </link>
 
+    <!-- Connector Plate for the connector system of the two mallet holder -->
     <link name="mallet_connector_plate">
         <collision> 
            <origin xyz="0.0 0.0 0.0" rpy="0.0 0.0 0.0"/>
@@ -29,6 +37,8 @@
        </collision>
     </link>
 
+    <!-- Base Link of the Mallet Assembly -->
+    <!-- Shows the model -->
     <link name="mallet_base_link">
         <visual>
             <origin xyz="0.0 0.0 0.057" rpy="0.0 -1.570796326 0.0"/>
@@ -48,6 +58,8 @@
         </collision>
     </link>
 
+    <!-- Joint Definitions -->
+    <!-- All Fixed Joints and only offsets -->
     <joint name="group_1_start_link" type="fixed">
         <parent link="mallet_base_link"/>
         <child link="mallet_neck"/>

marimbabot_description/urdf/static_mallet_holder.urdf

@@ -1,6 +1,9 @@
 <?xml version="1.0"?>
+<!-- Xacro definition of the static mallet holder with one mallet -->
 <robot name="static_mallet_holder">
 
+    <!-- Link definitions -->
+    <!-- Mallet Top Part -->
     <link name="mallet_head">
         <inertial>
             <origin xyz="0 0 0" rpy="0 0 0"/>
@@ -25,6 +28,7 @@
         </collision>
     </link>
 
+    <!-- Rod Part of the Mallet -->
     <link name="mallet_neck">
         <inertial>
             <origin xyz="0 0 0" rpy="0 0 0"/>
@@ -47,7 +51,8 @@
             </geometry>
         </collision>
     </link>
-
+
+    <!-- Base Link of the Mallet Assembly -->
     <link name="mallet_base_link">
         <inertial>
             <origin xyz="0 0 0" rpy="0 0 0"/>
@@ -71,6 +76,9 @@
         </collision>
     </link>
 
+    <!-- Joint definitions -->
+    <!-- All joints are fixed and only offsets -->
+
     <joint name="group_1_start_link" type="fixed">
         <parent link="mallet_base_link"/>
         <child link="mallet_neck"/>