From ca39891c7cce971b941f6d0f9ef865b7e5a6942f Mon Sep 17 00:00:00 2001
From: Miguel Camba <miguel.camba@gmail.com>
Date: Wed, 20 Dec 2023 13:01:09 +0100
Subject: [PATCH] Add documentation for new Valve integration (#29572)

* Add documentation for new Valve integration

* Update target version

* Set version to 2024.1.0

* Tiny tweaks

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Apply suggestions from code review

* Tweak

* Update source/_integrations/valve.markdown

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

* Update source/_integrations/valve.markdown

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

* Clarify what 0 and 100 mean in the position field

* tiny tweak

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
---
 CODEOWNERS                          |  1 +
 source/_data/glossary.yml           |  8 ++++
 source/_integrations/valve.markdown | 72 +++++++++++++++++++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 source/_integrations/valve.markdown

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
+```