Skip to content

Latest commit

 

History

History
100 lines (64 loc) · 8.16 KB

quick-start.md

File metadata and controls

100 lines (64 loc) · 8.16 KB

Quick Start

This page outlines the steps to quickly set up a basic yet operational VTherm. It is structured by equipment type.

Nodon SIN-4-FP-21 or similar (pilot wire)

This module allows controlling a radiator via a pilot wire. It appears in HA as a select entity that lets you choose the heating preset to apply.

VTherm will regulate the temperature by periodically changing the preset via customized commands until the setpoint is reached.

For this to work, the preset used for heating control must be higher than the maximum temperature you will need (24°C is a good value).

To integrate it into VTherm, you must:

  1. Create a VTherm of type over_switch. See creating a VTherm,
  2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See main attributes,
  3. Assign one or more underlying devices to control. The underlying device here is the select entity that controls the Nodon. See underlying devices,
  4. Provide custom on/off commands (mandatory for the Nodon). See command customization. The custom commands follow the format select_option/option:<preset> as indicated in the link.

After completing these four steps, you will have a fully functional VTherm that controls your Nodon or similar device.

Heatzy, eCosy, or similar (climate entity)

This module allows controlling a radiator that appears in HA as a climate entity, enabling you to choose the heating preset or mode (Heat / Cool / Off).

VTherm will regulate the temperature by turning the device on/off via customized commands at regular intervals until the setpoint is reached.

To integrate it into VTherm, you must:

  1. Create a VTherm of type over_switch. See creating a VTherm,
  2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See main attributes,
  3. Assign one or more underlying devices to control. The underlying device here is the climate entity that controls the Heatzy or eCosy. See underlying devices,
  4. Provide custom on/off commands (mandatory). See command customization. The custom commands follow the format set_hvac_mode/hvac_mode:<mode> or set_preset_mode/preset_mode:<preset> as indicated in the link.

After completing these four steps, you will have a fully functional VTherm that controls your Heatzy, eCosy, or similar device.

Simple switch such as Aqara T1, Nous B2Z, Sonoff ZBMini, Sonoff POW, ...

This module allows controlling a radiator via a simple switch. It appears in HA as a switch entity that directly turns the radiator on or off.

VTherm will regulate the temperature by periodically turning the switch on and off until the setpoint is reached.

To integrate it into VTherm, you must:

  1. Create a VTherm of type over_switch. See creating a VTherm,
  2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See main attributes,
  3. Assign one or more underlying devices to control. The underlying device here is the switch entity that controls the switch. See underlying devices.

After completing these three steps, you will have a fully functional VTherm that controls your switch or similar device.

Sonoff TRVZB or similar (TRV with valve control)

This type of TRV device controls the opening of a valve that allows more or less hot water from a boiler or heat pump to flow. It appears in HA as a climate entity along with number entities that control the valve. These number entities may be hidden and need to be explicitly added in some cases.

VTherm will adjust the valve opening degree until the setpoint temperature is reached.

To integrate it into VTherm, you must:

  1. Create a VTherm of type over_climate. See creating a VTherm,
  2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See main attributes,
  3. Assign one or more underlying devices to control. The underlying device here is the climate entity that controls the TRV. See underlying devices,
  4. Specify the regulation type as Direct valve control only. Leave the option Compensate for underlying temperature unchecked. See auto-regulation,
  5. Provide the number entities named opening_degree and calibration_offset. Do not configure the closing_degree entity. See underlying devices.

For this to work, the closing degree must be set to the maximum (100%). Do not immediately enable the Follow underlying temperature change option until you have verified that this basic configuration is working properly.

After completing these five steps, you will have a fully functional VTherm that controls your Sonoff TRVZB or similar device.

Reversible HP Units, Air Conditioning, or Devices Controlled via a climate Entity

Reversible heat pumps (HP) or similar devices are represented in HA as a climate entity, allowing you to select the heating preset or mode (Heat / Cool / Off).)

VTherm will regulate the temperature by controlling the target temperature and mode of the device through commands sent to the underlying climate entity.

To integrate it into VTherm, you need to:

  1. Create a VTherm of type over_climate. See creating a VTherm,
  2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at minimum). See main attributes,
  3. Define one or more underlying devices to control. The underlying entity here is the climate entity that manages the heat pump or air conditioner. See underlying devices,

After these three steps, you will have a fully operational VTherm to control your heat pump, air conditioner, or similar device.

To go further, self-regulation may be necessary depending on how well your device operates. Self-regulation involves VTherm slightly adjusting the target temperature to encourage the device to heat or cool more or less until the desired setpoint is reached. Self-regulation is explained in detail here: self-regulation.

Next Steps

Once created, you need to configure the preset temperatures. See presets for a minimal configuration. You can also (optional but recommended) install the dedicated UI card for your dashboards. (See VTHerm UI Card)

Once this minimal setup is functional—and only once it works correctly—you can add additional features such as presence detection to avoid heating when no one is present. Add them one by one, verifying that VTherm reacts correctly at each step before proceeding to the next.

You can then set up centralized configurations to share settings across all VTherm instances, enable central mode for unified control of all VTherms (centralized configuration), or integrate a central boiler control (central boiler). This is not an exhaustive list—please refer to the table of contents for a complete list of VTherm features.

Call for Contributions

This page is open for contributions. Feel free to suggest additional equipment and minimal configuration setups.