Add documentation for valve component (#3763)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
Keith Burzinski
GitHub
parent
eb1af142c1
commit
f1b31e85b7
|
|
@ -29,4 +29,5 @@ Components
|
|||
time/index
|
||||
alarm_control_panel/index
|
||||
text/index
|
||||
valve/index
|
||||
*
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
|
|
@ -0,0 +1,262 @@
|
|||
Valve Component
|
||||
===============
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up base valves in ESPHome.
|
||||
:image: folder-open.svg
|
||||
|
||||
The ``valve`` component is a generic representation of valves in ESPHome. A valve can (currently) either be *closed* or
|
||||
*open* and supports three commands: *open*, *close* and *stop*.
|
||||
|
||||
.. note::
|
||||
|
||||
To use a valve in Home Assistant requires Home Assistant 2024.5 or later.
|
||||
|
||||
.. figure:: images/valve-ui.png
|
||||
:align: center
|
||||
|
||||
.. _config-valve:
|
||||
|
||||
Base Valve Configuration
|
||||
------------------------
|
||||
|
||||
All valve config schemas inherit from this schema - you can set these keys for valves.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
valve:
|
||||
- platform: ...
|
||||
device_class: water
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **name** (**Required**, string): The name for the valve.
|
||||
|
||||
.. note::
|
||||
|
||||
If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and you want the valve
|
||||
to use that name, you can set ``name: None``.
|
||||
|
||||
- **device_class** (*Optional*, string): The device class for the sensor. See
|
||||
https://www.home-assistant.io/components/valve/ for a list of available options.
|
||||
- **icon** (*Optional*, icon): Manually set the icon to use for the valve in the frontend.
|
||||
|
||||
Advanced options:
|
||||
|
||||
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the
|
||||
frontend (like Home Assistant). Only specifying an ``id`` without a ``name`` will implicitly set this to true.
|
||||
- **disabled_by_default** (*Optional*, boolean): If true, this entity should not be added to any client's frontend,
|
||||
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to ``false``.
|
||||
- **entity_category** (*Optional*, string): The category of the entity. See
|
||||
https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Set to ``""`` to remove the default entity category.
|
||||
|
||||
MQTT options:
|
||||
|
||||
- **position_state_topic** (*Optional*, string): The topic to publish valve position changes to.
|
||||
- **position_command_topic** (*Optional*, string): The topic to receive valve position commands on.
|
||||
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
|
||||
|
||||
|
||||
.. _valve-open_action:
|
||||
|
||||
``valve.open`` Action
|
||||
---------------------
|
||||
|
||||
This :ref:`action <config-action>` opens the valve with the given ID when executed.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
then:
|
||||
- valve.open: valve_1
|
||||
|
||||
.. note::
|
||||
|
||||
This action can also be expressed in :ref:`lambdas <config-lambda>`:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
auto call = id(valve_1).make_call();
|
||||
call.set_command_open();
|
||||
call.perform();
|
||||
|
||||
.. _valve-close_action:
|
||||
|
||||
``valve.close`` Action
|
||||
----------------------
|
||||
|
||||
This :ref:`action <config-action>` closes the valve with the given ID when executed.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
then:
|
||||
- valve.close: valve_1
|
||||
|
||||
.. note::
|
||||
|
||||
This action can also be expressed in :ref:`lambdas <config-lambda>`:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
auto call = id(valve_1).make_call();
|
||||
call.set_command_close();
|
||||
call.perform();
|
||||
|
||||
.. _valve-stop_action:
|
||||
|
||||
``valve.stop`` Action
|
||||
---------------------
|
||||
|
||||
This :ref:`action <config-action>` stops the valve with the given ID when executed.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
then:
|
||||
- valve.stop: valve_1
|
||||
|
||||
.. note::
|
||||
|
||||
This action can also be expressed in :ref:`lambdas <config-lambda>`:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
auto call = id(valve_1).make_call();
|
||||
call.set_command_stop();
|
||||
call.perform();
|
||||
|
||||
.. _valve-toggle_action:
|
||||
|
||||
``valve.toggle`` Action
|
||||
-----------------------
|
||||
|
||||
This :ref:`action <config-action>` toggles the valve with the given ID when executed, cycling through the states
|
||||
close/stop/open/stop... This allows the valve to be controlled by a single push button.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
then:
|
||||
- valve.toggle: valve_1
|
||||
|
||||
.. note::
|
||||
|
||||
This action can also be expressed in :ref:`lambdas <config-lambda>`:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
auto call = id(valve_1).make_call();
|
||||
call.set_command_toggle();
|
||||
call.perform();
|
||||
|
||||
.. _valve-control_action:
|
||||
|
||||
``valve.control`` Action
|
||||
------------------------
|
||||
|
||||
This :ref:`action <config-action>` is a more generic version of the other valve actions and allows all valve attributes
|
||||
to be set.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
then:
|
||||
- valve.control:
|
||||
id: valve_1
|
||||
position: 50%
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): The valve to control.
|
||||
- **stop** (*Optional*, boolean): Whether to stop the valve.
|
||||
- **state** (*Optional*, string): The state to set the valve to - one of ``OPEN`` or ``CLOSE``.
|
||||
- **position** (*Optional*, float): The valve position to set.
|
||||
|
||||
- ``0.0`` = ``0%`` = ``CLOSED``
|
||||
- ``1.0`` = ``100%`` = ``OPEN``
|
||||
|
||||
.. note::
|
||||
|
||||
This action can also be expressed in :ref:`lambdas <config-lambda>`:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
auto call = id(valve_1).make_call();
|
||||
// set attributes
|
||||
call.set_position(0.5);
|
||||
call.perform();
|
||||
|
||||
.. _valve-lambda_calls:
|
||||
|
||||
Lambdas
|
||||
-------
|
||||
|
||||
From :ref:`lambdas <config-lambda>`, you can access the current state of the valve (note that these fields are
|
||||
read-only, if you want to act on the valve, use the ``make_call()`` method as shown above).
|
||||
|
||||
- ``position``: Retrieve the current position of the valve, as a value between ``0.0`` (closed) and ``1.0`` (open).
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
if (id(my_valve).position == VALVE_OPEN) {
|
||||
// Valve is open
|
||||
} else if (id(my_valve).position == VALVE_CLOSED) {
|
||||
// Valve is closed
|
||||
} else {
|
||||
// Valve is in-between open and closed
|
||||
}
|
||||
|
||||
- ``current_operation``: The operation the valve is currently performing:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
if (id(my_valve).current_operation == ValveOperation::VALVE_OPERATION_IDLE) {
|
||||
// Valve is idle
|
||||
} else if (id(my_valve).current_operation == ValveOperation::VALVE_OPERATION_OPENING) {
|
||||
// Valve is currently opening
|
||||
} else if (id(my_valve).current_operation == ValveOperation::VALVE_OPERATION_CLOSING) {
|
||||
// Valve is currently closing
|
||||
}
|
||||
|
||||
.. _valve-on_open_trigger:
|
||||
|
||||
``valve.on_open`` Trigger
|
||||
*************************
|
||||
|
||||
This trigger is activated each time the valve reaches a fully open state.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
valve:
|
||||
- platform: template # or any other platform
|
||||
# ...
|
||||
on_open:
|
||||
- logger.log: "Valve is Open!"
|
||||
|
||||
.. _valve-on_closed_trigger:
|
||||
|
||||
``valve.on_closed`` Trigger
|
||||
***************************
|
||||
|
||||
This trigger is activated each time the valve reaches a fully closed state.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
valve:
|
||||
- platform: template # or any other platform
|
||||
# ...
|
||||
on_closed:
|
||||
- logger.log: "Valve is Closed!"
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :apiref:`valve/valve.h`
|
||||
- :ghedit:`Edit`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
*
|
||||
|
|
@ -0,0 +1,118 @@
|
|||
Template Valve
|
||||
==============
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up template valves in ESPHome.
|
||||
:image: description.svg
|
||||
|
||||
The ``template`` valve platform allows you to create simple valves out of just a few actions and a value lambda. Once
|
||||
defined, it will automatically appear in Home Assistant as a valve and can be controlled through the frontend.
|
||||
|
||||
.. figure:: images/valve-ui.png
|
||||
:align: center
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
valve:
|
||||
- platform: template
|
||||
name: "Template Valve"
|
||||
lambda: |-
|
||||
if (id(top_end_stop).state) {
|
||||
return VALVE_OPEN;
|
||||
} else {
|
||||
return VALVE_CLOSED;
|
||||
}
|
||||
open_action:
|
||||
- switch.turn_on: open_valve_switch
|
||||
close_action:
|
||||
- switch.turn_on: close_valve_switch
|
||||
stop_action:
|
||||
- switch.turn_on: stop_valve_switch
|
||||
optimistic: true
|
||||
|
||||
|
||||
Possible return values for the optional lambda:
|
||||
|
||||
- ``return VALVE_OPEN;`` if the valve should be reported as OPEN.
|
||||
- ``return VALVE_CLOSED;`` if the valve should be reported as CLOSED.
|
||||
- ``return {};`` if the last state should be repeated.
|
||||
|
||||
Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **name** (**Required**, string): The name of the valve.
|
||||
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
|
||||
Lambda to be evaluated repeatedly to get the current state of the valve.
|
||||
- **open_action** (*Optional*, :ref:`Action <config-action>`): The action that should be performed when the remote
|
||||
(like Home Assistant's frontend) requests the valve to be opened.
|
||||
- **close_action** (*Optional*, :ref:`Action <config-action>`): The action that should be performed when the remote
|
||||
requests the valve to be closed.
|
||||
- **stop_action** (*Optional*, :ref:`Action <config-action>`): The action that should be performed when the remote
|
||||
requests the valve to be stopped.
|
||||
- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode, any command sent to
|
||||
the template valve will immediately update the reported state and no lambda needs to be used. Defaults to ``false``.
|
||||
- **assumed_state** (*Optional*, boolean): Whether the true state of the valve is not known. This will make the Home
|
||||
Assistant frontend show buttons for both OPEN and CLOSE actions, instead of hiding one of them. Defaults to ``false``.
|
||||
- **has_position** (*Optional*, boolean): Whether this valve will publish its position as a floating point number.
|
||||
By default (``false``), the valve only publishes OPEN/CLOSED position.
|
||||
- **position_action** (*Optional*, :ref:`Action <config-action>`): The action that should be performed when the remote
|
||||
(like Home Assistant's frontend) requests the valve be set to a specific position. The desired position is available
|
||||
in the lambda in the ``pos`` variable. Requires ``has_position`` (above) to be set to ``true``.
|
||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||
- All other options from :ref:`Valve <config-valve>`.
|
||||
|
||||
.. _valve-template-publish_action:
|
||||
|
||||
``valve.template.publish`` Action
|
||||
---------------------------------
|
||||
|
||||
You can also publish a state to a template valve from elsewhere in your YAML filewith the ``valve.template.publish`` action.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
valve:
|
||||
- platform: template
|
||||
name: "Template Valve"
|
||||
id: my_template_valve
|
||||
|
||||
# in some trigger
|
||||
on_...:
|
||||
- valve.template.publish:
|
||||
id: my_template_valve
|
||||
state: OPEN
|
||||
|
||||
# Templated
|
||||
- valve.template.publish:
|
||||
id: my_template_valve
|
||||
state: !lambda 'return VALVE_OPEN;'
|
||||
|
||||
Configuration options:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): The ID of the template valve.
|
||||
- **state** (*Optional*, :ref:`templatable <config-templatable>`):
|
||||
The state to publish. One of ``OPEN``, ``CLOSED``. If using a lambda, use ``VALVE_OPEN`` or ``VALVE_CLOSED``.
|
||||
- **position** (*Optional*, :ref:`templatable <config-templatable>`, float):
|
||||
The position to publish, from 0 (CLOSED) to 1.0 (OPEN)
|
||||
- **current_operation** (*Optional*, :ref:`templatable <config-templatable>`, string):
|
||||
The current operation mode to publish. One of ``IDLE``, ``OPENING`` and ``CLOSING``. If using a lambda, use
|
||||
``VALVE_OPERATION_IDLE``, ``VALVE_OPERATION_OPENING``, and ``VALVE_OPERATION_CLOSING``.
|
||||
|
||||
.. note::
|
||||
|
||||
This action can also be written in lambdas:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
id(my_template_valve).position = VALVE_OPEN;
|
||||
id(my_template_valve).publish_state();
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`/components/valve/index`
|
||||
- :ref:`automation`
|
||||
- :doc:`/cookbook/garage-door`
|
||||
- :apiref:`template/valve/template_valve.h`
|
||||
- :ghedit:`Edit`
|
||||
|
|
@ -733,6 +733,14 @@ Cover Components
|
|||
Tuya Cover, components/cover/tuya, tuya.png
|
||||
HE60R Cover, components/cover/he60r, he60r.jpg
|
||||
|
||||
Valve Components
|
||||
----------------
|
||||
|
||||
.. imgtable::
|
||||
|
||||
Valve Core, components/valve/index, folder-open.svg, dark-invert
|
||||
Template Valve, components/valve/template, description.svg, dark-invert
|
||||
|
||||
Text Sensor Components
|
||||
----------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue