From a3fd00696ab34fd50b17ce7b9f9d906ceb4fa498 Mon Sep 17 00:00:00 2001
From: Artur Pragacz <49985303+arturpragacz@users.noreply.github.com>
Date: Mon, 26 Feb 2024 19:39:51 +0100
Subject: [PATCH] Add turn on/off methods to climate entity (#2057)

* Add methods to climate entity.

Add turn_on, turn_off, toggle to climate entity.

* Mods

* blog

* Mods

* style

* link to doc

* Fix link

* Mod date

* Update docs/core/entity/climate.md

---------

Co-authored-by: G Johansson <goran.johansson@shiftit.se>
Co-authored-by: Erik Montnemery <erik@montnemery.com>
---
 blog/2024-02-25-Climate-toggle-service.md | 23 +++++++++++
 docs/core/entity/climate.md               | 48 +++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 blog/2024-02-25-Climate-toggle-service.md

diff --git a/blog/2024-02-25-Climate-toggle-service.md b/blog/2024-02-25-Climate-toggle-service.md
new file mode 100644
index 00000000..79b045f0
--- /dev/null
+++ b/blog/2024-02-25-Climate-toggle-service.md
@@ -0,0 +1,23 @@
+---
+author: G Johansson
+authorURL: https://github.com/gjohansson-ST
+title: "New Climate entity toggle method"
+---
+
+As of Home Assistant Core 2024.3 we have added a new `toggle` method to `ClimateEntity` and users can now call `climate.toggle` in their service calls.
+
+Integrations that support `turn_on` and `turn_off` implicitly also support the `toggle` method.
+
+[Read more about the toggle method in our documentation](/docs/core/entity/climate#toggle)
+
+Example (default implementation):
+
+```python
+async def async_toggle(self) -> None:
+    """Toggle the entity."""
+    if self.hvac_mode == HVACMode.OFF:
+        await self.async_turn_on()
+    else:
+        await self.async_turn_off()
+
+```
\ No newline at end of file
diff --git a/docs/core/entity/climate.md b/docs/core/entity/climate.md
index cd32d16b..3e3d6e28 100644
--- a/docs/core/entity/climate.md
+++ b/docs/core/entity/climate.md
@@ -142,6 +142,54 @@ class MyClimateEntity(ClimateEntity):
         """Set new target hvac mode."""
 ```
 
+### Turn on
+
+```python
+class MyClimateEntity(ClimateEntity):
+    # Implement one of these methods.
+    # The `turn_on` method should set `hvac_mode` to any other than
+    # `HVACMode.OFF` by optimistically setting it from the service handler
+    # or with the next state update
+
+    def turn_on(self):
+        """Turn the entity on."""
+
+    async def async_turn_on(self):
+        """Turn the entity on."""
+```
+
+### Turn off
+
+```python
+class MyClimateEntity(ClimateEntity):
+    # Implement one of these methods.
+    # The `turn_off` method should set `hvac_mode` to `HVACMode.OFF` by
+    # optimistically setting it from the service handler or with the next state update
+
+    def turn_off(self):
+        """Turn the entity off."""
+
+    async def async_turn_off(self):
+        """Turn the entity off."""
+```
+
+### Toggle
+
+```python
+class MyClimateEntity(ClimateEntity):
+    # It's not mandatory to implement the `toggle` method as the base implementation
+    # will call `turn_on`/`turn_off` according to the current HVAC mode.
+
+    # If implemented, the `toggle` method should set `hvac_mode` to the right `HVACMode` by
+    # optimistically setting it from the service handler or with the next state update.
+
+    def toggle(self):
+        """Toggle the entity."""
+
+    async def async_toggle(self):
+        """Toggle the entity."""
+```
+
 ### Set preset mode
 
 ```python