mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-12 11:56:29 +00:00
Update climate docs (#289)
* Update climate docs * Update docs/entity_climate.md Co-Authored-By: Franck Nijhof <frenck@frenck.nl> * Add off
This commit is contained in:
Paulus Schoutsen
GitHub
parent
2d257fd570
commit
7fdb533485
@ -3,77 +3,148 @@ title: Climate Entity
|
|||||||
sidebar_label: Climate
|
sidebar_label: Climate
|
||||||
---
|
---
|
||||||
|
|
||||||
> A climate entity is a device that controls temperature, humidity, or fans, such as A/C systems and humidifiers. Derive entity platforms from [`homeassistant.components.climate.ClimateDevice`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/climate/__init__.py)
|
A climate entity is a device that controls temperature, humidity, or fans, such as A/C systems and humidifiers. Derive entity platforms from [`homeassistant.components.climate.ClimateDevice`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/climate/__init__.py)
|
||||||
|
|
||||||
## Properties
|
## Properties
|
||||||
|
|
||||||
> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
|
> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
|
||||||
|
|
||||||
| Name | Type | Default | Description
|
| Name | Type | Default | Description |
|
||||||
| ---- | ---- | ------- | -----------
|
| ----------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
||||||
| current_fan_mode | string | None | Returns the current fan mode.
|
| temperature_unit | string | `NotImplementedError` | The unit of temperature measurement for the system (`TEMP_CELSIUS` or `TEMP_FAHRENHEIT`). |
|
||||||
| current_hold_mode | string | None | The current hold mode, e.g., home, away, temp.
|
| precision | float | Based on `temperature_unit` | The precision of the temperature in the system. Defaults to tenths for TEMP_CELSIUS, whole number otherwise. |
|
||||||
| current_humidity | float | None | The current humidity.
|
| current_temperature | float | None | The current temperature. |
|
||||||
| current_operation | string | None | The current operation (e.g. heat, cool, idle). Used to determine `state`.
|
| current_humidity | float | None | The current humidity. |
|
||||||
| current_swing_mode | string | None | Returns the fan setting.
|
| target_temperature | float | None | The temperature currently set to be reached. |
|
||||||
| current_temperature | float | None | The current temperature.
|
| target_temperature_high | float | None | The upper bound target temperature |
|
||||||
| fan_list | list | None | Returns the list of available fan modes.
|
| target_temperature_low | float | None | The lower bound target temperature |
|
||||||
| is_aux_heat_on | bool | None | Returns True if an auxiliary heater is on.
|
| target_temperature_step | float | None | The supported step size a target temperature can be increased/decreased |
|
||||||
| is_away_mode_on | bool | None | Return true if away mode is on.
|
| target_humidity | float | None | The target humidity the device is trying to reach. Requires `SUPPORT_TARGET_HUMIDITY`. |
|
||||||
| is_on | bool | None | Returns True if device is on. Used to determine `state`.
|
| max_temp | int | `DEFAULT_MAX_TEMP` (value == 35) | Returns the maximum temperature. |
|
||||||
| max_humidity | int | `DEFAULT_MAX_HUMIDITY` (value == 99) | Returns the maximum humidity.
|
| min_temp | int | `DEFAULT_MIN_TEMP` (value == 7) | Returns the minimum temperature. |
|
||||||
| max_temp | int | `DEFAULT_MAX_TEMP` (value == 35) | Returns the maximum temperature.
|
| max_humidity | int | `DEFAULT_MAX_HUMIDITY` (value == 99) | Returns the maximum humidity. Requires `SUPPORT_TARGET_HUMIDITY`. |
|
||||||
| min_humidity | int | `DEFAULT_MIN_HUMIDITY` (value == 30) | Returns the minimum humidity.
|
| min_humidity | int | `DEFAULT_MIN_HUMIDITY` (value == 30) | Returns the minimum humidity. Requires `SUPPORT_TARGET_HUMIDITY`. |
|
||||||
| min_temp | int | `DEFAULT_MIN_TEMP` (value == 7) | Returns the minimum temperature.
|
| hvac_mode | string | `NotImplementedError()` | The current operation (e.g. heat, cool, idle). Used to determine `state`. |
|
||||||
| operation_list | list | None | List of available operation modes.
|
| hvac_action | string | None | The current HVAC action (heating, cooling) |
|
||||||
| precision | float | PRECISION_WHOLE | The precision of the temperature in the system: tenths for TEMP_CELSIUS, whole number otherwise.
|
| hvac_modes | list | `NotImplementedError()` | List of available operation modes. See below. |
|
||||||
| state | string | None | Returns the current state.
|
| preset_mode | string | `NotImplementedError()` | The current active preset. Requires `SUPPORT_PRESET_MODE`. |
|
||||||
| state_attributes | dictionary | N/A | The optional state attributes: current temperature, minimum temperature, maximum temperature, and target temperature.
|
| preset_modes | list | `NotImplementedError()` | The available presets. Requires `SUPPORT_PRESET_MODE`. |
|
||||||
| supported_features | list | `NotImplementedError()` | Returns list of supported features.
|
| fan_mode | string | `NotImplementedError()` | Returns the current fan mode. Requires `SUPPORT_FAN_MODE`. |
|
||||||
| swing_list | list | None | Returns the list of available swing modes.
|
| fan_modes | list | `NotImplementedError()` | Returns the list of available fan modes. Requires `SUPPORT_FAN_MODE`. |
|
||||||
| target_humidity | float | None | The target humidity.
|
| swing_mode | string | `NotImplementedError()` | Returns the fan setting. |
|
||||||
| target_temperature | float | None | The temperature currently set to be reached.
|
| swing_modes | list | `NotImplementedError()` | Returns the list of available swing modes. |
|
||||||
| target_temperature_high | float | None | The upper bound target temperature
|
| is_aux_heat | bool | None | Returns True if an auxiliary heater is on. Requires `SUPPORT_AUX_HEAT`. |
|
||||||
| target_temperature_low | float | None | The lower bound target temperature
|
| supported_features | int | `NotImplementedError()` | Bitmap of supported features. See below. |
|
||||||
| target_temperature_step | float | None | The supported step of target temperature
|
|
||||||
| temperature_unit | string | `NotImplementedError` | The unit of temperature measurement for the system (e.g. Celsius).
|
|
||||||
|
|
||||||
### States
|
### HVAC modes
|
||||||
|
|
||||||
| Name | Description
|
You are only allowed to use the built-in HVAC modes. If you want another mode, add a preset instead.
|
||||||
| ---- | -----------
|
|
||||||
| STATE_HEAT | The device is set to heat.
|
| Name | Description |
|
||||||
| STATE_COOL | The device is set to cool.
|
| --------------------- | ------------------------------------------------------------------- |
|
||||||
| STATE_IDLE | The device is idle.
|
| `HVAC_MODE_OFF` | The device is turned off. |
|
||||||
| STATE_AUTO | The device is set to auto.
|
| `HVAC_MODE_HEAT` | The device is set to heat to a target temperature. |
|
||||||
| STATE_MANUAL | The device is set to manual.
|
| `HVAC_MODE_COOL` | The device is set to cool to a target temperature. |
|
||||||
| STATE_DRY | The device is set to dry.
|
| `HVAC_MODE_HEAT_COOL` | The device supports heating/cooling to a range |
|
||||||
| STATE_FAN_ONLY | The device is set to fan-only.
|
| `HVAC_MODE_AUTO` | The device is set to a schedule, learned behavior, AI. |
|
||||||
| STATE_ECO | The device is set to eco-mode.
|
| `HVAC_MODE_DRY` | The device is set to dry/humidity mode. |
|
||||||
|
| `HVAC_MODE_FAN_ONLY` | The device only has the fan on. No heating or cooling taking place. |
|
||||||
|
|
||||||
|
### HVAC Action
|
||||||
|
|
||||||
|
The HVAC action describes the _current_ action. This is different from the mode, because if a device is set to heat, and the target temperature is already achieved, the device will not be actively heating anymore.
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ------------------- | --------------------- |
|
||||||
|
| `CURRENT_HVAC_OFF` | Device is turned off. |
|
||||||
|
| `CURRENT_HVAC_HEAT` | Device is heating. |
|
||||||
|
| `CURRENT_HVAC_COOL` | Device is cooling. |
|
||||||
|
| `CURRENT_HVAC_DRY` | Device is dring. |
|
||||||
|
| `CURRENT_HVAC_IDLE` | Device is idle. |
|
||||||
|
|
||||||
|
### Presets
|
||||||
|
|
||||||
|
A device can have different presets that it might want to show to the user. Common presets are "Away" or "Eco". There are a couple of built-in presets that will offer translations, but you're also allowed to add custom presets.
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ---------- | ------------------------------------------------------ |
|
||||||
|
| `ECO` | Device is running an energy-saving mode |
|
||||||
|
| `AWAY` | Device is in away mode |
|
||||||
|
| `BOOST` | Device turn all valve full up |
|
||||||
|
| `COMFORT` | Device is in comfort mode |
|
||||||
|
| `HOME` | Device is in home mode |
|
||||||
|
| `SLEEP` | Device is prepared for sleep |
|
||||||
|
| `ACTIVITY` | Device is reacting to activity (e.g. movement sensors) |
|
||||||
|
|
||||||
|
### Fan modes
|
||||||
|
|
||||||
|
A device's fan can have different states. There are a couple of built-in fan modes, but you're also allowed to use custom fan modes.
|
||||||
|
|
||||||
|
| Name |
|
||||||
|
| ------------- |
|
||||||
|
| `FAN_ON` |
|
||||||
|
| `FAN_OFF` |
|
||||||
|
| `FAN_AUTO` |
|
||||||
|
| `FAN_LOW` |
|
||||||
|
| `FAN_MEDIUM` |
|
||||||
|
| `FAN_HIGH` |
|
||||||
|
| `FAN_MIDDLE` |
|
||||||
|
| `FAN_FOCUS` |
|
||||||
|
| `FAN_DIFFUSE` |
|
||||||
|
|
||||||
|
### Swing modes
|
||||||
|
|
||||||
|
The device fan can have different swing modes that it wants the user to know about/control.
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
| ------------------ | ------------------------------------------------ |
|
||||||
|
| `SWING_OFF` | The fan is not swinging. |
|
||||||
|
| `SWING_VERTICAL` | The fan is swinging vertical. |
|
||||||
|
| `SWING_HORIZONTAL` | The fan is swinging horizontal. |
|
||||||
|
| `SWING_BOTH` | The fan is swingin both horizontal and vertical. |
|
||||||
|
|
||||||
### Supported features
|
### Supported features
|
||||||
|
|
||||||
Supported features constants are combined using the bitwise or (`|`) operator.
|
Supported features constants are combined using the bitwise or (`|`) operator.
|
||||||
|
|
||||||
| Name | Description
|
| Name | Description |
|
||||||
| ---- | -----------
|
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||||
| SUPPORT_TARGET_TEMPERATURE | The device supports a target temperature.
|
| `SUPPORT_TARGET_TEMPERATURE` | The device supports a target temperature. |
|
||||||
| SUPPORT_TARGET_TEMPERATURE_HIGH | The device supports an upper bound target temperature.
|
| `SUPPORT_TARGET_TEMPERATURE_RANGE` | The device supports a ranged target temperature. Used for HVAC modes `heat_cool` and `auto` |
|
||||||
| SUPPORT_TARGET_TEMPERATURE_LOW | The device supports a lower bound target temperature.
|
| `SUPPORT_TARGET_HUMIDITY` | The device supports a target humidity. |
|
||||||
| SUPPORT_TARGET_HUMIDITY | The device supports a target humidity.
|
| `SUPPORT_FAN_MODE` | The device supports fan modes. |
|
||||||
| SUPPORT_TARGET_HUMIDITY_HIGH | The device supports an upper bound target humidity.
|
| `SUPPORT_PRESET_MODE` | The device supports presets. |
|
||||||
| SUPPORT_TARGET_HUMIDITY_LOW | The device supports a lower bound target humidity.
|
| `SUPPORT_SWING_MODE` | The device supports swing modes. |
|
||||||
| SUPPORT_FAN_MODE | The device supports fan modes.
|
| `SUPPORT_AUX_HEAT` | The device supports auxiliary heaters. |
|
||||||
| SUPPORT_OPERATION_MODE | The device supports operation modes.
|
|
||||||
| SUPPORT_HOLD_MODE | The device supports hold modes.
|
|
||||||
| SUPPORT_SWING_MODE | The device supports swing modes.
|
|
||||||
| SUPPORT_AWAY_MODE | The device supports away mode.
|
|
||||||
| SUPPORT_AUX_HEAT | The device supports auxiliary heaters.
|
|
||||||
| SUPPORT_ON_OFF | The device supports on/off states.
|
|
||||||
|
|
||||||
|
|
||||||
## Methods
|
## Methods
|
||||||
|
|
||||||
|
### Set hvac mode
|
||||||
|
|
||||||
|
```python
|
||||||
|
class MyClimateDevice(ClimateDevice):
|
||||||
|
# Implement one of these methods.
|
||||||
|
|
||||||
|
def set_hvac_mode(self, hvac_mode):
|
||||||
|
"""Set new target hvac mode."""
|
||||||
|
|
||||||
|
async def async_set_hvac_mode(self, hvac_mode):
|
||||||
|
"""Set new target hvac mode."""
|
||||||
|
```
|
||||||
|
|
||||||
|
### Set preset mode
|
||||||
|
|
||||||
|
```python
|
||||||
|
class MyClimateDevice(ClimateDevice):
|
||||||
|
# Implement one of these methods.
|
||||||
|
|
||||||
|
def set_preset_mode(self, preset_mode):
|
||||||
|
"""Set new target preset mode."""
|
||||||
|
|
||||||
|
async def async_set_preset_mode(self, preset_mode):
|
||||||
|
"""Set new target preset mode."""
|
||||||
|
```
|
||||||
|
|
||||||
### Set fan mode
|
### Set fan mode
|
||||||
|
|
||||||
```python
|
```python
|
||||||
@ -87,19 +158,6 @@ class MyClimateDevice(ClimateDevice):
|
|||||||
"""Set new target fan mode."""
|
"""Set new target fan mode."""
|
||||||
```
|
```
|
||||||
|
|
||||||
### Set hold mode
|
|
||||||
|
|
||||||
```python
|
|
||||||
class MyClimateDevice(ClimateDevice):
|
|
||||||
# Implement one of these methods.
|
|
||||||
|
|
||||||
def set_hold_mode(self, hold_mode):
|
|
||||||
"""Set new target hold mode."""
|
|
||||||
|
|
||||||
async def async_set_hold_mode(self, hold_mode):
|
|
||||||
"""Set new target hold mode."""
|
|
||||||
```
|
|
||||||
|
|
||||||
### Set humidity
|
### Set humidity
|
||||||
|
|
||||||
```python
|
```python
|
||||||
@ -113,19 +171,6 @@ class MyClimateDevice(ClimateDevice):
|
|||||||
"""Set new target humidity."""
|
"""Set new target humidity."""
|
||||||
```
|
```
|
||||||
|
|
||||||
### Set operation mode
|
|
||||||
|
|
||||||
```python
|
|
||||||
class MyClimateDevice(ClimateDevice):
|
|
||||||
# Implement one of these methods.
|
|
||||||
|
|
||||||
def set_operation_mode(self, operation_mode):
|
|
||||||
"""Set new target operation mode."""
|
|
||||||
|
|
||||||
async def async_set_operation_mode(self, operation_mode):
|
|
||||||
"""Set new target operation mode."""
|
|
||||||
```
|
|
||||||
|
|
||||||
### Set swing mode
|
### Set swing mode
|
||||||
|
|
||||||
```python
|
```python
|
||||||
@ -152,7 +197,7 @@ class MyClimateDevice(ClimateDevice):
|
|||||||
"""Set new target temperature."""
|
"""Set new target temperature."""
|
||||||
```
|
```
|
||||||
|
|
||||||
### Turn auxiliary heater on
|
### Control auxiliary heater
|
||||||
|
|
||||||
```python
|
```python
|
||||||
class MyClimateDevice(ClimateDevice):
|
class MyClimateDevice(ClimateDevice):
|
||||||
@ -163,12 +208,7 @@ class MyClimateDevice(ClimateDevice):
|
|||||||
|
|
||||||
async def async_turn_aux_heat_on(self):
|
async def async_turn_aux_heat_on(self):
|
||||||
"""Turn auxiliary heater on."""
|
"""Turn auxiliary heater on."""
|
||||||
```
|
|
||||||
|
|
||||||
### Turn auxiliary heater off
|
|
||||||
|
|
||||||
```python
|
|
||||||
class MyClimateDevice(ClimateDevice):
|
|
||||||
# Implement one of these methods.
|
# Implement one of these methods.
|
||||||
|
|
||||||
def turn_aux_heat_off(self):
|
def turn_aux_heat_off(self):
|
||||||
@ -177,55 +217,3 @@ class MyClimateDevice(ClimateDevice):
|
|||||||
async def async_turn_aux_heat_off(self):
|
async def async_turn_aux_heat_off(self):
|
||||||
"""Turn auxiliary heater off."""
|
"""Turn auxiliary heater off."""
|
||||||
```
|
```
|
||||||
|
|
||||||
### Turn away mode on
|
|
||||||
|
|
||||||
```python
|
|
||||||
class MyClimateDevice(ClimateDevice):
|
|
||||||
# Implement one of these methods.
|
|
||||||
|
|
||||||
def turn_away_mode_on(self):
|
|
||||||
"""Turn away mode on."""
|
|
||||||
|
|
||||||
async def async_turn_away_mode_on(self):
|
|
||||||
"""Turn away mode on."""
|
|
||||||
```
|
|
||||||
|
|
||||||
### Turn away mode off
|
|
||||||
|
|
||||||
```python
|
|
||||||
class MyClimateDevice(ClimateDevice):
|
|
||||||
# Implement one of these methods.
|
|
||||||
|
|
||||||
def turn_away_mode_off(self):
|
|
||||||
"""Turn away mode off."""
|
|
||||||
|
|
||||||
async def async_turn_away_mode_off(self):
|
|
||||||
"""Turn away mode off."""
|
|
||||||
```
|
|
||||||
|
|
||||||
### Turn the device on
|
|
||||||
|
|
||||||
```python
|
|
||||||
class MyClimateDevice(ClimateDevice):
|
|
||||||
# Implement one of these methods.
|
|
||||||
|
|
||||||
def turn_on(self):
|
|
||||||
"""Turn device on."""
|
|
||||||
|
|
||||||
async def async_turn_on(self):
|
|
||||||
"""Turn device on."""
|
|
||||||
```
|
|
||||||
|
|
||||||
### Turn the device off
|
|
||||||
|
|
||||||
```python
|
|
||||||
class MyClimateDevice(ClimateDevice):
|
|
||||||
# Implement one of these methods.
|
|
||||||
|
|
||||||
def turn_off(self):
|
|
||||||
"""Turn device off."""
|
|
||||||
|
|
||||||
async def async_turn_off(self):
|
|
||||||
"""Turn device off."""
|
|
||||||
```
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user