[JTC Doc] Update PID documentation for effort related command interface support (backport #1748) (#1752)

Co-authored-by: Julia Jia <[email protected]>
Co-authored-by: Christoph Fröhlich <[email protected]>

Author: 3 people

joint_trajectory_controller/doc/parameters_context.yaml

@@ -2,17 +2,29 @@ constraints:
     Default values for tolerances if no explicit values are set in the ``JointTrajectory`` message.
 
 gains: |
-  If ``velocity`` is the only command interface for all joints or an ``effort`` command interface is configured, PID controllers are used for every joint.
-  This structure contains the controller gains for every joint with the control law
+  The parameters are used to configure PID loops for the ``velocity`` or ``effort``-only command interfaces. This structure contains the controller gains for every joint with following the control laws
 
-  .. math:: u = k_{ff} v_d + k_p e + k_i \sum e dt + k_d (v_d - v)
+  * If ``velocity`` is the only command interface:
 
-  with the desired velocity :math:`v_d`, the measured velocity :math:`v`, the position error :math:`e` (definition see below),
-  the controller period :math:`dt`, and the ``velocity`` or ``effort`` manipulated variable (control variable) :math:`u`, respectively.
+    .. math::
+
+      u = k_{ff} v_d + k_p e + k_i \sum e dt + k_d (v_d - v)
+
+    with the desired velocity :math:`v_d`, the measured velocity :math:`v`, the position error :math:`e` (definition see below),
+    the controller period :math:`dt`, and the ``velocity`` manipulated variable (control variable) :math:`u`, respectively.
+
+  * If ``effort`` is the only command interface:
+
+    .. math::
+
+      u = k_{ff} v_d + \delta_d + k_p e + k_i \sum e dt + k_d (v_d - v)
+
+    with the desired velocity :math:`v_d`, the desired effort :math:`\delta_d` if provided in the trajectory (or 0 otherwise), the measured velocity :math:`v`, the position error :math:`e` (definition see below),
+    the controller period :math:`dt`, and the ``effort`` manipulated variable (control variable) :math:`u`, respectively.
 
   If the joint is of continuous type, the position error :math:`e = normalize(s_d - s)` is normalized between :math:`-\pi, \pi`,
   i.e., the shortest rotation to the target position is the desired motion.
   Otherwise  :math:`e = s_d - s` is used, with the desired position :math:`s_d` and the measured
   position :math:`s` from the state interface.
 
-  If you want to turn off the PIDs (open loop control), set the feedback gains to zero.
+  If you want to turn off the PIDs (open loop control), set the feedback gains to zero and an appropriate value for feed-forward gain :math:`k_{ff}`.

joint_trajectory_controller/doc/userdoc.rst

@@ -30,9 +30,9 @@ This means that the joints can have one or more command interfaces, where the fo
 
 * For command interfaces ``position``, the desired positions are simply forwarded to the joints,
 * For command interfaces ``acceleration``, desired accelerations are simply forwarded to the joints.
-* For ``velocity`` (``effort``) command interfaces, the position+velocity trajectory following error is mapped to ``velocity`` (``effort``) commands through a PID loop if it is configured (:ref:`parameters`).
-* For ``effort`` command interface (without ``position`` command interface), if the trajectory contains effort, this will be added to the PID commands as a feed forward effort.
-* For ``position, effort`` command interface, if the trajectory contains effort, this will be passed directly to the ``effort`` interface (PID won't be used) while the positions will be passed to the ``position`` interface.
+* For ``velocity`` command interfaces, the position+velocity trajectory following error is mapped to ``velocity`` commands through a PID loop if it is configured (:ref:`parameters`).
+* For ``effort`` command interface (without ``position`` command interface), the position+velocity trajectory following error is mapped to ``effort`` commands through a PID loop if it is configured (:ref:`parameters`). In addition, it adds trajectory's effort as feedforward effort to the PID output.
+* For ``position, effort`` command interface, PID loop is not used. If the trajectory contains effort, its value will be passed directly to the ``effort`` interface while the desired positions will be forwarded to the ``position`` interface. This could be useful for manipulation tasks where you need to add that extra force to maintain contact.
 
 This leads to the following allowed combinations of command and state interfaces: