[sprinkler] Update doc for removal of latching valve support (#5806)

* [sprinkler] Update doc for removal of latching valve support

* lint

Author: kbx81

content/components/sprinkler.md

@@ -139,20 +139,6 @@ examples that are ready for you to copy and paste!
   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*, [Time](/guides/configuration-types#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*, [Time](/guides/configuration-types#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.
-
 - **multiplier_number** (*Optional*, *string*): The name of the {{< docref "/components/number/index" "number" >}} component that
   should be presented to the front end (Home Assistant) to enable control of the sprinkler controller's `multiplier`
   value. See [Using the Sprinkler Controller's Numbers](#sprinkler-controller-sprinkler_controller_numbers) below for more detail.
@@ -189,23 +175,10 @@ examples that are ready for you to copy and paste!
   - **pump_switch_id** (*Optional*, [Switch](/components/switch#config-switch)): This is the [switch](/components/switch#config-switch)
     component to be used to control the valve's pump or upstream electric valve. Typically this would be a
     {{< docref "switch/gpio" "GPIO switch" >}} 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* [An Important Note about GPIO Switches and Control](#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*, [Switch](/components/switch#config-switch)): This is the [switch](/components/switch#config-switch)
-    component to be used to *turn off* the valve's pump or upstream electric *latching* valve. Typically this
-    would be a {{< docref "switch/gpio" "GPIO switch" >}} 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* [An Important Note about GPIO Switches and Control](#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*, [Switch](/components/switch#config-switch)): This is the [switch](/components/switch#config-switch)
-    component to be used to *turn on* the valve's pump or upstream electric *latching* valve. Typically this
-    would be a {{< docref "switch/gpio" "GPIO switch" >}} 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* [An Important Note about GPIO Switches and Control](#sprinkler-controller-an_important_note_about_gpio_switches_and_control) *below for more detail.*
-    May not be specified with *pump_switch_id*.
+    activate the respective pump/valve. For latching valves/pumps, use an {{< docref "switch/hbridge" "H-Bridge switch" >}}.
+    *It is not recommended to expose this switch to the front end; please see*
+    [An Important Note about GPIO Switches and Control](#sprinkler-controller-an_important_note_about_gpio_switches_and_control)
+    *below for more detail.*
 
   - **run_duration_number** (*Optional*, *string*): The name of the {{< docref "/components/number/index" "number" >}} component
     that should be presented to the front end (Home Assistant) to enable control of the valve's `run_duration` value.
@@ -222,71 +195,58 @@ examples that are ready for you to copy and paste!
   - **valve_switch_id** (**Required**, [Switch](/components/switch#config-switch)): This is the [switch](/components/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 {{< docref "switch/gpio" "GPIO switch" >}} 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* [An Important Note about GPIO Switches and Control](#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**, [Switch](/components/switch#config-switch)): This is the [switch](/components/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 {{< docref "switch/gpio" "GPIO switch" >}} 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* [An Important Note about GPIO Switches and Control](#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**, [Switch](/components/switch#config-switch)): This is the [switch](/components/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 {{< docref "switch/gpio" "GPIO switch" >}} 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* [An Important Note about GPIO Switches and Control](#sprinkler-controller-an_important_note_about_gpio_switches_and_control)
-    *below for more detail.* May not be specified with *valve_switch_id*.
+    or other switching device which in turn would activate the respective valve. For latching valves, use an
+    {{< docref "switch/hbridge" "H-Bridge switch" >}}. *It is not recommended to expose this switch to the front end; please see*
+    [An Important Note about GPIO Switches and Control](#sprinkler-controller-an_important_note_about_gpio_switches_and_control)
+    *below for more detail.*
 
 {{< anchor "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.
+The savvy and/or seasoned ESPHome user will quickly realize that `pump_switch_id` and `valve_switch_id` (as described
+above) are really just pointers to other switches elsewhere in the ESPHome yaml configuration.
 
-It might seem reasonable to assume that these {{< docref "switch/gpio" "GPIO switches" >}} 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 {{< docref "switch/gpio" "GPIO switch" >}} the zone is configured with.
+It might seem reasonable to assume that these switches (typically {{< docref "switch/gpio" "GPIO switches" >}} or
+{{< docref "switch/hbridge" "H-Bridge switches" >}}) 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 underlying
+switch the zone is configured with.
 
-Keep in mind that a {{< docref "switch/gpio" "GPIO switch" >}} 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 doing so 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.
+Keep in mind that a switch directly controls its associated hardware (GPIO pins, H-Bridge circuits, etc.). 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 manually during testing of your system/configuration, this would make doing so 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 {{< docref "switch/gpio" "GPIO switches" >}}
-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.
+As mentioned in the introduction, the sprinkler controller automates control of the switches 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 {{< docref "switch/gpio" "GPIO switch" >}} to control the various sprinkler zones directly? As it relates
+So why not just use the underlying switches 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 {{< docref "switch/gpio" "GPIO switch" >}} 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 {{< docref "switch/gpio" "GPIO switch" >}}
-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.
+that the switch 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 an underlying switch 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 {{< docref "switch/gpio" "GPIO switches" >}} you have in your configuration to control sprinkler zones/valves
-  outside of initial testing of your device configuration.
+- Do not use the underlying switches (GPIO, H-Bridge, etc.) 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 {{< docref "switch/gpio" "GPIO switches" >}} for each sprinkler zone are
-  **not** exposed to the front end. This can be accomplished in two ways:
+- To help prevent accidents, it's probably best if the underlying switches 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 {{< docref "switch/gpio" "GPIO switches" >}}, or
-  - Add `internal: true` to each of your {{< docref "switch/gpio" "GPIO switch" >}} configurations
+  - Do not provide a `name:` parameter to your switches, or
+  - Add `internal: true` to each of your switch configurations
 
 These simple configuration tweaks will help prevent any number of errors (human, automation, or otherwise) and may help
 to avert disaster!
@@ -646,7 +606,7 @@ esphome:
     name: esp-sprinkler-controller
 
 esp32:
-    board: featheresp32
+    board: esp32dev
 
 wifi:
     ssid: "wifi_ssid"
@@ -676,7 +636,7 @@ esphome:
     name: esp-sprinkler-controller
 
 esp32:
-    board: featheresp32
+    board: esp32dev
 
 wifi:
     ssid: "wifi_ssid"
@@ -727,7 +687,7 @@ esphome:
     name: esp-sprinkler-controller
 
 esp32:
-    board: featheresp32
+    board: esp32dev
 
 wifi:
     ssid: "wifi_ssid"
@@ -776,11 +736,8 @@ switch:
 ### 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 {{< docref "switch/gpio" "GPIO switches" >}} to
-operate -- one to switch the valve on and one to switch the valve off. To switch on the valve, the
-"on" {{< docref "switch/gpio" "GPIO switch" >}} is switched on for the configured duration and then switched
-off. To switch the valve off, the "off" {{< docref "switch/gpio" "GPIO switch" >}} is switched on for the
-configured duration and then switched off.
+valve can be configured using {{< docref "switch/hbridge" "H-Bridge switches" >}}. This type of valve
+requires two GPIO pins to operate -- one to switch the valve on and another to switch the valve 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
@@ -791,7 +748,7 @@ esphome:
   name: esp-sprinkler-controller
 
 esp32:
-  board: featheresp32
+  board: esp32dev
 
 wifi:
   ssid: "wifi_ssid"
@@ -805,57 +762,45 @@ sprinkler:
     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
+        pump_switch_id: sprinkler_pump_sw
         run_duration: 900s
-        valve_off_switch_id: lawn_sprinkler_valve_sw0_off
-        valve_on_switch_id: lawn_sprinkler_valve_sw0_on
+        valve_switch_id: lawn_sprinkler_valve_sw0
       - 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
+        pump_switch_id: sprinkler_pump_sw
         run_duration: 900s
-        valve_off_switch_id: lawn_sprinkler_valve_sw1_off
-        valve_on_switch_id: lawn_sprinkler_valve_sw1_on
+        valve_switch_id: lawn_sprinkler_valve_sw1
       - 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
+        pump_switch_id: sprinkler_pump_sw
         run_duration: 900s
-        valve_off_switch_id: lawn_sprinkler_valve_sw2_off
-        valve_on_switch_id: lawn_sprinkler_valve_sw2_on
+        valve_switch_id: lawn_sprinkler_valve_sw2
 
 switch:
-  - platform: gpio
-    id: sprinkler_pump_sw_off
-    pin: GPIOXX
-  - platform: gpio
-    id: sprinkler_pump_sw_on
-    pin: GPIOXX
-  - platform: gpio
-    id: lawn_sprinkler_valve_sw0_off
-    pin: GPIOXX
-  - platform: gpio
-    id: lawn_sprinkler_valve_sw0_on
-    pin: GPIOXX
-  - platform: gpio
-    id: lawn_sprinkler_valve_sw1_off
-    pin: GPIOXX
-  - platform: gpio
-    id: lawn_sprinkler_valve_sw1_on
-    pin: GPIOXX
-  - platform: gpio
-    id: lawn_sprinkler_valve_sw2_off
-    pin: GPIOXX
-  - platform: gpio
-    id: lawn_sprinkler_valve_sw2_on
-    pin: GPIOXX
+  - platform: hbridge
+    id: sprinkler_pump_sw
+    on_pin: GPIOXX
+    off_pin: GPIOXX
+    pulse_length: 250ms
+  - platform: hbridge
+    id: lawn_sprinkler_valve_sw0
+    on_pin: GPIOXX
+    off_pin: GPIOXX
+    pulse_length: 250ms
+  - platform: hbridge
+    id: lawn_sprinkler_valve_sw1
+    on_pin: GPIOXX
+    off_pin: GPIOXX
+    pulse_length: 250ms
+  - platform: hbridge
+    id: lawn_sprinkler_valve_sw2
+    on_pin: GPIOXX
+    off_pin: GPIOXX
+    pulse_length: 250ms
 ```
 
 ### Dual Controller, Five Valves, Two Pumps
@@ -869,7 +814,7 @@ esphome:
     name: esp-sprinkler-controller
 
 esp32:
-    board: featheresp32
+    board: esp32dev
 
 wifi:
     ssid: "wifi_ssid"
@@ -1025,8 +970,7 @@ sprinkler:
 ```
 
 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
+the exception of `pump_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: