> 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/optimizer/optstartheat32_v2.md).

# OptStartHeat32\_V2

## `OptStartHeat32_V2` (FB)

FUNCTION\_BLOCK OptStartHeat32\_V2

### Short description

> Switch-on optimization for heating operation with a connection to the FB ‘ClockSlave32’ (principle: variable preheating time)\
> Goal: room temperature = setpoint temperature at the start of day operation\
> Typical application: zone control loop with heating valve

### Representation

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

### Interfaces

#### Inputs

| Name                          | Data type      | Value range | Initial value | Function                                                                                                                                                                                       |
| ----------------------------- | -------------- | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *xClockMaster\_Holiday*       | BOOL           |             | FALSE         | Current state of the ‘Holiday’ channel of the instance of the associated FB ‘ClockMaster32’ (FALSE = no holiday)                                                                               |
| *xClockMaster\_PublicHoliday* | BOOL           |             | FALSE         | Current state of the ‘Public holidays’ channel of the instance of the associated FB ‘ClockMaster32’ (FALSE = no public holiday)                                                                |
| *xClockMaster\_SwitchTimeS*   | BOOL           |             | FALSE         | Current state of the ‘Exception days’ channel of the instance of the associated FB ‘ClockMaster32’ (FALSE = no exception day)                                                                  |
| *xClockMaster\_AllOn*         | BOOL           |             | FALSE         | Current state of the forced-ON control of all outputs ‘xClockActice’ of all associated FB ‘ClockSlave32’ of the instance of the associated FB ‘ClockMaster32’ ( FALSE = no forced-ON control ) |
| *xClockMaster\_AllOff*        | BOOL           |             | FALSE         | Current state of the forced-OFF control of all outputs ‘xClockActive’ of all associated FB ‘ClockSlave32’ of the instance of the associated FB ‘ClockMaster32’ (FALSE = no forced-OFF control) |
| *ClockSlave\_Param*           | stSlvClockData |             |               | Connection to some selected parameters of the FB ‘ClockSlave32’                                                                                                                                |
| *xEn*                         | BOOL           |             | FALSE         | General enable of the switch-on optimization                                                                                                                                                   |
| *xEnAdapt*                    | BOOL           |             | TRUE          | Enable data storage in historical memory                                                                                                                                                       |
| *xResAdapt*                   | BOOL           |             | TRUE          | Reset of historical memory                                                                                                                                                                     |
| *rTo*                         | REAL           |             |               | Current outside temperature                                                                                                                                                                    |
| *rTi*                         | REAL           |             |               | Current room temperature                                                                                                                                                                       |
| *rSetTemp*                    | REAL           |             |               | Current room setpoint temperature in comfort/day operation                                                                                                                                     |

#### Outputs

| Name           | Data type | Value range | Initial value | Function                                                                                                                     |
| -------------- | --------- | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| *xDaytime*     | BOOL      |             | FALSE         | Enable of comfort/day operation (Off = FALSE, On = TRUE)                                                                     |
| *xProcess*     | BOOL      |             | FALSE         | Enable - preheating process (Off = FALSE, On = TRUE)                                                                         |
| *bState*       | BYTE      |             | 0             | Phase of the preheating process (0=Off/Deactivated, 1 = test time, 2 = dead time, 3 = heating time, 4 = end of heating time) |
| *wError*       | WORD      |             | 0             | Error status of the last preheating process                                                                                  |
| *bResult*      | BYTE      |             | 0             | Quality of the last preheating process (0 = invalid, 1 = good, 2 = normal, 3 = poor)                                         |
| *xActive*      | BOOL      |             | FALSE         | State of the clock channel (Off = FALSE, On = TRUE)                                                                          |
| *uiDeadTime*   | UINT      |             | 0             | Display of the current dead time duration (min)                                                                              |
| *uiHeatTime*   | UINT      |             | 0             | Display of the current heating time duration (min)                                                                           |
| *uiNumber*     | UINT      |             | 0             | Display of the total number of successful preheating processes                                                               |
| *rAverageDiff* | REAL      |             | 0.0           | Average absolute room temperature deviation of the last 10 successful preheating processes                                   |

#### Setpoints / Parameters

