Add new members for PID controller parameters (backport #1585) (#1769)

Co-authored-by: Victor Coutinho Vieira Santos <69547580+ViktorCVS@users.noreply.github.com>
Co-authored-by: Christoph Fröhlich <christophfroehlich@users.noreply.github.com>

Author: 3 people

doc/migration.rst

@@ -12,7 +12,6 @@ diff_drive_controller
 
 joint_trajectory_controller
 *****************************
-
 * Parameter ``allow_nonzero_velocity_at_trajectory_end`` is now per default ``false`` (`#834 <https://github.com/ros-controls/ros2_controllers/pull/834>`_).
 * The parameter ``start_with_holding`` is removed, it now always holds the position at activation (`#839 <https://github.com/ros-controls/ros2_controllers/pull/839>`_).
 * Goals are now cancelled in ``on_deactivate`` transition (`#962 <https://github.com/ros-controls/ros2_controllers/pull/962>`_).
@@ -22,6 +21,12 @@ joint_trajectory_controller
 * Tolerances sent with the action goal were not used before, but are now processed and used for the upcoming action. (`#716 <https://github.com/ros-controls/ros2_controllers/pull/716>`_). Adaptions to the action goal might be necessary.
 * Parameter ``open_loop_control`` is replaced by ``interpolate_from_desired_state`` and setting the feedback gains to zero (`#1525 <https://github.com/ros-controls/ros2_controllers/pull/1525>`_).
 
+pid_controller
+************************
+* Parameters ``enable_feedforward`` and service ``set_feedforward_control`` are deprecated. Instead, set the feedforward_gain to zero or a non-zero value. (`#1553 <https://github.com/ros-controls/ros2_controllers/pull/1553>`_).
+* The legacy ``antiwindup`` boolean and integral clamp parameters ``i_clamp_max``/``i_clamp_min`` have
+  been deprecated in favor of the new ``antiwindup_strategy`` parameter (`#1585 <https://github.com/ros-controls/ros2_controllers/pull/1585>`__). Choose a suitable anti-windup strategy and set the parameters accordingly.
+
 steering_controllers_library
 ********************************
 * ``front_steering`` parameter was removed (`#1166 <https://github.com/ros-controls/ros2_controllers/pull/1166>`_). Now every kinematics type (bicycle, tricycle, Ackermann) has dedicated parameters for steering or traction wheels instead of front/rear wheels.

doc/release_notes.rst

@@ -65,6 +65,10 @@ pid_controller
 ************************
 * 🚀 The PID controller was added 🎉 (`#434 <https://github.com/ros-controls/ros2_controllers/pull/434>`_).
 * Add ``save_i_term`` parameter to control retention of integral state after re-activation (`#1507 <https://github.com/ros-controls/ros2_controllers/pull/1507>`_).
+* The controller now supports the new anti-windup strategy of the PID class, which allows for more flexible control of the anti-windup behavior (`#1585 <https://github.com/ros-controls/ros2_controllers/pull/1585>`__).
+  * Output clamping via ``u_clamp_max`` and ``u_clamp_min`` was added, allowing users to bound the controller output.
+  * The legacy ``antiwindup`` boolean and integral clamp parameters ``i_clamp_max``/``i_clamp_min`` have been deprecated in favor of the new ``antiwindup_strategy`` parameter. A ``tracking_time_constant`` parameter has also been introduced to configure the back-calculation strategy.
+  * A new ``error_deadband`` parameter stops integration when the error is within a specified range.
 
 steering_controllers_library
 ********************************

pid_controller/src/pid_controller.yaml

@@ -65,23 +65,59 @@ pid_controller:
         default_value: 0.0,
         description: "Derivative gain for PID"
       }
+      u_clamp_max: {
+        type: double,
+        default_value: .inf,
+        description: "Upper output clamp."
+      }
+      u_clamp_min: {
+        type: double,
+        default_value: -.inf,
+        description: "Lower output clamp."
+      }
       antiwindup: {
         type: bool,
         default_value: false,
-        description: "Antiwindup functionality. When set to true, limits
+        description: "[Deprecated, see antiwindup_strategy] Anti-windup functionality. When set to true, limits
         the integral error to prevent windup; otherwise, constrains the
         integral contribution to the control output. i_clamp_max and
         i_clamp_min are applied in both scenarios."
       }
       i_clamp_max: {
         type: double,
         default_value: 0.0,
-        description: "Upper integral clamp."
+        description: "[Deprecated, see antiwindup_strategy] Upper integral clamp."
       }
       i_clamp_min: {
         type: double,
         default_value: 0.0,
-        description: "Lower integral clamp."
+        description: "[Deprecated, see antiwindup_strategy] Lower integral clamp."
+      }
+      antiwindup_strategy: {
+        type: string,
+        default_value: "legacy",
+        description: "Specifies the anti-windup strategy. Options: 'back_calculation',
+        'conditional_integration', 'legacy' or 'none'. Note that the 'back_calculation' strategy use the
+        tracking_time_constant parameter to tune the anti-windup behavior.",
+        validation: {
+          one_of<>: [[
+            "back_calculation",
+            "conditional_integration",
+            "legacy",
+            "none"
+          ]]
+        }
+      }
+      tracking_time_constant: {
+        type: double,
+        default_value: 0.0,
+        description: "Specifies the tracking time constant for the 'back_calculation' strategy. If
+        set to 0.0 when this strategy is selected, a recommended default value will be applied."
+      }
+      error_deadband: {
+        type: double,
+        default_value: 1.e-16,
+        description: "Is used to stop integration when the error is within the given range."
       }
       feedforward_gain: {
         type: double,