Repository: UniversalRobots/Universal_Robots_ROS2_Description
Pull request #286: Add documentation about the different base and base_link frames
Author: login: urfeex
Created: 2025-05-07T12:46:24Z | Merged: 2025-05-13T06:35:58Z

This is basically a documentation-only attempt on the issue that the meaning of the different frames isn't completely obvious to every user. This isn't changing anything about the URDF as #282 and #283 attempt to do, but only documents the state and the reasons why things are the way they are.

@gavanderhoorn I hope, I summarized your comments well enough.

Personally, I would prefer #283, but I do understand that there are cases where this additional frame is needed. Hence this PR as a non-changing alternative.


Diff:
diff --git a/doc/frames/base.png b/doc/frames/base.png
new file mode 100644
index 00000000..1c317b1d
Binary files /dev/null and b/doc/frames/base.png differ
diff --git a/doc/frames/base_link.png b/doc/frames/base_link.png
new file mode 100644
index 00000000..96c463f9
Binary files /dev/null and b/doc/frames/base_link.png differ
diff --git a/doc/index.rst b/doc/index.rst
index 85fd4c00..43b1ebdb 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -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
 ---------------------------
 
diff --git a/doc/robot_frames.rst b/doc/robot_frames.rst
new file mode 100644
index 00000000..6573b352
--- /dev/null
+++ b/doc/robot_frames.rst
@@ -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.
diff --git a/urdf/ur_macro.xacro b/urdf/ur_macro.xacro
index d399ef3f..089a5a3c 100644
--- a/urdf/ur_macro.xacro
+++ b/urdf/ur_macro.xacro
@@ -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">
       <visual>


Reviews:
user: login: gavanderhoorn
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:14:58Z
user: login: gavanderhoorn
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:15:43Z
user: login: urfeex
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-09T12:18:13Z
user: login: gavanderhoorn
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:31:04Z
user: login: urfeex
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-09T12:36:16Z
user: login: urfeex
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-12T06:27:56Z
user: login: urmahp
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-12T09:02:33Z
user: login: urmahp
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-05-13T05:48:36Z

Review comments:
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: ```suggestion
the purpose of each of those frames is. In particular, there are three frames representing the
```
created_at: 2025-05-09T12:14:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: nit: I'm also not sure *representing the robot's base* is the best way to describe what's going on.
created_at: 2025-05-09T12:15:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if the kinematic chain. It follows `REP-103
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: ```suggestion
- ``base_link`` - This serves as the root link of the kinematic chain. It follows `REP-103
```
created_at: 2025-05-09T12:15:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if the kinematic chain. It follows `REP-103
+  <https://ros.org/reps/rep-0103.html>`_ , where "forward" for the ``base_link`` is defined as the
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: ```suggestion
  <https://ros.org/reps/rep-0103.html>`_ , where *forward* for the ``base_link`` is defined as the
```
created_at: 2025-05-09T12:16:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm pointing to for an all-zero joint configuration.
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: point to where? :)
created_at: 2025-05-09T12:16:29Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: ```suggestion
     The robot with an all-zeros joint configuration showing its ``base_link`` frame
```

?

Not sure figure captions support this

created_at: 2025-05-09T12:17:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
path: doc/robot_frames.rst
user: login: urfeex
body: You mean because of the term "base" being the same as the `base` frame which has a special meaning?
created_at: 2025-05-09T12:18:13Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: Does *base* refer to the physical base (ie: the link) or the `Base` frame?

The idea (of the REP in any case) would be the latter (ie: `Base` coordinate frame).
created_at: 2025-05-09T12:21:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: Isn't it called `Base` (capital B) on the TP?
created_at: 2025-05-09T12:22:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: ```suggestion
     The robot with an all-zeros joint configuration showing its ``base`` frame
```
created_at: 2025-05-09T12:22:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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 in
+  fact rotated the same way as ``base``, which is for no particular reason.
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: > which is for no particular reason 

:confused:
created_at: 2025-05-09T12:24:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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 in
+  fact rotated the same way as ``base``, which is for no particular reason.
+
+
+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, that is equivalent to the tool frame on the control box / teach pendant.
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: ```suggestion
all-zero tool configured, this should be equivalent to the tool frame on the control box / teach pendant.
```
created_at: 2025-05-09T12:25:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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 in
+  fact rotated the same way as ``base``, which is for no particular reason.
+
+
+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
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: might perhaps mention this frame as well and explain it's the intended `link` to attach end-effector (sub) `xacro:macro`s to?
created_at: 2025-05-09T12:26:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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 in
+  fact rotated the same way as ``base``, which is for no particular reason.
+
+
+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, that is equivalent to the tool frame on the control box / teach pendant.
+
+.. 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,
path: doc/robot_frames.rst
user: login: gavanderhoorn
body: So the UR control box doesn't know anything about TF, or the structure of the URDF. The phrasing here sort-of implies it does, and explains the CB will use the frame called `base` instead of `base_link`.

If this is instead supposed to refer to concepts known/used by the UR CB, I'd perhaps use the name *Base*, as that's I believe the name of the *feature* the TCP pose will be relative to on the TP (if that feature is selected).
created_at: 2025-05-09T12:26:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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 in
+  fact rotated the same way as ``base``, which is for no particular reason.
+
+
+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, that is equivalent to the tool frame on the control box / teach pendant.
+
+.. 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,
path: doc/robot_frames.rst
user: login: urfeex
body: Hm, that's a bit of a stretch. On PolyScope X the controller does indeed use TF and uses the term "frame" rather than "feature". 

![image](https://github.com/user-attachments/assets/9ef98f74-a8bc-4e31-a499-686fb4e5c6c2)

But we might have to make this clearer, yes. Thank you.
created_at: 2025-05-09T12:36:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+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 that frames is. In particular, there are three frames representing the
+robot's base:
+
+- ``base_link`` - This serves as the root link if 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 of the arm 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.
+  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
path: doc/robot_frames.rst
user: login: urfeex
body: Not on PolyScope X.
created_at: 2025-05-12T06:27:56Z
author_association: MEMBER
diff_hunk: @@ -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 in rotated the same way as ``base``.
path: doc/robot_frames.rst
user: login: urmahp
body: ```suggestion
  attached to the ``base_link_inertia`` frame. This frame is rotated in the same way as ``base``.
```
created_at: 2025-05-12T08:54:31Z
author_association: COLLABORATOR

PR comments:
user: login: urfeex
created_at: 2025-05-13T06:36:26Z
body: @mergifyio backport jazzy
author_association: MEMBER
user: login: mergify[bot]
created_at: 2025-05-13T06:36:32Z
body: > backport jazzy

#### ✅ Backports have been created

<details>

* [#289 Add documentation about the different base and base_link frames (backport #286)](https://github.com/UniversalRobots/Universal_Robots_ROS2_Description/pull/289) has been created for branch `jazzy`

</details>


<!---
DO NOT EDIT
-*- Mergify Payload -*-
{"command": "backport jazzy", "conclusion": "success", "action_is_running": true}
-*- Mergify Payload End -*-
-->
author_association: NONE