> For the complete documentation index, see [llms.txt](https://docs.mclimate.eu/mclimate-lorawan-devices/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mclimate.eu/mclimate-lorawan-devices/devices/mclimate-vicki-lorawan/vicki-lorawan-device-communication-protocol/temperature-control.md).

# Temperature Control

Vicki has an internal temperature control algorithms that allows it to intelligently adjust the valve openness in order to reach the target temperature and remain within as close a proximity of it as possible. The main algorithm that is utilized is the Proportionate integral (PI) control algorithms.

{% hint style="warning" %}
This algorithm is the newest and most optimized one available for Vicki devices and is the only one available for firmware >=4.3.

Other algorithms are available for older firmware versions, you can find information on them in the [Deprecated temperature](/mclimate-lorawan-devices/devices/mclimate-vicki-lorawan/vicki-lorawan-device-communication-protocol/temperature-control/deprecated-temperature-control-algorithms.md) control algorithms page.
{% endhint %}

## Proportionate Integral (PI) Control Algorithm

This algorithm is an implementation of a typical PI algorithm.

$$
ValveOpening \[%]  = Kp \* e + Ki\*\sum\_{}^{}e
$$

Both the proportional gain Kp and the integral gain Ki can be set with 5 decimal places after the comma.

The algorithm will run on 3 occasions:

 \- Periodic run (by default every 10 minutes)

 \- New target temperature is set

 \- T(measured) - T(target) > 2 degrees Celsius

$$
Integral = \sum\_{}^{}e
$$

There's a [software hysteresis](#temperature-hysteresis) in place, which prevents the movement of the motor unless the error is > Thys.

{% hint style="info" %}
The implementation does not have integral reset time - it integrates all previous errors. There's an integral anti wind-up and anti wind-down in place, which limits the integral to 0-50 degrees by default. You can change the maximum value via the command below, increasing the error limit.
{% endhint %}

## Maximum allowed Integral value

{% tabs %}
{% tab title="SET" %}

<table><thead><tr><th width="149">Byte Index</th><th>Byte value - meaning</th></tr></thead><tbody><tr><td><strong>Byte Index</strong></td><td><strong>Byte value - meaning</strong></td></tr><tr><td>0</td><td>4C - The command code</td></tr><tr><td>1</td><td>XX - I[15:8]</td></tr><tr><td>2</td><td>XX -I[7:0] </td></tr></tbody></table>

**Example command:** `0x4C012C`

I\[15:0] = `0x012C` = 300

Integral = I / 10 = 300 / 10 = 30

The error is set to its maximum allowed value of 30°C

**Default:**\
**I\[15:0] = `0x01F4` = 500 = 50°C**
{% endtab %}

{% tab title="GET" %}

<table><thead><tr><th width="135">Byte index</th><th width="157">Sent request</th><th>Response - Meaning</th></tr></thead><tbody><tr><td>0</td><td>4D – The command code.</td><td>4D – The command code.</td></tr><tr><td>1</td><td> </td><td>XX - I[15:8]</td></tr><tr><td>2</td><td></td><td>XX -I[7:0] </td></tr></tbody></table>

**Example command:** `0x4D`

**Example command response:** `0x4D03E8`

I\[15:0] = `0x03E8` = 1000

Integral = I / 10 = 1000 / 10 = 100

The error is set to its maximum allowed value of 100°C

**Default:**\
**I\[15:0] = `0x01F4` = 50 = 50°C**
{% endtab %}
{% endtabs %}

## Proportional gain - Kp

{% tabs %}
{% tab title="SET" %}

<table><thead><tr><th width="149">Byte Index</th><th>Byte value - meaning</th></tr></thead><tbody><tr><td><strong>Byte Index</strong></td><td><strong>Byte value - meaning</strong></td></tr><tr><td>0</td><td>37 - The command code</td></tr><tr><td>1</td><td>XX[23:16]</td></tr><tr><td>2</td><td>XX[15:8]</td></tr><tr><td>3</td><td>XX[7:0]</td></tr><tr><td></td><td>XX[23:0] = Kp * 131072 <br><strong>Default: <code>0x0C0000</code>= 786432 -> Kp = 6</strong></td></tr></tbody></table>

**Example command:** Setting Kp to 2.74688: 37057E67

2.74688\*131072 = 360039 = `0x057E67`
{% endtab %}

{% tab title="GET" %}

<table><thead><tr><th width="135">Byte index</th><th width="157">Sent request</th><th>Response - Meaning</th></tr></thead><tbody><tr><td>0</td><td>36 – The command code.</td><td>36 – The command code.</td></tr><tr><td>1</td><td> </td><td>A[23:16]</td></tr><tr><td>2</td><td></td><td>A[15:8]</td></tr><tr><td>3</td><td></td><td>A[7:0]</td></tr><tr><td></td><td></td><td>Kp = A[23:0]/131072</td></tr></tbody></table>

**Example command:** `0x36`

**Example response:** `0x36123456`

A\[23:0] = `0x123456` = 1193046

Kp = 1193046 / 131072 = 9.1
{% endtab %}
{% endtabs %}

## Integral gain - Ki

{% tabs %}
{% tab title="SET" %}

<table><thead><tr><th width="136"></th><th></th></tr></thead><tbody><tr><td><strong>Byte Index</strong></td><td><strong>Byte value - meaning</strong></td></tr><tr><td>0</td><td>3E - The command code</td></tr><tr><td>1</td><td>XX[23:16]</td></tr><tr><td>2</td><td>XX[15:8]</td></tr><tr><td>3</td><td>XX[7:0]</td></tr><tr><td></td><td><p>XX[23:0] = Ki * 131072</p><p><strong>Default: <code>0x020000</code> = 131072 -> Kpi = 1</strong></p></td></tr></tbody></table>

**Example command:** Setting Ki to 0.412678: `0x3E00D34A`\
0.412678\*131072 = 54090 = `0x00D34A`
{% endtab %}

{% tab title="GET" %}

<table><thead><tr><th width="135">Byte index</th><th width="157">Sent request</th><th>Response - Meaning</th></tr></thead><tbody><tr><td>0</td><td>3D – The command code.</td><td>3D – The command code.</td></tr><tr><td>1</td><td> </td><td>B[23:16]</td></tr><tr><td>2</td><td></td><td>B[15:8]</td></tr><tr><td>3</td><td></td><td>B[7:0]</td></tr><tr><td></td><td></td><td>Ki = B[23:0]/131072</td></tr></tbody></table>

**Example command:** `0x3D`

**Example response:** `0x3D112233`

B\[23:0] = `0x112233` = 1122867

Ki = 1122867/131072 = 8.57
{% endtab %}
{% endtabs %}

## Get the value of the integral

<table><thead><tr><th width="135">Byte index</th><th width="157">Sent request</th><th>Response - Meaning</th></tr></thead><tbody><tr><td>0</td><td>3F – The command code.</td><td>3F – The command code.</td></tr><tr><td>1</td><td> </td><td>Integral [15:8]</td></tr><tr><td>2</td><td> </td><td>Integral [7:0]</td></tr></tbody></table>

The value of the integral is pre-multiplied by 10 by the device, so it can use 0.1 resolution.

**Example command:** `0x3F`

**Example response:** `0x3f0019`

Integral \[15:0] = `0x0019` = 25

Integral = 25/10 = 2.5

## PI run period

{% tabs %}
{% tab title="SET" %}

<table><thead><tr><th width="136"></th><th></th></tr></thead><tbody><tr><td><strong>Byte Index</strong></td><td><strong>Byte value - meaning</strong></td></tr><tr><td>0</td><td>41 - The command code</td></tr><tr><td>1</td><td>XX = Run period in minutes. <strong>(default value: 10 minutes)</strong></td></tr></tbody></table>

**Example command:** `0x410F` - sets the run period to 15 minutes.
{% endtab %}

{% tab title="GET" %}

<table><thead><tr><th width="135">Byte index</th><th width="157">Sent request</th><th>Response - Meaning</th></tr></thead><tbody><tr><td>0</td><td>40 – The command code.</td><td>40 – The command code.</td></tr><tr><td>1</td><td> </td><td>XX - Run period in minutes.</td></tr></tbody></table>

**Example command:** `0x40`

**Example response:** `0x400B` - the run period is 11 minutes
{% endtab %}
{% endtabs %}

## Temperature hysteresis (Thys)

{% tabs %}
{% tab title="SET" %}

<table><thead><tr><th width="136"></th><th></th></tr></thead><tbody><tr><td><strong>Byte Index</strong></td><td><strong>Byte value - meaning</strong></td></tr><tr><td>0</td><td>43 - The command code</td></tr><tr><td>1</td><td>XX = Temperature hysteresis value (Thys), multiplied by 10. <strong>(</strong><a data-footnote-ref href="#user-content-fn-1"><strong>Default value: 0.2 deg. C</strong></a><strong>, Default value for f.w. ≥ 4.6 - 0 deg. C)</strong></td></tr></tbody></table>

**Example command:** `0x4303` - sets the temperature hysteresis to 0.3 degrees Celsius.
{% endtab %}

{% tab title="GET" %}

<table><thead><tr><th width="135">Byte index</th><th width="157">Sent request</th><th>Response - Meaning</th></tr></thead><tbody><tr><td>0</td><td>42 – The command code.</td><td>42 – The command code.</td></tr><tr><td>1</td><td> </td><td>XX - Temperature hysteresis value, multiplied by 10.</td></tr></tbody></table>

**Example uplink:** `0x42`

**Example response:** `0x4210` - The temperature hysteresis is 1.6 degrees Celsius.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The is no minimum limit for Thys (it can have a 0 value).

The maximum allowed values is 100, which corresponds to 10 degrees.
{% endhint %}

[^1]: Didn't we make it 0 by default since some firmware version?


---

# 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://docs.mclimate.eu/mclimate-lorawan-devices/devices/mclimate-vicki-lorawan/vicki-lorawan-device-communication-protocol/temperature-control.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.