# Troubleshooting - [Troubleshooting](#troubleshooting) - [Using a Heatzy](#using-a-heatzy) - [Using a radiator with a pilot wire (Nodon SIN-4-FP-21)](#using-a-radiator-with-a-pilot-wire-nodon-sin-4-fp-21) - [Using a Netatmo System](#using-a-netatmo-system) - [Only the first radiator heats](#only-the-first-radiator-heats) - [The radiator heats even though the setpoint temperature is exceeded, or it does not heat when the room temperature is well below the setpoint](#the-radiator-heats-even-though-the-setpoint-temperature-is-exceeded-or-it-does-not-heat-when-the-room-temperature-is-well-below-the-setpoint) - [Type `over_switch` or `over_valve`](#type-over_switch-or-over_valve) - [Type `over_climate`](#type-over_climate) - [Adjust the window open detection parameters in auto mode](#adjust-the-window-open-detection-parameters-in-auto-mode) - [Why is my Versatile Thermostat going into Safety Mode?](#why-is-my-versatile-thermostat-going-into-safety-mode) - [How to detect Safety Mode?](#how-to-detect-safety-mode) - [How to Be Notified When This Happens?](#how-to-be-notified-when-this-happens) - [How to Fix It?](#how-to-fix-it) - [Using a Group of People as a Presence Sensor](#using-a-group-of-people-as-a-presence-sensor) - [Enable Logs for the Versatile Thermostat](#enable-logs-for-the-versatile-thermostat) - [Use the log-collector (recommended method)](#use-the-log-collector-recommended-method) - [Enable logs in Home Assistant (old method)](#enable-logs-in-home-assistant-old-method) - [VTherm does not track setpoint changes made directly on the underlying device (`over_climate`)](#vtherm-does-not-track-setpoint-changes-made-directly-on-the-underlying-device-over_climate) - [VTherm Automatically Switches to 'Cooling' or 'Heating' Mode](#vtherm-automatically-switches-to-cooling-or-heating-mode) - [Open Window Detection Does Not Prevent Preset Changes](#open-window-detection-does-not-prevent-preset-changes) - [Example:](#example) - [Error stabilization\_threshold is an invalid option](#error-stabilization_threshold-is-an-invalid-option) - [Error stabilization\_threshold is an invalid option](#error-stabilization_threshold-is-an-invalid-option) ## Using a Heatzy The Heatzy is now natively supported by _VTherm_. See [Quick Start](quick-start.md#heatzy-or-ecosy-or-similar-climate-entity). This configuration is kept for reference only. Using a Heatzy or Nodon is possible provided you use a virtual switch with this model: ```yaml - platform: template switches: chauffage_sdb: unique_id: chauffage_sdb friendly_name: Bathroom heating value_template: "{{ is_state_attr('climate.bathroom', 'preset_mode', 'comfort') }}" icon_template: >- {% if is_state_attr('climate.bathroom', 'preset_mode', 'comfort') %} mdi:radiator {% elif is_state_attr('climate.bathroom', 'preset_mode', 'away') %} mdi:snowflake {% else %} mdi:radiator-disabled {% endif %} turn_on: service: climate.set_preset_mode entity_id: climate.bathroom data: preset_mode: "comfort" turn_off: service: climate.set_preset_mode entity_id: climate.bathroom data: preset_mode: "eco" ``` Thanks to @gael for this example. ## Using a radiator with a pilot wire (Nodon SIN-4-FP-21) The Nodon is now natively supported by _VTherm_. See [Quick Start](quick-start.md#nodon-sin-4-fp-21-or-similar-pilot-wire). This configuration is kept for reference only. As with the Heatzy above, you can use a virtual switch that will change the preset of your radiator based on the VTherm’s on/off state. Example: ```yaml - platform: template switches: chauffage_chb_parents: unique_id: chauffage_chb_parents friendly_name: Chauffage chambre parents value_template: "{{ is_state('select.fp_chb_parents_pilot_wire_mode', 'comfort') }}" icon_template: >- {% if is_state('select.fp_chb_parents_pilot_wire_mode', 'comfort') %} mdi:radiator {% elif is_state('select.fp_chb_parents_pilot_wire_mode', 'frost_protection') %} mdi:snowflake {% else %} mdi:radiator-disabled {% endif %} turn_on: service: select.select_option target: entity_id: select.fp_chb_parents_pilot_wire_mode data: option: comfort turn_off: service: select.select_option target: entity_id: select.fp_chb_parents_pilot_wire_mode data: option: eco ``` Another more complex example is [here](https://github.com/jmcollin78/versatile_thermostat/discussions/431#discussioncomment-11393065) ## Using a Netatmo System The system based on Netatmo TRVs does not work well with _VTherm_. You can find a discussion about the specific behavior of Netatmo systems (in French) here: [https://forum.hacf.fr/t/vannes-netatmo-et-vtherm/56063](https://forum.hacf.fr/t/vannes-netatmo-et-vtherm/56063). However, some users have successfully integrated _VTherm_ with Netatmo by incorporating a virtual switch between _VTherm_ and the Netatmo `climate` entity, as follows: ``` TODO ``` ## Only the first radiator heats In `over_switch` mode, if multiple radiators are configured for the same VTherm, the heating will be triggered sequentially to smooth out the consumption peaks as much as possible. This is completely normal and intentional. It is described here: [For a thermostat of type ```thermostat_over_switch```](over-switch.md#over_switch-type-thermostat) ## The radiator heats even though the setpoint temperature is exceeded, or it does not heat when the room temperature is well below the setpoint ### Type `over_switch` or `over_valve` With a VTherm of type `over_switch` or `over_valve`, this issue simply indicates that the TPI algorithm parameters are not properly configured. See [TPI Algorithm](algorithms.md#the-tpi-algorithm) to optimize the settings. ### Type `over_climate` With a VTherm of type `over_climate`, the regulation is handled directly by the underlying `climate`, and VTherm simply transmits the setpoints to it. So if the radiator is heating even though the setpoint temperature is exceeded, it is likely that its internal temperature measurement is biased. This often happens with TRVs and reversible air conditioners that have an internal temperature sensor, either too close to the heating element (so it's too cold in winter). Examples of discussions on these topics: [#348](https://github.com/jmcollin78/versatile_thermostat/issues/348), [#316](https://github.com/jmcollin78/versatile_thermostat/issues/316), [#312](https://github.com/jmcollin78/versatile_thermostat/discussions/312), [#278](https://github.com/jmcollin78/versatile_thermostat/discussions/278) To resolve this, VTherm is equipped with a feature called self-regulation, which allows it to adjust the setpoint sent to the underlying device until the setpoint is met. This function compensates for the bias of internal temperature sensors. If the bias is significant, the regulation should also be significant. See [Self-regulation](self-regulation.md) for configuring self-regulation. ## Adjust the window open detection parameters in auto mode If you are unable to configure the automatic window open detection function (see [auto](feature-window.md#auto-mode)), you can try modifying the temperature smoothing algorithm parameters. Indeed, the automatic window open detection is based on calculating the temperature slope. To avoid artifacts caused by an imprecise temperature sensor, this slope is calculated using a temperature smoothed with an algorithm called Exponential Moving Average (EMA). This algorithm has 3 parameters: 1. `lifecycle_sec`: the duration in seconds considered for smoothing. The higher it is, the smoother the temperature will be, but the detection delay will also increase. 2. `max_alpha`: if two temperature readings are far apart in time, the second one will carry much more weight. This parameter limits the weight of a reading that comes well after the previous one. This value must be between 0 and 1. The lower it is, the less distant readings are taken into account. The default value is 0.5, meaning that a new temperature reading will never weigh more than half of the moving average. 3. `precision`: the number of digits after the decimal point retained for calculating the moving average. To change these parameters, you need to modify the `configuration.yaml` file and add the following section (the values below are the default values): ```yaml versatile_thermostat: short_ema_params: max_alpha: 0.5 halflife_sec: 300 precision: 2 ``` These parameters are sensitive and quite difficult to adjust. Please only use them if you know what you’re doing and if your temperature readings are not already smoothed. ## Why is my Versatile Thermostat going into Safety Mode? Safety mode is only available for VTherm types `over_switch` and `over_valve`. It occurs when one of the two thermometers (providing either the room temperature or the external temperature) has not sent a value for more than `safety_delay_min` minutes, and the radiator had been heating at least `safety_min_on_percent`. See [safety mode](feature-advanced.md#safety-mode) Since the algorithm relies on temperature measurements, if they are no longer received by the VTherm, there is a risk of overheating and fire. To prevent this, when the above conditions are detected, heating is limited to the `safety_default_on_percent` parameter. This value should therefore be reasonably low (10% is a good value). It helps avoid a fire while preventing the radiator from being completely turned off (risk of freezing). All these parameters are configured on the last page of the VTherm configuration: "Advanced Settings". ### How to detect Safety Mode? The first symptom is an unusually low temperature with a short and consistent heating time during each cycle. Example: [security mode](images/security-mode-symptome1.png) If you have installed the [Versatile Thermostat UI Card](https://github.com/jmcollin78/versatile-thermostat-ui-card), the affected VTherm will appear like this: [security mode UI Card](images/security-mode-symptome2.png) You can also check the VTherm's attributes for the dates of the last received values. **The attributes are available in the Developer Tools / States**. Example: ```yaml safety_state: true last_temperature_datetime: "2023-12-06T18:43:28.346010+01:00" last_ext_temperature_datetime: "2023-12-06T13:04:35.164367+01:00" last_update_datetime: "2023-12-06T18:43:28.351103+01:00" ... safety_delay_min: 60 ``` We can see that: 1. The VTherm is indeed in safety mode (`safety_state: true`), 2. The current time is 06/12/2023 at 18:43:28 (`last_update_datetime: "2023-12-06T18:43:28.351103+01:00"`), 3. The last reception time of the room temperature is 06/12/2023 at 18:43:28 (`last_temperature_datetime: "2023-12-06T18:43:28.346010+01:00"`), so it's recent, 4. The last reception time of the external temperature is 06/12/2023 at 13:04:35 (`last_ext_temperature_datetime: "2023-12-06T13:04:35.164367+01:00"`). The external temperature is over 5 hours late, which triggered the safety mode, as the threshold is set to 60 minutes (`safety_delay_min: 60`). ### How to Be Notified When This Happens? The VTherm sends an event as soon as this happens and again at the end of the safety alert. You can capture these events in an automation and send a notification, blink a light, trigger a siren, etc. It's up to you. For handling events generated by VTherm, see [Events](reference.md#events). ### How to Fix It? It depends on the cause of the problem: 1. If a sensor is faulty, it should be repaired (replace batteries, change it, check the weather integration that provides the external temperature, etc.), 2. If the `safety_delay_min` parameter is too small, it may generate many false alerts. A correct value is around 60 minutes, especially if you have battery-powered temperature sensors. See [my settings](tuning-examples.md#battery-powered-temperature-sensor), 3. Some temperature sensors don't send measurements if the temperature hasn't changed. So if the temperature stays very stable for a long time, safety mode can trigger. This is not a big issue since it will deactivate once the VTherm receives a new temperature. On some thermometers (e.g., TuYA or Zigbee), you can force a max delay between two measurements. The max delay should be set to a value lower than `safety_delay_min`, 4. As soon as the temperature is received again, safety mode will turn off, and the previous preset, target temperature, and mode values will be restored. 5. If the external temperature sensor is faulty, you can disable safety mode triggering as it has a minimal impact on the results. To do so, see [here](feature-advanced.md#safety-mode). ## Using a Group of People as a Presence Sensor Unfortunately, groups of people are not recognized as presence sensors. Therefore, you cannot use them directly in VTherm. A workaround is to create a binary sensor template with the following code: File `template.yaml`: ```yaml - binary_sensor: - name: maison_occupee unique_id: maison_occupee state: "{{is_state('person.person1', 'home') or is_state('person.person2', 'home') or is_state('input_boolean.force_presence', 'on')}}" device_class: occupancy ``` In this example, note the use of an `input_boolean` called `force_presence`, which forces the sensor to `True`, thereby forcing any VTherm that uses it to have active presence. This can be used, for example, to trigger a pre-heating of the house when leaving work or when an unrecognized person is present in HA. File `configuration.yaml`: ```yaml ... template: !include templates.yaml ... ``` ## Enable Logs for the Versatile Thermostat ### Use the log-collector (recommended method) To collect and analyze Versatile Thermostat logs, **it is strongly recommended to use the integrated log download feature** (log-collector). This method: - ✅ Collects logs **independently of the level configured in Home Assistant** - ✅ Does not affect Home Assistant performance - ✅ Allows filtering by period, thermostat, and severity level - ✅ Provides an easy-to-analyze downloadable file See the full documentation: [Download Past Logs - Diagnosis and Troubleshooting](feature-logs-collector.md) ### Enable logs in Home Assistant (old method) If you need a more advanced debugging mode, you can enable logs at the Home Assistant level by editing the `logger.yaml` file: ```yaml logger: default: warning logs: custom_components.versatile_thermostat: debug ``` You must reload the YAML configuration (Developer Tools / YAML / Reload all YAML configuration) or restart Home Assistant for this change to take effect. ⚠️ **Warning**: In debug mode, Versatile Thermostat is very verbose and may slow down Home Assistant or saturate your hard drive. This approach is only recommended for advanced debugging over a short duration. **Prefer the log-collector in all normal cases.** ## VTherm does not track setpoint changes made directly on the underlying device (`over_climate`) See the details of this feature [here](over-climate.md#track-underlying-temperature-changes). ## VTherm Automatically Switches to 'Cooling' or 'Heating' Mode Some reversible heat pumps have modes that allow the heat pump to decide whether to heat or cool. These modes are labeled as 'Auto' or 'Heat_cool' depending on the brand. These two modes should not be used with _VTherm_ because _VTherm_'s algorithms require explicit knowledge of whether the system is in heating or cooling mode, which these modes do not provide. You should only use the following modes: `Heat`, `Cool`, `Off`, or optionally `Fan` (although `Fan` has no practical purpose with _VTherm_). ## Open Window Detection Does Not Prevent Preset Changes Indeed, preset changes while a window is open are taken into account, and this is the expected behavior. If the action mode is set to _Turn Off_ or _Fan Only_, the preset change and target temperature adjustment are applied immediately. Since the device is either turned off or in fan-only mode, there is no risk of heating the outside. When the device mode switches to Heating or Cooling, the preset and temperature will be applied and used. If the action mode is set to _Frost Protection_ or _Eco_, the preset temperature is applied, **but the preset itself remains unchanged**. This allows for preset changes while the window is open without altering the setpoint temperature, which remains as programmed in the action mode. ### Example: 1. **Initial state**: Window closed, action mode set to _Frost Protection_, preset on Comfort, and setpoint temperature at 19°C. 2. **Window opens and system waits**: The preset remains on Comfort, **but the setpoint temperature switches to 10°C** (frost protection). This state may seem inconsistent because the displayed preset does not match the applied setpoint temperature. 3. **Preset change to Boost** (by the user or the Scheduler): The preset switches to Boost, but the setpoint temperature remains at 10°C (frost protection). This state may also appear inconsistent. 4. **Window closes**: The preset remains on Boost, and the setpoint temperature changes to 21°C (Boost). The inconsistency disappears, and the user's preset change is correctly applied. ## Error stabilization_threshold is an invalid option This error happend after an upgrade from version 8.6.0 (and below) to version 8.6.1 (or above), for users who use the self regulation feature in expert mode. In this mode, they was a setting `stabilization_threshold` to write in your `configuration.yaml`. This setting is not used anymore since many years and was removed. You need to remove it from your `configuration.yaml`.