| Name        | Data type | Value range | Initial value | Function                                 |
| ----------- | --------- | ----------- | ------------- | ---------------------------------------- |
| **uiHGMin** | UINT      |             | 30            | Minimum value - heating gradient (min/K) |
| **uiHGMax** | UINT      |             | 240           | Maximum value - heating gradient (min/K) |
| **uiDTMin** | UINT      |             | 10            | Minimum value - dead time (min)          |
| **uiDTMax** | UINT      |             | 180           | Maximum value - dead time (min)          |
| **uiHTMin** | UINT      |             | 15            | Minimum value - heating time (min)       |
| **uiHTMax** | UINT      |             | 600           | Maximum value - heating time (min)       |

#### Global variables

| Name                               | Data type | Value range | Initial value | Function                                                                               |
| ---------------------------------- | --------- | ----------- | ------------- | -------------------------------------------------------------------------------------- |
| `gc_Parameters.rTOMin`             | REAL      |             | -25           | Minimum value - outside temperature (°C)                                               |
| `gc_Parameters.rTOMax`             | REAL      |             | 25            | Maximum value - outside temperature (°C)                                               |
| `gc_Parameters.rTIMin`             | REAL      |             | 15            | Minimum value - room temperature (°C)                                                  |
| `gc_Parameters.rTIMax`             | REAL      |             | 30            | Maximum value - room temperature (°C)                                                  |
| `gc_Parameters.rDiffSetTemp`       | REAL      |             | 0             | Deviation from the room setpoint temperature at the end of the preheating process (K)  |
| `gc_Parameters.rDTDiffTemp`        | REAL      |             | 0.2           | Increase in room temperature for detecting the end of dead time (K)                    |
| `gc_Parameters.uiPHMaxTime`        | UINT      |             | 720           | Maximum duration of the preheating process                                             |
| `gc_Parameters.rLimitResultWell`   | REAL      |             | 0.5           | Result display: room temperature deviation - threshold for a good preheating process   |
| `gc_Parameters.rLimitResultNormal` | REAL      |             | 1             | Result display: room temperature deviation - threshold for a normal preheating process |

### Restrictions / boundary conditions

\
1\) This FB does not allow preheating processes that cross over a day boundary. The preheating process can therefore start at the earliest at 00:01 on each weekday.

{% hint style="info" %}
Example: Start - comfort operation: Monday - 05:30 // Calculated preheating time = 7 hours\
Optimal start time - preheating process: Sunday - 22:30\
Actual start time - preheating process: Monday - 00:01
{% endhint %}

2\) Special switching times, if assigned (FB ‘ClockSlave32’: parameter ‘xSwitchTimeS’ = TRUE) and active (FB ‘ClockMaster32’: output ‘xSwitchTimeS’ = TRUE), do not cause the start of a preheating process and cause an immediate interruption of any active preheating process.

\
3\) The value of the output ‘ctClockSlave32’ of the FB ‘ClockMaster32’ is incremented by one by each instance of the FB ‘OptStartHeat32’.

### Functional description

\
The output **xDaytime** is activated when switch-on optimization is generally enabled (xEn = TRUE) depending on the historical data, the current outside temperature, the current room temperature and the current setpoint temperature for day/comfort operation **before** the planned start of comfort/day operation.\
\
This preheating ensures that the room temperature at the start of day operation already corresponds to the desired setpoint temperature.\
The preheating time required for this is **individually** recalculated, and the actual preheating time is also incorporated into the historical data.\
No preheating processes that cross over a day boundary are possible.\
Switch-on optimization serves to save energy and increase operating comfort.\
The components relevant for switch-on optimization are processed every 60 s.\
\
A new preheating process is not started, or an active preheating process is interrupted, if at least one of the following conditions is met:\
\
1\) Holiday channel active (FB ‘ClockMaster32’ - xHoliday = TRUE AND FB ‘ClockSlave32’ - ClockSlaveParam.xHoliday = TRUE)\
2\) Public holidays channel active (FB ‘ClockMaster32’ - xPublicHoliday = TRUE AND FB ‘ClockSlave32’ - ClockSlaveParam.xPublicHoliday = TRUE)\
3\) Special switching times channel active (FB ‘ClockMaster32’ - xSwitchTimeS = TRUE AND FB ‘ClockSlave32’ - ClockSlaveParam.xSwitchTimeS = TRUE)\
4\) Central command ON active (FB ‘ClockMaster32’ - xAllOn = TRUE)\
5\) Central command OFF active (FB ‘ClockMaster32’ - xAllOff = TRUE)\
\
The preheating process is divided into four time sections.\
They are passed through in sequence for each successful preheating process.\
The preheating process can end before, exactly at, or after the switching point (= transition to comfort/day operation).

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

