# Valves (over_valve)

The `over_valve` type controls an equipment that can take a value from 0 to 100 %. At 0, heating is off, and at 100 % it is fully open. This type allows controlling a thermostatic valve (e.g., Shelly valve) that exposes a `number` type entity, enabling direct control of the valve's opening. Versatile Thermostat regulates the room temperature by adjusting the opening percentage, using both the internal and external temperature sensors, and the TPI algorithm.

> [!NOTE]
> 1. The `over_valve` type is often confused with the `over_climate` type equipped with auto-regulation and direct valve control.
> 2. You should only choose this type when you do not have an associated `climate` entity for your _TRV_ in Home Assistant, and if you only have a `number` type entity to control the valve's opening percentage. The `over_climate` with auto-regulation on the valve is much more powerful than the `over_valve` type.

## Underlying entities

Only `number` or `input_number` entities are accepted as underlying devices. The TPI algorithm recalculates the valve's opening percentage at each cycle and modifies the value of the underlying `number` entities.

## Valve opening control

`over_valve` can adjust the TPI opening command to match the physical limits of each valve:

1. `opening_threshold_degree`: below this raw TPI percentage, the valve is considered closed.
2. `max_closing_degree`: maximum closing percentage. The command under the threshold is `100 - max_closing_degree`; keep the default `100` to close it fully.
3. `min_opening_degrees`: comma-separated minimum opening values, one per underlying valve. A value is applied as soon as the threshold is reached.
4. `max_opening_degrees`: comma-separated maximum opening values, one per underlying valve. Omitted values use the maximum supported by the related `number` entity.

It is possible to choose a `thermostat_over_valve` to control an air conditioner by checking the "AC Mode" box. In this case, only the cooling mode will be visible.

## Sleep mode

`over_valve` supports sleep mode. Selecting `sleep`, or calling the `versatile_thermostat.set_hvac_mode_sleep` action, presents VTherm as off while sending a raw 100 % opening request to every underlying valve. Sleep mode does not request central boiler heating; `is_sleeping` identifies this state.

See the full [`over_valve` documentation](https://www.versatile-thermostat.org/en/docs/over-valve/) for more details.

## Shelly BLU TRV

The Shelly BLU TRV exposes its valve position as a `number` entity and needs a Shelly BLU gateway. It is partially compatible: some valve commands are lost over Bluetooth, the device has no `off` mode, and it can become unavailable when the Bluetooth link drops.

## Compatibility status

- **Partial**: This device is supported by Versatile Thermostat, but some advanced features may not be supported. Devices: Shelly - BLU TRV

## VTherm configuration

### Initialization

Go to your settings, then integrations, then click on add a new integration. Search for Versatile Thermostat.

Click on Thermostat over a valve.

### Basic attributes

Go to the "Main attributes" section.

1. Choose a name for your thermostat
2. Set the temperature sensor for your room
3. If you are using the Zigbee protocol and you have a "last_seen" entity for your temperature sensor, fill it in.

You can validate and return to the configuration menu.

### Underlying entities

Go to the underlying entities section.

1. Add the valves that will be controlled

You can validate and return to the configuration menu.

## Community references

Additional references may be old. A bug reported on an old version of VTherm may have been corrected on a more recent version.

- [Discussion #1775 Vtherm and Shelly TRV BLU valve opening values not always consistent](https://github.com/jmcollin78/versatile_thermostat/discussions/1775)
- [#1222 ValueError: Unsupported HVAC mode: unavailable when underlying climate entity becomes temporarily unavailable](https://github.com/jmcollin78/versatile_thermostat/issues/1222)
- [Discussion #1223 ValueError: Unsupported HVAC mode: unavailable when underlying climate entity becomes temporarily unavailable](https://github.com/jmcollin78/versatile_thermostat/discussions/1223)
- [#2015 Before issuing a climate.set_hvac_mode() service call with HVACMode.OFF, Versatile Thermostat should verify that OFF is actually present in the underlying entity's hvac_modes.](https://github.com/jmcollin78/versatile_thermostat/issues/2015)
- [Discussion #1219 Presence + Motion Sensor Configuration - Guest Detection Issue](https://github.com/jmcollin78/versatile_thermostat/discussions/1219)
- [Discussion #1238 Clogging prevention for Valves](https://github.com/jmcollin78/versatile_thermostat/discussions/1238)
- [#1163 VHT can get stuck in heating mode on single thermostat.](https://github.com/jmcollin78/versatile_thermostat/issues/1163)