Filtration Control¶

When a pump switch entity is configured in the integration, Pool Manager can automatically control your pool pump on a daily schedule. This feature creates additional entities that let you enable scheduling, set a start time, and configure a duration -- the pump then turns on and off automatically every day.

Prerequisites¶

Filtration control requires a switch entity that controls your pool pump. This can be:

• A smart plug or relay connected via any integration (Shelly, Sonoff, Tasmota, etc.)
• An ESPHome GPIO switch
• A virtual switch for testing

Configure the pump entity in the integration's filtration settings step (or update it later via Settings > Devices & Services > Pool Manager > Configure).

Entities¶

When a pump entity is configured, the following entities are added to your Pool Manager device:

Switch¶

When turned on, the scheduler activates and the pump follows the configured schedule. When turned off, the pump is turned off immediately and all scheduled triggers are cancelled.

Select¶

See Duration Mode below for details.

Time¶

Number¶

Event¶

Each event carries the following attributes:

Duration Mode¶

The Filtration duration mode select entity controls how the daily filtration duration is determined. The default mode is dynamic.

There are four modes, organised into two categories: single-period modes (one continuous filtration window per day) and split modes (two separate filtration windows per day).

Single-period modes¶

Dynamic mode (default)¶

In dynamic mode, Pool Manager automatically sets the filtration duration from the computed recommended value on each data refresh (every 5 minutes). The recommendation is based on water temperature, filter type efficiency, outdoor heat stress, and pump turnover rate (see Pool Modes for the full algorithm).

When the coordinator updates:

1. The recommended filtration hours are computed from current sensor readings
2. If a valid recommendation is available, the scheduler duration is automatically updated to match
3. The filtration duration number entity reflects the active duration

If the water temperature sensor becomes unavailable, the scheduler keeps the last known duration until a new reading is available.

Manual mode¶

In manual mode, the computed recommendation is not applied to the scheduler. The user controls the duration entirely through the filtration duration number entity. The recommended filtration sensor (sensor.{pool}_filtration_duration) still displays the computed value for reference, but it has no effect on the schedule.

Split modes¶

Split modes divide the daily filtration into two separate periods, each with its own start time and duration. This is useful when you want to distribute pump runtime across the day (e.g. morning and afternoon) rather than running a single long filtration cycle.

When a split mode is selected:

• The period 2 entities (time.{pool}_filtration_start_time_2 and number.{pool}_filtration_duration_setting_2) become available
• The scheduler manages two independent start/stop trigger pairs
• Filtration events include a period_index attribute (0 or 1) to identify which period triggered the event

Split (static) mode¶

Both periods use user-set durations. You configure a start time and duration for each period independently through the time and number entities.

The recommended filtration sensor still displays the computed value for reference, but neither period is automatically adjusted.

Split (dynamic) mode¶

The first period has a user-set duration, while the second period's duration is automatically computed to reach the daily filtration recommendation. On each coordinator update:

1. The recommended total filtration hours are computed
2. The second period's duration is set to: max(min_dynamic_duration, recommendation − period_1_duration)
3. If the recommendation is less than or equal to the first period's duration, the second period effectively has zero duration (or the configured minimum)

This mode is ideal when you want a guaranteed base filtration in the morning and an adaptive top-up in the afternoon based on current conditions.

The filtration_duration_setting_2 number entity reflects the auto-computed duration. It is available but adjustments are overwritten on the next coordinator refresh.

Switching modes¶

• Dynamic to manual: The scheduler keeps the last dynamically computed duration. The user can then adjust it via the number entity.
• Manual to dynamic: The next coordinator update (within 5 minutes) syncs the scheduler to the current recommendation.
• Single to split: Period 2 entities become available with their default values (start 16:00, duration 4 h). A second set of start/stop triggers is registered in the scheduler.
• Split to single: Period 2 entities become unavailable. The second period's triggers are removed from the scheduler.

The selected mode is persisted across Home Assistant restarts.

Scheduling Behavior¶

Daily cycle¶

The scheduler registers time-based triggers for the start and end of each filtration period. In single-period modes, one start/stop pair is registered. In split modes, two independent start/stop pairs are managed.

