====== Advanced PI Controller ======

{{:en:mervis-ide:35-help:advancedpicontroller.png}}

==== Full Name ====

Lib.Mervis.v1_0.AdvancedPiController

==== Required Project References ====

  * Lib.Mervis

===== Description =====

This auxiliary block is used to implement a PI controller with the ability to track a control variable.

===== Usage in ST =====

<code>
program test
    var
        pi: lib.mervis.v1_0.AdvancedPiController := (Xp := ..., Ti := ..., Min := ..., Max := ...);
    end_var

    pi(Input := ..., SetPoint := ..., Enable := ..., TrackingEnable := ..., TrackingValue := ..., Output => ...);
end_program
</code>

===== Inputs =====

|Name                     |Data Type|Allowed Range|Retain|Required                                                                                                                  |Meaning|
|Input                    |real     |             |No    |Yes       |Actual value                                                                                                              |      |
|SetPoint                 |real     |             |No    |Yes       |Desired value                                                                                                             |      |
|Enable                   |bool     |             |No    |No        |Function enable, if //false// the output is 0                                                                             |      |
|TrackingEnable           |bool     |             |No    |No        |Enable tracking mode                                                                                                      |      |
|TrackingValue            |real     |             |No    |No        |Tracked value                                                                                                             |      |
|Min                      |real     |<= 0         |No    |No        |Minimum output value                                                                                                      |      |
|Max                      |real     |>= 0         |No    |No        |Maximum output value                                                                                                      |      |
|Xp                       |real     |> 0          |No    |No        |Proportional gain                                                                                                         |      |
|Ti                       |real     |> 0          |No    |No        |Integral time constant                                                                                                    |      |
|TrackingDontIncludePPart |bool     |             |No    |No        |Determines the method of calculating the new control action in tracking mode - see description below                      |      |
|TrackingThreshold        |real     |             |No    |No        |Value for converting the input variable to the control action size (e.g., how many percent of output corresponds to one degree Celsius)|      |

===== Outputs =====

|Name                      |Data Type|Meaning                                                                                         |
|Output                    |real     |Output                                                                                         |      |
|TrackingCalculatedThreshold|real    |Value for converting the input variable to the control action size (e.g., how many percent of output corresponds to one degree Celsius)|      |
|InvalidParameters         |bool     |Indicates invalid controller settings (//Xp, Ti, Min, or Max// out of allowed range)            |      |

===== Block Methods =====

|Name                                                                          |Meaning|
|[[SimplePiControllerWithEn_Adjust.htm|Adjust]]              |Used to adjust the integral component so the output reaches the maximum value |      |
|[[SimplePiControllerWithEn_AdjustToValue.htm|AdjustToValue]]|Used to adjust the integral component so the output reaches the desired value|      |
|[[SimplePiControllerWithEn_Restart.htm|Restart]]            |Used to reset internal values and restart the calculation                      |      |

===== Detailed Function Description =====

The functional block implements a PI controller with the ability to operate in tracking mode, where the control variable can be obtained from another controller. The following formulas are used for output calculation:

  * Control deviation\\
**e = SetPoint - Input**
  * Proportional component\\
**PPart = (Max - Min) / Xp * e**
  * Integral component (every scan cycle)\\
**IPart = IPart + (Max - Min) / (Xp * Ti) * e * ΔT**
  * Output\\
**Output = PPart + IPart**

The controller includes algorithms to limit the size of the integral component in case of saturation - **Anti-windup**

==== Tracking Mode ====

When the //TrackingEnable// input is set to //true//, the controller's behavior changes. In each calculation cycle, the //TrackingValue// is used as the basis for calculating the new control action. The usage method varies according to the setting of the //TrackingDontIncludePPart// parameter:

  * **true**. The controller adjusts its I-part to exactly match the //TrackingValue// - considering e = 0 for the calculation.
  * **false**. The controller adjusts its I-part so that the controller output exactly matches the //TrackingValue// - including the current values of the //SetPoint// and //Input// inputs in the calculation.

Then, the new control action (including the current P-part) is calculated and set to the //Output//. For easier use with the [[TrackingPiSelector.htm|TrackingPiSelector]] block, the //TrackingThreshold// input and //TrackingCalculatedThreshold// output are provided to determine the hysteresis for selecting the controller whose output will be used.

==== Usage Notes ====

  * For use in **heating** control, connect the controller as follows
    * SetPoint = Desired value
    * Input = Measured value
  * For use in **cooling** control, connect the controller as follows
    * SetPoint = Measured value
    * Input = Desired value
  * ! Due to its definition and implementation of anti-windup, the controller **does not support "non-zero" mode**, meaning the range //Min//..//Max// does not include a zero value - this is also indicated by the //InvalidParameters// output