pid.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file pid.h
//! \brief Provides a compact and efficient PID controller implementation
//!
//! Small, easy to use PID implementation with advanced controller capability.
//! Minimal usage:
//! \code
//! setPID(p,i,d);
//! ...looping code...{
//! output=getOutput(sensorvalue,target);
//! }
//! \endcode
//!
//! @see
//! http://brettbeauregard.com/blog/2011/04/improving-the-beginners-pid-direction/improving-the-beginners-pid-introduction
 
#include "vreUtil/export.h"
 
namespace makVre
{
//! \brief A compact PID (Proportional-Integral-Derivative) controller class
//!
//! This class implements a PID controller with additional features like
//! feed-forward control, output ramping, setpoint limiting, and output
//! filtering to prevent oscillations. It provides methods for tuning
//! individual parameters and configuring various aspects of the controller's
//! behavior.
class UTIL_DLL MiniPID
{
public:
   //! \brief Constructor with P, I, and D parameters
   //!
   //! \param p Proportional gain coefficient
   //! \param i Integral gain coefficient
   //! \param d Derivative gain coefficient
   MiniPID(double p, double i, double d);
 
   //! \brief Constructor with P, I, D, and F parameters
   //!
   //! \param p Proportional gain coefficient
   //! \param i Integral gain coefficient
   //! \param d Derivative gain coefficient
   //! \param f Feed-forward gain coefficient
   MiniPID(double p, double i, double d, double f);
 
   //! \brief Sets the proportional gain coefficient
   //!
   //! This parameter responds quickly to changes in setpoint and provides most of the
   //! initial driving force to make corrections. For position-based controllers,
   //! this is the first parameter to tune, with I second.
   //!
   //! \param p New proportional gain value
   void setP(double p);
 
   //! \brief Sets the integral gain coefficient
   //!
   //! This parameter is used for overcoming disturbances and ensuring that the controller
   //! always reaches the setpoint. Typically tuned second for position-based modes,
   //! and third for rate-based modes.
   //!
   //! \param i New integral gain value
   void setI(double i);
 
   //! \brief Sets the derivative gain coefficient
   //!
   //! This parameter responds quickly to large changes in error and helps prevent
   //! overshoot. Small values prevent the P and I terms from causing overshoot.
   //!
   //! \param d New derivative gain value
   void setD(double d);
 
   //! \brief Sets the feed-forward gain coefficient
   //!
   //! This parameter is excellent for velocity, rate, and other continuous control modes
   //! where you can expect a rough output value based solely on the setpoint.
   //! Should not be used in position-based control modes.
   //!
   //! \param f New feed-forward gain value
   void setF(double f);
 
   //! \brief Sets all three standard PID parameters at once
   //!
   //! \param p New proportional gain value
   //! \param i New integral gain value
   //! \param d New derivative gain value
   void setPID(double p, double i, double d);
 
   //! \brief Sets all four PID parameters including feed-forward at once
   //!
   //! \param p New proportional gain value
   //! \param i New integral gain value
   //! \param d New derivative gain value
   //! \param f New feed-forward gain value
   void setPID(double p, double i, double d, double f);
 
   //! \brief Sets the maximum output value contributed by the I component
   //!
   //! This can be used to prevent large windup issues and make tuning simpler.
   //!
   //! \param maximum Maximum I component contribution (in the same units as the output)
   void setMaxIOutput(double maximum);
 
   //! \brief Sets symmetric output limits (from -output to +output)
   //!
   //! \param output Maximum output magnitude (minimum is set to -output)
   void setOutputLimits(double output);
 
   //! \brief Sets asymmetric output limits
   //!
   //! \param minimum Minimum output value
   //! \param maximum Maximum output value
   void setOutputLimits(double minimum, double maximum);
 
   //! \brief Sets the direction of the PID controller
   //!
   //! \param reversed If true, reverses the PID output
   void setDirection(bool reversed);
 
