Skip to content
ESPHome - Smart Home Made Simple 2026.5.2

Time Based Valve

The time_based valve platform allows you to create valves with position control that do not have any position feedback. The state of the valve is thus always an assumed one, the current position is approximated with the time the valve has been moving in a direction. The state of the valve can be restored at node reboot.

# Example configuration entry
valve:
  - platform: time_based
    name: "Time-Based Valve"


    open_action:
      - switch.turn_on: open_valve_switch
    open_duration: 2.1min


    close_action:
      - switch.turn_on: close_valve_switch
    close_duration: 2min


    stop_action:
      - switch.turn_off: open_valve_switch
      - switch.turn_off: close_valve_switch

Configuration variables

Section titled “Configuration variables”

  • open_action (Required, Action): The action that should be performed when the remote requests the valve to be opened.

  • open_duration (Required, Time): The amount of time it takes the valve to open up from the fully-closed state.

  • close_action (Required, Action): The action that should be performed when the remote requests the valve to be closed.

  • close_duration (Required, Time): The amount of time it takes the valve to close from the fully-open state.

  • stop_action (Required, Action): The action that should be performed to stop the valve when the remote requests the valve to be stopped or when the valve has been opening/closing for the given durations.

  • has_built_in_endstop (Optional, boolean): Indicates that the valve has built in end stop detectors. In this configuration the stop_action is not performed when the open or close time is completed and if the valve is commanded to open or close the corresponding actions will be performed without checking current state. Defaults to false.

  • manual_control (Optional, boolean): For valves with manual external controls. With this configuration if the valve is commanded to open or close the corresponding actions will be performed even if the current state fully open or fully closed matches desired state, then stop_action will be called after the full duration of the action elapses. The current state will then be relearned upon completion. It’s recommended to set assumed_state to true so the valve control buttons aren’t disabled in the interface. 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 or disabling one of them. Defaults to true.

  • All other options from Valve.

NOTE

The stop button on the UI is always enabled even when the valve is stopped and each press on the button will cause the stop_action to be performed.

Handle stop_action

Section titled “Handle stop_action”

For some valve controllers, separate switches for OPEN and CLOSE action are used while a stop is issued when sending a counter command. This can be handled at the stop_action by using the following lambda function:

stop_action:
  - lambda: !lambda |-
      if (id(valve).get_last_operation() == ValveOperation::VALVE_OPERATION_OPENING) {
        // Valve is currently opening
        id(valve_button_close).press();
      } else if (id(valve).get_last_operation() == ValveOperation::VALVE_OPERATION_CLOSING) {
        // Valve is currently closing
        id(valve_button_open).press();
      }

See Also

Section titled “See Also”