Advanced Configuration

Advanced Configuration

Why this feature?

VTherm's advanced configuration offers essential tools to ensure the safety and reliability of your heating system. These parameters allow you to manage situations where temperature sensors no longer communicate correctly, which could lead to dangerous or ineffective commands.

Safety Context

The absence or malfunction of a temperature sensor can be very dangerous for your home. Consider this concrete example:

Your temperature sensor becomes stuck at a value of 10°
Your VTherm of type over_climate or over_valve detects a very low temperature
It commands maximum heating of the underlying equipment
Result: the room overheats considerably

The consequences can range from simple material damage to more serious risks such as a fire or explosion (in the case of a faulty electric radiator).

Safety Mode Operating Principle

What is Safety Mode?

Safety mode is a protective mechanism that detects when temperature sensors no longer respond regularly. When data absence is detected, VTherm activates a special mode that:

Reduces immediate risk: the system no longer commands maximum power
Maintains minimum heating: ensures the home doesn't cool down excessively
Alerts you: by changing the thermostat's state, visible in Home Assistant

When does it activate?

Safety mode triggers when:

Missing internal temperature: no measurement received since the configured maximum delay
Missing external temperature: no measurement received since the configured maximum delay (optional)
Stuck sensor: the sensor no longer sends value changes (typical behavior of battery-powered sensors)

A particular challenge comes from battery-powered sensors that only send data when a value changes. It's therefore possible to receive no updates for several hours without the sensor being truly faulty. This is why the parameters are configurable to adapt detection to your setup.

Limitations

VTherm of type over_climate self-regulated: safety mode is automatically disabled. Indeed, there is no danger risk if the equipment regulates itself (it maintains its own temperature). The only risk is an uncomfortable temperature, not a physical danger.

Configuration

To configure advanced safety parameters:

Open your VTherm configuration
Access general configuration parameters
Scroll down to the "Advanced Configuration" section

The advanced configuration form is as follows:

Advice

If your thermometer has an attribute last_seen or similar that gives the time of its last contact, configure this attribute in the main selections of your VTherm. This significantly improves detection and reduces false alerts. See basic attribute configuration and troubleshooting for more details.

Safety Parameters

Parameter	Description	Default Value	Attribute Name
Maximum delay before safety mode	Maximum allowed delay between two temperature measurements before the VTherm enters safety mode. If no new measurement is received after this delay, safety mode activates.	60 minutes	`safety_delay_min`
Minimum `on_percent` threshold for safety	Minimum percentage of `on_percent` below which safety mode does not activate. This avoids activating safety mode when the radiator is running very little (`on_percent` low), as there is no immediate risk of overheating. `0.00` always activates the mode, `1.00` completely disables it.	0.5 (50%)	`safety_min_on_percent`
Default `on_percent` value in safety mode	The heating power used when the thermostat is in safety mode. `0` completely stops heating (risk of freezing), `0.1` maintains minimum heating to prevent freezing in case of prolonged thermometer failure.	0.1 (10%)	`safety_default_on_percent`

Exposed Attributes

When safety mode is active, VTherm expose the following attributes:

safety_mode: "on"                # "on" or "off"
safety_delay_min: 60             # Configured delay in minutes
safety_min_on_percent: 0.5       # on_percent threshold (0.0 to 1.0)
safety_default_on_percent: 0.1   # Power in safety mode (0.0 to 1.0)
last_safety_event: "2024-03-20 14:30:00"  # Time of last event

Available Actions

A VTherm action allows to dynamically reconfigure the 3 safety parameters without restarting Home Assistant:

Service: versatile_thermostat.set_safety_parameters
Parameters:
- entity_id: the VTherm to reconfigure
- safety_delay_min: new delay (minutes)
- safety_min_on_percent: new threshold (0.0 to 1.0)
- safety_default_on_percent: new power (0.0 to 1.0)

This allows dynamically adapting the safety mode sensitivity according to your usage (for example, reduce the delay when people are home, increase it when the home is unoccupied).

Global Advanced Configuration

It is possible to disable checking of the outdoor temperature sensor for safety mode. Indeed, the outdoor sensor generally has little impact on regulation (depending on your settings) and can be absent without endangering the home.

To do this, add the following lines to your configuration.yaml:

versatile_thermostat:
  safety_mode:
    check_outdoor_sensor: false

Important

This change is common to all VTherm in the system

It affects outdoor thermometer detection for all thermostats

Home Assistant must be restarted for changes to take effect

By default, the outdoor thermometer can trigger safety mode if it stops sending data

