Issue #872 (#886)

* ConfigFlow (translation to change)

* +1

* With implemn in thermostat_switch (not finished)

* GUI fixe

* +1

* Select Working

* Test input in config_flow ok

* documentation

* Add github copilot
Add first test ok for UnderlyingSwitch

* All tests ok

* Fix warnings

* Fix All tests ok

* Translations

* safety

* Add quick-start documentation

---------

Co-authored-by: Jean-Marc Collin <jean-marc.collin-extern@renault.com>

documentation/en/over-switch.md

@@ -3,10 +3,11 @@
 - [`over_switch` Type Thermostat](#over_switch-type-thermostat)
   - [Prerequisites](#prerequisites)
   - [Configuration](#configuration)
-    - [The Underlying Entities](#the-underlying-entities)
+    - [The underlying devices](#the-underlying-devices)
     - [Keep-Alive](#keep-alive)
     - [AC Mode](#ac-mode)
     - [Command Inversion](#command-inversion)
+    - [Command Customization](#command-customization)
 
 
 ## Prerequisites
@@ -18,8 +19,8 @@ The installation should look like this:
 1. The user or automation, or the Scheduler, sets a setpoint via a preset or directly using a temperature.
 2. Periodically, the internal thermometer (2) or external thermometer (2b) sends the measured temperature. The internal thermometer should be placed in a relevant spot for the user's comfort: ideally in the middle of the living space. Avoid placing it too close to a window or too near the radiator.
 3. Based on the setpoint values, the different temperatures, and the TPI algorithm parameters (see [TPI](algorithms.md#lalgorithme-tpi)), VTherm will calculate a percentage of the on-time.
-4. It will then regularly command the turning on and off of the underlying `switch` entities.
-5. These underlying switch entities will control the physical switch.
+4. It will then regularly command the turning on and off of the underlying `switch` (or `select` or `climate`) entities.
+5. These underlying entities will control the physical device.
 6. The physical switch will turn the radiator on or off.
 
 > The on-time percentage is recalculated each cycle, which is what allows regulating the room temperature.
@@ -31,8 +32,11 @@ Then, click on the "Underlying Entities" option from the menu, and you will see
 
 ![image](images/config-linked-entity.png)
 
-### The Underlying Entities
-In the "Equipment to Control" list, you should add the switches that will be controlled by VTherm. Only `switch` or `input_boolean` entities are accepted.
+### The underlying devices
+
+In the "list of devices to control," you add the switches that will be controlled by VTherm. Only entities of type `switch`, `input_boolean`, `select`, `input_select`, or `climate` are accepted.
+
+If one of the underlying devices is not a `switch`, then command customization is mandatory. By default, for `switch` entities, the commands are the standard switch on/off commands (`turn_on`, `turn_off`).
 
 The algorithm currently available is TPI. See [algorithm](#algorithm).
 If multiple entities are configured, the thermostat staggers the activations to minimize the number of switches on at any given time. This allows for better power distribution, as each radiator will turn on in turn.
@@ -53,4 +57,39 @@ It is possible to choose a `thermostat_over_switch` to control an air conditione
 
 ### Command Inversion
 
-If your equipment is controlled by a pilot wire with a diode, you may need to check the "Invert the Command" box. This will set the switch to `On` when you need to turn off the equipment and to `Off` when you need to turn it on. The cycle times will be inverted with this option.
+If your equipment is controlled by a pilot wire with a diode, you may need to check the "Invert the Command" box. This will set the switch to `On` when you need to turn off the equipment and to `Off` when you need to turn it on. The cycle times will be inverted with this option.
+
+### Command Customization
+
+This configuration section allows you to customize the on and off commands sent to the underlying device.
+These commands are mandatory if one of the underlying devices is not a `switch` (for `switch` entities, standard on/off commands are used).
+
+To customize the commands, click on `Add` at the bottom of the page for both the on and off commands:
+
+![virtual switch](images/config-vswitch1.png)
+
+Then, specify the on and off commands using the format `command[/attribute[:value]]`.
+The available commands depend on the type of underlying device:
+
+| Underlying Device Type      | Possible On Commands                  | Possible Off Commands               | Applies To                    |
+| --------------------------- | ------------------------------------- | ----------------------------------- | ----------------------------- |
+| `switch` or `input_boolean` | `turn_on`                             | `turn_off`                          | All switches                  |
+| `select` or `input_select`  | `select_option/option:comfort`        | `set_option/option:frost`           | Nodon SIN-4-FP-21 and similar |
+| `climate` (hvac_mode)       | `set_hvac_mode/hvac_mode:heat`        | `set_hvac_mode/hvac_mode:off`       | eCosy (via Tuya Local)        |
+| `climate` (preset)          | `set_preset_mode/preset_mode:comfort` | `set_preset_mode/preset_mode:frost` | Heatzy                        |
+
+Of course, these examples can be adapted to your specific case.
+
+Example for a Nodon SIN-4-FP-21:
+![virtual switch Nodon](images/config-vswitch2.png)
+
+Click "Validate" to confirm the modifications.
+
+If the following error occurs:
+
+> The command customization configuration is incorrect. It is required for non-switch underlying devices, and the format must be 'service_name[/attribute:value]'. More details in the README.
+
+This means that one of the entered commands is invalid. The following rules must be followed:
+1. Each command must follow the format `command[/attribute[:value]]` (e.g., `select_option/option:comfort` or `turn_on`) without spaces or special characters except `_`.
+2. There must be as many commands as there are declared underlying devices, except when all underlying devices are `switch` entities, in which case command customization is not required.
+3. If multiple underlying devices are configured, the commands must be in the same order. The number of on commands must equal the number of off commands and the number of underlying devices (in the correct order). It is possible to mix different types of underlying devices. As soon as one underlying device is not a `switch`, all commands for all underlying devices, including `switch` entities, must be configured.

documentation/en/quick-start.md

@@ -0,0 +1,84 @@
+# Quick Start
+
+This page outlines the steps to quickly set up a basic yet operational _VTherm_. It is structured by equipment type.
+
+- [Quick Start](#quick-start)
+  - [Nodon SIN-4-FP-21 or similar (pilot wire)](#nodon-sin-4-fp-21-or-similar-pilot-wire)
+  - [Heatzy, eCosy, or similar (`climate` entity)](#heatzy-ecosy-or-similar-climate-entity)
+  - [Simple switch such as Aqara T1, Nous B2Z, Sonoff ZBMini, Sonoff POW, ...](#simple-switch-such-as-aqara-t1-nous-b2z-sonoff-zbmini-sonoff-pow-)
+  - [Sonoff TRVZB or similar (TRV with valve control)](#sonoff-trvzb-or-similar-trv-with-valve-control)
+- [Next Steps](#next-steps)
+- [Call for Contributions](#call-for-contributions)
+
+## 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_](creation.md),
+2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See [main attributes](base-attributes.md),
+3. Assign one or more underlying devices to control. The underlying device here is the `select` entity that controls the Nodon. See [underlying devices](over-switch.md),
+4. Provide custom on/off commands (mandatory for the Nodon). See [command customization](over-switch.md#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_](creation.md),
+2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See [main attributes](base-attributes.md),
+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](over-switch.md),
+4. Provide custom on/off commands (mandatory). See [command customization](over-switch.md#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_](creation.md),
+2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See [main attributes](base-attributes.md),
+3. Assign one or more underlying devices to control. The underlying device here is the `switch` entity that controls the switch. See [underlying devices](over-switch.md).
+
+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_](creation.md),
+2. Assign it the main attributes (name, room temperature sensor, and outdoor temperature sensor at a minimum). See [main attributes](base-attributes.md),
+3. Assign one or more underlying devices to control. The underlying device here is the `climate` entity that controls the TRV. See [underlying devices](over-climate.md),
+4. Specify the regulation type as `Direct valve control` only. Leave the option `Compensate for underlying temperature` unchecked. See [auto-regulation](over-climate.md#auto-regulation),
+5. Provide the `number` entities named `opening_degree` and `calibration_offset`. Do not configure the `closing_degree` entity. See [underlying devices](over-switch.md).
+
+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.
+
+# Next Steps
+
+Once created, you need to configure the preset temperatures. See [presets](feature-presets.md) for a minimal configuration.
+You can also (optional but recommended) install the dedicated UI card for your dashboards. (See [VTHerm UI Card](https://github.com/jmcollin78/versatile-thermostat-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](feature-central-mode.md)), or integrate a central boiler control ([central boiler](feature-central-boiler.md)). 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.

documentation/en/troubleshooting.md

@@ -22,6 +22,10 @@
 
 ## 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
@@ -53,6 +57,12 @@ Using a Heatzy or Nodon is possible provided you use a virtual switch with this
 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: