diff --git a/components/index.rst b/components/index.rst index b9aba9769..a3e62fc17 100644 --- a/components/index.rst +++ b/components/index.rst @@ -29,4 +29,5 @@ Components time/index alarm_control_panel/index text/index + valve/index * diff --git a/components/valve/images/valve-ui.png b/components/valve/images/valve-ui.png new file mode 100644 index 000000000..33c91f984 Binary files /dev/null and b/components/valve/images/valve-ui.png differ diff --git a/components/valve/index.rst b/components/valve/index.rst new file mode 100644 index 000000000..c6f196ac1 --- /dev/null +++ b/components/valve/index.rst @@ -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 ` 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 `. + + +.. _valve-open_action: + +``valve.open`` Action +--------------------- + +This :ref:`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 `: + + .. 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 ` 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 `: + + .. 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 ` 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 `: + + .. 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 ` 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 `: + + .. 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 ` 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 `: + + .. 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 `, 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: + + * diff --git a/components/valve/template.rst b/components/valve/template.rst new file mode 100644 index 000000000..f3d3ffb5c --- /dev/null +++ b/components/valve/template.rst @@ -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 `): + Lambda to be evaluated repeatedly to get the current state of the valve. +- **open_action** (*Optional*, :ref:`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 `): The action that should be performed when the remote + requests the valve to be closed. +- **stop_action** (*Optional*, :ref:`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 `): 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 `. + +.. _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 `): + The state to publish. One of ``OPEN``, ``CLOSED``. If using a lambda, use ``VALVE_OPEN`` or ``VALVE_CLOSED``. +- **position** (*Optional*, :ref:`templatable `, float): + The position to publish, from 0 (CLOSED) to 1.0 (OPEN) +- **current_operation** (*Optional*, :ref:`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` diff --git a/index.rst b/index.rst index 3c8d4b96d..c89beaad8 100644 --- a/index.rst +++ b/index.rst @@ -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 ----------------------