Practical Tips

Notes and Best Practices

Restoration after correction: When the temperature sensor comes back to life and sends data again, the preset mode will be restored to its previous value.
Two temperatures required: The system needs both internal AND external temperature to function correctly. If either is missing, the thermostat will enter safety mode.
Relationship between parameters: For natural operation, the value safety_default_on_percent should be less than safety_min_on_percent. For example: safety_min_on_percent = 0.5 and safety_default_on_percent = 0.1.
Adaptation to your sensor:
- If you have false alerts, increase the delay (safety_delay_min) or decrease safety_min_on_percent
- If you have battery-powered sensors, increase the delay further (e.g.: 2-4 hours)
- If you use the last_seen attribute, the delay can be reduced (the system is more accurate)
UI Visualization: If you use the Versatile Thermostat UI card, a VTherm in safety mode is visually indicated by:
- A grayish veil over the thermostat
- Display of the failing sensor
- Time elapsed since last update
.

Fixing Incorrect Equipment State

Why this feature?

When using a VTherm with heating equipment (over_switch, over_valve, over_climate, over_climate_valve), it can happen that the equipment does not properly follow the command sent by the thermostat. For example:

A stuck relay that doesn't switch to the commanded state
A thermostatic valve that doesn't obey commands
A temporary loss of communication with the equipment
Equipment that takes too long to respond

The "Fix Incorrect State" feature detects these situations and automatically resends the command to synchronize the actual state with the desired state.

Use cases

This feature is particularly useful for:

Unstable relays: relays that stick or don't always switch correctly
Intermittent Zigbee/WiFi communication: equipment that occasionally loses connection
Slow valves: thermostatic valves that take time to react to commands
Faulty equipment: electric radiators or valves that no longer respond to commands
Heat pumps: to ensure the heat pump properly executes heating/cooling commands

Operating Principle

On each thermostat control cycle, the feature:

Compares states: verifies that the actual state of each equipment matches what was commanded
Detects discrepancies: if the equipment didn't follow the command, that's a discrepancy
Resends the command: if a discrepancy is detected, resends the command to synchronize the state
Counts attempts: the number of consecutive repairs is limited to avoid infinite loops
Controls activation delay: the feature only activates after a minimum delay to let equipment finish initializing

Configuration

This feature is configured in the VTherm configuration interface:

Open your VTherm configuration
Access general configuration parameters
Scroll down to the "Advanced Configuration" section
Enable the "Fix incorrect equipment state" option

Parameters

Parameter	Description	Default Value
Fix incorrect state	Enables or disables automatic detection and repair of state discrepancies. When enabled, each detected discrepancy triggers a command resend.	Disabled

Internal System Parameters

Some parameters are configured at system level and cannot be modified:

Minimum delay before activation: 30 seconds after thermostat startup (allows all equipment to initialize)

Maximum consecutive attempts: 5 consecutive repairs before temporarily stopping

Reset delay: the repair counter resets once equipment returns to correct state

Exposed Attributes

When the repair feature is enabled, VTherm expose the following attribute:

repair_incorrect_state_manager:
  consecutive_repair_count: 2       # Number of consecutive repairs performed
  max_attempts: 5                   # Cap before temporary stop
  min_delay_after_init_sec: 30      # Minimum delay before activation
is_repair_incorrect_state_configured: true  # Feature status

The consecutive_repair_count counter allows you to:

Diagnose frequent hardware issues
Identify faulty equipment
Monitor your installation's stability

Limitations and Safety

Important

No behavior change: This feature does not change the heating logic. It simply ensures your commands are properly executed.
Safety cap: The maximum consecutive attempts (5) prevents infinite loops. If this cap is reached, an error is logged and repairs temporarily stop.
Startup delay: The feature only activates after 30 seconds to allow all equipment time to fully initialize.
Applicable to all VTherm types: This feature works for all types over_switch, over_valve, over_climate and over_climate_valve (the over_climate with direct valve control regulation). For the latter, the state of the underlying climate is verified as well as the valve opening state.
Overactivity symptoms: If you regularly see warning messages indicating a repair, it means there is a hardware issue:
- Check equipment connection
- Check network stability (Zigbee/WiFi)
- Test equipment manually via Home Assistant
- Consider replacement if the issue persists
Counter reset: The counter automatically resets as soon as equipment returns to the correct state, allowing new attempts in case of intermittent issues.
Regular retry: after 5 failed repair attempts, repair pauses to avoid infinite loops. It resumes after 10 cycles without repair, allowing new attempts in case of intermittent problems.