app-thermo

Description

The app-thermo block is a software thermostat available at the same time to the project logic, the mobile application, and the web interface. It allows you to set the target temperature, provide the current sensor temperature, and select the thermostat operating mode.

Depending on the configuration, the block may operate in heating mode, cooling mode, or automatic mode. After the block is added to the project, an associated virtual device is created, so the thermostat state is visible not only inside the logic itself.

The block has one main input, two inputs labeled using the tag block, and four outputs.

Configuration parameters

Parameter name	Value
`name`	Optional parameter. Defines the name visible to the user in the mobile application and in the web interface. The absence of this parameter does not prevent the block from working.
`heating_mode`	Required boolean parameter with values `true` or `false`. Defines whether the block supports heating mode.
`cooling_mode`	Required boolean parameter with values `true` or `false`. Defines whether the block supports cooling mode. At least one of the `heating_mode` or `cooling_mode` parameters must be set to `true`.
`auto_mode`	Required boolean parameter with values `true` or `false`. The value `true` enables the use of automatic mode. Automatic mode may be enabled only when both heating and cooling modes are supported.
`hysteresis`	Required parameter defining the temperature hysteresis width. The allowed range is from 0°C to 12°C.
`minimum_temperature`	Required parameter defining the minimum allowed target temperature. The allowed range is from -270°C to 3000°C. The value must be smaller than `maximum_temperature`.
`maximum_temperature`	Required parameter defining the maximum allowed target temperature. The allowed range is from -270°C to 3000°C. The value must be greater than `minimum_temperature`.
`step`	Required parameter defining the target temperature adjustment step presented in the mobile application and in the web interface. The allowed range is from 0.1°C to 10°C.
`persistent_state`	Optional boolean parameter with values `true` or `false`. When set to `true`, after a project restart the block tries to restore the last saved target temperature. This parameter applies only to the target temperature. The thermostat on/off state and the selected operating mode are remembered independently of it.

Input handling

At the main input, the block reacts to the following values:

the value true turns the thermostat on
the value false turns the thermostat off
the heating command sent from the command block switches the thermostat to heating mode
the cooling command sent from the command block switches the thermostat to cooling mode
the auto command sent from the command block switches the thermostat to automatic mode, if such a mode is allowed by the configuration

Other values delivered to the main input are ignored.

Additionally, the block supports the following inputs labeled using the tag block:

Input number and name	Description
`tag1`: Target temperature	A numeric value delivered to the `tag1` input sets a new thermostat target temperature. A value outside the range defined by the `minimum_temperature` and `maximum_temperature` parameters is ignored. If `tag1` is not connected, the target temperature may still be changed from the mobile application, the web interface, or by scenes and schedulers.
`tag2`: Measured temperature	A numeric value delivered to the `tag2` input sets the current temperature read from the sensor. A value outside the range from -270°C to 3000°C is treated as the absence of a valid measurement. In that case, the block does not switch to heating or cooling and remains in the `idle` state unless it has been turned off earlier.

At most one tag block may be connected to each of the tag1 and tag2 inputs. A larger number of such connections is a configuration error.

The block may also operate without any input connections, but without a valid measured temperature it will not switch to heating or cooling automatically.

Thermostat operating rules

The block uses the target temperature, the measured temperature, and the hysteresis parameter to determine the current operating state.

If the thermostat is turned off, it does not heat and does not cool regardless of the temperatures.

If either a valid target temperature or a valid measured temperature is missing, the block switches to the idle state.

In automatic mode:

when the measured temperature drops below target_temperature - hysteresis, the thermostat switches to heating
when the measured temperature rises above target_temperature + hysteresis, the thermostat switches to cooling
if the thermostat is already heating, it returns to the idle state after the target temperature is reached
if the thermostat is already cooling, it returns to the idle state after the temperature drops to the target value

In heating-only mode or cooling-only mode:

the operating state is changed only after the temperature leaves the hysteresis band
in heating mode, the thermostat starts heating when the temperature drops below target_temperature - hysteresis
in cooling mode, the thermostat starts cooling when the temperature rises above target_temperature + hysteresis
once operation has started, the thermostat keeps its current state until the opposite hysteresis boundary is crossed

In practice, this means that in heating-only mode heating is turned off only after the temperature rises above target_temperature + hysteresis, and in cooling-only mode cooling is turned off only after the temperature drops below target_temperature - hysteresis.

Block outputs

Output number and name	Description
1. Target temperature	Returns the current thermostat target temperature as a temperature value. The output is emitted after a valid target temperature has been set.
2. Heating state	Returns true when the thermostat is currently heating. In all other states it returns false.
3. Cooling state	Returns true when the thermostat is currently cooling. In all other states it returns false.
4. Thermostat off state	Returns true when the thermostat is turned off. The `idle` state does not set this output to true.

If the thermostat is in the idle state, outputs 2, 3, and 4 all return false at the same time.

Errors returned by the block

The block can return the following errors:

Error code	Error description
`Invalid heating mode configuration.`	The `heating_mode` parameter was not provided or has an invalid value.
`Invalid cooling mode configuration.`	The `cooling_mode` parameter was not provided or has an invalid value.
`Both heating and cooling modes are not supported.`	Both heating and cooling support were disabled at the same time. The block must support at least one of these modes.
`Invalid auto mode configuration.`	The `auto_mode` parameter was not provided or has an invalid value.
`Auto mode is supported but heating mode is not supported.`	`auto_mode` was enabled, but `heating_mode` was disabled.
`Auto mode is supported but cooling mode is not supported.`	`auto_mode` was enabled, but `cooling_mode` was disabled.
`Invalid hysteresis temperature.`	The `hysteresis` parameter is invalid or outside the allowed range.
`Invalid minimum temperature.`	The `minimum_temperature` parameter is invalid or outside the allowed range.
`Invalid maximum temperature.`	The `maximum_temperature` parameter is invalid or outside the allowed range.
`Minimum temperature greater/equal than maximum temperature.`	The `minimum_temperature` value is greater than or equal to `maximum_temperature`.
`Invalid step temperature.`	The `step` parameter is invalid or outside the allowed range.
`Too many tag1 connections.`	More than one `tag` block was connected to the `tag1` input.
`Too many tag2 connections.`	More than one `tag` block was connected to the `tag2` input.

Usage examples

If the block operates in heating-only mode, target_temperature = 22.0°C, hysteresis = 0.5°C, and the measured temperature drops to 21.4°C, output 2 will switch to true.
In the same configuration, heating will not turn off at 22.0°C, but only after the temperature rises above 22.5°C.
If the block operates in automatic mode, target_temperature = 22.0°C, hysteresis = 0.5°C, and the measured temperature drops to 21.4°C, the thermostat starts heating. After the temperature rises to 22.0°C, it switches to the idle state.
If the block operates in automatic mode, target_temperature = 22.0°C, hysteresis = 0.5°C, and the measured temperature rises to 22.6°C, the thermostat starts cooling.
If the value false is delivered to the main input, output 4 switches to true, and outputs 2 and 3 switch to false regardless of the temperatures.