> For the complete documentation index, see [llms.txt](https://support.powerio.com/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.powerio.com/hub/codesys-hvac/en/hvac-library/functionblocks/control/controlpiext.md).

# ControlPIext

## `ControlPIext` (FB)

FUNCTION\_BLOCK ControlPIext

### Short description

> Proportional-integral controller (PI controller), parameters as inputs.\
> The action direction (inverted / direct) is also configurable.\
> Typical application: control loops with actuators that do not have a storing character.

### Representation

<figure><img src="https://2592874069-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQR4vCFzt6ixgsqlR3pdR%2Fuploads%2Fgit-blob-dd438b0376daa81300d511807f55d35b8df10df3%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Interfaces

#### Inputs

| Name           | Data type | Value range | Initial value | Function                                        |
| -------------- | --------- | ----------- | ------------- | ----------------------------------------------- |
| *rX*           | REAL      |             |               | Analog actual value                             |
| *rW*           | REAL      |             |               | Analog setpoint value                           |
| *xEn*          | BOOL      |             |               | Controller enable                               |
| **rYDisabled** | REAL      |             | 0.0           | Switch-off value                                |
| **rInitValue** | REAL      |             | 0.0           | Initialization value for the output signal      |
| **rKp**        | REAL      | 0.0 …       | 2.0           | Gain factor                                     |
| **rTn**        | REAL      | 0.0 …       | 200.0         | Reset time in seconds                           |
| **rMin**       | REAL      |             | 0.0           | Lower absolute limit value of the output signal |
| **rMax**       | REAL      |             | 100.0         | Upper absolute limit value of the output signal |

#### Outputs

| Name           | Data type | Value range | Initial value | Function                                    |
| -------------- | --------- | ----------- | ------------- | ------------------------------------------- |
| *rY*           | REAL      |             | 0.0           | Controller output signal                    |
| *rDiff*        | REAL      |             |               | Control deviation                           |
| *rPartP*       | REAL      |             |               | Proportional component of the output signal |
| *rPartI*       | REAL      |             |               | Integral component of the output signal     |
| *xLimitActive* | BOOL      |             |               | Status - limit exceedance                   |

#### Setpoints / Parameters

| Name          | Data type    | Value range | Initial value         | Function                                              |
| ------------- | ------------ | ----------- | --------------------- | ----------------------------------------------------- |
| **rOffset**   | REAL         |             | 0.0                   | Offset                                                |
| **eAction**   | eControlMode |             | eControlMode.Inverted | Action direction of the controller (Inverted, Direct) |
| **eManModeN** | eManNum      |             | eManNum.Auto          | Operating mode for the controller output signal       |
| **rManValue** | REAL         |             |                       | Output signal in manual mode                          |

### Functional description

#### General

This function block contains a proportional-integral controller (PI controller).\
Some parameters are defined as inputs and are therefore not persistent. This allows the values to be changed continuously by the program.\
The output signal of the controller *rY* is calculated when the controller is enabled (*xEn* = TRUE) and in automatic mode of the controller (**eManModeN** = eManNum.Auto) is calculated as follows:\
\
\
Output signal: *rY* = Proportional component + Integral component\
\
\
Proportional component: Proportional component = **rKp** \* control deviation\
\
Control deviation: Control deviation = *rW* - (*rx* + **rOffset**) \[Action direction - Inverted: **eAction** = eControlMode.Inverted]\
\
Control deviation = *rX* - (*rW* + **rOffset**) \[Action direction - Direct: **eAction** = eControlMode.Direct]\
\
Integral component: Integral component = (Proportional component \* (sampling time / reset time)) + Integral component (t-sampling time)\
\
\
Legend: t-sampling time … time point that was one sampling time before the current time t\
Sampling time … time duration between two calls of the function block\
t … current time

> **Control / Properties - Reset time rTn**
>
> It may only take values > 0.\
> **rTn** >>> Sampling time: The integral component remains constant\
> Control deviation = 0: The integral component remains constant\
> Depending on the action direction of the controller **eAction** the actual and setpoint values are defined as follows:
>
> \
> \| \*\*eAction\*\* | Control deviation | Function |\
> \|-------------------------|-------------------------------|-----------------------|\
> \| eControlMode.Inverted | \*rW\* - ( \*rx\* + \*\*rOffset\*\* ) | Action direction - Inverted |\
> \| eControlMode.Direct | \*rX\* - ( \*rW\* + \*\*rOffset\*\* ) | Action direction - Direct |

#### Integral component

The integral component is limited both upwards and downwards by the following absolute limit values:\
Upper limit = **rMax** - Proportional component\
Lower limit = **rMin** - Proportional component

#### Enable input *xEn*

If the enable input is not active (*xEn* = FALSE) the switch-off value **rYDisabled** to the output *rY* is transferred (prerequisite: **eManModeN** = eManNum.Auto) and limited by the absolute limit values. The integral component is set to 0.0.\
\
If the enable input is active (*xEn* = TRUE) the output signal is calculated according to the formula above and to the output *rY* is transferred (prerequisite: **eManModeN** = eManNum.Auto) and limited by the absolute limit values.\
\
With every rising edge at the enable input *xEn* the control process is restarted.

#### Controller restart

With every rising edge at the enable input *xEn* the control process is restarted. (Prerequisites: **eManModeN** = eManNum.Auto and *xEn* = TRUE)\
The integral component is set to the difference between **rInitValue** and the proportional component.

#### Control deviation *rDiff*

The control deviation corresponds to the value of the control deviation according to the formula above.

#### Proportional component of the output signal *rPartP*

This output always provides the proportional component of the output signal, see description above.

#### Integral component of the output signal *rPartI*

This output always provides the integral component of the output signal, see description above.

#### Absolute limit values **rMin** and **rMax**

The controller output signal *rY* is limited by the absolute limit values **rMin** downward and **rMax** upward.\
The absolute limit value **rMin** is set to the current value of **rMax** - 0.1, if it is >= the current value of **rMax** is.\
The only exception is manual mode for the controller output signal (**eManModeN** = eManNum.Man).

#### Status - limit exceedance *xLimitActive*

The limit exceedance status is activated (*xLimitActive* = TRUE), if a limit violation above or below is present (*xEn* = TRUE).\
The status of the limit violation is not activated (*xLimitActive* = FALSE), if no limit violation is present or the enable signal is deactivated (*xEn* = FALSE).\
\
A limit violation is present if the output signal of the controller *rY* the upper limit value **rMax** reaches / exceeds or the lower limit value **rMin** reaches / falls below.

#### Operating mode for the controller output signal **eManModeN**

The parameter **eManModeN** allows switching the output signal *rY* from automatic mode to manual mode and vice versa.\
In manual mode, the output signal takes over *rY* the output signal in manual mode **rManValue**. The integral component is set to the difference between **rInitValue** and the proportional component.

| **eManModeN** | *rY*                                           | Function                       |
| ------------- | ---------------------------------------------- | ------------------------------ |
| eManNum.Auto  | Signal according to formula / switch-off value | Automatic mode - output signal |
| eManNum.Man   | **rManValue**                                  | Manual mode - output signal    |

### Codesys

InOut:

| Scope       | Name           | Type         | Initial               |
| ----------- | -------------- | ------------ | --------------------- |
| Input       | `rX`           | `REAL`       |                       |
| Input       | `rW`           | `REAL`       |                       |
| Input       | `xEn`          | `BOOL`       |                       |
| Input       | `rYDisabled`   | `REAL`       | 0                     |
| Input       | `rInitValue`   | `REAL`       | 0                     |
| Input       | `rKp`          | `REAL`       | 2                     |
| Input       | `rTn`          | `REAL`       | 200                   |
| Input       | `rYMin`        | `REAL`       | 0                     |
| Input       | `rYMax`        | `REAL`       | 100                   |
| Input Const | `rOffset`      | `REAL`       | 0                     |
| Input Const | `eAction`      | eControlMode | eControlMode.Inverted |
| Input Const | `eManModeN`    | eManNum      | eManNum.Auto          |
| Input Const | `rManValue`    | `REAL`       |                       |
| Output      | `rY`           | `REAL`       | 0                     |
| Output      | `rDiff`        | `REAL`       |                       |
| Output      | `rPartP`       | `REAL`       |                       |
| Output      | `rPartI`       | `REAL`       |                       |
| Output      | `xLimitActive` | `BOOL`       |                       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://support.powerio.com/hub/codesys-hvac/en/hvac-library/functionblocks/control/controlpiext.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.