Each period operates independently: the pump turns on at the period's start time and off after its duration elapses.

Cross-midnight schedules¶

Schedules that cross midnight are fully supported for any period. For example, a start time of 22:00 with a duration of 8 hours creates a window from 22:00 to 06:00 the next day.

Restart recovery¶

Both the filtration control switch state and all time/duration settings are persisted across Home Assistant restarts using RestoreEntity. On restart:

1. The switch restores its last known on/off state
2. The time, duration, and duration mode entities restore their last values (including period 2 entities in split modes)
3. If the switch was on, the scheduler re-enables and checks whether the current time falls within any active window -- if so, the pump is turned on immediately
4. If the restored mode is dynamic or split (dynamic), the first coordinator refresh syncs the scheduler duration(s) from the current recommendation

Mid-cycle changes¶

Changing the start time or duration while the scheduler is enabled takes effect immediately:

• Triggers are recalculated for the new schedule
• The pump state is adjusted right away: if the current time is now inside the new window the pump turns on; if outside, it turns off

Disabling filtration control¶

Turning off the filtration control switch:

1. Cancels all scheduled triggers
2. Turns the pump off immediately

Automation Examples¶

Notify when filtration starts¶

automation:
  - alias: "Notify filtration started"
    trigger:
      - platform: state
        entity_id: event.demo_pool_filtration
        attribute: event_type
        to: "filtration_started"
    action:
      - action: notify.notify
        data:
          title: "Pool"
          message: "Filtration pump started"

Relationship to the Recommended Filtration Sensor¶

The sensor.{pool}_filtration_duration entity is an advisory value computed from water temperature, filter type, outdoor temperature, and pump capacity (see Pool Modes for the algorithm).

The filtration control feature provides active control: it actually turns the pump on and off.

• In dynamic mode (the default), the recommendation feeds directly into the scheduler on each coordinator refresh.
• In manual mode, the recommendation has no effect on the schedule.
• In split (static) mode, the recommendation is displayed for reference only; both periods are fully user-controlled.
• In split (dynamic) mode, the recommendation drives the second period's duration: the remaining hours after subtracting period 1's duration are assigned to period 2.

Filtration Boost¶

The filtration boost lets you manually trigger extra continuous filtration time on top of the daily schedule. This is useful when you need additional circulation -- for example, after adding chemicals, after a pool party, or during a heat wave.

How it works¶

• Inside a scheduled window: the boost extends the pump run past the next natural stop. The pump continues running without interruption until the boost expires.
• Outside a scheduled window: the pump starts immediately and runs for the boost duration.
• Split mode: while a boost is active the pump does not stop between periods. The boost keeps the pump running continuously until it expires.
• A new boost replaces any previously active boost.

Boost entities¶

The filtration event entity (event.{pool}_filtration) also fires boost events:

Boost events include the following attributes:

Service¶

You can also activate a boost with a custom duration using the poolman.boost_filtration service:

service: poolman.boost_filtration
data:
  device_id: "your_pool_device_id"
  hours: 6.0

Set hours to 0 to cancel an active boost.

Persistence¶

The boost end time is persisted via the select entity's extra state attributes. After a Home Assistant restart, the integration restores any active boost and resumes the countdown. If the boost has already expired during the downtime, it is silently discarded.

Cancellation¶

A boost can be cancelled by:

• Selecting None in the boost select entity
• Calling poolman.boost_filtration with hours: 0
• Disabling the filtration control switch (which also stops the pump)

If the pump was only running because of the boost (outside the normal schedule), it is turned off upon cancellation.

Automation examples¶

Boost filtration after a treatment¶

automation:
  - alias: "Boost after shock chlorine"
    trigger:
      - platform: state
        entity_id: event.demo_pool_chlore_choc
        attribute: event_type
        to: "applied"
    action:
      - action: poolman.boost_filtration
        data:
          device_id: "your_pool_device_id"
          hours: 8.0

Notify when boost expires¶

automation:
  - alias: "Notify boost consumed"
    trigger:
      - platform: state
        entity_id: event.demo_pool_filtration
        attribute: event_type
        to: "boost_consumed"
    action:
      - action: notify.notify
        data:
          title: "Pool"
          message: "Filtration boost has finished"