From 4d90ac6bb18be8989e93f9d26150470799d6f136 Mon Sep 17 00:00:00 2001 From: Jay <49540618+Tediore@users.noreply.github.com> Date: Tue, 22 Oct 2019 13:48:16 -0500 Subject: [PATCH] Improve clarity and descriptions (#10944) Improved descriptions for service data attributes under `climate.set_temperature`. I think we should also add a note about `heat_cool` and `auto` HVAC modes not being the same thing, but I'm not exactly sure how to word it even after rereading the changes to the Climate integration in 0.96. --- source/_integrations/climate.markdown | 58 +++++++++++++++++---------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/source/_integrations/climate.markdown b/source/_integrations/climate.markdown index 1b367c3e967..de691fce92c 100644 --- a/source/_integrations/climate.markdown +++ b/source/_integrations/climate.markdown @@ -8,7 +8,7 @@ ha_qa_scale: internal ha_release: 0.19 --- -The `climate` integration is built for the controlling and monitoring of HVAC (heating, ventilating, and air conditioning) and thermostat devices. +The Climate integration allows you to control and monitor HVAC (heating, ventilating, and air conditioning) devices and thermostats. ## Services @@ -16,7 +16,7 @@ The `climate` integration is built for the controlling and monitoring of HVAC (h Available services: `climate.set_aux_heat`, `climate.set_preset_mode`, `climate.set_temperature`, `climate.set_humidity`, `climate.set_fan_mode`, `climate.set_hvac_mode`, `climate.set_swing_mode`, `climate.turn_on`, `climate.turn_off` -
\ +
Not all climate services may be available for your platform. Be sure to check the available services Home Assistant has enabled by checking service developer tool icon **Services**. @@ -28,7 +28,7 @@ Turn auxiliary heater on/off for climate device | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. | `aux_heat` | no | New value of auxiliary heater. #### Automation example @@ -47,13 +47,13 @@ automation: ### Service `climate.set_preset_mode` -Set preset mode for climate device. The away mode changes the target temperature permanently to a temperature -reflecting a situation where the climate device is set to save energy. This may be used to emulate a -"vacation mode", for example. +Set preset mode for climate device. Away mode changes the target temperature permanently to a temperature +reflecting a situation where the climate device is set to save energy. For example, this may be used to emulate a +"vacation mode." | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. | `preset_mode` | no | New value of preset mode. #### Automation example @@ -76,15 +76,16 @@ Set target temperature of climate device | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. -| `temperature` | no | New target temperature for hvac -| `target_temp_high` | yes | New target high temperature for hvac -| `target_temp_low` | yes | New target low temperature for hvac -| `hvac_mode` | yes | HVAC mode to set temperature to. This defaults to current HVAC mode if not set, or set incorrectly. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. +| `temperature` | no | New target temperature for climate device (commonly referred to as a *setpoint*). Do not use if `hvac_mode` is `heat_cool`. +| `target_temp_high` | yes | The highest temperature that the climate device will allow. Required if `hvac_mode` is `heat_cool`. +| `target_temp_low` | yes | The lowest temperature that the climate device will allow. Required if `hvac_mode` is `heat_cool`. +| `hvac_mode` | yes | HVAC mode to set the climate device to. This defaults to current HVAC mode if not set, or set incorrectly. -#### Automation example +#### Automation examples ```yaml +### Set temperature to 24 in heat mode automation: trigger: platform: time @@ -97,13 +98,28 @@ automation: hvac_mode: heat ``` +```yaml +### Set temperature range to 20 to 24 in heat_cool mode +automation: + trigger: + platform: time + at: "07:15:00" + action: + - service: climate.set_temperature + data: + entity_id: climate.kitchen + target_temp_high: 24 + target_temp_low: 20 + hvac_mode: heat_cool +``` + ### Service `climate.set_humidity` Set target humidity of climate device | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. | `humidity` | no | New target humidity for climate device #### Automation example @@ -126,7 +142,7 @@ Set fan operation for climate device | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. | `fan_mode` | no | New value of fan mode #### Automation example @@ -145,11 +161,11 @@ automation: ### Service `climate.set_hvac_mode` -Set HVAC mode for climate device +Set climate device's HVAC mode | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. | `hvac_mode` | no | New value of HVAC mode #### Automation example @@ -172,7 +188,7 @@ Set swing operation mode for climate device | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. | `swing_mode` | no | New value of swing mode #### Automation example @@ -195,12 +211,12 @@ Turn climate device on. This is only supported if the climate device supports be | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Targets all when omitted. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted. ### Service `climate.turn_off` -Turn climate device off. This is only supported if the climate device has the hvac mode "off". +Turn climate device off. This is only supported if the climate device has the hvac mode `off`. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Targets all when omitted. +| `entity_id` | yes | String or list of strings that define the entity ID(s) of climate device(s) to control. Targets all when omitted.