   //! \brief Sets the target setpoint for the PID calculations
   //!
   //! \param setpoint The desired target value
   void setSetpoint(double setpoint);
 
   //! \brief Resets the controller state
   //!
   //! Erases the integral term buildup and removes derivative gain on the next loop.
   void reset();
 
   //! \brief Sets the maximum rate the output can increase per cycle
   //!
   //! \param rate Maximum change in output per iteration
   void setOutputRampRate(double rate);
 
   //! \brief Sets a limit on how far the setpoint can be from the current position
   //!
   //! This can simplify tuning by allowing tuning over a small range to apply to a much larger range.
   //! It limits the reactivity of the P term and restricts the impact of large D term
   //! during large setpoint adjustments. May increase lag and I term if range is too small.
   //!
   //! \param range Maximum allowed setpoint distance from the current position
   void setSetpointRange(double range);
 
   //! \brief Sets a filter on the output to reduce sharp oscillations
   //!
   //! A value of 0.1 is a good starting point. Larger values smooth P and D oscillations,
   //! but may force larger I values.
   //!
   //! \param strength Filter strength between 0 and 1 (0 = no filter, 1 = infinite filter)
   void setOutputFilter(double strength);
 
   //! \brief Calculates the PID output using the last provided setpoint and actual values
   //!
   //! \return Calculated output value
   double getOutput();
 
   //! \brief Calculates the PID output for a new actual value and the stored setpoint
   //!
   //! \param actual Current measured value
   //! \return Calculated output value
   double getOutput(double actual);
 
   //! \brief Calculates the PID output for new actual and setpoint values
   //!
   //! This is the main calculation function. It computes all PID terms and applies
   //! all configured constraints.
   //!
   //! \param actual Current measured value
   //! \param setpoint Desired target value
   //! \return Calculated output value to drive the actual to the setpoint
   double getOutput(double actual, double setpoint);
 
private:
   //! \brief Clamps a value between minimum and maximum bounds
   //!
   //! \param value Value to clamp
   //! \param min Minimum allowed value
   //! \param max Maximum allowed value
   //! \return Clamped value
   double clamp(double value, double min, double max);
 
   //! \brief Checks if a value is within bounds (exclusive)
   //!
   //! \param value Value to check
   //! \param min Minimum bound (exclusive)
   //! \param max Maximum bound (exclusive)
   //! \return true if min < value < max
   bool bounded(double value, double min, double max);
 
   //! \brief Ensures all PID parameters have the correct sign
   //!
   //! The correct sign depends on the 'reversed' setting
   void checkSigns();
 
   //! \brief Initializes controller parameters to default values
   void init();
 
   //! \brief Proportional gain coefficient
   double P;
 
   //! \brief Integral gain coefficient
   double I;
 
   //! \brief Derivative gain coefficient
   double D;
 
   //! \brief Feed-forward gain coefficient
   double F;
 
   //! \brief Maximum output value contributed by the I component
   double maxIOutput;
 
   //! \brief Maximum error value used for I term calculation
   double maxError;
 
   //! \brief Sum of errors for the I term
   double errorSum;
 
   //! \brief Maximum allowed output value
   double maxOutput;
 
   //! \brief Minimum allowed output value
   double minOutput;
 
   //! \brief Target setpoint value
   double setpoint;
 
   //! \brief Last measured input value (used for D term)
   double lastActual;
 
   //! \brief Flag indicating if this is the first execution
   bool firstRun;
 
   //! \brief Flag indicating if the controller direction is reversed
   bool reversed;
 
   //! \brief Maximum rate the output can increase per cycle
   double outputRampRate;
 
   //! \brief Last calculated output value
   double lastOutput;
 
   //! \brief Output filter strength (0-1)
   double outputFilter;
 
   //! \brief Maximum allowed setpoint distance from the current position
   double setpointRange;
};
} // namespace makVre