diff --git a/CODEOWNERS b/CODEOWNERS index 2c098560539..162f6bae087 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -804,6 +804,7 @@ source/_integrations/utility_meter.markdown @dgomes source/_integrations/v2c.markdown @dgomes source/_integrations/vacuum.markdown @home-assistant/core source/_integrations/vallox.markdown @andre-richter @slovdahl @viiru- +source/_integrations/valve.markdown @home-assistant/core source/_integrations/velbus.markdown @Cereal2nd @brefra source/_integrations/velux.markdown @Julius2342 source/_integrations/venstar.markdown @garbled1 @jhollowe diff --git a/source/_data/glossary.yml b/source/_data/glossary.yml index 15436a4a85a..af8e517f322 100644 --- a/source/_data/glossary.yml +++ b/source/_data/glossary.yml @@ -387,6 +387,14 @@ definition: >- TTS (text-to-speech) allows Home Assistant to talk to you. link: /integrations/tts/ + + +- term: Valve + definition: >- + Valves are devices to control the flow of liquids and gases. All valves in Home Assistant can be opened + and closed. Some valves can also be set to a specific position. + link: /integrations/valve + - term: Variables definition: >- Variables are used to store values in memory that can be processed diff --git a/source/_integrations/valve.markdown b/source/_integrations/valve.markdown new file mode 100644 index 00000000000..9a994887949 --- /dev/null +++ b/source/_integrations/valve.markdown @@ -0,0 +1,72 @@ +--- +title: Valve +description: Instructions on how to integrate valves into Home Assistant. +ha_category: + - Valve +ha_release: 2024.1.0 +ha_quality_scale: internal +ha_codeowners: + - '@home-assistant/core' +ha_domain: valve +ha_integration_type: entity +--- + +The valve entity in Home Assistant provides an interface to control valves such as water, gas, or air valves. + +{% include integrations/building_block_integration.md %} + +## Device class + +You can change the device class of the valve in the [customize section](/docs/configuration/customizing-devices/). Valves support the following device classes: + +- **None**: Generic valve. This is the default and doesn't need to be set. +- **water**: Valve that controls the flow of water through a system. +- **gas**: Valve that controls the flow of gas through a system. + +## Services + +### Valve control services + +All valves respond to `valve.open`, `valve.close`, and `valve.toggle`. +Valves that allow setting a specific position may also be controlled with `valve.set_position` and `valve.stop`. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of valves. Use `entity_id: all` to target all. + +#### Automation example + +```yaml +automation: + trigger: + platform: time + at: "07:15:00" + action: + - service: valve.close + target: + entity_id: valve.demo +``` + +### Service `valve.set_position` + +Set the position of one or multiple valves if they support setting a specific position. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of valves. Use `entity_id: all` to target all. +| `position` | no | Integer between 0 (fully closed) and 100 (fully open). + +#### Automation example + +```yaml +automation: + trigger: + platform: time + at: "07:15:00" + action: + - service: valve.set_position + target: + entity_id: valve.demo + data: + position: 50 +```