Update anti-windup techniques (#298)

(cherry picked from commit f652c3d)

# Conflicts:
#	control_toolbox/include/control_toolbox/pid.hpp
#	control_toolbox/include/control_toolbox/pid_ros.hpp
#	control_toolbox/src/pid.cpp
#	control_toolbox/src/pid_ros.cpp
#	control_toolbox/test/pid_tests.cpp
#	doc/release_notes.rst

Author: ViktorCVS

control_toolbox/include/control_toolbox/pid.hpp

@@ -92,13 +92,14 @@ class PidROS
    * \param d The derivative gain.
    * \param i_max Upper integral clamp.
    * \param i_min Lower integral clamp.
-   * \param antiwindup Antiwindup functionality. When set to true, limits
+   * \param antiwindup Anti-windup functionality. When set to true, limits
         the integral error to prevent windup; otherwise, constrains the
         integral contribution to the control output. i_max and
         i_min are applied in both scenarios.
    *
    * \note New gains are not applied if i_min_ > i_max_
    */
+  [[deprecated("Use initialize_from_args with AntiwindupStrategy instead.")]]
   void initialize_from_args(
     double p, double i, double d, double i_max, double i_min, bool antiwindup);
 
@@ -125,11 +126,15 @@ class PidROS
    * \param d The derivative gain.
    * \param i_max The max integral windup.
    * \param i_min The min integral windup.
-   * \param antiwindup antiwindup.
+   * \param antiwindup Anti-windup functionality. When set to true, limits
+        the integral error to prevent windup; otherwise, constrains the
+        integral contribution to the control output. i_max and
+        i_min are applied in both scenarios.
    * \param save_i_term save integrator output between resets.
    *
    * \note New gains are not applied if i_min_ > i_max_
    */
+  [[deprecated("Use initialize_from_args with AntiwindupStrategy instead.")]]
   void initialize_from_args(
     double p, double i, double d, double i_max, double i_min, bool antiwindup, bool save_i_term);
 
@@ -140,17 +145,71 @@ class PidROS
    * \param d The derivative gain.
    * \param i_max The max integral windup.
    * \param i_min The min integral windup.
+<<<<<<< HEAD
    * \param antiwindup antiwindup.
    * \param save_i_term save integrator output between resets.
    *
    * \note New gains are not applied if i_min_ > i_max_
    */
   [[deprecated("Use initialize_from_args() instead")]] void initPid(
     double p, double i, double d, double i_max, double i_min, bool antiwindup, bool save_i_term);
+=======
+   * \param u_max Upper output clamp.
+   * \param u_min Lower output clamp.
+   * \param trk_tc 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.
+   * \param saturation Enables output saturation. When true, the controller output is
+        clamped between u_max and u_min.
+   * \param antiwindup Anti-windup functionality. When set to true, limits
+        the integral error to prevent windup; otherwise, constrains the
+        integral contribution to the control output. i_max and
+        i_min are applied in both scenarios.
+   * \param antiwindup_strat Specifies the anti-windup strategy. Options: 'back_calculation',
+        'conditional_integration', or 'none'. Note that the 'back_calculation' strategy use the
+        tracking_time_constant parameter to tune the anti-windup behavior. When a strategy other
+        than 'none' is selected, it will override the controller's default anti-windup behavior.
+   * \deprecated{only when `antiwindup_strat == AntiwindupStrategy::NONE`:}
+   *     Old anti-windup technique is deprecated and will be removed by
+   *     the ROS 2 Kilted Kaiju release.
+   * \warning{If you pass `AntiwindupStrategy::NONE`, at runtime a warning will be printed:}
+   *     `"Old anti-windup technique is deprecated. This option will be removed by the ROS 2 Kilted Kaiju release."`
+   * \param save_i_term save integrator output between resets.
+   *
+   * \note New gains are not applied if i_min_ > i_max_ or if u_min_ > u_max_.
+   */
+  [[deprecated("Use initialize_from_args with AntiwindupStrategy only.")]]
+  void initialize_from_args(
+    double p, double i, double d, double i_max, double i_min, double u_max, double u_min,
+    double trk_tc, bool saturation, bool antiwindup, AntiwindupStrategy antiwindup_strat,
+    bool save_i_term);
+
+  /*!
+   * \brief Initialize the PID controller and set the parameters.
+   *
+   * \param p The proportional gain.
+   * \param i The integral gain.
+   * \param d The derivative gain.
+   * \param u_max Upper output clamp.
+   * \param u_min Lower output clamp.
+   * \param trk_tc 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.
+   * \param saturation Enables output saturation. When true, the controller output is
+        clamped between u_max and u_min.
+   * \param antiwindup_strat Specifies the anti-windup strategy. Options: 'back_calculation',
+        'conditional_integration', or 'none'. Note that the 'back_calculation' strategy use the
+        tracking_time_constant parameter to tune the anti-windup behavior.
+   * \param save_i_term save integrator output between resets.
+   *
+   * \note New gains are not applied if u_min_ > u_max_.
+   */
+  void initialize_from_args(
+    double p, double i, double d, double u_max, double u_min, double trk_tc, bool saturation,
+    AntiwindupStrategy antiwindup_strat, bool save_i_term);
+>>>>>>> f652c3d (Update anti-windup techniques (#298))
 
   /*!
    * \brief Initialize the PID controller based on already set parameters
-   * \return True if all parameters are set (p, i, d, i_min and i_max), False otherwise
+   * \return True if all parameters are set (p, i, d, i_max, i_min, u_max, u_min and trk_tc), False otherwise
    */
   bool initialize_from_ros_parameters();
 
@@ -252,8 +311,67 @@ class PidROS
    *
    * \note New gains are not applied if i_min > i_max
    */
+  [[deprecated("Use set_gains with AntiwindupStrategy instead.")]]
   void set_gains(double p, double i, double d, double i_max, double i_min, bool antiwindup = false);
 
+  /*!
+   * \brief Initialize the PID controller and set the parameters
+   * \param p The proportional gain.
+   * \param i The integral gain.
+   * \param d The derivative gain.
+   * \param i_max The max integral windup.
+   * \param i_min The min integral windup.
+   * \param u_max Upper output clamp.
+   * \param u_min Lower output clamp.
+   * \param trk_tc 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.
+   * \param saturation Enables output saturation. When true, the controller output is
+        clamped between u_max and u_min.
+   * \param antiwindup Anti-windup functionality. When set to true, limits
+        the integral error to prevent windup; otherwise, constrains the
+        integral contribution to the control output. i_max and
+        i_min are applied in both scenarios.
+   * \param antiwindup_strat Specifies the anti-windup strategy. Options: 'back_calculation',
+        'conditional_integration', or 'none'. Note that the 'back_calculation' strategy use the
+        tracking_time_constant parameter to tune the anti-windup behavior. When a strategy other
+        than 'none' is selected, it will override the controller's default anti-windup behavior.
+   * \deprecated{only when `antiwindup_strat == AntiwindupStrategy::NONE`:}
+   *     Old anti-windup technique is deprecated and will be removed by
+   *     the ROS 2 Kilted Kaiju release.
+   * \warning{If you pass `AntiwindupStrategy::NONE`, at runtime a warning will be printed:}
+   *   `"Old anti-windup technique is deprecated. This option will be removed by
+   *     the ROS 2 Kilted Kaiju release."`
+   *
+   * \note New gains are not applied if i_min > i_max or if u_min_ > u_max_.
+   */
+  [[deprecated("Use set_gains with AntiwindupStrategy only.")]]
+  void set_gains(
+    double p, double i, double d, double i_max, double i_min, double u_max, double u_min,
+    double trk_tc = 0.0, bool saturation = false, bool antiwindup = false,
+    AntiwindupStrategy antiwindup_strat = AntiwindupStrategy::NONE);
+
+  /*!
+   * \brief Set PID gains for the controller (preferred).
+   *
+   * \param p The proportional gain.
+   * \param i The integral gain.
+   * \param d The derivative gain.
+   * \param u_max Upper output clamp.
+   * \param u_min Lower output clamp.
+   * \param trk_tc 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.
+   * \param saturation Enables output saturation. When true, the controller output is
+        clamped between u_max and u_min.
+   * \param antiwindup_strat Specifies the anti-windup strategy. Options: 'back_calculation',
+        'conditional_integration', or 'none'. Note that the 'back_calculation' strategy use the
+        tracking_time_constant parameter to tune the anti-windup behavior.
+   *
+   * \note New gains are not applied if u_min_ > u_max_.
+   */
+  void set_gains(
+    double p, double i, double d, double u_max, double u_min, double trk_tc, bool saturation,
+    AntiwindupStrategy antiwindup_strat);
+
   /*!
    * \brief Set PID gains for the controller.
    * \param p The proportional gain.
@@ -409,6 +527,8 @@ class PidROS
 
   bool get_boolean_param(const std::string & param_name, bool & value);
 
+  bool get_string_param(const std::string & param_name, std::string & value);
+
   /*!
    * \brief Set prefix for topic and parameter names
    * \param[in] topic_prefix prefix to add to the pid parameters.