mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-09-07 01:08:15 +02:00
1041 lines
48 KiB
ReStructuredText
1041 lines
48 KiB
ReStructuredText
Sprinkler Controller
|
|
====================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up the sprinkler controller component in ESPHome to control sprinkler valves.
|
|
:image: sprinkler-variant.svg
|
|
|
|
.. figure:: images/sprinkler.png
|
|
:align: center
|
|
|
|
The ``sprinkler`` controller component aims to behave like a sprinkler/irrigation valve controller,
|
|
much like those made by companies such as Rain Bird or Hunter. It does so by automating control of a
|
|
number of :ref:`switch <config-switch>` components, each of which would typically be used to control
|
|
an individual electric valve via a relay or other switching device. It provides a number of features
|
|
you'd expect of a sprinkler controller, including:
|
|
|
|
- Virtually any number of zones (sections of the sprinkler system) per controller instance, limited only by
|
|
available memory and/or GPIO (including I/O expanders!) pin availability on the ESP
|
|
- The ability to run:
|
|
|
|
- One or more full cycles (iterations through all zones) of the system
|
|
- Only a single zone
|
|
|
|
- Automatic cycle repeating
|
|
- A multiplier value to proportionally increase or decrease the run duration for all zones
|
|
- Support for pumps/main valves located upstream of distribution valves
|
|
- Pausing and resuming a zone/cycle
|
|
- Iterating through zones in forward or reverse order
|
|
- Support for both latching ("pulsed") and non-latching valves (which can be arbitrarily mixed!)
|
|
|
|
It reaches even further, however, offering several more advanced features, as well:
|
|
|
|
- Multiple sprinkler controller instances can operate simultaneously on a single (ESP) device
|
|
- Multiple pumps, each of which may be shared across controller instances
|
|
- Enable/disable switches for each individual zone, allowing zones to be omitted from full cycles of the system
|
|
- A valve/zone queuing mechanism aimed at providing advanced support for automation
|
|
- Several valve management strategies to accommodate varying types of hardware/installations:
|
|
|
|
- Adjustable "valve open delay" to help ensure valves are fully closed before the next one is opened
|
|
- Adjustable "valve overlap" to help minimize banging of pipes due to water hammer
|
|
- Adjustable delay intervals to coordinate pump starting and stopping relative to distribution valve opening and closing
|
|
|
|
.. note::
|
|
|
|
While the term "pump" is used throughout this document, the device controlled need not be a
|
|
physical pump. Instead, it may simply be another electric valve located upstream of distribution
|
|
valves (often known in the industry as a "main" or "master" valve). The pump or upstream valve
|
|
simply controls the water supply to other downstream valves.
|
|
|
|
.. figure:: images/sprinkler-ui.jpg
|
|
:align: center
|
|
:width: 60.0%
|
|
|
|
Example Sprinkler Controller UI -- Note that this example leverages :ref:`number <config-number>` components
|
|
for setting run durations, repeat and multiplier values. More details below.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example minimal configuration entry
|
|
# (...but please see more detailed examples below!)
|
|
sprinkler:
|
|
- id: sprinkler_ctrlr
|
|
main_switch: "Sprinklers"
|
|
auto_advance_switch: "Sprinklers Auto Advance"
|
|
valves:
|
|
- valve_switch: "Front Lawn"
|
|
enable_switch: "Enable Front Lawn"
|
|
run_duration: 1800s
|
|
valve_switch_id: lawn_sprinkler_valve_sw0
|
|
- valve_switch: "Back Lawn"
|
|
enable_switch: "Enable Back Lawn"
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw1
|
|
|
|
Please see the :ref:`sprinkler-controller-examples` section below for extensive, detailed configuration
|
|
examples that are ready for you to copy and paste!
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **main_switch** (*Optional*, *string*): Required with more than one valve. The name for the sprinkler
|
|
controller's main switch as it will appear in the front end. This switch, when turned on, calls the
|
|
``sprinkler.resume_or_start_full_cycle`` action; when turned off, it calls the ``sprinkler.shutdown``
|
|
action (see below). It will appear to be "on" when any valve on the controller is active. This switch
|
|
will not appear in the front end if the controller is configured with only one valve.
|
|
- **auto_advance_switch** (*Optional*, *string*): Required with more than one valve. The name for the
|
|
sprinkler controller's "auto-advance" switch as it will appear in the front end. When this switch is
|
|
turned on while a valve is active, when the valve's ``run_duration`` is reached, the sprinkler
|
|
controller will automatically advance to the next enabled valve as a part of a "full cycle" of the
|
|
system. When turned off, the sprinkler controller will shut down after the active valve's
|
|
``run_duration`` is reached (unless there are valves in the queue -- see
|
|
:ref:`sprinkler-controller-sprinkler_controller_queue` section below for more detail). This switch will
|
|
not appear in the front end if the controller is configured with only one valve.
|
|
- **manual_selection_delay** (*Optional*, :ref:`config-time`): The amount of time the controller should
|
|
wait to activate a valve after the ``next_valve`` and ``previous_valve`` actions are called. Useful
|
|
if the control interface consists of only forward/reverse buttons as the button(s) may be pressed
|
|
multiple times to make the selection.
|
|
- **queue_enable_switch** (*Optional*, *string*): The name for the sprinkler controller's queue enable
|
|
switch as it will appear in the front end. When this switch is turned on or not provided, the controller
|
|
will select the next valve/zone to run based on the contents of the queue; the queue takes precedence over
|
|
valves that would otherwise run as a part of a full cycle of the system (when auto-advance is on/enabled).
|
|
See :ref:`sprinkler-controller-sprinkler_controller_queue` section below for more detail.
|
|
- **reverse_switch** (*Optional*, *string*): The name for the sprinkler controller's reverse switch
|
|
as it will appear in the front end. When this switch is turned on, the controller will iterate through
|
|
the valves in reverse order (last-to-first as they appear in the controller's configuration). When
|
|
this switch is turned off or not provided, the controller will iterate through the valves first-to-last.
|
|
This switch will not appear in the front end if the controller is configured with only one valve.
|
|
- **valve_open_delay** (*Optional*, :ref:`config-time`): The *minimum* delay in seconds that should be
|
|
inserted between (distribution) valve switching -- in other words, the amount of time that must elapse
|
|
between one valve switching off and the next one switching on. Useful for systems with valves which depend
|
|
on sufficient water pressure to close. May not be used with *valve_overlap*.
|
|
- **valve_overlap** (*Optional*, :ref:`config-time`): The amount of time in seconds that the current valve
|
|
and the next valve should run simultaneously as the next valve/zone starts up. This may help prevent pipes
|
|
from banging as valves close. May not be used with *valve_open_delay*.
|
|
- **pump_switch_off_during_valve_open_delay** (*Optional*, boolean): If set to ``true``, the pump will be
|
|
switched off during the ``valve_open_delay`` interval; otherwise, it remains on. This may only be
|
|
specified when ``valve_open_delay`` is configured (see above). Defaults to ``false``.
|
|
- **pump_start_pump_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a distribution
|
|
valve is opened to when the associated pump is activated. Useful to ensure pressure does not build
|
|
up from running the pump when no distribution valves are open. May not be used with *pump_start_valve_delay*.
|
|
- **pump_start_valve_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a pump
|
|
is started to when the associated distribution valve is opened. Useful for systems where distribution
|
|
valves require sufficient pressure to fully/quickly close. May not be used with *pump_start_pump_delay*.
|
|
- **pump_stop_pump_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a distribution
|
|
valve is closed to when the respective pump is deactivated. Useful for systems where distribution valves
|
|
require sufficient pressure to fully/quickly close. May not be used with *pump_stop_valve_delay*.
|
|
- **pump_stop_valve_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a pump is
|
|
deactivated to when the respective distribution valve is closed. Useful to ensure pressure does not build
|
|
up from running the pump when no distribution valves are open or to allow the main line out to distribution
|
|
valves to drain. May not be used with *pump_stop_pump_delay*.
|
|
- **pump_pulse_duration** (*Optional*, :ref:`config-time`): The *minimum* length of the pulse generated to
|
|
operate a pump in milliseconds. *Required* when one or more latching pumps is configured. Note that the *exact*
|
|
length of the pulse is determined by the frequency of the main application loop (as are other ``delay`` timers
|
|
used in ESPHome). Typically this is expected to provide a resolution of approximately 16 milliseconds, however
|
|
this may vary somewhat depending on your exact configuration. Regardless, it should provide
|
|
more-than-sufficient precision to operate any such valve.
|
|
- **valve_pulse_duration** (*Optional*, :ref:`config-time`): The *minimum* length of the pulse generated to
|
|
operate a valve in milliseconds. *Required* when one or more latching valves is configured. Note that the *exact*
|
|
length of the pulse is determined by the frequency of the main application loop (as are other ``delay`` timers
|
|
used in ESPHome). Typically this is expected to provide a resolution of approximately 16 milliseconds, however
|
|
this may vary somewhat depending on your exact configuration. Regardless, it should provide more-than-sufficient
|
|
precision to operate any such valve.
|
|
- **repeat** (*Optional*, int): The number of times a full cycle should be repeated. Defaults to 0.
|
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. While optional,
|
|
this is necessary to identify the controller instance (particularly in cases where more than one is
|
|
defined) when calling controller actions (see below) such as ``start_full_cycle`` or ``shutdown``.
|
|
- **valves** (**Required**, *list*): A list of valves the controller should use. Each valve consists of:
|
|
|
|
- **enable_switch** (*Optional*, *string*): The name for the switch component to be used to enable
|
|
this valve to be run as a part of a full cycle of the system. When this switch is turned off, the valve
|
|
will be excluded from a full cycle of the system. When this switch is turned on or not provided, the
|
|
controller will include the valve in a full cycle of the system.
|
|
- **valve_switch** (**Required**, *string*): The name for the switch component to be used to control
|
|
the valve for this part of the sprinkler system (often referred to as a "zone"). When this switch is
|
|
turned on, the controller's "auto-advance" feature is disabled and it will activate the associated
|
|
valve for its ``run_duration`` multiplied by the controller's multiplier value. When this switch is
|
|
turned off, the ``sprinkler.shutdown`` action is called (see below).
|
|
- **pump_switch_id** (*Optional*, :ref:`Switch <config-switch>`): This is the :ref:`switch <config-switch>`
|
|
component to be used to control the valve's pump or upstream electric valve. Typically this would be a
|
|
:doc:`GPIO switch <switch/gpio>` wired to control a relay or other switching device which in turn would
|
|
activate the respective pump/valve. *It is not recommended to expose this switch to the front end; please
|
|
see* :ref:`sprinkler-controller-an_important_note_about_gpio_switches_and_control` *below for more detail.*
|
|
May not be specified with *pump_off_switch_id* or *pump_on_switch_id*.
|
|
- **pump_off_switch_id** (*Optional*, :ref:`Switch <config-switch>`): This is the :ref:`switch <config-switch>`
|
|
component to be used to *turn off* the valve's pump or upstream electric *latching* valve. Typically this
|
|
would be a :doc:`GPIO switch <switch/gpio>` wired to control a relay or other switching device which in turn
|
|
would *switch off* the respective pump/valve. *It is not recommended to expose this switch to the front end; please
|
|
see* :ref:`sprinkler-controller-an_important_note_about_gpio_switches_and_control` *below for more detail.*
|
|
May not be specified with *pump_switch_id*.
|
|
- **pump_on_switch_id** (*Optional*, :ref:`Switch <config-switch>`): This is the :ref:`switch <config-switch>`
|
|
component to be used to *turn on* the valve's pump or upstream electric *latching* valve. Typically this
|
|
would be a :doc:`GPIO switch <switch/gpio>` wired to control a relay or other switching device which in turn
|
|
would *switch on* the respective pump/valve. *It is not recommended to expose this switch to the front end; please
|
|
see* :ref:`sprinkler-controller-an_important_note_about_gpio_switches_and_control` *below for more detail.*
|
|
May not be specified with *pump_switch_id*.
|
|
- **run_duration** (**Required**, :ref:`config-time`): The duration in seconds this valve should
|
|
remain on/open after it is activated. When a given valve is activated, the controller's multiplier value
|
|
is multiplied by this value to determine the actual run duration for the valve, thus allowing the run
|
|
duration for all valves/zones to be proportionally increased or decreased as desired.
|
|
- **valve_switch_id** (**Required**, :ref:`Switch <config-switch>`): This is the :ref:`switch <config-switch>`
|
|
component to be used to control the valve that operates the given section or zone of the sprinkler
|
|
system. Typically this would be a :doc:`GPIO switch <switch/gpio>` wired to control a relay
|
|
or other switching device which in turn would activate the respective valve. *It is not recommended
|
|
to expose this switch to the front end; please see* :ref:`sprinkler-controller-an_important_note_about_gpio_switches_and_control`
|
|
*below for more detail.* May not be specified with *valve_off_switch_id* or *valve_on_switch_id*.
|
|
- **valve_off_switch_id** (**Required**, :ref:`Switch <config-switch>`): This is the :ref:`switch <config-switch>`
|
|
component to be used to *turn off* the *latching* valve that operates the given section or zone of the
|
|
sprinkler system. Typically this would be a :doc:`GPIO switch <switch/gpio>` wired to control a relay
|
|
or other switching device which in turn would *switch off* the respective valve. *It is not recommended
|
|
to expose this switch to the front end; please see* :ref:`sprinkler-controller-an_important_note_about_gpio_switches_and_control`
|
|
*below for more detail.* May not be specified with *valve_switch_id*.
|
|
- **valve_on_switch_id** (**Required**, :ref:`Switch <config-switch>`): This is the :ref:`switch <config-switch>`
|
|
component to be used to *turn on* the *latching* valve that operates the given section or zone of the
|
|
sprinkler system. Typically this would be a :doc:`GPIO switch <switch/gpio>` wired to control a relay
|
|
or other switching device which in turn would *switch on* the respective valve. *It is not recommended
|
|
to expose this switch to the front end; please see* :ref:`sprinkler-controller-an_important_note_about_gpio_switches_and_control`
|
|
*below for more detail.* May not be specified with *valve_switch_id*.
|
|
|
|
.. _sprinkler-controller-an_important_note_about_gpio_switches_and_control:
|
|
|
|
An Important Note about GPIO Switches and Control
|
|
-------------------------------------------------
|
|
|
|
The savvy and/or seasoned ESPHome user will quickly realize that ``pump_switch_id``, ``pump_off_switch_id``,
|
|
``pump_on_switch_id``, ``valve_switch_id``, ``valve_off_switch_id`` and ``valve_on_switch_id`` (as described above)
|
|
are really just pointers to other (GPIO) switches elsewhere in the ESPHome yaml configuration.
|
|
|
|
It might seem reasonable to assume that these :doc:`GPIO switches <switch/gpio>` may be used to switch the various
|
|
sprinkler zones on and off, however, this is **not** the case. It's important to note that the sprinkler controller
|
|
provides a switch for each configured zone -- ultimately, this switch is to be used to switch any given zone on or
|
|
off, **not** the :doc:`GPIO switch <switch/gpio>` the zone is configured with.
|
|
|
|
Keep in mind that a :doc:`GPIO switch <switch/gpio>` directly controls the state of the GPIO pin it is associated
|
|
with. While it's technically feasible to "override" this behavior, it might not always be desirable. For example,
|
|
if you *wanted* to control the state of the switch/pin manually during testing of your system/configuration, this
|
|
would make that impossible (or at least more difficult than necessary), presenting other complications. Ultimately,
|
|
flexibility is key, as we've learned from any number of conversations on the ESPHome Discord server.
|
|
|
|
As mentioned in the introduction, the sprinkler controller automates control of the :doc:`GPIO switches <switch/gpio>`
|
|
you provide it with -- it does not "override" control of these switches or alter how they behave beyond simply
|
|
switching them on or off as required based on the configured scheduling.
|
|
|
|
So why not just use the :doc:`GPIO switch <switch/gpio>` to control the various sprinkler zones directly? As it relates
|
|
to the sprinkler controller itself, the primary reason relates to *state* -- that is, we need to be able to ensure
|
|
that the :doc:`GPIO switch <switch/gpio>` state(s) are kept consistent with the configuration of the sprinkler
|
|
controller. While it's less important for systems that simply consist of one valve per zone, it becomes very important
|
|
for systems with some additional complexity. Consider the example of a system with a pump and multiple distribution
|
|
valves attached to said pump; the controller in this case is configured to switch the pump off three seconds *before*
|
|
switching off any given distribution valve. If you suddenly manually switch off a :doc:`GPIO switch <switch/gpio>`
|
|
connected to one of these distribution valves, what happens to the pump? What should the sprinkler controller do? Should
|
|
it switch the distribution valve back on?...or maybe just switch the pump off, too? In either case, based on its
|
|
configuration, the pump was supposed be shut down before the valve, but you just went and turned off the valve. The pump
|
|
could be damaged. There are many other similar situations such as this that may occur, the simplest of which is little
|
|
more than ensuring that any given valve is switched off after *some* duration and does not remain on/open perpetually.
|
|
|
|
In summary, to ensure that your sprinkler controller consistently operates as expected:
|
|
|
|
- Only use the switches provided by the sprinkler controller component to switch any given sprinkler zone on or off.
|
|
- Do not use the :doc:`GPIO switches <switch/gpio>` you have in your configuration to control sprinkler zones/valves
|
|
outside of initial testing of your device configuration.
|
|
- To help prevent accidents, it's probably best if the :doc:`GPIO switches <switch/gpio>` for each sprinkler zone are
|
|
**not** exposed to the front end. This can be accomplished in two ways:
|
|
|
|
- Do not provide a ``name:`` parameter to your :doc:`GPIO switches <switch/gpio>`, or
|
|
- Add ``internal: true`` to each of your :doc:`GPIO switch <switch/gpio>` configurations
|
|
|
|
These simple configuration tweaks will help prevent any number of errors (human, automation, or otherwise) and may help
|
|
to avert disaster!
|
|
|
|
.. _sprinkler-controller-actions:
|
|
|
|
Controller Actions
|
|
------------------
|
|
|
|
.. _sprinkler-controller-action_start_full_cycle:
|
|
|
|
``sprinkler.start_full_cycle`` action
|
|
*************************************
|
|
|
|
Starts a full cycle of the system. This enables the controller's "auto-advance" feature and disables
|
|
the queue. The controller will iterate through all enabled valves/zones. They will each run for their
|
|
configured ``run_duration`` multiplied by the controller's multiplier value. *Note that if NO valves
|
|
are enabled when this action is called, the controller will automatically enable all valves.*
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.start_full_cycle: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_start_from_queue:
|
|
|
|
``sprinkler.start_from_queue`` action
|
|
*************************************
|
|
|
|
Starts the controller running valves from its queue. If no valves are in the queue, this action does
|
|
nothing; otherwise, this disables the controller's "auto-advance" feature so that only queued
|
|
valves/zones will run. Queued valves will remain on for either the amount of time specified in the
|
|
queue request or for their configured ``run_duration`` multiplied by the controller's multiplier value
|
|
(if the queue request run duration is not specified or is zero). *Note that queued valves ignore whether
|
|
the valve is enabled; that is, queued valves will always run once the controller is started, unless, of
|
|
course, the queue is (manually) cleared prior to the queue reaching them. Also note that, at present,
|
|
the queue has a hard-coded limit of 100 entries to limit memory use.*
|
|
See :ref:`sprinkler-controller-sprinkler_controller_queue` section below for more detail.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.start_from_queue:
|
|
id: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_start_single_valve:
|
|
|
|
``sprinkler.start_single_valve`` action
|
|
***************************************
|
|
|
|
Starts a single valve. This disables the controller's "auto-advance" and queue features so that
|
|
only this valve/zone will run. The valve will remain on for its configured ``run_duration``
|
|
multiplied by the controller's multiplier value. *Note that this action ignores whether the valve
|
|
is enabled; that is, when called, the specified valve will always run.* Valves are numbered in the
|
|
order they appear in the sprinkler controller's configuration starting at zero (0).
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.start_single_valve:
|
|
id: sprinkler_ctrlr
|
|
valve_number: 0
|
|
|
|
.. _sprinkler-controller-action_shutdown:
|
|
|
|
``sprinkler.shutdown`` action
|
|
*****************************
|
|
|
|
Immediately (begins to) turns off all valves, effectively shutting down the system, respecting any
|
|
configured pump or valve stop delays.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.shutdown: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_next_valve:
|
|
|
|
``sprinkler.next_valve`` action
|
|
*******************************
|
|
|
|
Advances to the next valve (numerically). If ``manual_selection_delay`` is configured, the controller
|
|
will wait before activating the selected valve. If no valve is active, the first valve (as they appear
|
|
in the controller's configuration) will be started.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.next_valve: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_previous_valve:
|
|
|
|
``sprinkler.previous_valve`` action
|
|
***********************************
|
|
|
|
Advances to the previous valve (numerically). If ``manual_selection_delay`` is configured, the controller
|
|
will wait before activating the selected valve. If no valve is active, the last valve (as they appear in
|
|
the controller's configuration) will be started.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.previous_valve: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_pause:
|
|
|
|
``sprinkler.pause`` action
|
|
**************************
|
|
|
|
Immediately turns off all valves, saving the active valve and the amount of time remaining so that
|
|
the cycle may be resumed later on.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.pause: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_resume:
|
|
|
|
``sprinkler.resume`` action
|
|
***************************
|
|
|
|
Resumes a cycle placed on hold with ``sprinkler.pause``. If there is no paused cycle, this action
|
|
will do nothing.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.resume: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_resume_or_start_full_cycle:
|
|
|
|
``sprinkler.resume_or_start_full_cycle`` action
|
|
***********************************************
|
|
|
|
Resumes a cycle placed on hold with ``sprinkler.pause``, but if no cycle was paused, starts a full
|
|
cycle (equivalent to ``sprinkler.start_full_cycle``).
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.resume_or_start_full_cycle: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_queue_valve:
|
|
|
|
``sprinkler.queue_valve`` action
|
|
********************************
|
|
|
|
Adds the specified valve into the controller's queue. When the queue is enabled, valves in the queue
|
|
take precedence over valves scheduled as a part of a full cycle of the system (when auto-advance is
|
|
enabled). If ``run_duration`` is not specified or is zero, the sprinkler controller will use the
|
|
valve's configured run duration. Valves are numbered in the order they appear in the sprinkler
|
|
controller's configuration starting at zero (0). *Note that, at present, the queue has a hard-coded
|
|
limit of 100 entries to limit memory use.* Please see :ref:`sprinkler-controller-sprinkler_controller_queue`
|
|
section below for more detail and examples.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.queue_valve:
|
|
id: sprinkler_ctrlr
|
|
valve_number: 2
|
|
run_duration: 900s
|
|
|
|
.. _sprinkler-controller-action_clear_queued_valves:
|
|
|
|
``sprinkler.clear_queued_valves`` action
|
|
****************************************
|
|
|
|
Removes all queued valves from the controller's queue. Please see :ref:`sprinkler-controller-sprinkler_controller_queue`
|
|
section below for more detail and examples.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.clear_queued_valves:
|
|
id: sprinkler_ctrlr
|
|
|
|
.. _sprinkler-controller-action_set_multiplier:
|
|
|
|
``sprinkler.set_multiplier`` action
|
|
***********************************
|
|
|
|
Sets the multiplier value used to proportionally increase or decrease the run duration for all valves/zones.
|
|
When a given valve is activated, this value is multiplied by the valve's run duration (see below) to
|
|
determine the valve's actual run duration.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.set_multiplier:
|
|
id: sprinkler_ctrlr
|
|
multiplier: 1.5
|
|
|
|
.. _sprinkler-controller-action_set_repeat:
|
|
|
|
``sprinkler.set_repeat`` action
|
|
*******************************
|
|
|
|
Specifies the number of times full cycles should be repeated. **Note that the total number of cycles
|
|
the controller will run is equal to the repeat value plus one.** For example, with a ``repeat`` value
|
|
of 1, the initial cycle will run, then the repeat cycle will run, resulting in a total of two cycles.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.set_repeat:
|
|
id: sprinkler_ctrlr
|
|
repeat: 2 # would run three cycles
|
|
|
|
.. _sprinkler-controller-action_set_valve_run_duration:
|
|
|
|
``sprinkler.set_valve_run_duration`` action
|
|
*******************************************
|
|
|
|
Sets the run duration for the specified valve. When the valve is activated, this value is multiplied
|
|
by the multiplier value (see above) to determine the valve's actual run duration.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
then:
|
|
- sprinkler.set_valve_run_duration:
|
|
id: sprinkler_ctrlr
|
|
valve_number: 0
|
|
run_duration: 600s
|
|
|
|
.. note::
|
|
|
|
- The ``next_valve``, ``previous_valve`` and ``start_single_valve`` actions ignore whether a valve
|
|
is enabled via its enable switch.
|
|
- The ``next_valve`` and ``previous_valve`` actions may not appear to respond immediately if either
|
|
``manual_selection_delay`` or any of the various delay mechanisms described in the
|
|
:ref:`sprinkler-controller-pump_and_distribution_valve_coordination` section below are configured.
|
|
If you are using any of these configuration options, be sure to allow the delay intervals to elapse
|
|
before assuming something isn't working!
|
|
- If a valve is active when its ``run_duration`` or the multiplier value is changed, the active
|
|
valve's run duration will remain unaffected until the next time it is started.
|
|
|
|
.. _sprinkler-controller-pump_and_distribution_valve_coordination:
|
|
|
|
Pump and Distribution Valve Coordination
|
|
----------------------------------------
|
|
|
|
The sprinkler controller allows extensive flexibility relating to the switching of pumps and valves.
|
|
Let's take a closer look at how to use these features to tune your system.
|
|
|
|
Delayed Starting and/or Stopping of Pumps or Valves
|
|
***************************************************
|
|
|
|
For systems with pumps, it's generally a bad idea to run the pump with no distribution valves open.
|
|
This causes pressure to build up and can even destroy the pump after some time. For systems with (a)
|
|
pump(s), you'll likely want to add two configuration options:
|
|
|
|
.. code-block:: yaml
|
|
|
|
sprinkler:
|
|
- id: lawn_sprinkler_ctrlr
|
|
pump_start_pump_delay: 3s
|
|
pump_stop_valve_delay: 3s
|
|
...
|
|
|
|
This will cause any given pump to start (in this example) three seconds *after* any associated distribution
|
|
valve is opened. In addition, it will wait three seconds to close the *last* distribution valve *after*
|
|
the pump is stopped. This would allow the pump to spin down, pressure to drop and lines to drain prior
|
|
to switching off the (last) associated distribution valve. (In these configurations, it might also be
|
|
desirable to enable ``valve_overlap``, as well -- more on this below.)
|
|
|
|
Some types of electric valves require sufficient water pressure to (fully/quickly) close. These types of
|
|
valves, when coupled with electric valves upstream of distribution valves (often known in the industry as
|
|
"main" or "master" valves), may require that the upstream valve is switched on *before* any given distribution
|
|
valve(s), allowing the water pressure to stabilize and force all distribution valves closed *before* any single
|
|
distribution valve is opened. In these situations, the reverse of the above configuration may be desirable:
|
|
|
|
.. code-block:: yaml
|
|
|
|
sprinkler:
|
|
- id: lawn_sprinkler_ctrlr
|
|
pump_start_valve_delay: 3s
|
|
pump_stop_pump_delay: 3s
|
|
...
|
|
|
|
In this example, the upstream valve would open three seconds prior to any given associated distribution
|
|
valve, allowing the water pressure to force any attached distribution valves closed. After the delay, the
|
|
required distribution valve is opened and the cycle starts. When the cycle is complete, the (last) distribution
|
|
valve would be switched off three seconds prior to the upstream valve. (In these configurations, it might also
|
|
be desirable to enable ``valve_open_delay``, as well.)
|
|
|
|
.. note::
|
|
|
|
Using ``pump_stop_valve_delay`` or ``pump_stop_pump_delay`` with ``valve_open_delay`` and
|
|
``pump_switch_off_during_valve_open_delay`` may increase the off-time inserted between the operation
|
|
of each zone, as the controller must wait for a given zone (pump *and* valve) to fully shut down before
|
|
it can be started again.
|
|
|
|
Banging Pipes or Valves That Don't Consistently Close
|
|
*****************************************************
|
|
|
|
A common complaint people have with sprinkler systems is that of banging pipes. In other, less common situations,
|
|
some systems suffer from valves that do not (fully/quickly) close. There are three controller options available to
|
|
address either of these complaints/concerns:
|
|
|
|
- ``valve_overlap``
|
|
- ``valve_open_delay``
|
|
- ``pump_switch_off_during_valve_open_delay``
|
|
|
|
The first option, ``valve_overlap``, causes the current valve and the next valve (as the controller is iterating
|
|
through valves) to run simultaneously for the duration specified. The idea here is that this causes a reduction
|
|
in water pressure as the next zone starts up, therefore minimizing banging pipes (aka the "water hammer" effect)
|
|
when the valve that is finishing up finally closes.
|
|
|
|
The second and third options may be used to ensure sufficient water pressure is available to force valves closed.
|
|
This may be useful for pressure-sensitive valves that don't quickly and/or fully close when water pressure is low.
|
|
|
|
For systems with pumps, it may be desirable to switch off the pump before switching to the next distribution
|
|
valve/zone. In these situations, ``pump_switch_off_during_valve_open_delay`` may prove useful in conjunction
|
|
with ``valve_open_delay``.
|
|
|
|
In any case, the examples in the next section illustrate how/where to add these options into your configuration.
|
|
|
|
.. _sprinkler-controller-examples:
|
|
|
|
Controller Examples
|
|
-------------------
|
|
|
|
Single Controller, Single Valve, No Pump
|
|
****************************************
|
|
|
|
This first example illustrates a complete, single-valve system with no pump/upstream valve(s). It
|
|
could be useful for controlling a single valve independent of any other sprinkler controllers. A pump
|
|
could easily be added by adding the ``pump_switch_id`` parameter and a :ref:`switch <config-switch>`.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
name: esp-sprinkler-controller
|
|
platform: ESP32
|
|
board: featheresp32
|
|
|
|
wifi:
|
|
ssid: "wifi_ssid"
|
|
password: "wifi_password"
|
|
|
|
logger:
|
|
|
|
sprinkler:
|
|
- id: garden_sprinkler_ctrlr
|
|
valves:
|
|
- valve_switch: "Flower Garden"
|
|
run_duration: 300s
|
|
valve_switch_id: garden_sprinkler_valve
|
|
|
|
switch:
|
|
- platform: gpio
|
|
id: garden_sprinkler_valve
|
|
pin: 5
|
|
|
|
Single Controller, Three Valves, No Pump
|
|
****************************************
|
|
|
|
This example illustrates a complete, simple three-valve system with no pump/upstream valve(s):
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
name: esp-sprinkler-controller
|
|
platform: ESP32
|
|
board: featheresp32
|
|
|
|
wifi:
|
|
ssid: "wifi_ssid"
|
|
password: "wifi_password"
|
|
|
|
logger:
|
|
|
|
sprinkler:
|
|
- id: lawn_sprinkler_ctrlr
|
|
main_switch: "Lawn Sprinklers"
|
|
auto_advance_switch: "Lawn Sprinklers Auto Advance"
|
|
reverse_switch: "Lawn Sprinklers Reverse"
|
|
valve_overlap: 5s
|
|
valves:
|
|
- valve_switch: "Front Lawn"
|
|
enable_switch: "Enable Front Lawn"
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw0
|
|
- valve_switch: "Side Lawn"
|
|
enable_switch: "Enable Side Lawn"
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw1
|
|
- valve_switch: "Back Lawn"
|
|
enable_switch: "Enable Back Lawn"
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw2
|
|
|
|
switch:
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw0
|
|
pin: 0
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw1
|
|
pin: 2
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw2
|
|
pin: 4
|
|
|
|
Single Controller, Three Valves, Single Pump
|
|
********************************************
|
|
|
|
This example illustrates a complete three-valve system with a single pump/upstream valve:
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
name: esp-sprinkler-controller
|
|
platform: ESP32
|
|
board: featheresp32
|
|
|
|
wifi:
|
|
ssid: "wifi_ssid"
|
|
password: "wifi_password"
|
|
|
|
logger:
|
|
|
|
sprinkler:
|
|
- id: lawn_sprinkler_ctrlr
|
|
main_switch: "Lawn Sprinklers"
|
|
auto_advance_switch: "Lawn Sprinklers Auto Advance"
|
|
reverse_switch: "Lawn Sprinklers Reverse"
|
|
valve_open_delay: 5s
|
|
valves:
|
|
- valve_switch: "Front Lawn"
|
|
enable_switch: "Enable Front Lawn"
|
|
pump_switch_id: sprinkler_pump_sw
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw0
|
|
- valve_switch: "Side Lawn"
|
|
enable_switch: "Enable Side Lawn"
|
|
pump_switch_id: sprinkler_pump_sw
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw1
|
|
- valve_switch: "Back Lawn"
|
|
enable_switch: "Enable Back Lawn"
|
|
pump_switch_id: sprinkler_pump_sw
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw2
|
|
|
|
switch:
|
|
- platform: gpio
|
|
id: sprinkler_pump_sw
|
|
pin: 12
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw0
|
|
pin: 0
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw1
|
|
pin: 2
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw2
|
|
pin: 4
|
|
|
|
Single Controller, Three Latching Valves, Single Latching Pump
|
|
**************************************************************
|
|
|
|
This example is similar to the previous example, however it illustrates how a "latching" or "pulsed"
|
|
valve can be configured. This type of valve requires two :doc:`GPIO switches <switch/gpio>` to
|
|
operate -- one to switch the valve on and one to switch the valve off. To switch on the valve, the
|
|
"on" :doc:`GPIO switch <switch/gpio>` is switched on for the configured duration and then switched
|
|
off. To switch the valve off, the "off" :doc:`GPIO switch <switch/gpio>` is switched on for the
|
|
configured duration and then switched off.
|
|
|
|
Note that, while this example illustrates a configuration that uses exclusively latching valves,
|
|
latching and non-latching valves may be mixed and matched in any configuration, even if attached to
|
|
a common pump/upstream valve.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
name: esp-sprinkler-controller
|
|
platform: ESP32
|
|
board: featheresp32
|
|
|
|
wifi:
|
|
ssid: "wifi_ssid"
|
|
password: "wifi_password"
|
|
|
|
logger:
|
|
|
|
sprinkler:
|
|
- id: lawn_sprinkler_ctrlr
|
|
main_switch: "Lawn Sprinklers"
|
|
auto_advance_switch: "Lawn Sprinklers Auto Advance"
|
|
queue_enable_switch: "Lawn Sprinklers Queue Enable"
|
|
reverse_switch: "Lawn Sprinklers Reverse"
|
|
pump_pulse_duration: 250ms
|
|
valve_pulse_duration: 250ms
|
|
valve_open_delay: 5s
|
|
valves:
|
|
- valve_switch: "Front Lawn"
|
|
enable_switch: "Enable Front Lawn"
|
|
pump_off_switch_id: sprinkler_pump_sw_off
|
|
pump_on_switch_id: sprinkler_pump_sw_on
|
|
run_duration: 900s
|
|
valve_off_switch_id: lawn_sprinkler_valve_sw0_off
|
|
valve_on_switch_id: lawn_sprinkler_valve_sw0_on
|
|
- valve_switch: "Side Lawn"
|
|
enable_switch: "Enable Side Lawn"
|
|
pump_off_switch_id: sprinkler_pump_sw_off
|
|
pump_on_switch_id: sprinkler_pump_sw_on
|
|
run_duration: 900s
|
|
valve_off_switch_id: lawn_sprinkler_valve_sw1_off
|
|
valve_on_switch_id: lawn_sprinkler_valve_sw1_on
|
|
- valve_switch: "Back Lawn"
|
|
enable_switch: "Enable Back Lawn"
|
|
pump_off_switch_id: sprinkler_pump_sw_off
|
|
pump_on_switch_id: sprinkler_pump_sw_on
|
|
run_duration: 900s
|
|
valve_off_switch_id: lawn_sprinkler_valve_sw2_off
|
|
valve_on_switch_id: lawn_sprinkler_valve_sw2_on
|
|
|
|
switch:
|
|
- platform: gpio
|
|
id: sprinkler_pump_sw_off
|
|
pin: 14
|
|
- platform: gpio
|
|
id: sprinkler_pump_sw_on
|
|
pin: 15
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw0_off
|
|
pin: 0
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw0_on
|
|
pin: 2
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw1_off
|
|
pin: 4
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw1_on
|
|
pin: 5
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw2_off
|
|
pin: 12
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw2_on
|
|
pin: 13
|
|
|
|
Dual Controller, Five Valves, Two Pumps
|
|
***************************************
|
|
|
|
This example illustrates a complete and more complex dual-controller system with a total of five
|
|
valves (three on the first controller and two on the second controller) and two pumps/upstream
|
|
valves, each of which are shared between the two controllers:
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
name: esp-sprinkler-controller
|
|
platform: ESP32
|
|
board: featheresp32
|
|
|
|
wifi:
|
|
ssid: "wifi_ssid"
|
|
password: "wifi_password"
|
|
|
|
logger:
|
|
|
|
sprinkler:
|
|
- id: lawn_sprinkler_ctrlr
|
|
main_switch: "Lawn Sprinklers"
|
|
auto_advance_switch: "Lawn Sprinklers Auto Advance"
|
|
reverse_switch: "Lawn Sprinklers Reverse"
|
|
valve_overlap: 5s
|
|
valves:
|
|
- valve_switch: "Front Lawn"
|
|
enable_switch: "Enable Front Lawn"
|
|
pump_switch_id: sprinkler_pump_sw0
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw0
|
|
- valve_switch: "Side Lawn"
|
|
enable_switch: "Enable Side Lawn"
|
|
pump_switch_id: sprinkler_pump_sw0
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw1
|
|
- valve_switch: "Back Lawn"
|
|
enable_switch: "Enable Back Lawn"
|
|
pump_switch_id: sprinkler_pump_sw1
|
|
run_duration: 900s
|
|
valve_switch_id: lawn_sprinkler_valve_sw2
|
|
- id: garden_sprinkler_ctrlr
|
|
main_switch: "Garden Sprinklers"
|
|
auto_advance_switch: "Garden Sprinklers Auto Advance"
|
|
reverse_switch: "Garden Sprinklers Reverse"
|
|
valve_open_delay: 5s
|
|
valves:
|
|
- valve_switch: "Front Garden"
|
|
enable_switch: "Enable Front Garden"
|
|
pump_switch_id: sprinkler_pump_sw0
|
|
run_duration: 900s
|
|
valve_switch_id: garden_sprinkler_valve_sw0
|
|
- valve_switch: "Back Garden"
|
|
enable_switch: "Enable Back Garden"
|
|
pump_switch_id: sprinkler_pump_sw1
|
|
run_duration: 900s
|
|
valve_switch_id: garden_sprinkler_valve_sw1
|
|
|
|
switch:
|
|
- platform: gpio
|
|
id: sprinkler_pump_sw0
|
|
pin: 12
|
|
- platform: gpio
|
|
id: sprinkler_pump_sw1
|
|
pin: 13
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw0
|
|
pin: 0
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw1
|
|
pin: 2
|
|
- platform: gpio
|
|
id: lawn_sprinkler_valve_sw2
|
|
pin: 4
|
|
- platform: gpio
|
|
id: garden_sprinkler_valve_sw0
|
|
pin: 14
|
|
- platform: gpio
|
|
id: garden_sprinkler_valve_sw1
|
|
pin: 15
|
|
|
|
.. note::
|
|
|
|
In this final complete configuration example, pump control is split among the two sprinkler
|
|
controller instances. This will behave as expected; multiple instances of the controller will
|
|
communicate to ensure any given pump is activated and deactivated only as necessary, even when
|
|
the controllers are operating simultaneously.
|
|
|
|
Extending the Sprinkler Controller's Switches
|
|
*********************************************
|
|
|
|
It is worth noting that each of the various switches in the sprinkler controller's configuration are standard
|
|
ESPHome :ref:`switch <config-switch>` components. Their configuration may be extended in a manner similar to
|
|
the following example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Extended switch configuration for 'main_switch'
|
|
sprinkler:
|
|
- id: sprinkler_ctrlr
|
|
main_switch:
|
|
name: "Lawn Sprinklers"
|
|
id: sprinkler_ctrlr_main_switch_id
|
|
on_turn_on:
|
|
light.turn_on: my_light
|
|
...
|
|
|
|
This arrangement is possible for any other switch within the sprinkler controller's configuration block, with
|
|
the exception of ``pump_off_switch_id``, ``pump_on_switch_id``, ``pump_switch_id``, ``valve_off_switch_id``,
|
|
``valve_on_switch_id`` and ``valve_switch_id`` (because these are the IDs of other switch components already
|
|
defined elsewhere in your configuration). In addition, specifying each switch ID enables the ability to refer
|
|
to any of the sprinkler controller's switches from elsewhere in your configuration. Here's another brief example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Template switch as a secondary main switch
|
|
switch:
|
|
- platform: template
|
|
id: my_switch
|
|
name: "My Special Sprinkler Switch"
|
|
on_turn_off:
|
|
- switch.turn_off: sprinkler_ctrlr_main_switch_id
|
|
- light.turn_off: sprinkler_indicator_light
|
|
on_turn_on:
|
|
- switch.turn_on: sprinkler_ctrlr_main_switch_id
|
|
- light.turn_on: sprinkler_indicator_light
|
|
...
|
|
|
|
While the above example simply illustrates creating a secondary "main" switch, this approach could be extended
|
|
to take advantage of other devices such as a moisture :ref:`sensor <config-sensor>` -- when the moisture level
|
|
is too low (look for ``on_value`` or ``on_value_range``), the sprinkler controller (or a specific valve) could
|
|
be activated by calling one of the controller's start-up actions, such as ``sprinkler.start_full_cycle``,
|
|
``sprinkler.start_from_queue``, ``sprinkler.start_single_valve``, or ``sprinkler.resume_or_start_full_cycle``.
|
|
|
|
.. _sprinkler-controller-sprinkler_controller_queue:
|
|
|
|
The Sprinkler Controller Queue
|
|
******************************
|
|
|
|
The queuing mechanism is an unusual feature for a sprinkler controller; it becomes useful as a result of the
|
|
extreme flexibility of both ESPHome and Home Assistant. Given the extensive ecosystem of devices available today,
|
|
the sprinkler controller's queuing mechanism provides an advanced feature aimed at allowing even more advanced automation.
|
|
|
|
In general, it comes down to flexibility: the more traditional "run full cycle" and "run single valve" functionality
|
|
is intended for use by humans (via the front end or physical control interface) while the queuing mechanism is aimed
|
|
at supporting automation.
|
|
|
|
Here's a practical example:
|
|
|
|
Consider a home with a yard divided into a number of sprinkler zones -- perhaps it even includes a garden or two
|
|
(flowers and vegetables, of course!). An array of soil moisture sensors could be deployed throughout the various
|
|
zones and gardens and when a given sensor falls below some defined threshold, that sensor's zone is entered into
|
|
the sprinkler controller's queue.
|
|
|
|
Then, each morning at some specific hour, Home Assistant (or even the ESP device itself!) calls the sprinkler
|
|
controller's ``sprinkler.start_from_queue`` action, causing the controller to iterate only through queued zones.
|
|
Because the run duration may be specified as a part of the queue request, this could be extended to compute a
|
|
specific run duration for each zone depending on the specific moisture level of the soil on any given day. The
|
|
possibilities are endless and are only limited by your creativity!
|
|
|
|
It is important to note that, if *both* the auto-advance and queue switches are turned on/enabled, **queued valves
|
|
take precedence over valves that would run as a part of a full cycle of the system.** In other words, if the queue
|
|
is enabled and a valve is entered into the queue while a full cycle is active, at the next valve transition, the
|
|
queue entry will be picked up *before* the next valve that would run as a part of the full cycle. At present, this
|
|
behavior cannot be changed. It should also be noted that the queue has a hard-coded limit of 100 entries to limit
|
|
memory use.
|
|
|
|
Additional Tricks
|
|
*****************
|
|
|
|
Beyond what is shown in the configuration examples above, other ESPHome elements may be called into
|
|
play to help build out an extensive interface for the controller in the front end (Home Assistant).
|
|
For example, the :ref:`number <config-number>` component may be used to set valve run durations or
|
|
the controller's multiplier value:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration to set multiplier via number
|
|
number:
|
|
- platform: template
|
|
id: sprinkler_ctrlr_multiplier
|
|
name: "Sprinkler Controller Multiplier"
|
|
min_value: 0.1
|
|
max_value: 10.0
|
|
step: 0.1
|
|
lambda: "return id(lawn_sprinkler_ctrlr).multiplier();"
|
|
set_action:
|
|
- sprinkler.set_multiplier:
|
|
id: lawn_sprinkler_ctrlr
|
|
multiplier: !lambda 'return x;'
|
|
|
|
Expose Sprinkler Controller Actions via user-API
|
|
************************************************
|
|
|
|
This configuration snippet illustrates how user-defined ESPHome API services may be used to expose
|
|
various sprinkler controller actions to the front end. This could be useful to change settings
|
|
and/or trigger sprinkler controller actions using automations.
|
|
|
|
.. code-block:: yaml
|
|
|
|
api:
|
|
services:
|
|
- service: set_multiplier
|
|
variables:
|
|
multiplier: float
|
|
then:
|
|
- sprinkler.set_multiplier:
|
|
id: lawn_sprinkler_ctrlr
|
|
multiplier: !lambda 'return multiplier;'
|
|
- service: start_full_cycle
|
|
then:
|
|
- sprinkler.start_full_cycle: lawn_sprinkler_ctrlr
|
|
- service: start_single_valve
|
|
variables:
|
|
valve: int
|
|
then:
|
|
- sprinkler.start_single_valve:
|
|
id: lawn_sprinkler_ctrlr
|
|
valve_number: !lambda 'return valve;'
|
|
- service: next_valve
|
|
then:
|
|
- sprinkler.next_valve: lawn_sprinkler_ctrlr
|
|
- service: previous_valve
|
|
then:
|
|
- sprinkler.previous_valve: lawn_sprinkler_ctrlr
|
|
- service: shutdown
|
|
then:
|
|
- sprinkler.shutdown: lawn_sprinkler_ctrlr
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :apiref:`sprinkler/sprinkler.h`
|
|
- :apiref:`switch/switch.h`
|
|
- :ghedit:`Edit`
|