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