Documentation for the template/climate component

components/climate/template.rst

@@ -0,0 +1,118 @@
+Template Climate
+================
+
+.. seo::
+    :description: Instructions for setting up template climate controllers with ESPHome.
+    :image: description.svg
+
+The ``template`` climate platform allows you to create a climate controller which combines the state
+of other components.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    climate:
+      - platform: template
+        name: "LG Therma"
+        target_temperature_id: climate_target_temperature
+        current_temperature_id: climate_current_temperature
+        mode_id: climate_mode
+        fan_mode_id: climate_fan_mode
+        action_id: climate_action
+        supported_modes:
+          - "OFF"
+          - "COOL"
+          - "HEAT"
+          - "AUTO"
+        supported_fan_modes:
+          - "ON"
+          - "QUIET"
+        visual:
+          temperature_step: 0.5C
+
+Configuration variables:
+------------------------
+
+- **target_temperature_id** (*Required*, :ref:`Number <config-number>`):
+  A Number which stores the target temperature.
+- **current_temperature_id** (*Required*, :ref:`Sensor <config-sensor>`):
+  A sensor to read the current temperature from.
+- **mode_id** (*Required*, :ref:`Select <config-select>`):
+  A select that configures the desired operation of the device.
+- **fan_mode_id** (*Optional*, :ref:`Select <config-select>`):
+- **swing_mode_id** (*Optional*, :ref:`Select <config-select>`):
+- **preset_id** (*Optional*, :ref:`Select <config-select>`):
+- **action_id** (*Optional*, :ref:`TextSensor <config-text_sensor>`):
+  A text sensor that returns the current operation state of the device.
+- **supported_modes** (*Required*, list):
+  List of the modes supported by `mode_id`. Items must be members of the set of valid climate modes.
+  The respective Select must be able to handle all these items.
+- **supported_fan_modes** (*Optional*, list)
+- **supported_swing_modes** (*Optional*, list)
+- **supported_presets** (*Optional*, list)
+- All other options from :ref:`Climate <config-climate>`.
+
+.. _climate-template-select:
+
+Templated Selects
+-----------------
+
+It may very well be that the Select of the device you are configuring does not map well to the
+states required by the Climate component. In this case, you can choose to use a template Select to
+route specific states to the right components:
+
+.. code-block:: yaml
+
+    select:
+        # This select routes the OFF state to a switch, and the other states to a select.
+      - platform: template
+        id: climate_mode
+        lambda: !lambda |-
+            return id(lg_therma_active).state
+                 ? id(lg_therma_mode).state
+                 : std::string("OFF");
+        update_interval: 1s
+        set_action:
+          - if:
+              condition:
+                lambda: 'return x != "OFF";'
+              then:
+                - switch.turn_on: lg_therma_active
+                - select.set:
+                    id: lg_therma_mode
+                    option: !lambda return x;
+              else:
+                - switch.turn_off: lg_therma_active
+        options:
+          - "OFF"
+          - "COOL"
+          - "HEAT"
+          - "AUTO"
+
+        # This select handles the states for when the device is active.
+      - platform: modbus_controller
+        id: lg_therma_mode
+        address: 0
+        value_type: U_WORD
+        optionsmap:
+          "COOL": 0
+          "HEAT": 4
+          "AUTO": 5
+
+    switch:
+        # This switch determines whether the device is active.
+      - platform: modbus_controller
+        id: lg_therma_active
+        modbus_controller_id: lg
+        register_type: coil
+        address: 0
+
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :ref:`automation`
+- :apiref:`template/sensor/template_sensor.h`
+- :ghedit:`Edit`
+

index.rst

@@ -768,6 +768,7 @@ Climate Components
     Thermostat Controller, components/climate/thermostat, air-conditioner.svg, dark-invert
     Tuya Climate, components/climate/tuya, tuya.png
     Uponor Smatrix Base Pulse Underfloor Heating, components/uponor_smatrix, uponor.svg
+    Template Climate, components/climate/template, folder-open.svg, dark-invert
 
 Cover Components
 ----------------