#### Test time (bState = 1)

The test time is used for cyclic checking (every 60 s) whether the conditions for enabling preheating are met.\
\
It starts if the following conditions are met at the same time:

1. The preheating process is not active (*xProcess* = FALSE)
2. The clock channel is not active (**xActive** = FALSE)
3. There is a valid next switching point

\
It ends properly if the conditions for enabling preheating are met (= start of dead time).\
It ends in any case if the next valid switching point is equal to the current time.

#### Dead time (bState = 2)

The dead time is used for preconditioning of the heating.\
\
It starts with the proper end of the test time.\
\
It ends properly if the current room temperature *rTi* the room temperature at the start of dead time by the adjustable difference `gc_Parameters.rDTDiffTemp` exceeds continuously for a duration of at least 120 s (= start of heating time).\
\
It ends in any case if the next valid switching point is equal to the current time.

#### Heating time (bState = 3)

The heating time is used to preheat the zone.\
\
It starts with the proper end of dead time.\
\
It ends properly if the current room temperature *rTI* the current room setpoint temperature in comfort/day operation *rSetTemp* approaches continuously for a duration of at least 120 s to within a difference smaller than the global variable `gc_Parameters.rDiffSetTemp` .\
\
It ends if a falling edge is detected at the state of the clock channel *xActive* .\
\
It ends if the current heating time duration exceeds the adjustable maximum value **uiHTMax** .

#### End of heating time (bState = 4)

The end of heating time serves to complete the successful preheating process. The historical data are updated, provided no limit values are violated, if the enabling of data storage in the historical memory (*xEnAdapt*) is active.\
\
It starts with the proper end of heating time.

#### Enable *xEn*

This input is used for the general enable of the switch-on optimization (*xEn* = TRUE). In the locked state (*xEn* = FALSE) the outputs are defined as follows:

| Output         | State/Value | Notes |
| -------------- | ----------- | ----- |
| *xDaytime*     | FALSE       |       |
| *xProcess*     | FALSE       |       |
| *bState*       | 0           |       |
| *wError*       | 0           |       |
| *bResult*      | 0           |       |
| *uiDeadTime*   | 0           |       |
| *uiHeatTime*   | 0           |       |
| *uiNumber*     | 0           |       |
| *rAverageDiff* | 0           |       |

The historical data are retained even in the locked state.\
\
This input can also be used for the connection of sensor faults (fault - room temperature sensor, fault - outdoor temperature sensor) or for operation of the zone in the usage time extension.

#### Enable *xEnAdapt*

This input is used to enable data storage in the historical memory (*xEnAdapt* = TRUE, prerequisite: *xEn* = TRUE).\
After each successful preheating process, the relevant parameters are stored and are therefore available again for the next preheating process.\
In the locked state (*xEnAdapt* = FALSE) no data storage takes place.

#### Enable *xResAdapt*

This input is used to initialize the historical memory on each rising edge (prerequisite: *xEn* = TRUE).

| Memory                         | State/Value | Notes |
| ------------------------------ | ----------- | ----- |
| Heating gradients              | **uiHGMax** |       |
| Dead times                     | **uiDTMax** |       |
| Number of preheating processes | 0           |       |

In addition, the intermediate memory for the average absolute room temperature deviation of the last 10 successful preheating processes and the data memory for the current data are reset.

{% hint style="info" %}
**Useful use of the input&#x20;*****xResAdapt***

This input can be used in combination with the output *rAverageDiff* (Average absolute room temperature deviation of the last 10 successful preheating processes) to cause reinitialization of the historical and current data in case of larger deviations.
{% endhint %}

#### Input *rTo*

This input is used to capture the current outside temperature.\
For switch-on optimization it is additionally time-filtered and limited (Minimum value = `gc_Parameters.rTOMin`, Maximum value = `gc_Parameters.rTOMax`).

#### Input *rTi*

This input is used to capture the current room temperature.\
For switch-on optimization it is additionally time-filtered and limited (Minimum value = `gc_Parameters.rTIMin`, Maximum value = `gc_Parameters.rTIMax`).

#### Input *rSetTemp*

This input is used to capture the current room setpoint temperature for comfort/day operation.\
Whenever the setpoint temperature changes, a reset to the basic state occurs (see Enable *xEn* - locked state).

#### Output *xDaytime*

This output is used to enable comfort/day operation (Off = FALSE, On = TRUE) **by the switch-on optimization**.\
It is activated when transitioning from the test time to dead time.\
It is deactivated if the next valid switching point is reached.

#### Output *xProcess*

This output is used to display the active preheating process (Off = FALSE, On = TRUE).\
It is active if the preheating process is in phases 1 - 4 and/or the output *xDaytime* is active.

#### Output *bState*

This output is used to display the active phase of the preheating process.

| Value | Phase                      |
| ----- | -------------------------- |
| 0     | Off / Deactivated          |
| 1     | Test time active           |
| 2     | Dead time active           |
| 3     | Heating time active        |
| 4     | End of heating time active |

#### Output *wError*

This output is used to display warnings / errors during the last preheating process.\
Each message is assigned a bit (bit = 0 = no error, bit = 1 = warning / error active).\
This output is updated continuously.\
Whenever it changes, the date / current time is additionally recorded.\
This output is always initialized to 0 (= no error) at the beginning of the test time.\
Whenever an error occurs, the preheating process is stopped and the phase ‘Off / Deactivated’ is initiated.\
Whenever a warning occurs, the output *wError* is updated.

| Bit | Cause                                   | Error type | Notes |
| --- | --------------------------------------- | ---------- | ----- |
| 1   | Exceeding the maximum heating time      | Error      |       |
| 4   | Violation of heating gradient threshold | Warning    |       |
| 5   | Violation of dead time threshold        | Warning    |       |
| 6   | Underrun of the minimum heating time    | Warning    |       |

#### Output *bResult*

This output is used to display the quality of the last successful preheating process.\
The output is updated at the switching point (= transition into comfort/day operation) if necessary.\
The absolute value from the calculation of *rSetTemp* - `gc_Parameters.rDiffSetTemp` - *rTi* is used for the evaluation.\
This output is always initialized to 0 (= no result) at the beginning of the test time.

| Result                   | Threshold                          | *bResult* | Notes                     |
| ------------------------ | ---------------------------------- | --------- | ------------------------- |
| less than                | `gc_Parameters.rLimitResultWell`   | 1         | Good preheating process   |
| less than                | `gc_Parameters.rLimitResultNormal` | 2         | Normal preheating process |
| greater than or equal to | `gc_Parameters.rLimitResultNormal` | 3         | Poor preheating process   |

#### Output *xActive*

This output is used to display the state of the output ‘xClockActive’ of the FB ‘ClockSlave32’ (Off = FALSE, On = TRUE).\
It is updated continuously regardless of the state of *xEn* (= General enable of the switch-on optimization).

#### Output *uiDeadTime*

This output is used to display the current dead time duration (min).\
This output is always initialized to 0 min at the beginning of the test time.

#### Output *uiHeatTime*

This output is used to display the current heating time duration (min).\
This output is always initialized to 0 min at the beginning of the test time.

#### Output *uiNumber*

This output is used to display the total number of successful preheating processes.

#### Output *rAverageDiff*

This output is used to display the average absolute room temperature deviation of the last 10 successful preheating processes.\
This output is always updated after the output *bResult* is updated.\
This output is initialized on each rising edge at the input *xResAdapt* with 0 K.

{% hint style="info" %}
**Useful use of the output&#x20;*****rAverageDiff***

This output can be used in combination with the input *xResAdapt* (Reset of historical memory) to cause reinitialization of the historical and current data in case of larger deviations.
{% endhint %}

#### 1. Preheating process

After the software download or after each rising edge at the input *xResAdapt* the historical data are reinitialized.\
The dead times are thereby assigned the parameter **uiDTMax**, the heating gradients the parameter **uiHGMax** and the number of successful preheating processes the value 0.

#### Parameter **uiHGMin**

This parameter is used to define the minimum permissible heating gradient (min / K).\
It is used to check for limit value violations. In the event of a limit value violation, the historical data are not updated.

#### Parameter **uiHGMax**

This parameter is used to define the maximum permissible heating gradient (min / K).\
It is used to check for limit value violations. In the event of a limit value violation, the historical data are not updated.

#### Parameter **uiDTMin**

This parameter is used to define the minimum permissible dead time (min).\
It is used to check for limit value violations. In the event of a limit value violation, the historical data are not updated.

#### Parameter **uiDTMax**

