Add documentation about the different base and base_link frames (#286)

There are three different frames in the robot's base. They all represent different aspects and have their respective right to be there, but that lead to a lot of confusion on the users' side. This documentation should hopefully help reducing that confusion.

---------

Co-authored-by: G.A. vd. Hoorn <[email protected]>
Co-authored-by: Mads Holm Peters <[email protected]>

Author: 3 people

doc/frames/base.png

@@ -8,6 +8,16 @@ ur_description
 This package contains the kinematic and visual description of Universal Robots manipulators for ROS
 2.
 
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+   robot_frames
+
+.. contents::
+   :depth: 2
+   :local:
+
 Structure of the repository
 ---------------------------
 

doc/frames/base_link.png

@@ -0,0 +1,65 @@
+Robot Frames
+============
+
+The URDF model uses multiple frames in the robot's base. This page describes why that is and what
+the purpose of each of those frames is. In particular, there are three frames in the robot's base:
+
+- ``base_link`` - This serves as the root link of the kinematic chain. It follows `REP-103
+  <https://ros.org/reps/rep-0103.html>`_ , where *forward* for the ``base_link`` is defined as the
+  direction where the arm is pointing to for an all-zero joint configuration.
+
+  .. figure:: frames/base_link.png
+     :alt: The robot with an all-zeros joint configuration showing its base_link frame
+
+     The robot with an all-zeros joint configuration showing its ``base_link`` frame
+
+- ``base`` - This is the frame that is used by the robot controller to represent the robot's *Base*
+  feature (Polyscope 5) / *base* frame (PolyScope X).
+  It has the same position as ``base_link`` but is rotated by 180 degrees around the Z-axis.
+  This follows the `REP proposal 199 <https://gavanderhoorn.github.io/rep/rep-0199.html>`_ with
+  respect to the frame ``base`` and ``tool0``.
+
+  Any lookup of ``tool0`` w.r.t. ``base`` will yield the same result as the pose shown on the teach
+  pendant when ``base`` is selected as a reference there and the tool is set to "all-zero" being in
+  the center of the flange.
+
+  .. figure:: frames/base.png
+     :alt: The robot with an all-zeros joint configuration showing its base frame
+
+     The robot with an all-zeros joint configuration showing its ``base`` frame
+
+- ``base_link_inertia`` - Since some libraries such as KDL don't support inertia for the root link
+  of a kinematic chain (see `ros/kdl_parser#27 <https://github.com/ros/kdl_parser/issues/27>`_),
+  the ``base_link`` doesn't contain any meshes or inertia attached to it. Instead, those are
+  attached to the ``base_link_inertia`` frame. This frame is rotated in the same way as ``base``.
+
+
+This leads to the following kinematic chain:
+
+.. code:: text
+
+   base_link
+   ├ base
+   └ base_link_inertia
+     └ shoulder_link
+       └ upper_arm_link
+         └ forearm_link
+           └ wrist_1_link
+             └ wrist_2_link
+               └ wrist_3_link
+                 └ flange
+                 └ tool0
+
+The frame ``tool0`` is the tool frame as calculated using forward kinematics. If the robot has an
+all-zero tool configured, this should be equivalent to the tool frame on the control box / teach pendant.
+
+The frame ``flange`` is supposed to be used to attach custom tool frame or end-effectors to the
+robot. For instance, with a gripper's ``xacro:macro`` available, it is often possible to specify a
+parent frame, for which ``flange`` should be used.
+
+.. note::
+
+   When making TF lookups in the ROS system and comparing that to what the teach pendant shows,
+   please consider that the robot uses the ``base`` frame as reference, not ``base_link``. Also,
+   make sure that the teach pendant's view is set to "Base" and that any configured tool will have
+   an effect on the values.

doc/index.rst

@@ -76,6 +76,13 @@
       force_abs_paths="${force_abs_paths}"/>
 
     <!-- links -  main serial chain -->
+
+    <!-- base_link serves as the root of the robot's kinematic tree. It follows REP-103
+        conventions (i.e., X+ forward, Y+ left, Z+ up).
+        Since some kinematic solvers forbid having inertia values attached to a root link, we've
+        added the base_link_inertia link that carries the visual, collision and inertia
+        information.
+    -->
     <link name="${tf_prefix}base_link"/>
     <link name="${tf_prefix}base_link_inertia">
       <xacro:get_visual_params name="base" type="mesh_offset"/>