components/PID/PID_v1.h

/**
 * @file
 * @brief Interface definitions for the PID controller.
 *
 * Loger description
 */

#ifndef	_PID_V1_H
#define	_PID_V1_H

/**
 * @brief PID mode codes.
 */
typedef enum
{
    PID_MANUAL    = 0,		///< PID mode manual.
    PID_AUTOMATIC = 1,		///< PID mode is automatic.
} PID_MODE;

/**
 * @brief PID direction codes.
 */
typedef enum
{
    PID_DIRECT  = 0,		///< PID direction normal.
    PID_REVERSE = 1,		///< PID direction reverse.
} PID_DIRECTION;

/**
 * @brief PID calculation mode.
 */
typedef enum
{
    PID_P_ON_M = 0,		///< PID on Measurement.
    PID_P_ON_E = 1,		///< PID on Errors.
} PID_PON;


/**
 * @brief Setup the PID controller and initialize.
 * @param[in] Input The measured value.
 * @param[in,out] Output The computed result.
 * @param[in] Setpoint The setpoint to regulate to.
 * @param[in] Kp The Proportional value.
 * @param[in] Ki The Intergral value.
 * @param[in] Kd The Derivate value.
 * @param[in] POn 0 - PID on Measurement, 1 - PID on Error.
 * @param[in] Direction Direct or Reverse action.
 */
void PID(double* Input, double* Output, double* Setpoint, double Kp, double Ki, double Kd, PID_PON POn, PID_DIRECTION Direction);

/**
 * @brief sets PID to either Manual or Automatic.
 * @param Mode Manual (0) or Automatic (1).
 */
void PID_SetMode(PID_MODE Mode);

/**
 * @brief This, as they say, is where the magic happens.  this function should be called
 *        every time "void loop()" executes.  the function will decide for itself whether a new
 *        pid Output needs to be computed.
 * @return Returns true when the output is computed, false when nothing has been done.
 */
bool PID_Compute(void);

/**
 * @brief Clamps the output to a specific range. 0-255 by default, but it's likely the user
 *        will want to change this depending on the application.
 * @param[in] Min The minimal value that Output can be.
 * @param[in] Max The maximum value that Output can be.
 */
void PID_SetOutputLimits(double Min, double Max);

/**
 * @brief While most users will set the tunings once in the constructor, this function gives
 *        the user the option of changing tunings during runtime for Adaptive control.
 * @param[in] Kp The Proportional value.
 * @param[in] Ki The Intergral value.
 * @param[in] Kd The Derivate value.
 * @param[in] POn 0 - PID on Measurement, 1 - PID on Error.
 */
void PID_SetTunings(double Kp, double Ki, double Kd, PID_PON POn);

/**
 * @brief The PID will either be connected to a DIRECT acting process (+Output leads
 *        to +Input) or a REVERSE acting process(+Output leads to -Input.)  we need to
 *        know which one, because otherwise we may increase the output when we should
 *        be decreasing.
 * @param[in] Direction Direct or Reverse action.
 */
void PID_SetControllerDirection(PID_DIRECTION Direction);

/**
 * @brief Sets the frequency, in Milliseconds, with which the PID calculation is performed.
 *        default is 100
 * @param[in] NewSampleTime The new time in Milliseconds.
 */
void PID_SetSampleTime(int NewSampleTime);

/**
 * @brief This function queries the internal state of the PID.  It's here for display
 *        purposes.  this are the functions the PID Front-end uses for example.
 * @return The Kp setting.
 */
double PID_GetKp();

/**
 * @brief This function queries the internal state of the PID.  It's here for display
 *        purposes.  this are the functions the PID Front-end uses for example.
 * @return The Ki setting.
 */
double PID_GetKi();

/**
 * @brief This function queries the internal state of the PID.  It's here for display
 *        purposes.  this are the functions the PID Front-end uses for example.
 * @return The Kp setting.
 */
double PID_GetKd();

/**
 * @brief This function queries the internal state of the PID.  It's here for display
 *        purposes.  this are the functions the PID Front-end uses for example.
 * @return Returns PID_AUTOMATIC or PID_MANUAL.
 */
PID_MODE PID_GetMode();

/**
 * @brief This function queries the internal state of the PID.  It's here for display
 *        purposes.  this are the functions the PID Front-end uses for example.
 * @return Returns PID_DIRECT or PID_REVERSE.
 */
PID_DIRECTION PID_GetDirection();


#endif