This parameter is used to define the maximum permissible dead time (min).\
It is used to check for limit value violations. In the event of a limit value violation, the historical data are not updated.

#### Parameter **uiHTMin**

This parameter is used to define the minimum permissible heating time (min).\
It is used to check for limit value violations.

#### Parameter **uiHTMax**

This parameter is used to define the maximum permissible heating time (min).\
It is used to check for limit value violations.\
Whenever a limit value violation occurs, the preheating process is stopped and the phase ‘Off / Deactivated’ is initiated.

#### Global variable `gc_Parameters.rTOMin`

This global variable is used to define the minimum permissible outside temperature (°C).\
It is used for checking and correction in the event of limit value violations.

#### Global variable `gc_Parameters.rTOMax`

This global variable is used to define the maximum permissible outside temperature (°C).\
It is used for checking and correction in the event of limit value violations.

#### Global variable `gc_Parameters.rTIMin`

This global variable is used to define the minimum permissible room temperature (°C).\
It is used for checking and correction in the event of limit value violations.

#### Global variable `gc_Parameters.rTIMax`

This global variable is used to define the maximum permissible room temperature (°C).\
It is used for checking and correction in the event of limit value violations.

#### Global variable `gc_Parameters.rDiffSetTemp`

This global variable is used to define the deviation from the room setpoint temperature at the end of the preheating process (K).\
It specifies how close the room temperature must approach the setpoint temperature in day/comfort operation in order to end the active preheating process.

#### Global variable `gc_Parameters.rDTDiffTemp`

This global variable is used to define the increase in room temperature for detecting the end of dead time (K).\
It specifies how much the room temperature must increase continuously during dead time in order to initiate the heating time.

#### Global variable `gc_Parameters.uiPHMaxTime`

This global variable is used to define the maximum duration of the preheating process.\
It is used for internal calculations.

#### Global variable `gc_Parameters.rLimitResultWell`

This global variable is used to define the threshold ‘Good preheating process’ for the quality display *bResult*.

#### Global variable `gc_Parameters.rLimitResultNormal`

This global variable is used to define the threshold ‘Normal preheating process’ for the quality display *bResult*.

#### Typical application

This function block can be used as follows:

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

### CODESYS

InOut:

| Scope       | Name                         | Type           | Initial |
| ----------- | ---------------------------- | -------------- | ------- |
| Input       | `xClockMaster_Holiday`       | `BOOL`         | FALSE   |
| Input       | `xClockMaster_PublicHoliday` | `BOOL`         | FALSE   |
| Input       | `xClockMaster_SwitchTimeS`   | `BOOL`         | FALSE   |
| Input       | `xClockMaster_AllOn`         | `BOOL`         | FALSE   |
| Input       | `xClockMaster_AllOff`        | `BOOL`         | FALSE   |
| Input       | `ClockSlave_Param`           | stSlvClockData |         |
| Input       | `xEn`                        | `BOOL`         | FALSE   |
| Input       | `xEnAdapt`                   | `BOOL`         | TRUE    |
| Input       | `xResAdapt`                  | `BOOL`         | FALSE   |
| Input       | `rTo`                        | `REAL`         |         |
| Input       | `rTi`                        | `REAL`         |         |
| Input       | `rSetTemp`                   | `REAL`         |         |
| Output      | `xDaytime`                   | `BOOL`         | FALSE   |
| Output      | `xProcess`                   | `BOOL`         | FALSE   |
| Output      | `bState`                     | `BYTE`         | 0       |
| Output      | `wError`                     | `WORD`         | 0       |
| Output      | `bResult`                    | `BYTE`         | 0       |
| Output      | `xActive`                    | `BOOL`         | FALSE   |
| Output      | `uiDeadTime`                 | `UINT`         | 0       |
| Output      | `uiHeatTime`                 | `UINT`         | 0       |
| Output      | `uiNumber`                   | `UINT`         | 0       |
| Output      | `rAverageDiff`               | `REAL`         | 0.0     |
| Input Const | `uiHGMin`                    | `UINT`         | 30      |
| Input Const | `uiHGMax`                    | `UINT`         | 240     |
| Input Const | `uiDTMin`                    | `UINT`         | 10      |
| Input Const | `uiDTMax`                    | `UINT`         | 180     |
| Input Const | `uiHTMin`                    | `UINT`         | 15      |
| Input Const | `uiHTMax`                    | `UINT`         | 600     |


---

# 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/optimizer/optstartheat32_v2.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.
