diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 0000000..7aa4961
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,57 @@
+name: Tests
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ["3.13"]
+ ha-version: ["stable", "dev"]
+ continue-on-error: ${{ matrix.ha-version == 'dev' }}
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python ${{ matrix.python-version }}
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python-version }}
+
+ - name: Install dependencies
+ run: |
+ python -m pip install --upgrade pip
+ if [ "${{ matrix.ha-version }}" = "dev" ]; then
+ python -m pip install pytest pytest-asyncio
+ python -m pip install --pre pytest-homeassistant-custom-component
+ else
+ python -m pip install homeassistant
+ python -m pip install pytest pytest-asyncio pytest-homeassistant-custom-component
+ fi
+
+ - name: Run tests
+ run: pytest tests/ -v
+
+ lint:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.13"
+
+ - name: Install ruff
+ run: python -m pip install ruff
+
+ - name: Check formatting
+ run: ruff format --check .
+
+ - name: Check linting
+ run: ruff check .
diff --git a/.gitignore b/.gitignore
index 0e008a5..0a5fc39 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,4 +6,6 @@
__pycache__/
-*.iml
\ No newline at end of file
+*.iml
+.coverage
+docs/plans/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7f95a53..4d78fd3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,43 @@
+## Unreleased
+
+### Features
+
+- **UI-first configuration:** Config flow creates covers via UI; all settings managed through a Lovelace card and WebSocket API
+- **Control mode:** Single `control_mode` setting replaces separate `device_type`/`input_mode` — choose from wrapped, switch, pulse, or toggle
+- **External state monitoring:** Detects physical switch presses and keeps the position tracker in sync with actual motor state. Supports all control modes for both cover and tilt switches
+- **Separate tilt motor (dual_motor) mode:** Support for covers with a dedicated tilt motor, with configurable safe tilt position and max tilt allowed position
+- **Inline tilt mode:** Support for covers where the tilt mechanism is part of the main travel range (e.g. Venetian blinds), with configurable tilt range within the overall travel
+- **Calibration system:** Measure timing parameters interactively — start calibration, let the motor run, stop when done. Supports all travel and tilt timing attributes with overhead compensation
+- **Background pulse completion:** Pulse and toggle mode commands return immediately while the relay pulse completes in the background
+- **Tilt switch monitoring:** Monitors tilt switch entities for external changes in all modes (pulse, switch, toggle)
+- **Lovelace configuration card:** Full settings UI with entity pickers, timing fields, tilt strategy selection, and calibration controls
+- **Toggle mode improvements:** Debounce for momentary switches, cross-direction external toggles treated as stop, HA UI direction changes still reverse
+
+### Improvements
+
+- Replaced external `xknx` TravelCalculator dependency with a local HA-convention copy (no external dependencies)
+- Card translations embedded directly in JS with `_t()` helper and `hass.language` locale lookup (English, Portuguese, Polish)
+- Refactored codebase: extracted calibration mixin, tilt strategies package, shared constants, entity resolution helpers
+- Updated calibration hint descriptions for all tilt modes (inline, sequential, dual_motor)
+- Frontend defaults safe_tilt_position=100 and max_tilt_allowed_position=0 for new dual_motor configs
+- Cleaned up diagnostic logging in toggle mode
+- Improved test coverage from 66% to 97% (528 tests)
+
+### Bug Fixes
+
+- Fixed calibration direction override for tilt attributes — server now derives direction from attribute name instead of card sending position-based guess
+- Fixed calibration overhead calculation for tilt (3 steps vs 8 travel steps)
+- Fixed toggle mode tilt restore clearing `_last_command` prematurely, breaking stop pulse
+- Fixed dual_motor tilt commands using wrong service calls
+- Fixed `safe_tilt_position=0` being coerced to default 100
+- Fixed zero travel/tilt times accepted by WebSocket API schema
+- Fixed `_last_command` not set during toggle mode calibration
+- Fixed pulse mode stop switch not stopping the position tracker
+- Fixed toggle mode external state handler only reacting to ON→OFF (now handles both transitions)
+- Fixed switch mode tilt handler using pulse-mode behavior (now uses latching: ON=start, OFF=stop)
+- Fixed tilt switch echo filtering (pending=2 for direction switches to handle ON+OFF transitions)
+- Fixed wrapped cover handler not tracking direction changes (opening→closing)
+
## 3.0.0 (2025-12-10)
### Features
diff --git a/README.md b/README.md
index b5bae9a..abe8ea8 100644
--- a/README.md
+++ b/README.md
@@ -11,27 +11,26 @@ A Home Assistant integration to control your cover based on time.
This integration is based on [davidramosweb/home-assistant-custom-components-cover-time-based](https://github.com/davidramosweb/home-assistant-custom-components-cover-time-based/).
-It improves the original integration by adding tilt control and synchronized travel/tilt movements.
+It improves the original integration by adding tilt control, synchronized travel/tilt movements, and a visual configuration card.
### Features:
-- **Control the height of your cover based on time**.
-- **Control the tilt of your cover based on time**.
-- **Synchronized movement:** Travel and tilt move proportionally on the same motor.
-- **Optional endpoint delay:** Configurable relay delay at endpoints for covers with mechanical endstops.
-- **Minimum movement time:** Prevents position drift from very short relay activations.
-- **Motor startup compensation:** Optional delay compensation for motor inertia to improve position accuracy.
-
-_To enable tilt control you need to add the `tilting_time_down` and `tilting_time_up` options to your configuration.yaml._
+- **Control the position of your cover based on time**.
+- **External state monitoring:** Detects physical switch presses and keeps the position tracker in sync.
+- **Multiple input modes:** Latching switches, momentary pulse buttons, or toggle-style relays.
+- **Wrap an existing cover:** Add time-based position tracking to any cover entity.
+- **Control the tilt of your cover based on time** with three tilt modes: inline, sequential (closes then tilts), or separate tilt motor.
+- **Built-in configuration and calibration:** Calibrate travel times directly from the UI, including finer parameters to compensate for the time it takes the motor to startup.
+- **Resyncs position at endpoints:** The motor can be configured to run-on at the 0%/100% endpoints to resync the position tracker with the physical cover.
## Install
### HACS
-_This repo is available for install through the HACS._
+_This repo is available for install through HACS._
-- Go to HACS → Integrations
-- Use the FAB "Explore and download repositories" to search "cover-time-based".
+- Go to HACS
+- Search for "Cover time based"
_or_
@@ -41,197 +40,287 @@ Click here:
## Setup
-### Example configuration.yaml entry
+### Creating a cover via the UI
-#### Basic configuration with individual device settings:
+1. Go to **Settings → Devices & Services → Helpers**
+2. Click **Create Helper → Cover Time Based**
+3. Enter a name for your cover
-```yaml
-cover:
- - platform: cover_time_based
- devices:
- room_rolling_shutter:
- name: Room Rolling Shutter
- open_switch_entity_id: switch.wall_switch_right
- close_switch_entity_id: switch.wall_switch_left
- travel_moves_with_tilt: false
- travelling_time_down: 23
- travelling_time_up: 25
- tilting_time_down: 2.3
- tilting_time_up: 2.7
- travel_delay_at_end: 2.0
- min_movement_time: 0.5
- travel_startup_delay: 0.1
- tilt_startup_delay: 0.08
-```
+### Setup the configuration card
-#### Configuration with shared defaults:
+The configuration card provides a visual interface for all settings and supports built-in calibration to measure timing parameters automatically.
-```yaml
-cover:
- - platform: cover_time_based
- # Optional: Default values for all devices
- defaults:
- travelling_time_down: 49.2
- travelling_time_up: 50.7
- tilting_time_down: 1.5
- tilting_time_up: 1.5
- travel_delay_at_end: 1.5
- min_movement_time: 0.5
- travel_startup_delay: 0.1
- tilt_startup_delay: 0.08
+1. Go to **Settings → Dashboards**.
+2. Click **Add dashboard → New dashboard from scratch**.
+3. Fill in a name and make sure **Add to sidebar** is selected.
+4. Click **Create**.
+5. Click the new dashboard icon in the Home Assistant side bar.
+6. Click the **Edit dashboard** icon in the top right corner.
+7. Under **New section** click the **+** icon to add a new card.
+8. Search for and select the **Cover time based configuration** card and click **Save**.
+9. Click **Done** to stop editing the dashboard.
- devices:
- # This device uses all defaults
- bedroom_left:
- name: Bedroom Left
- open_switch_entity_id: switch.bedroom_left_open
- close_switch_entity_id: switch.bedroom_left_close
-
- # This device overrides some defaults
- bedroom_right:
- name: Bedroom Right
- travelling_time_down: 52.0 # Override default
- open_switch_entity_id: switch.bedroom_right_open
- close_switch_entity_id: switch.bedroom_right_close
-
- # This device explicitly disables startup delay
- kitchen:
- name: Kitchen
- travel_startup_delay: null # Override to disable
- open_switch_entity_id: switch.kitchen_open
- close_switch_entity_id: switch.kitchen_close
-```
+### Configuration and Calibration Card
-### Options
-
-| Name | Type | Requirement | Description | Default |
-| ---------------------- | ------------ | ----------------------------------------------- | ------------------------------------------------------------------------- | ------- |
-| name | string | **Required** | Name of the created entity | |
-| open_switch_entity_id | state entity | **Required** or `cover_entity_id` | Entity ID of the switch for opening the cover | |
-| close_switch_entity_id | state entity | **Required** or `cover_entity_id` | Entity ID of the switch for closing the cover | |
-| stop_switch_entity_id | state entity | _Optional_ or `cover_entity_id` | Entity ID of the switch for stopping the cover | None |
-| cover_entity_id | state entity | **Required** or `open_\|close_switch_entity_id` | Entity ID of a existing cover entity | |
-| travel_moves_with_tilt | boolean | _Optional_ | Whether tilt movements also cause proportional travel changes | False |
-| travelling_time_down | int | _Optional_ | Time it takes in seconds to close the cover | 30 |
-| travelling_time_up | int | _Optional_ | Time it takes in seconds to open the cover | 30 |
-| tilting_time_down | float | _Optional_ | Time it takes in seconds to tilt the cover all the way down | None |
-| tilting_time_up | float | _Optional_ | Time it takes in seconds to tilt the cover all the way up | None |
-| travel_delay_at_end | float | _Optional_ | Additional relay time (seconds) at endpoints (0%/100%) for position reset | None |
-| min_movement_time | float | _Optional_ | Minimum movement duration (seconds) - blocks shorter movements | None |
-| travel_startup_delay | float | _Optional_ | Motor startup time compensation (seconds) for travel movements | None |
-| tilt_startup_delay | float | _Optional_ | Motor startup time compensation (seconds) for tilt movements | None |
-| input_mode | string | _Optional_ (`cover_entity_id` not supported) | `switch` (latching), `pulse` (momentary+stop), `toggle` (same btn stops) | switch |
-| pulse_time | float | _Optional_ | Duration in seconds for button press in `pulse`/`toggle` modes | 1.0 |
-
-## Advanced Features
-
-### Default Values (defaults)
-
-You can define default values for timing parameters that will be used by all devices unless explicitly overridden. This reduces configuration duplication when you have multiple covers with similar characteristics.
+The configuration card provides a visual interface for all settings and supports built-in calibration to measure timing parameters automatically.
-**How it works:**
+The configuration card has two tabs: **Device** and **Calibration**. The Device tab must be fully configured before accessing the Calibration tab.
-- Values in `defaults` section apply to all devices
-- Device-specific values override defaults
-- Explicit `null` in device config overrides defaults (disables feature)
-- If neither defaults nor device config specify a value, schema defaults are used
+The main items on the **Device** configure how to interface with the
+physical cover:
-**Priority order:**
+- **Device type**: whether this helper talks to the cover via open/close switches or via an existing cover entity
+- **Switch type**: whether the switches are latching, pulsed, or toggled.
+- **Tilting**: what type of tilt, if any, is supported.
-1. Device-specific value (highest priority)
-2. Defaults value
-3. Schema default (lowest priority)
+The **Calibration** tab is used to configure:
-### Synchronized Travel and Tilt
+- **Position**: sync the position tracker with the physical cover and slat position.
+- **Travel**: how long it takes to open and close the cover, and how much time it takes to start the motor.
+- **Tilt**: how long it takes to open and close the slats, and how much time it takes to start the motor.
-When both `tilting_time_down/up` are configured, the integration simulates realistic blind behavior:
+## Device
-- **Travel movements** always adjust tilt proportionally
-- **Tilt movements** affect travel only when `travel_moves_with_tilt: true`
-- Movements are time-synchronized and stop simultaneously
+First configure the **Device type**. A cover-time-based helper can either:
-**Example:** With `travelling_time=10s` and `tilting_time=5s`, moving travel 50% changes tilt 100%.
+- wrap an existing cover entity to add time-based position tracking, or
+- use relay switches to control cover movement, and optionally to
+ control tilt movement.
-### Travel Moves With Tilt (travel_moves_with_tilt)
+### Wrapped covers
-Controls whether tilt adjustments cause proportional travel movement.
+Wrap an existing cover entity to add time-based position tracking. Useful for covers that already have basic open/close/stop functionality but lack position tracking.
-- **`false` (default):** Only travel movements affect tilt. Tilt can be adjusted independently.
-- **`true`:** Both travel and tilt movements are synchronized on the same motor.
+Specify the **Cover entity**.
-```yaml
-travel_moves_with_tilt: true
-```
+### Switch-based covers
-### Automatic Position Constraints
+Control a cover using two relay switches (one for open, one for close), with an optional third stop switch.
-At endpoint positions, tilt is automatically constrained to prevent drift:
+Specify the **Open switch**, **Close switch**, and optionally the **Stop switch** entities.
-- **At 0% (fully open):** Tilt is set to 0% (horizontal)
-- **At 100% (fully closed):** Tilt is set to 100% (vertical)
+### Input Mode for switch-based covers
-### Endpoint Delay (travel_delay_at_end)
+Three input modes are available to describe how the switch entities for switch-based covers function:
-For covers with mechanical endstops, keeps the relay active for additional time after reaching endpoints to reset position.
+| Mode | Description |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Switch** | Latching relays. The direction switch stays ON for the entire movement. Movement stops when the switch is turned OFF |
+| **Pulse** | Momentary pulse buttons. A brief ON-OFF pulse latches the motor on. Requires a stop button to stop movement, or movement stops when the hardware reaches its endpoint. |
+| **Toggle** | Toggle-style relays. A brief ON-OFF pulse latches the motor on. A second pulse on the same direction button stops the motor. |
-```yaml
-travel_delay_at_end: 2.0
-```
+#### Pulse time
-Recommended values: 1.0 - 3.0 seconds
+With the **Pulse** and **Toggle** input modes, the **Pulse time** configures how long the switch should send the ON signal before it turns OFF. Defaults to **1s**.
-### Minimum Movement Time (min_movement_time)
+## Tilt Mode
-Prevents position drift by blocking relay activations too brief to physically move the cover. Movements to 0% or 100% are always allowed.
+The **Tilt Mode** setting controls how tilt and travel interact:
-```yaml
-min_movement_time: 0.5
-```
+- **None:** Tilt is disabled. Only position tracking is used.
+- **Inline:** Tilt and travel use the same motor. Tilting can happen with the cover in any position. When closing the cover, the closing movement first causes the slats to tilt closed before the cover starts closing. When opening the cover, the opening movement first causes the slats to tilt open before the cover starts opening.
+- **Sequential (closes then tilts):** Tilting can only happen in the fully closed position. First the cover closes then the slats tilt closed. When opening, first the slats tilt open then the cover opens.
+- **Separate tilt motor (dual_motor):** A separate motor controls the tilt. Requires dedicated tilt open/close/stop switches. Tilt is only allowed when the cover is in a safe position (configurable).
+
+### Tilt Motor
+
+For covers with a dedicated tilt motor, configure:
+
+- **Tilt open/close/stop switches:** The relay switches controlling the tilt motor (unless this is a wrapped cover entity which doesn't require extra switches).
+- **Safe tilt position:** The tilt moves to this position before travel starts (default: 100 = fully open).
+- **Max tilt allowed position:** Tilt is only allowed when the cover position is at or below this value (e.g., 0 = only when fully closed).
+
+## Calibration
+
+The **Calibration** tab is used to synchronise the position tracker with the position of the physical cover and slats, and to configure the timings that allow this integration to track the physical hardware.
-Recommended values: 0.5 - 1.5 seconds
+### Current Position
-### Motor Startup Delay (travel_startup_delay, tilt_startup_delay)
+Use the open/stop/close buttons to move the cover (and slats, if tilting is enabled) into a known position and then change the **Current Position** dropdown from `Unknown` to that position. The position must be specified in order to access the calibration tests further down the page.
-Optional feature to compensate for **motor inertia** by delaying position tracking after relay activation. This improves position accuracy, especially for short movements.
+### Timing Calibration
-**The problem:**
+Select the attribute that you wish to calibrate. The available attributes depend on the current position of the cover and slats, and which other attributes have already been configured. For instance, in position **Fully open** you can only calibrate **Travel time (close)** and **Minimum movement time**. **Travel startup delay** becomes configurable once **Travel time (open)** or **Travel time (close)** has been configured.
-- Motors have startup inertia - after relay turns ON, there's a brief delay before the cover actually starts moving
-- This delay (typically 0.05-0.15s) is counted in timing but doesn't move the cover
-- For long movements (e.g., 30s), this is negligible (0.3% error)
-- For short movements (e.g., 0.5s), this is significant (20-30% error)
-- Multiple short movements accumulate drift
+1. Set the **Current position** of the cover and slats.
+2. Select the attribute you wish to configure.
+3. Read the description of what needs to be measured.
+4. Click **Start**.
+5. Once the cover or slats reach the position described in the description, click **Finish**. Alternatively, click **Cancel** to abort the calibration.
+
+### Calibration Attributes for Travel
+
+| Option | Description | Default |
+| -------------------- | --------------------------------------------------------------------- | ------- |
+| Travel time (close) | Time in seconds for the cover to fully close | |
+| Travel time (open) | Time in seconds for the cover to fully open | |
+| Travel startup delay | Motor startup compensation for travel (see below) | None |
+| Endpoint run-on time | Extra relay time at endpoints (0%/100%) to reset position | 2.0 |
+| Min movement time | Minimum movement duration - blocks shorter movements to prevent drift | None |
+
+### Calibration Attributes for Tilt
+
+| Option | Description | Default |
+| ------------------ | ---------------------------------------------- | ------- |
+| Tilt time (close) | Time in seconds to tilt the cover fully closed | None |
+| Tilt time (open) | Time in seconds to tilt the cover fully open | None |
+| Tilt startup delay | Motor startup compensation for tilt | None |
+
+#### Travel/Tilt startup delay
+
+Compensates for motor inertia by delaying position tracking after relay activation. This improves position accuracy, especially for short movements.
+
+**The problem:** Motors have startup inertia. After the relay turns ON, there's a brief delay before the cover starts moving. For long movements (e.g., 30s) this is negligible, but for short movements (e.g. 0.5s) it can cause 20-30% position error that accumulates over time.
**How it works:**
1. Relay turns ON immediately
-2. Waits for `startup_delay` (motor is starting up)
-3. Only then starts counting position change in Home Assistant
-4. Can be cancelled at any time (STOP or direction change)
+2. Waits for the configured startup delay (motor is starting up)
+3. Only then starts counting position change
+4. Can be cancelled at any time (stop or direction change)
+
+Recommended values: 0.05 - 0.15 seconds. Can be configured separately for travel and tilt.
+
+#### Endpoint Run-on Time
+
+Position tracking is not exact and can drift over time. To reduce drift, the position tracker resyncs itself whenever the cover is sent to the 0% or 100% endpoints. The motor continues running for the number of seconds specified in the **Endpoint Run-on Time** in case the physical cover hasn't quite reached the endpoint. Defaults to 2s.
+
+#### Min movement time
-**Example:**
+Prevents position drift by blocking relay activations too brief to physically move the cover. Movements to 0% or 100% are always allowed. Recommended values: 0.5 - 1.5 seconds.
+
+## Services
+
+### `cover_time_based.set_known_position`
+
+Manually set the internal position of a cover. Useful for correcting drift.
+
+| Field | Description |
+| --------- | --------------------------- |
+| entity_id | The cover entity |
+| position | The position to set (0-100) |
+
+### `cover_time_based.set_known_tilt_position`
+
+Manually set the internal tilt position of a cover.
+
+| Field | Description |
+| ------------- | -------------------------------- |
+| entity_id | The cover entity |
+| tilt_position | The tilt position to set (0-100) |
+
+### `cover_time_based.start_calibration`
+
+Start a calibration test to measure a timing parameter.
+
+| Field | Description |
+| --------- | ------------------------------------------------------------------------------ |
+| entity_id | The cover entity |
+| attribute | The timing parameter to calibrate |
+| timeout | Safety timeout in seconds - motor auto-stops if stop_calibration is not called |
+| direction | Direction to move (`open` or `close`). Auto-detects if not set |
+
+### `cover_time_based.stop_calibration`
+
+Stop an active calibration test and save the result.
+
+| Field | Description |
+| --------- | --------------------------------------------- |
+| entity_id | The cover entity |
+| cancel | If `true`, discard the results without saving |
+
+## Debugging
+
+If something isn't working as expected, you can enable debug logging to see detailed information about what the integration is doing.
+
+### Via Developer Tools
+
+1. Go to **Developer Tools → Actions**.
+2. Search for **Logger: Set level** and select it.
+3. Switch to YAML mode and enter:
```yaml
-travel_startup_delay: 0.1 # 100ms startup delay for travel
-tilt_startup_delay: 0.08 # 80ms startup delay for tilt
+action: logger.set_level
+data:
+ custom_components.cover_time_based: debug
+```
-# User command: Tilt 1% (normally 0.03s)
-# Actual timing: Relay ON for 0.11s total (0.08s startup + 0.03s movement)
-# Result: Cover actually moves 1%
+4. Click **Perform action**.
+5. Reproduce the issue — debug messages will appear in the Home Assistant log.
+
+To turn off debug logging, repeat the steps above but change `debug` to `info`.
+
+### Via YAML
+
+Add the following to your `configuration.yaml`:
+
+```yaml
+logger:
+ default: info
+ logs:
+ custom_components.cover_time_based: debug
```
-**Recommended values:** 0.05 - 0.15 seconds
+Restart Home Assistant to apply.
+
+## Reporting Issues
-**Important notes:**
+If you encounter a bug or have a feature request, please open an issue on [GitHub](https://github.com/clintongormley/ha-cover-time-based/issues). Include debug logs if possible — they help diagnose problems much faster.
+
+## YAML configuration (deprecated)
+
+> **Note:** YAML configuration is deprecated and will be removed in a future version. Please use the UI method described above instead. Existing YAML configurations will continue to work, and a deprecation notice will appear in your Home Assistant repairs panel.
+
+
+Show YAML configuration (deprecated)
+
+### Basic configuration with individual device settings:
+
+```yaml
+cover:
+ - platform: cover_time_based
+ devices:
+ room_rolling_shutter:
+ name: Room Rolling Shutter
+ open_switch_entity_id: switch.wall_switch_right
+ close_switch_entity_id: switch.wall_switch_left
+ travel_moves_with_tilt: false
+ travelling_time_down: 23
+ travelling_time_up: 25
+ tilting_time_down: 2.3
+ tilting_time_up: 2.7
+ travel_delay_at_end: 2.0
+ min_movement_time: 0.5
+ travel_startup_delay: 0.1
+ tilt_startup_delay: 0.08
+```
-- This is a fixed time per relay activation, not a percentage
-- Works best when calibrated for your specific motor
-- Can be different for travel and tilt if needed
-- Compatible with `min_movement_time` and `travel_delay_at_end`
+### YAML options
+
+| Name | Type | Requirement | Description | Default |
+| ---------------------- | ------- | ----------------------------------------------- | ----------------------------------------------------------------------- | ------- |
+| name | string | **Required** | Name of the created entity | |
+| open_switch_entity_id | entity | **Required** or `cover_entity_id` | Entity ID of the switch for opening the cover | |
+| close_switch_entity_id | entity | **Required** or `cover_entity_id` | Entity ID of the switch for closing the cover | |
+| stop_switch_entity_id | entity | _Optional_ | Entity ID of the switch for stopping the cover | None |
+| cover_entity_id | entity | **Required** or `open_\|close_switch_entity_id` | Entity ID of an existing cover entity | |
+| is_button | boolean | _Optional_ | Set to `true` for momentary pulse buttons (same as `input_mode: pulse`) | false |
+| travelling_time_down | float | _Optional_ | Time in seconds to close the cover | 30 |
+| travelling_time_up | float | _Optional_ | Time in seconds to open the cover | 30 |
+| tilting_time_down | float | _Optional_ | Time in seconds to tilt the cover fully closed | None |
+| tilting_time_up | float | _Optional_ | Time in seconds to tilt the cover fully open | None |
+| travel_moves_with_tilt | boolean | _Optional_ | Whether tilt movements also cause proportional travel changes | false |
+| travel_delay_at_end | float | _Optional_ | Additional relay time (seconds) at endpoints for position reset | None |
+| min_movement_time | float | _Optional_ | Minimum movement duration (seconds) - blocks shorter movements | None |
+| travel_startup_delay | float | _Optional_ | Motor startup time compensation (seconds) for travel movements | None |
+| tilt_startup_delay | float | _Optional_ | Motor startup time compensation (seconds) for tilt movements | None |
+| pulse_time | float | _Optional_ | Duration in seconds for button press in pulse mode | 1.0 |
+
+
[commits-shield]: https://img.shields.io/github/commit-activity/y/Sese-Schneider/ha-cover-time-based.svg?style=for-the-badge
[commits]: https://github.com/Sese-Schneider/ha-cover-time-based/commits/main
[license-shield]: https://img.shields.io/github/license/Sese-Schneider/ha-cover-time-based.svg?style=for-the-badge
-[maintenance-shield]: https://img.shields.io/maintenance/yes/2025.svg?style=for-the-badge
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg?style=for-the-badge
[releases-shield]: https://img.shields.io/github/release/Sese-Schneider/ha-cover-time-based.svg?style=for-the-badge
[releases]: https://github.com/Sese-Schneider/ha-cover-time-based/releases
diff --git a/custom_components/cover_time_based/__init__.py b/custom_components/cover_time_based/__init__.py
new file mode 100644
index 0000000..54c7a86
--- /dev/null
+++ b/custom_components/cover_time_based/__init__.py
@@ -0,0 +1,57 @@
+"""Cover Time Based integration."""
+
+import logging
+from pathlib import Path
+
+from homeassistant.components import frontend
+from homeassistant.components.http import StaticPathConfig
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import Platform
+from homeassistant.core import HomeAssistant
+
+from .const import DOMAIN
+from .websocket_api import async_register_websocket_api
+
+_LOGGER = logging.getLogger(__name__)
+PLATFORMS: list[Platform] = [Platform.COVER]
+_FRONTEND_KEY = f"{DOMAIN}_frontend_registered"
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+ """Set up Cover Time Based from a config entry."""
+ # Register frontend and WebSocket API once (not per entry).
+ # Done before platform setup so the card works even if the entity fails.
+ if _FRONTEND_KEY not in hass.data:
+ hass.data[_FRONTEND_KEY] = True
+
+ async_register_websocket_api(hass)
+
+ if hass.http is not None:
+ await hass.http.async_register_static_paths(
+ [
+ StaticPathConfig(
+ "/cover_time_based_panel",
+ str(Path(__file__).parent / "frontend"),
+ cache_headers=False,
+ )
+ ]
+ )
+
+ frontend.add_extra_js_url(
+ hass, "/cover_time_based_panel/cover-time-based-card.js"
+ )
+
+ await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+ entry.async_on_unload(entry.add_update_listener(async_update_options))
+
+ return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+ """Unload a config entry."""
+ return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
+
+
+async def async_update_options(hass: HomeAssistant, entry: ConfigEntry) -> None:
+ """Handle options update - reload the entry."""
+ await hass.config_entries.async_reload(entry.entry_id)
diff --git a/custom_components/cover_time_based/calibration.py b/custom_components/cover_time_based/calibration.py
new file mode 100644
index 0000000..0cfccbc
--- /dev/null
+++ b/custom_components/cover_time_based/calibration.py
@@ -0,0 +1,45 @@
+"""Calibration support for cover_time_based."""
+
+from __future__ import annotations
+
+import time
+from asyncio import Task
+from dataclasses import dataclass, field
+
+CALIBRATION_STEP_PAUSE = 2.0
+CALIBRATION_OVERHEAD_STEPS = 8
+CALIBRATION_TILT_OVERHEAD_STEPS = 3
+CALIBRATION_MIN_MOVEMENT_START = 0.1
+CALIBRATION_MIN_MOVEMENT_INCREMENT = 0.1
+CALIBRATION_MIN_MOVEMENT_INITIAL_PAUSE = 3.0
+
+CALIBRATABLE_ATTRIBUTES = [
+ "travel_time_close",
+ "travel_time_open",
+ "travel_startup_delay",
+ "tilt_time_close",
+ "tilt_time_open",
+ "tilt_startup_delay",
+ "min_movement_time",
+]
+
+SERVICE_START_CALIBRATION = "start_calibration"
+SERVICE_STOP_CALIBRATION = "stop_calibration"
+
+
+@dataclass
+class CalibrationState:
+ """Holds state for an in-progress calibration test."""
+
+ attribute: str
+ timeout: float
+ started_at: float = field(default_factory=time.monotonic)
+ step_count: int = 0
+ final_step: bool = False
+ step_duration: float | None = None
+ last_pulse_duration: float | None = None
+ continuous_start: float | None = None
+ move_command: str | None = None
+ saved_startup_delay: float | None = None
+ timeout_task: Task | None = field(default=None, repr=False)
+ automation_task: Task | None = field(default=None, repr=False)
diff --git a/custom_components/cover_time_based/config_flow.py b/custom_components/cover_time_based/config_flow.py
new file mode 100644
index 0000000..7e826d5
--- /dev/null
+++ b/custom_components/cover_time_based/config_flow.py
@@ -0,0 +1,40 @@
+"""Config flow for Cover Time Based integration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import voluptuous as vol
+from homeassistant.config_entries import (
+ ConfigFlow,
+ ConfigFlowResult,
+)
+from homeassistant.const import CONF_NAME
+from homeassistant.helpers.selector import TextSelector
+
+from .cover import DOMAIN
+
+
+class CoverTimeBasedConfigFlow(ConfigFlow, domain=DOMAIN):
+ """Handle a config flow for Cover Time Based."""
+
+ VERSION = 2
+
+ async def async_step_user(
+ self, user_input: dict[str, Any] | None = None
+ ) -> ConfigFlowResult:
+ """Create a new time-based cover helper."""
+ if user_input is not None:
+ return self.async_create_entry(
+ title=user_input[CONF_NAME],
+ data={},
+ options={},
+ )
+
+ schema = vol.Schema(
+ {
+ vol.Required(CONF_NAME): TextSelector(),
+ }
+ )
+
+ return self.async_show_form(step_id="user", data_schema=schema)
diff --git a/custom_components/cover_time_based/const.py b/custom_components/cover_time_based/const.py
new file mode 100644
index 0000000..b6580a7
--- /dev/null
+++ b/custom_components/cover_time_based/const.py
@@ -0,0 +1,14 @@
+"""Constants for the cover_time_based integration."""
+
+DOMAIN = "cover_time_based"
+
+CONF_TILT_MODE = "tilt_mode"
+CONF_TRAVEL_TIME_CLOSE = "travel_time_close"
+CONF_TRAVEL_TIME_OPEN = "travel_time_open"
+CONF_TILT_TIME_CLOSE = "tilt_time_close"
+CONF_TILT_TIME_OPEN = "tilt_time_open"
+CONF_TRAVEL_STARTUP_DELAY = "travel_startup_delay"
+CONF_TILT_STARTUP_DELAY = "tilt_startup_delay"
+CONF_ENDPOINT_RUNON_TIME = "endpoint_runon_time"
+CONF_MIN_MOVEMENT_TIME = "min_movement_time"
+DEFAULT_ENDPOINT_RUNON_TIME = 2.0
diff --git a/custom_components/cover_time_based/cover.py b/custom_components/cover_time_based/cover.py
index d982eef..f749e9b 100644
--- a/custom_components/cover_time_based/cover.py
+++ b/custom_components/cover_time_based/cover.py
@@ -1,67 +1,94 @@
"""Cover time based"""
-import asyncio
import logging
-from asyncio import sleep
-from datetime import timedelta
import homeassistant.helpers.config_validation as cv
import voluptuous as vol
from homeassistant.components.cover import (
- ATTR_CURRENT_POSITION,
- ATTR_CURRENT_TILT_POSITION,
ATTR_POSITION,
ATTR_TILT_POSITION,
PLATFORM_SCHEMA,
- CoverEntity,
- CoverEntityFeature,
)
from homeassistant.const import (
- CONF_NAME,
ATTR_ENTITY_ID,
- SERVICE_CLOSE_COVER,
- SERVICE_OPEN_COVER,
- SERVICE_STOP_COVER,
+ CONF_NAME,
)
-from homeassistant.core import callback
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant, SupportsResponse
from homeassistant.helpers import entity_platform
-from homeassistant.helpers.event import (
- async_track_time_interval,
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
+
+from .calibration import (
+ CALIBRATABLE_ATTRIBUTES,
+ SERVICE_START_CALIBRATION,
+ SERVICE_STOP_CALIBRATION,
+)
+from .const import (
+ CONF_ENDPOINT_RUNON_TIME,
+ CONF_MIN_MOVEMENT_TIME,
+ CONF_TILT_MODE,
+ CONF_TILT_STARTUP_DELAY,
+ CONF_TILT_TIME_CLOSE,
+ CONF_TILT_TIME_OPEN,
+ CONF_TRAVEL_STARTUP_DELAY,
+ CONF_TRAVEL_TIME_CLOSE,
+ CONF_TRAVEL_TIME_OPEN,
+ DEFAULT_ENDPOINT_RUNON_TIME,
)
-from homeassistant.helpers.restore_state import RestoreEntity
-from xknx.devices import TravelStatus, TravelCalculator
+from .cover_base import CoverTimeBased # noqa: F401
+from .helpers import resolve_entity
_LOGGER = logging.getLogger(__name__)
+DOMAIN = "cover_time_based"
+
+# ---------------------------------------------------------------------------
+# YAML config constants (deprecated + current)
+# ---------------------------------------------------------------------------
+
CONF_DEVICES = "devices"
CONF_DEFAULTS = "defaults"
+
+# Deprecated YAML key names (renamed)
CONF_TRAVEL_MOVES_WITH_TILT = "travel_moves_with_tilt"
CONF_TRAVELLING_TIME_DOWN = "travelling_time_down"
CONF_TRAVELLING_TIME_UP = "travelling_time_up"
CONF_TILTING_TIME_DOWN = "tilting_time_down"
CONF_TILTING_TIME_UP = "tilting_time_up"
CONF_TRAVEL_DELAY_AT_END = "travel_delay_at_end"
-CONF_MIN_MOVEMENT_TIME = "min_movement_time"
-CONF_TRAVEL_STARTUP_DELAY = "travel_startup_delay"
-CONF_TILT_STARTUP_DELAY = "tilt_startup_delay"
-DEFAULT_TRAVEL_TIME = 30
+CONF_IS_BUTTON = "is_button"
CONF_OPEN_SWITCH_ENTITY_ID = "open_switch_entity_id"
CONF_CLOSE_SWITCH_ENTITY_ID = "close_switch_entity_id"
CONF_STOP_SWITCH_ENTITY_ID = "stop_switch_entity_id"
-CONF_IS_BUTTON = "is_button"
-CONF_INPUT_MODE = "input_mode"
+CONF_SAFE_TILT_POSITION = "safe_tilt_position"
+CONF_MAX_TILT_ALLOWED_POSITION = "max_tilt_allowed_position"
+CONF_TILT_OPEN_SWITCH = "tilt_open_switch"
+CONF_TILT_CLOSE_SWITCH = "tilt_close_switch"
+CONF_TILT_STOP_SWITCH = "tilt_stop_switch"
+CONF_COVER_ENTITY_ID = "cover_entity_id"
+
+# ---------------------------------------------------------------------------
+# Control mode constants
+# ---------------------------------------------------------------------------
+
+CONF_CONTROL_MODE = "control_mode"
+CONTROL_MODE_WRAPPED = "wrapped"
+CONTROL_MODE_SWITCH = "switch"
+CONTROL_MODE_PULSE = "pulse"
+CONTROL_MODE_TOGGLE = "toggle"
+
CONF_PULSE_TIME = "pulse_time"
DEFAULT_PULSE_TIME = 1.0
-INPUT_MODE_SWITCH = "switch"
-INPUT_MODE_PULSE = "pulse"
-INPUT_MODE_TOGGLE = "toggle"
-
-CONF_COVER_ENTITY_ID = "cover_entity_id"
SERVICE_SET_KNOWN_POSITION = "set_known_position"
SERVICE_SET_KNOWN_TILT_POSITION = "set_known_tilt_position"
+# ---------------------------------------------------------------------------
+# Schema definitions
+# ---------------------------------------------------------------------------
+
BASE_DEVICE_SCHEMA = {
vol.Required(CONF_NAME): cv.string,
}
@@ -72,10 +99,11 @@
vol.Optional(CONF_TRAVELLING_TIME_UP): cv.positive_float,
vol.Optional(CONF_TILTING_TIME_DOWN): cv.positive_float,
vol.Optional(CONF_TILTING_TIME_UP): cv.positive_float,
- vol.Optional(CONF_TRAVEL_DELAY_AT_END): cv.positive_float,
- vol.Optional(CONF_MIN_MOVEMENT_TIME): cv.positive_float,
vol.Optional(CONF_TRAVEL_STARTUP_DELAY): cv.positive_float,
vol.Optional(CONF_TILT_STARTUP_DELAY): cv.positive_float,
+ vol.Optional(CONF_ENDPOINT_RUNON_TIME): cv.positive_float,
+ vol.Optional(CONF_TRAVEL_DELAY_AT_END): cv.positive_float,
+ vol.Optional(CONF_MIN_MOVEMENT_TIME): cv.positive_float,
}
SWITCH_COVER_SCHEMA = {
@@ -84,9 +112,6 @@
vol.Required(CONF_CLOSE_SWITCH_ENTITY_ID): cv.entity_id,
vol.Optional(CONF_STOP_SWITCH_ENTITY_ID, default=None): vol.Any(cv.entity_id, None),
vol.Optional(CONF_IS_BUTTON, default=False): cv.boolean,
- vol.Optional(CONF_INPUT_MODE, default=None): vol.Any(
- vol.In([INPUT_MODE_SWITCH, INPUT_MODE_PULSE, INPUT_MODE_TOGGLE]), None
- ),
vol.Optional(CONF_PULSE_TIME): cv.positive_float,
**TRAVEL_TIME_SCHEMA,
}
@@ -97,29 +122,36 @@
**TRAVEL_TIME_SCHEMA,
}
-DEFAULTS_SCHEMA = vol.Schema({
- vol.Optional(CONF_TRAVEL_MOVES_WITH_TILT, default=False): cv.boolean,
- vol.Optional(
- CONF_TRAVELLING_TIME_DOWN, default=DEFAULT_TRAVEL_TIME
- ): cv.positive_float,
- vol.Optional(CONF_TRAVELLING_TIME_UP, default=DEFAULT_TRAVEL_TIME): cv.positive_float,
- vol.Optional(CONF_TILTING_TIME_DOWN, default=None): vol.Any(
- cv.positive_float, None
- ),
- vol.Optional(CONF_TILTING_TIME_UP, default=None): vol.Any(cv.positive_float, None),
- vol.Optional(CONF_TRAVEL_DELAY_AT_END, default=None): vol.Any(
- cv.positive_float, None
- ),
- vol.Optional(CONF_MIN_MOVEMENT_TIME, default=None): vol.Any(
- cv.positive_float, None
- ),
- vol.Optional(CONF_TRAVEL_STARTUP_DELAY, default=None): vol.Any(
- cv.positive_float, None
- ),
- vol.Optional(CONF_TILT_STARTUP_DELAY, default=None): vol.Any(
- cv.positive_float, None
- ),
-})
+DEFAULTS_SCHEMA = vol.Schema(
+ {
+ vol.Optional(CONF_TRAVEL_MOVES_WITH_TILT, default=False): cv.boolean,
+ vol.Optional(CONF_TRAVELLING_TIME_DOWN, default=None): vol.Any(
+ cv.positive_float, None
+ ),
+ vol.Optional(CONF_TRAVELLING_TIME_UP, default=None): vol.Any(
+ cv.positive_float, None
+ ),
+ vol.Optional(CONF_TILTING_TIME_DOWN, default=None): vol.Any(
+ cv.positive_float, None
+ ),
+ vol.Optional(CONF_TILTING_TIME_UP, default=None): vol.Any(
+ cv.positive_float, None
+ ),
+ vol.Optional(CONF_TRAVEL_STARTUP_DELAY, default=None): vol.Any(
+ cv.positive_float, None
+ ),
+ vol.Optional(CONF_TILT_STARTUP_DELAY, default=None): vol.Any(
+ cv.positive_float, None
+ ),
+ vol.Optional(
+ CONF_ENDPOINT_RUNON_TIME, default=DEFAULT_ENDPOINT_RUNON_TIME
+ ): vol.Any(cv.positive_float, None),
+ vol.Optional(CONF_TRAVEL_DELAY_AT_END): cv.positive_float,
+ vol.Optional(CONF_MIN_MOVEMENT_TIME, default=None): vol.Any(
+ cv.positive_float, None
+ ),
+ }
+)
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
{
@@ -143,123 +175,255 @@
}
)
-DOMAIN = "cover_time_based"
+# ---------------------------------------------------------------------------
+# YAML migration helpers
+# ---------------------------------------------------------------------------
+
+_YAML_KEY_RENAMES = {
+ CONF_TRAVEL_DELAY_AT_END: CONF_ENDPOINT_RUNON_TIME,
+ CONF_TRAVELLING_TIME_DOWN: CONF_TRAVEL_TIME_CLOSE,
+ CONF_TRAVELLING_TIME_UP: CONF_TRAVEL_TIME_OPEN,
+ CONF_TILTING_TIME_DOWN: CONF_TILT_TIME_CLOSE,
+ CONF_TILTING_TIME_UP: CONF_TILT_TIME_OPEN,
+}
+
+
+def _migrate_yaml_keys(config):
+ """Migrate deprecated YAML key names to current names."""
+ for old_key, new_key in _YAML_KEY_RENAMES.items():
+ if old_key in config:
+ if new_key not in config:
+ config[new_key] = config[old_key]
+ config.pop(old_key)
+
+
+_TIMING_DEFAULTS = {
+ CONF_TILT_MODE: "none",
+ CONF_TRAVEL_TIME_CLOSE: None,
+ CONF_TRAVEL_TIME_OPEN: None,
+ CONF_TILT_TIME_CLOSE: None,
+ CONF_TILT_TIME_OPEN: None,
+ CONF_TRAVEL_STARTUP_DELAY: None,
+ CONF_TILT_STARTUP_DELAY: None,
+ CONF_ENDPOINT_RUNON_TIME: DEFAULT_ENDPOINT_RUNON_TIME,
+ CONF_MIN_MOVEMENT_TIME: None,
+}
+
+
+def _get_value(key, device_config, defaults_config, schema_default=None):
+ """Get config value with priority: device config > defaults > schema default."""
+ if key in device_config:
+ return device_config[key]
+ if key in defaults_config:
+ return defaults_config[key]
+ return schema_default
+
+
+def _resolve_control_mode(config, defaults, has_cover_entity):
+ """Resolve control mode from config, handling legacy keys."""
+ if has_cover_entity:
+ config.pop(CONF_IS_BUTTON, None)
+ return CONTROL_MODE_WRAPPED
+
+ # Explicit input_mode takes precedence
+ explicit = config.pop("input_mode", None) or defaults.get("input_mode")
+ if explicit:
+ config.pop(CONF_IS_BUTTON, None)
+ return explicit
+
+ # Legacy is_button → pulse mode
+ is_button = config.pop(CONF_IS_BUTTON, False)
+ if is_button:
+ return CONTROL_MODE_PULSE
+
+ return CONTROL_MODE_SWITCH
+
+
+# ---------------------------------------------------------------------------
+# Entity factory
+# ---------------------------------------------------------------------------
+
+
+def _resolve_tilt_strategy(tilt_mode_str, tilt_time_close, tilt_time_open, **kwargs):
+ """Map tilt_mode config string to a TiltStrategy instance (or None)."""
+ from .tilt_strategies import DualMotorTilt, InlineTilt, SequentialTilt
+
+ if tilt_mode_str == "none":
+ return None
+
+ has_tilt_times = tilt_time_close is not None and tilt_time_open is not None
+ if not has_tilt_times:
+ return None
+
+ if tilt_mode_str == "dual_motor":
+ return DualMotorTilt(
+ safe_tilt_position=kwargs.get("safe_tilt_position", 100),
+ max_tilt_allowed_position=kwargs.get("max_tilt_allowed_position"),
+ )
+ if tilt_mode_str == "inline":
+ return InlineTilt()
+ # "sequential" or any other value with tilt times → sequential
+ return SequentialTilt()
+
+
+def _create_cover_from_options(options, device_id="", name=""):
+ """Create the appropriate cover subclass based on options."""
+ from .cover_wrapped import WrappedCoverTimeBased
+ from .cover_switch_mode import SwitchModeCover
+ from .cover_pulse_mode import PulseModeCover
+ from .cover_toggle_mode import ToggleModeCover
+
+ control_mode = options.get(CONF_CONTROL_MODE, CONTROL_MODE_SWITCH)
+
+ tilt_mode_str = options.get(CONF_TILT_MODE, "none")
+ tilt_strategy = _resolve_tilt_strategy(
+ tilt_mode_str,
+ options.get(CONF_TILT_TIME_CLOSE),
+ options.get(CONF_TILT_TIME_OPEN),
+ safe_tilt_position=options.get(CONF_SAFE_TILT_POSITION, 100),
+ max_tilt_allowed_position=options.get(CONF_MAX_TILT_ALLOWED_POSITION),
+ )
+
+ # Common params for all subclasses
+ common = dict(
+ device_id=device_id,
+ name=name,
+ tilt_strategy=tilt_strategy,
+ travel_time_close=options.get(CONF_TRAVEL_TIME_CLOSE),
+ travel_time_open=options.get(CONF_TRAVEL_TIME_OPEN),
+ tilt_time_close=options.get(CONF_TILT_TIME_CLOSE),
+ tilt_time_open=options.get(CONF_TILT_TIME_OPEN),
+ travel_startup_delay=options.get(CONF_TRAVEL_STARTUP_DELAY),
+ tilt_startup_delay=options.get(CONF_TILT_STARTUP_DELAY),
+ endpoint_runon_time=options.get(
+ CONF_ENDPOINT_RUNON_TIME, DEFAULT_ENDPOINT_RUNON_TIME
+ ),
+ min_movement_time=options.get(CONF_MIN_MOVEMENT_TIME),
+ tilt_open_switch=options.get(CONF_TILT_OPEN_SWITCH),
+ tilt_close_switch=options.get(CONF_TILT_CLOSE_SWITCH),
+ tilt_stop_switch=options.get(CONF_TILT_STOP_SWITCH),
+ )
+
+ if control_mode == CONTROL_MODE_WRAPPED:
+ return WrappedCoverTimeBased(
+ cover_entity_id=options.get(CONF_COVER_ENTITY_ID, ""),
+ **common,
+ )
+
+ switch_args = dict(
+ open_switch_entity_id=options.get(CONF_OPEN_SWITCH_ENTITY_ID, ""),
+ close_switch_entity_id=options.get(CONF_CLOSE_SWITCH_ENTITY_ID, ""),
+ stop_switch_entity_id=options.get(CONF_STOP_SWITCH_ENTITY_ID),
+ **common,
+ )
+
+ pulse_time = options.get(CONF_PULSE_TIME, DEFAULT_PULSE_TIME)
+
+ if control_mode == CONTROL_MODE_PULSE:
+ return PulseModeCover(pulse_time=pulse_time, **switch_args)
+ elif control_mode == CONTROL_MODE_TOGGLE:
+ return ToggleModeCover(pulse_time=pulse_time, **switch_args)
+ else:
+ return SwitchModeCover(**switch_args)
def devices_from_config(domain_config):
"""Parse configuration and add cover devices."""
devices = []
defaults = domain_config.get(CONF_DEFAULTS, {})
-
- def get_value(key, device_config, defaults_config, schema_default=None):
- """
- Get value with priority: device config > defaults > schema default.
-
- If key EXISTS in device config (even if None/null), use that value.
- Otherwise, try defaults, then schema default.
- """
- # Priority: device config > defaults > schema default
- if key in device_config:
- return device_config[key]
- if key in defaults_config:
- return defaults_config[key]
- return schema_default
-
+
+ _migrate_yaml_keys(defaults)
+
for device_id, config in domain_config[CONF_DEVICES].items():
name = config.pop(CONF_NAME)
-
- travel_moves_with_tilt = get_value(CONF_TRAVEL_MOVES_WITH_TILT, config, defaults, False)
- travel_time_down = get_value(CONF_TRAVELLING_TIME_DOWN, config, defaults, DEFAULT_TRAVEL_TIME)
- travel_time_up = get_value(CONF_TRAVELLING_TIME_UP, config, defaults, DEFAULT_TRAVEL_TIME)
- tilt_time_down = get_value(CONF_TILTING_TIME_DOWN, config, defaults, None)
- tilt_time_up = get_value(CONF_TILTING_TIME_UP, config, defaults, None)
- travel_delay_at_end = get_value(CONF_TRAVEL_DELAY_AT_END, config, defaults, None)
- min_movement_time = get_value(CONF_MIN_MOVEMENT_TIME, config, defaults, None)
- travel_startup_delay = get_value(CONF_TRAVEL_STARTUP_DELAY, config, defaults, None)
- tilt_startup_delay = get_value(CONF_TILT_STARTUP_DELAY, config, defaults, None)
-
+
+ _migrate_yaml_keys(config)
+
+ # Extract timing values with defaults, then remove from config
+ options = {}
+ for key, schema_default in _TIMING_DEFAULTS.items():
+ options[key] = _get_value(key, config, defaults, schema_default)
+ config.pop(key, None)
+
+ # Legacy travel_moves_with_tilt → inline tilt mode
+ travel_moves = _get_value(CONF_TRAVEL_MOVES_WITH_TILT, config, defaults, False)
config.pop(CONF_TRAVEL_MOVES_WITH_TILT, None)
- config.pop(CONF_TRAVELLING_TIME_DOWN, None)
- config.pop(CONF_TRAVELLING_TIME_UP, None)
- config.pop(CONF_TILTING_TIME_DOWN, None)
- config.pop(CONF_TILTING_TIME_UP, None)
- config.pop(CONF_TRAVEL_DELAY_AT_END, None)
- config.pop(CONF_MIN_MOVEMENT_TIME, None)
- config.pop(CONF_TRAVEL_STARTUP_DELAY, None)
- config.pop(CONF_TILT_STARTUP_DELAY, None)
-
- open_switch_entity_id = (
- config.pop(CONF_OPEN_SWITCH_ENTITY_ID)
- if CONF_OPEN_SWITCH_ENTITY_ID in config
- else None
- )
- close_switch_entity_id = (
- config.pop(CONF_CLOSE_SWITCH_ENTITY_ID)
- if CONF_CLOSE_SWITCH_ENTITY_ID in config
- else None
- )
- stop_switch_entity_id = (
- config.pop(CONF_STOP_SWITCH_ENTITY_ID)
- if CONF_STOP_SWITCH_ENTITY_ID in config
- else None
- )
- is_button = config.pop(CONF_IS_BUTTON) if CONF_IS_BUTTON in config else False
- input_mode = (
- config.pop(CONF_INPUT_MODE, None) if CONF_INPUT_MODE in config else None
- )
- pulse_time = get_value(CONF_PULSE_TIME, config, defaults, DEFAULT_PULSE_TIME)
+ if travel_moves and options.get(CONF_TILT_MODE) == "none":
+ options[CONF_TILT_MODE] = "inline"
+
+ # Entity IDs
+ open_switch = config.pop(CONF_OPEN_SWITCH_ENTITY_ID, None)
+ close_switch = config.pop(CONF_CLOSE_SWITCH_ENTITY_ID, None)
+ stop_switch = config.pop(CONF_STOP_SWITCH_ENTITY_ID, None)
+ cover_entity_id = config.pop(CONF_COVER_ENTITY_ID, None)
+
+ # Control mode (handles is_button deprecation)
+ control_mode = _resolve_control_mode(config, defaults, bool(cover_entity_id))
+ pulse_time = _get_value(CONF_PULSE_TIME, config, defaults, DEFAULT_PULSE_TIME)
config.pop(CONF_PULSE_TIME, None)
- if input_mode is not None and is_button:
- _LOGGER.warning(
- "Device '%s': both 'is_button' and 'input_mode' are set. "
- "'input_mode: %s' takes precedence. Please remove 'is_button'.",
- device_id,
- input_mode,
- )
- elif is_button:
- input_mode = INPUT_MODE_PULSE
- _LOGGER.warning(
- "Device '%s': 'is_button' is deprecated. "
- "Use 'input_mode: pulse' instead.",
- device_id,
- )
- elif input_mode is None:
- input_mode = INPUT_MODE_SWITCH
-
- cover_entity_id = (
- config.pop(CONF_COVER_ENTITY_ID) if CONF_COVER_ENTITY_ID in config else None
- )
+ options[CONF_CONTROL_MODE] = control_mode
+ options[CONF_PULSE_TIME] = pulse_time
+
+ if open_switch:
+ options[CONF_OPEN_SWITCH_ENTITY_ID] = open_switch
+ options[CONF_CLOSE_SWITCH_ENTITY_ID] = close_switch
+ options[CONF_STOP_SWITCH_ENTITY_ID] = stop_switch
+ if cover_entity_id:
+ options[CONF_COVER_ENTITY_ID] = cover_entity_id
- device = CoverTimeBased(
- device_id,
- name,
- travel_moves_with_tilt,
- travel_time_down,
- travel_time_up,
- tilt_time_down,
- tilt_time_up,
- travel_delay_at_end,
- min_movement_time,
- travel_startup_delay,
- tilt_startup_delay,
- open_switch_entity_id,
- close_switch_entity_id,
- stop_switch_entity_id,
- input_mode,
- pulse_time,
- cover_entity_id,
+ devices.append(
+ _create_cover_from_options(options, device_id=device_id, name=name)
)
- devices.append(device)
return devices
-async def async_setup_platform(hass, config, async_add_entities, discovery_info=None):
+# ---------------------------------------------------------------------------
+# Platform setup
+# ---------------------------------------------------------------------------
+
+
+async def async_setup_platform(hass, config, async_add_entities, _discovery_info=None):
"""Set up the cover platform."""
+ _LOGGER.warning(
+ "Configuration of Cover Time Based via YAML is deprecated and "
+ "will be removed in a future version. Please use the UI to "
+ "configure your covers (Settings > Devices & Services > Helpers)"
+ )
+ async_create_issue(
+ hass,
+ DOMAIN,
+ "deprecated_yaml",
+ is_fixable=False,
+ severity=IssueSeverity.WARNING,
+ translation_key="deprecated_yaml",
+ )
async_add_entities(devices_from_config(config))
platform = entity_platform.current_platform.get()
+ _register_services(platform)
+
+
+async def async_setup_entry(
+ _hass: HomeAssistant,
+ config_entry: ConfigEntry,
+ async_add_entities: AddEntitiesCallback,
+) -> None:
+ """Set up a single cover entity from a config entry."""
+ entity = _create_cover_from_options(
+ config_entry.options,
+ device_id=config_entry.entry_id,
+ name=config_entry.title,
+ )
+ entity._config_entry_id = config_entry.entry_id
+ async_add_entities([entity])
+
+ platform = entity_platform.current_platform.get()
+ _register_services(platform)
+
+def _register_services(platform):
+ """Register entity services on the given platform."""
platform.async_register_entity_service(
SERVICE_SET_KNOWN_POSITION, POSITION_SCHEMA, "set_known_position"
)
@@ -267,1067 +431,49 @@ async def async_setup_platform(hass, config, async_add_entities, discovery_info=
SERVICE_SET_KNOWN_TILT_POSITION, TILT_POSITION_SCHEMA, "set_known_tilt_position"
)
-
-class CoverTimeBased(CoverEntity, RestoreEntity):
- def __init__(
- self,
- device_id,
- name,
- travel_moves_with_tilt,
- travel_time_down,
- travel_time_up,
- tilt_time_down,
- tilt_time_up,
- travel_delay_at_end,
- min_movement_time,
- travel_startup_delay,
- tilt_startup_delay,
- open_switch_entity_id,
- close_switch_entity_id,
- stop_switch_entity_id,
- input_mode,
- pulse_time,
- cover_entity_id,
- ):
- """Initialize the cover."""
- self._unique_id = device_id
-
- self._travel_moves_with_tilt = travel_moves_with_tilt
- self._travel_time_down = travel_time_down
- self._travel_time_up = travel_time_up
- self._tilting_time_down = tilt_time_down
- self._tilting_time_up = tilt_time_up
- self._travel_delay_at_end = travel_delay_at_end
- self._min_movement_time = min_movement_time
- self._travel_startup_delay = travel_startup_delay
- self._tilt_startup_delay = tilt_startup_delay
-
- self._open_switch_entity_id = open_switch_entity_id
- self._close_switch_entity_id = close_switch_entity_id
- self._stop_switch_entity_id = stop_switch_entity_id
- self._input_mode = input_mode
- self._pulse_time = pulse_time
-
- self._cover_entity_id = cover_entity_id
-
- if name:
- self._name = name
- else:
- self._name = device_id
-
- self._unsubscribe_auto_updater = None
- self._delay_task = None
- self._startup_delay_task = None
- self._last_command = None
-
- self.travel_calc = TravelCalculator(
- self._travel_time_down,
- self._travel_time_up,
- )
- if self._has_tilt_support():
- self.tilt_calc = TravelCalculator(
- self._tilting_time_down,
- self._tilting_time_up,
- )
-
- async def async_added_to_hass(self):
- """Only cover's position and tilt matters."""
- old_state = await self.async_get_last_state()
- _LOGGER.debug("async_added_to_hass :: oldState %s", old_state)
- if (
- old_state is not None
- and self.travel_calc is not None
- and old_state.attributes.get(ATTR_CURRENT_POSITION) is not None
- ):
- self.travel_calc.set_position(
- 100 - int(old_state.attributes.get(ATTR_CURRENT_POSITION))
- )
-
- if (
- self._has_tilt_support()
- and old_state.attributes.get(ATTR_CURRENT_TILT_POSITION) is not None
- ):
- self.tilt_calc.set_position(
- 100 - int(old_state.attributes.get(ATTR_CURRENT_TILT_POSITION))
- )
-
- def _handle_stop(self):
- """Handle stop"""
- if self.travel_calc.is_traveling():
- _LOGGER.debug("_handle_stop :: button stops cover movement")
- self.travel_calc.stop()
- self.stop_auto_updater()
-
- if self._has_tilt_support() and self.tilt_calc.is_traveling():
- _LOGGER.debug("_handle_stop :: button stops tilt movement")
- self.tilt_calc.stop()
- self.stop_auto_updater()
-
- def _stop_travel_if_traveling(self):
- """Stop cover movement if it's currently traveling."""
- if self.travel_calc.is_traveling():
- _LOGGER.debug("_stop_travel_if_traveling :: stopping cover movement")
- self.travel_calc.stop()
- if self._has_tilt_support() and self.tilt_calc.is_traveling():
- _LOGGER.debug("_stop_travel_if_traveling :: also stopping tilt")
- self.tilt_calc.stop()
-
- def _cancel_delay_task(self):
- """Cancel any active delay task."""
- if self._delay_task is not None and not self._delay_task.done():
- _LOGGER.debug("_cancel_delay_task :: cancelling active delay task")
- self._delay_task.cancel()
- self._delay_task = None
- return True
- return False
-
- def _cancel_startup_delay_task(self):
- """Cancel any active startup delay task."""
- if self._startup_delay_task is not None and not self._startup_delay_task.done():
- _LOGGER.debug("_cancel_startup_delay_task :: cancelling active startup delay task")
- self._startup_delay_task.cancel()
- self._startup_delay_task = None
-
- async def _execute_with_startup_delay(self, startup_delay, start_callback):
- """
- Execute movement with startup delay.
-
- This method handles the motor inertia by:
- 1. Turning relay ON immediately
- 2. Waiting for startup_delay (motor "wakes up")
- 3. Starting TravelCalculator (position starts changing in HA)
-
- Args:
- startup_delay: Time in seconds to wait before starting position tracking
- start_callback: Callback to execute after delay (starts TravelCalculator)
- """
- # Motor inertia handling: relay ON → wait → start position tracking
- _LOGGER.debug("_execute_with_startup_delay :: waiting %fs before starting position tracking", startup_delay)
- try:
- await sleep(startup_delay)
- _LOGGER.debug("_execute_with_startup_delay :: startup delay complete, starting position tracking")
- start_callback()
- self._startup_delay_task = None
- except asyncio.CancelledError:
- _LOGGER.debug("_execute_with_startup_delay :: startup delay cancelled")
- self._startup_delay_task = None
- raise
-
- @property
- def name(self):
- """Return the name of the cover."""
- return self._name
-
- @property
- def unique_id(self):
- """Return the unique id."""
- return "cover_timebased_uuid_" + self._unique_id
-
- @property
- def device_class(self):
- """Return the device class of the cover."""
- return None
-
- @property
- def extra_state_attributes(self):
- """Return the device state attributes."""
- attr = {}
- if self._travel_moves_with_tilt is not None:
- attr[CONF_TRAVEL_MOVES_WITH_TILT] = self._travel_moves_with_tilt
- if self._travel_time_down is not None:
- attr[CONF_TRAVELLING_TIME_DOWN] = self._travel_time_down
- if self._travel_time_up is not None:
- attr[CONF_TRAVELLING_TIME_UP] = self._travel_time_up
- if self._tilting_time_down is not None:
- attr[CONF_TILTING_TIME_DOWN] = self._tilting_time_down
- if self._tilting_time_up is not None:
- attr[CONF_TILTING_TIME_UP] = self._tilting_time_up
- if self._travel_delay_at_end is not None:
- attr[CONF_TRAVEL_DELAY_AT_END] = self._travel_delay_at_end
- if self._min_movement_time is not None:
- attr[CONF_MIN_MOVEMENT_TIME] = self._min_movement_time
- if self._travel_startup_delay is not None:
- attr[CONF_TRAVEL_STARTUP_DELAY] = self._travel_startup_delay
- if self._tilt_startup_delay is not None:
- attr[CONF_TILT_STARTUP_DELAY] = self._tilt_startup_delay
- return attr
-
- @property
- def current_cover_position(self) -> int | None:
- """Return the current position of the cover."""
- current_position = self.travel_calc.current_position()
- return 100 - current_position if current_position is not None else None
-
- @property
- def current_cover_tilt_position(self) -> int | None:
- """Return the current tilt of the cover."""
- if self._has_tilt_support():
- current_position = self.tilt_calc.current_position()
- return 100 - current_position if current_position is not None else None
- return None
-
- @property
- def is_opening(self):
- """Return if the cover is opening or not."""
- return (
- self.travel_calc.is_traveling()
- and self.travel_calc.travel_direction == TravelStatus.DIRECTION_UP
- ) or (
- self._has_tilt_support()
- and self.tilt_calc.is_traveling()
- and self.tilt_calc.travel_direction == TravelStatus.DIRECTION_UP
- )
-
- @property
- def is_closing(self):
- """Return if the cover is closing or not."""
- return (
- self.travel_calc.is_traveling()
- and self.travel_calc.travel_direction == TravelStatus.DIRECTION_DOWN
- ) or (
- self._has_tilt_support()
- and self.tilt_calc.is_traveling()
- and self.tilt_calc.travel_direction == TravelStatus.DIRECTION_DOWN
+ hass = platform.hass
+
+ if not hass.services.has_service(DOMAIN, SERVICE_START_CALIBRATION):
+
+ async def _handle_start_calibration(call):
+ entity_id = call.data["entity_id"]
+ entity = resolve_entity(hass, entity_id)
+ data = {k: v for k, v in call.data.items() if k != "entity_id"}
+ await entity.start_calibration(**data)
+
+ hass.services.async_register(
+ DOMAIN,
+ SERVICE_START_CALIBRATION,
+ _handle_start_calibration,
+ schema=vol.Schema(
+ {
+ vol.Required("entity_id"): cv.entity_id,
+ vol.Required("attribute"): vol.In(CALIBRATABLE_ATTRIBUTES),
+ vol.Required("timeout"): vol.All(
+ vol.Coerce(float), vol.Range(min=1)
+ ),
+ vol.Optional("direction"): vol.In(["open", "close"]),
+ }
+ ),
)
- @property
- def is_closed(self):
- """Return if the cover is closed."""
- if not self._has_tilt_support():
- return self.travel_calc.is_closed()
-
- return self.travel_calc.is_closed() and self.tilt_calc.is_closed()
-
- @property
- def assumed_state(self):
- """Return True because covers can be stopped midway."""
- return True
-
- @property
- def supported_features(self) -> CoverEntityFeature:
- """Flag supported features."""
- supported_features = (
- CoverEntityFeature.OPEN | CoverEntityFeature.CLOSE | CoverEntityFeature.STOP
+ if not hass.services.has_service(DOMAIN, SERVICE_STOP_CALIBRATION):
+
+ async def _handle_stop_calibration(call):
+ entity_id = call.data["entity_id"]
+ entity = resolve_entity(hass, entity_id)
+ data = {k: v for k, v in call.data.items() if k != "entity_id"}
+ return await entity.stop_calibration(**data)
+
+ hass.services.async_register(
+ DOMAIN,
+ SERVICE_STOP_CALIBRATION,
+ _handle_stop_calibration,
+ schema=vol.Schema(
+ {
+ vol.Required("entity_id"): cv.entity_id,
+ vol.Optional("cancel", default=False): cv.boolean,
+ }
+ ),
+ supports_response=SupportsResponse.OPTIONAL,
)
- if self.current_cover_position is not None:
- supported_features |= CoverEntityFeature.SET_POSITION
-
- if self._has_tilt_support():
- supported_features |= (
- CoverEntityFeature.OPEN_TILT
- | CoverEntityFeature.CLOSE_TILT
- | CoverEntityFeature.STOP_TILT
- )
- if self.current_cover_tilt_position is not None:
- supported_features |= CoverEntityFeature.SET_TILT_POSITION
-
- return supported_features
-
- async def async_set_cover_position(self, **kwargs):
- """Move the cover to a specific position."""
- if ATTR_POSITION in kwargs:
- position = kwargs[ATTR_POSITION]
- _LOGGER.debug("async_set_cover_position: %d", position)
- await self.set_position(position)
-
- async def async_set_cover_tilt_position(self, **kwargs):
- """Move the cover tilt to a specific position."""
- if ATTR_TILT_POSITION in kwargs:
- position = kwargs[ATTR_TILT_POSITION]
- _LOGGER.debug("async_set_cover_tilt_position: %d", position)
- await self.set_tilt_position(position)
-
- async def async_close_cover(self, **kwargs):
- """Turn the device close."""
- _LOGGER.debug("async_close_cover")
-
- if self._input_mode == INPUT_MODE_TOGGLE and (self.is_closing or self.is_opening):
- if self.is_closing:
- _LOGGER.debug("async_close_cover :: toggle mode, already closing, treating as stop")
- await self.async_stop_cover()
- return
- else:
- _LOGGER.debug("async_close_cover :: toggle mode, currently opening, stopping first")
- await self.async_stop_cover()
-
- current_travel_position = self.travel_calc.current_position()
- if current_travel_position is None or current_travel_position < 100:
- if self._startup_delay_task and not self._startup_delay_task.done():
- if self._last_command == SERVICE_OPEN_COVER:
- _LOGGER.debug("async_close_cover :: direction change, cancelling startup delay")
- self._cancel_startup_delay_task()
- await self._async_handle_command(SERVICE_STOP_COVER)
- else:
- # EDGE CASE: Tilt→travel switch during startup delay - ignore startup_delay difference
- _LOGGER.debug("async_close_cover :: startup delay already active, not restarting")
- return
-
- relay_was_on = self._cancel_delay_task()
- if relay_was_on:
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- travel_distance = 100 - (current_travel_position if current_travel_position is not None else 0)
- movement_time = (travel_distance / 100.0) * self._travel_time_down
-
- _LOGGER.debug(
- "async_close_cover :: travel_distance=%f%%, movement_time=%fs",
- travel_distance, movement_time
- )
-
- self._last_command = SERVICE_CLOSE_COVER
-
- tilt_target = None
- if self._has_tilt_support():
- tilt_distance = (movement_time / self._tilting_time_down) * 100.0
- current_tilt_position = self.tilt_calc.current_position()
- tilt_target = min(100, current_tilt_position + tilt_distance)
- _LOGGER.debug(
- "async_close_cover :: tilt_distance=%f%%, new_tilt_pos=%f",
- tilt_distance, tilt_target
- )
-
- await self._async_handle_command(SERVICE_CLOSE_COVER)
-
- if self._travel_startup_delay and self._travel_startup_delay > 0:
- def start_movement():
- self.travel_calc.start_travel_down()
- if tilt_target is not None:
- self.tilt_calc.start_travel(int(tilt_target))
- self.start_auto_updater()
-
- self._startup_delay_task = self.hass.async_create_task(
- self._execute_with_startup_delay(self._travel_startup_delay, start_movement)
- )
- else:
- self.travel_calc.start_travel_down()
- if tilt_target is not None:
- self.tilt_calc.start_travel(int(tilt_target))
- self.start_auto_updater()
-
- async def async_open_cover(self, **kwargs):
- """Turn the device open."""
- _LOGGER.debug("async_open_cover")
-
- if self._input_mode == INPUT_MODE_TOGGLE and (self.is_opening or self.is_closing):
- if self.is_opening:
- _LOGGER.debug("async_open_cover :: toggle mode, already opening, treating as stop")
- await self.async_stop_cover()
- return
- else:
- _LOGGER.debug("async_open_cover :: toggle mode, currently closing, stopping first")
- await self.async_stop_cover()
-
- current_travel_position = self.travel_calc.current_position()
- if current_travel_position is None or current_travel_position > 0:
- if self._startup_delay_task and not self._startup_delay_task.done():
- if self._last_command == SERVICE_CLOSE_COVER:
- _LOGGER.debug("async_open_cover :: direction change, cancelling startup delay")
- self._cancel_startup_delay_task()
- await self._async_handle_command(SERVICE_STOP_COVER)
- else:
- # EDGE CASE: Tilt→travel switch during startup delay - ignore startup_delay difference
- _LOGGER.debug("async_open_cover :: startup delay already active, not restarting")
- return
-
- relay_was_on = self._cancel_delay_task()
- if relay_was_on:
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- travel_distance = (current_travel_position if current_travel_position is not None else 100)
- movement_time = (travel_distance / 100.0) * self._travel_time_up
-
- _LOGGER.debug(
- "async_open_cover :: travel_distance=%f%%, movement_time=%fs",
- travel_distance, movement_time
- )
-
- self._last_command = SERVICE_OPEN_COVER
-
- tilt_target = None
- if self._has_tilt_support():
- tilt_distance = (movement_time / self._tilting_time_up) * 100.0
- current_tilt_position = self.tilt_calc.current_position()
- tilt_target = max(0, current_tilt_position - tilt_distance)
- _LOGGER.debug(
- "async_open_cover :: tilt_distance=%f%%, new_tilt_pos=%f",
- tilt_distance, tilt_target
- )
-
- await self._async_handle_command(SERVICE_OPEN_COVER)
-
- if self._travel_startup_delay and self._travel_startup_delay > 0:
- def start_movement():
- self.travel_calc.start_travel_up()
- if tilt_target is not None:
- self.tilt_calc.start_travel(int(tilt_target))
- self.start_auto_updater()
-
- self._startup_delay_task = self.hass.async_create_task(
- self._execute_with_startup_delay(self._travel_startup_delay, start_movement)
- )
- else:
- self.travel_calc.start_travel_up()
- if tilt_target is not None:
- self.tilt_calc.start_travel(int(tilt_target))
- self.start_auto_updater()
-
- async def async_close_cover_tilt(self, **kwargs):
- """Turn the device close."""
- _LOGGER.debug("async_close_cover_tilt")
-
- if self._startup_delay_task and not self._startup_delay_task.done():
- if self._last_command == SERVICE_OPEN_COVER:
- _LOGGER.debug("async_close_cover_tilt :: direction change, cancelling startup delay")
- self._cancel_startup_delay_task()
- await self._async_handle_command(SERVICE_STOP_COVER)
- else:
- # EDGE CASE: Travel→tilt switch during startup delay - ignore startup_delay difference
- _LOGGER.debug("async_close_cover_tilt :: startup delay already active, not restarting")
- return
-
- relay_was_on = self._cancel_delay_task()
- if relay_was_on:
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- self._stop_travel_if_traveling()
-
- current_tilt_position = self.tilt_calc.current_position()
- if current_tilt_position is None or current_tilt_position < 100:
- tilt_distance = 100 - (current_tilt_position if current_tilt_position is not None else 0)
- movement_time = (tilt_distance / 100.0) * self._tilting_time_down
-
- travel_target = None
- if self._travel_moves_with_tilt:
- travel_distance = (movement_time / self._travel_time_down) * 100.0
- current_travel_position = self.travel_calc.current_position()
- travel_target = min(100, current_travel_position + travel_distance)
-
- _LOGGER.debug(
- "async_close_cover_tilt :: tilt_distance=%f%%, movement_time=%fs, travel_distance=%f%%, new_travel_pos=%s",
- tilt_distance, movement_time,
- (movement_time / self._travel_time_down) * 100.0 if self._travel_moves_with_tilt else 0,
- travel_target if travel_target is not None else "N/A"
- )
-
- self._last_command = SERVICE_CLOSE_COVER
-
- await self._async_handle_command(SERVICE_CLOSE_COVER)
-
- if self._tilt_startup_delay and self._tilt_startup_delay > 0:
- def start_movement():
- self.tilt_calc.start_travel_down()
- if travel_target is not None:
- self.travel_calc.start_travel(int(travel_target))
- self.start_auto_updater()
-
- self._startup_delay_task = self.hass.async_create_task(
- self._execute_with_startup_delay(self._tilt_startup_delay, start_movement)
- )
- else:
- self.tilt_calc.start_travel_down()
- if travel_target is not None:
- self.travel_calc.start_travel(int(travel_target))
- self.start_auto_updater()
-
- async def async_open_cover_tilt(self, **kwargs):
- """Turn the device open."""
- _LOGGER.debug("async_open_cover_tilt")
-
- if self._startup_delay_task and not self._startup_delay_task.done():
- if self._last_command == SERVICE_CLOSE_COVER:
- _LOGGER.debug("async_open_cover_tilt :: direction change, cancelling startup delay")
- self._cancel_startup_delay_task()
- await self._async_handle_command(SERVICE_STOP_COVER)
- else:
- # EDGE CASE: Travel→tilt switch during startup delay - ignore startup_delay difference
- _LOGGER.debug("async_open_cover_tilt :: startup delay already active, not restarting")
- return
-
- relay_was_on = self._cancel_delay_task()
- if relay_was_on:
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- self._stop_travel_if_traveling()
-
- current_tilt_position = self.tilt_calc.current_position()
- if current_tilt_position is None or current_tilt_position > 0:
- tilt_distance = (current_tilt_position if current_tilt_position is not None else 100)
- movement_time = (tilt_distance / 100.0) * self._tilting_time_up
-
- travel_target = None
- if self._travel_moves_with_tilt:
- travel_distance = (movement_time / self._travel_time_up) * 100.0
- current_travel_position = self.travel_calc.current_position()
- travel_target = max(0, current_travel_position - travel_distance)
-
- _LOGGER.debug(
- "async_open_cover_tilt :: tilt_distance=%f%%, movement_time=%fs, travel_distance=%f%%, new_travel_pos=%s",
- tilt_distance, movement_time,
- (movement_time / self._travel_time_up) * 100.0 if self._travel_moves_with_tilt else 0,
- travel_target if travel_target is not None else "N/A"
- )
-
- self._last_command = SERVICE_OPEN_COVER
-
- await self._async_handle_command(SERVICE_OPEN_COVER)
-
- if self._tilt_startup_delay and self._tilt_startup_delay > 0:
- def start_movement():
- self.tilt_calc.start_travel_up()
- if travel_target is not None:
- self.travel_calc.start_travel(int(travel_target))
- self.start_auto_updater()
-
- self._startup_delay_task = self.hass.async_create_task(
- self._execute_with_startup_delay(self._tilt_startup_delay, start_movement)
- )
- else:
- self.tilt_calc.start_travel_up()
- if travel_target is not None:
- self.travel_calc.start_travel(int(travel_target))
- self.start_auto_updater()
-
- async def async_stop_cover(self, **kwargs):
- """Turn the device stop."""
- _LOGGER.debug("async_stop_cover")
-
- was_active = (
- self.is_opening or self.is_closing
- or (self._startup_delay_task and not self._startup_delay_task.done())
- or (self._delay_task and not self._delay_task.done())
- )
-
- self._cancel_startup_delay_task()
- self._cancel_delay_task()
- self._handle_stop()
- self._enforce_tilt_constraints()
-
- if was_active or self._input_mode != INPUT_MODE_TOGGLE:
- await self._async_handle_command(SERVICE_STOP_COVER)
- self._last_command = None
-
- async def set_position(self, position):
- """Move cover to a designated position."""
- _LOGGER.debug("set_position")
-
- current_travel_position = self.travel_calc.current_position()
- new_travel_position = 100 - position
- _LOGGER.debug(
- "set_position :: current_position: %d, new_position: %d",
- current_travel_position,
- position,
- )
- command = None
- if current_travel_position is None or new_travel_position > current_travel_position:
- command = SERVICE_CLOSE_COVER
- travel_time = self._travel_time_down
- tilt_time = self._tilting_time_down if self._has_tilt_support() else None
- startup_delay = self._travel_startup_delay
- elif new_travel_position < current_travel_position:
- command = SERVICE_OPEN_COVER
- travel_time = self._travel_time_up
- tilt_time = self._tilting_time_up if self._has_tilt_support() else None
- startup_delay = self._travel_startup_delay
- else:
- return
-
- if command is not None:
- is_direction_change = False
-
- if self._last_command is not None and self._last_command != command:
- is_direction_change = True
- _LOGGER.debug("set_position :: direction change detected (%s → %s)", self._last_command, command)
-
- # EDGE CASE: User adjusts target position during startup (e.g., 50%→60%)
- # We don't restart the delay since motor is already starting up
- if (self._startup_delay_task and not self._startup_delay_task.done()
- and not is_direction_change):
- _LOGGER.debug("set_position :: startup delay already active for same direction, not restarting")
- return
-
- if is_direction_change and self._startup_delay_task and not self._startup_delay_task.done():
- self._cancel_startup_delay_task()
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- if is_direction_change and self.travel_calc.is_traveling():
- _LOGGER.debug("set_position :: stopping active travel movement")
- self.travel_calc.stop()
- self.stop_auto_updater()
- if self._has_tilt_support() and self.tilt_calc.is_traveling():
- self.tilt_calc.stop()
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- current_travel_position = self.travel_calc.current_position()
- _LOGGER.debug("set_position :: position after stop: %d", 100 - current_travel_position)
-
- if new_travel_position == current_travel_position:
- _LOGGER.debug("set_position :: already at target after stop, no movement needed")
- return
-
- relay_was_on = self._cancel_delay_task()
- if relay_was_on:
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- travel_distance = abs(new_travel_position - current_travel_position)
- movement_time = (travel_distance / 100.0) * travel_time
-
- is_to_endpoint = (new_travel_position == 0 or new_travel_position == 100)
- if (
- self._min_movement_time is not None
- and self._min_movement_time > 0
- and not is_to_endpoint
- and movement_time < self._min_movement_time
- ):
- _LOGGER.info(
- "set_position :: movement too short (%fs < %fs), ignoring - from %d%% to %d%%",
- movement_time,
- self._min_movement_time,
- 100 - current_travel_position,
- position,
- )
- self.async_write_ha_state()
- return
-
- _LOGGER.debug(
- "set_position :: travel_distance=%f%%, movement_time=%fs",
- travel_distance, movement_time
- )
-
- self._last_command = command
-
- tilt_target = None
- if self._has_tilt_support():
- tilt_distance = (movement_time / tilt_time) * 100.0
- current_tilt_position = self.tilt_calc.current_position()
- if command == SERVICE_CLOSE_COVER:
- tilt_target = min(100, current_tilt_position + tilt_distance)
- else:
- tilt_target = max(0, current_tilt_position - tilt_distance)
-
- _LOGGER.debug(
- "set_position :: tilt_distance=%f%%, new_tilt_pos=%f",
- tilt_distance, tilt_target
- )
-
- await self._async_handle_command(command)
-
- if startup_delay and startup_delay > 0:
- def start_movement():
- self.travel_calc.start_travel(new_travel_position)
- if tilt_target is not None:
- self.tilt_calc.start_travel(int(tilt_target))
- self.start_auto_updater()
-
- self._startup_delay_task = self.hass.async_create_task(
- self._execute_with_startup_delay(startup_delay, start_movement)
- )
- else:
- self.travel_calc.start_travel(new_travel_position)
- if tilt_target is not None:
- self.tilt_calc.start_travel(int(tilt_target))
- self.start_auto_updater()
- return
-
- async def set_tilt_position(self, position):
- """Move cover tilt to a designated position."""
- _LOGGER.debug("set_tilt_position")
-
- current_tilt_position = self.tilt_calc.current_position()
- new_tilt_position = 100 - position
- _LOGGER.debug(
- "set_tilt_position :: current_position: %d, new_position: %d",
- current_tilt_position,
- new_tilt_position,
- )
- command = None
- if current_tilt_position is None or new_tilt_position > current_tilt_position:
- command = SERVICE_CLOSE_COVER
- tilt_time = self._tilting_time_down
- travel_time = self._travel_time_down
- startup_delay = self._tilt_startup_delay
- elif new_tilt_position < current_tilt_position:
- command = SERVICE_OPEN_COVER
- tilt_time = self._tilting_time_up
- travel_time = self._travel_time_up
- startup_delay = self._tilt_startup_delay
- else:
- return
-
- if command is not None:
- is_direction_change = False
-
- if self._last_command is not None and self._last_command != command:
- is_direction_change = True
- _LOGGER.debug("set_tilt_position :: direction change detected (%s → %s)", self._last_command, command)
-
- # EDGE CASE: User adjusts tilt target during startup (e.g., 50%→60% tilt)
- # We don't restart the delay since motor is already starting up
- if (self._startup_delay_task and not self._startup_delay_task.done()
- and not is_direction_change):
- _LOGGER.debug("set_tilt_position :: startup delay already active for same direction, not restarting")
- return
-
- if is_direction_change and self._startup_delay_task and not self._startup_delay_task.done():
- self._cancel_startup_delay_task()
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- if is_direction_change:
- if self.tilt_calc.is_traveling():
- _LOGGER.debug("set_tilt_position :: stopping active tilt movement")
- self.tilt_calc.stop()
- if self.travel_calc.is_traveling():
- self.travel_calc.stop()
- self.stop_auto_updater()
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- current_tilt_position = self.tilt_calc.current_position()
- _LOGGER.debug("set_tilt_position :: tilt position after stop: %d", 100 - current_tilt_position)
-
- if new_tilt_position == current_tilt_position:
- _LOGGER.debug("set_tilt_position :: already at target after stop, no movement needed")
- return
-
- relay_was_on = self._cancel_delay_task()
- if relay_was_on:
- await self._async_handle_command(SERVICE_STOP_COVER)
-
- if not is_direction_change:
- self._stop_travel_if_traveling()
-
- tilt_distance = abs(new_tilt_position - current_tilt_position)
- movement_time = (tilt_distance / 100.0) * tilt_time
-
- travel_target = None
- if self._travel_moves_with_tilt:
- travel_distance = (movement_time / travel_time) * 100.0
- current_travel_position = self.travel_calc.current_position()
- if command == SERVICE_CLOSE_COVER:
- travel_target = min(100, current_travel_position + travel_distance)
- else:
- travel_target = max(0, current_travel_position - travel_distance)
-
- is_to_endpoint = (new_tilt_position == 0 or new_tilt_position == 100)
- if (
- self._min_movement_time is not None
- and self._min_movement_time > 0
- and not is_to_endpoint
- and movement_time < self._min_movement_time
- ):
- _LOGGER.info(
- "set_tilt_position :: movement too short (%fs < %fs), ignoring - from %d%% to %d%%",
- movement_time,
- self._min_movement_time,
- 100 - current_tilt_position,
- position,
- )
- self.async_write_ha_state()
- return
-
- self._last_command = command
-
- _LOGGER.debug(
- "set_tilt_position :: tilt_distance=%f%%, movement_time=%fs, travel_distance=%f%%, new_travel_pos=%s",
- tilt_distance, movement_time,
- (movement_time / travel_time) * 100.0 if self._travel_moves_with_tilt else 0,
- travel_target if travel_target is not None else "N/A"
- )
-
- await self._async_handle_command(command)
-
- if startup_delay and startup_delay > 0:
- def start_movement():
- self.tilt_calc.start_travel(new_tilt_position)
- if travel_target is not None:
- self.travel_calc.start_travel(int(travel_target))
- self.start_auto_updater()
-
- self._startup_delay_task = self.hass.async_create_task(
- self._execute_with_startup_delay(startup_delay, start_movement)
- )
- else:
- self.tilt_calc.start_travel(new_tilt_position)
- if travel_target is not None:
- self.travel_calc.start_travel(int(travel_target))
- self.start_auto_updater()
- return
-
- def start_auto_updater(self):
- """Start the autoupdater to update HASS while cover is moving."""
- _LOGGER.debug("start_auto_updater")
- if self._unsubscribe_auto_updater is None:
- _LOGGER.debug("init _unsubscribe_auto_updater")
- interval = timedelta(seconds=0.1)
- self._unsubscribe_auto_updater = async_track_time_interval(
- self.hass, self.auto_updater_hook, interval
- )
-
- @callback
- def auto_updater_hook(self, now):
- """Call for the autoupdater."""
- _LOGGER.debug("auto_updater_hook")
- self.async_schedule_update_ha_state()
- if self.position_reached():
- _LOGGER.debug("auto_updater_hook :: position_reached")
- self.stop_auto_updater()
- self.hass.async_create_task(self.auto_stop_if_necessary())
-
- def stop_auto_updater(self):
- """Stop the autoupdater."""
- _LOGGER.debug("stop_auto_updater")
- if self._unsubscribe_auto_updater is not None:
- self._unsubscribe_auto_updater()
- self._unsubscribe_auto_updater = None
-
- def position_reached(self):
- """Return if cover has reached its final position."""
- return self.travel_calc.position_reached() and (
- not self._has_tilt_support() or self.tilt_calc.position_reached()
- )
-
- def _has_tilt_support(self):
- """Return if cover has tilt support."""
- return self._tilting_time_down is not None and self._tilting_time_up is not None
-
- def _enforce_tilt_constraints(self):
- """Enforce tilt position constraints at travel boundaries."""
- if not self._has_tilt_support():
- return
-
- if not self._travel_moves_with_tilt:
- return
-
- current_travel = self.travel_calc.current_position()
- current_tilt = self.tilt_calc.current_position()
-
- if current_travel == 0 and current_tilt != 0:
- _LOGGER.debug(
- "_enforce_tilt_constraints :: Travel at 0%%, forcing tilt to 0%% (was %d%%)",
- current_tilt
- )
- self.tilt_calc.set_position(0)
-
- elif current_travel == 100 and current_tilt != 100:
- _LOGGER.debug(
- "_enforce_tilt_constraints :: Travel at 100%%, forcing tilt to 100%% (was %d%%)",
- current_tilt
- )
- self.tilt_calc.set_position(100)
-
- async def auto_stop_if_necessary(self):
- """Do auto stop if necessary."""
- if self.position_reached():
- _LOGGER.debug("auto_stop_if_necessary :: calling stop command")
- self.travel_calc.stop()
- if self._has_tilt_support():
- self.tilt_calc.stop()
-
- self._enforce_tilt_constraints()
-
- current_travel = self.travel_calc.current_position()
- if self._travel_delay_at_end is not None and self._travel_delay_at_end > 0 and (current_travel == 0 or current_travel == 100):
- _LOGGER.debug(
- "auto_stop_if_necessary :: at endpoint (position=%d), delaying relay stop by %fs",
- current_travel,
- self._travel_delay_at_end
- )
- self._delay_task = self.hass.async_create_task(
- self._delayed_stop(self._travel_delay_at_end)
- )
- else:
- await self._async_handle_command(SERVICE_STOP_COVER)
- self._last_command = None
-
- async def _delayed_stop(self, delay):
- """Stop the relay after a delay."""
- _LOGGER.debug("_delayed_stop :: waiting %fs before stopping relay", delay)
- try:
- await sleep(delay)
- _LOGGER.debug("_delayed_stop :: delay complete, stopping relay")
- await self._async_handle_command(SERVICE_STOP_COVER)
- self._last_command = None
- self._delay_task = None
- except asyncio.CancelledError:
- _LOGGER.debug("_delayed_stop :: delay cancelled")
- self._delay_task = None
- raise
-
- async def set_known_position(self, **kwargs):
- """We want to do a few things when we get a position"""
- position = kwargs[ATTR_POSITION]
- was_active = self.is_opening or self.is_closing
- self._handle_stop()
- if was_active or self._input_mode != INPUT_MODE_TOGGLE:
- await self._async_handle_command(SERVICE_STOP_COVER)
- self.travel_calc.set_position(position)
- self._enforce_tilt_constraints()
- self._last_command = None
-
- async def set_known_tilt_position(self, **kwargs):
- """We want to do a few things when we get a position"""
- position = kwargs[ATTR_TILT_POSITION]
- was_active = self.is_opening or self.is_closing
- if was_active or self._input_mode != INPUT_MODE_TOGGLE:
- await self._async_handle_command(SERVICE_STOP_COVER)
- self.tilt_calc.set_position(position)
- self._last_command = None
-
- async def _async_handle_command(self, command, *args):
- if command == SERVICE_CLOSE_COVER:
- cmd = "DOWN"
- self._state = False
- if self._cover_entity_id is not None:
- await self.hass.services.async_call(
- "cover",
- "close_cover",
- {"entity_id": self._cover_entity_id},
- False,
- )
- else:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._open_switch_entity_id},
- False,
- )
- await self.hass.services.async_call(
- "homeassistant",
- "turn_on",
- {"entity_id": self._close_switch_entity_id},
- False,
- )
- if self._stop_switch_entity_id is not None:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._stop_switch_entity_id},
- False,
- )
-
- if self._input_mode in (INPUT_MODE_PULSE, INPUT_MODE_TOGGLE):
- await sleep(self._pulse_time)
-
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._close_switch_entity_id},
- False,
- )
-
- elif command == SERVICE_OPEN_COVER:
- cmd = "UP"
- self._state = True
- if self._cover_entity_id is not None:
- await self.hass.services.async_call(
- "cover",
- "open_cover",
- {"entity_id": self._cover_entity_id},
- False,
- )
- else:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._close_switch_entity_id},
- False,
- )
- await self.hass.services.async_call(
- "homeassistant",
- "turn_on",
- {"entity_id": self._open_switch_entity_id},
- False,
- )
- if self._stop_switch_entity_id is not None:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._stop_switch_entity_id},
- False,
- )
- if self._input_mode in (INPUT_MODE_PULSE, INPUT_MODE_TOGGLE):
- await sleep(self._pulse_time)
-
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._open_switch_entity_id},
- False,
- )
-
- elif command == SERVICE_STOP_COVER:
- cmd = "STOP"
- self._state = True
- if self._cover_entity_id is not None:
- await self.hass.services.async_call(
- "cover",
- "stop_cover",
- {"entity_id": self._cover_entity_id},
- False,
- )
- elif self._input_mode == INPUT_MODE_TOGGLE:
- # Toggle mode: pulse the last-used direction button to stop
- if self._last_command == SERVICE_CLOSE_COVER:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_on",
- {"entity_id": self._close_switch_entity_id},
- False,
- )
- await sleep(self._pulse_time)
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._close_switch_entity_id},
- False,
- )
- elif self._last_command == SERVICE_OPEN_COVER:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_on",
- {"entity_id": self._open_switch_entity_id},
- False,
- )
- await sleep(self._pulse_time)
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._open_switch_entity_id},
- False,
- )
- else:
- _LOGGER.debug(
- "_async_handle_command :: STOP in toggle mode with no last command, skipping"
- )
- else:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._close_switch_entity_id},
- False,
- )
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._open_switch_entity_id},
- False,
- )
- if self._stop_switch_entity_id is not None:
- await self.hass.services.async_call(
- "homeassistant",
- "turn_on",
- {"entity_id": self._stop_switch_entity_id},
- False,
- )
-
- if self._input_mode == INPUT_MODE_PULSE:
- await sleep(self._pulse_time)
-
- await self.hass.services.async_call(
- "homeassistant",
- "turn_off",
- {"entity_id": self._stop_switch_entity_id},
- False,
- )
-
- _LOGGER.debug("_async_handle_command :: %s", cmd)
-
- self.async_write_ha_state()
diff --git a/custom_components/cover_time_based/cover_base.py b/custom_components/cover_time_based/cover_base.py
new file mode 100644
index 0000000..05cb523
--- /dev/null
+++ b/custom_components/cover_time_based/cover_base.py
@@ -0,0 +1,1638 @@
+"""Base class for time-based cover entities."""
+
+import asyncio
+import logging
+from abc import abstractmethod
+from asyncio import sleep
+from datetime import timedelta
+
+from homeassistant.components.cover import (
+ ATTR_CURRENT_POSITION,
+ ATTR_CURRENT_TILT_POSITION,
+ ATTR_POSITION,
+ ATTR_TILT_POSITION,
+ CoverEntity,
+ CoverEntityFeature,
+)
+from homeassistant.const import (
+ SERVICE_CLOSE_COVER,
+ SERVICE_OPEN_COVER,
+ SERVICE_STOP_COVER,
+)
+from homeassistant.core import callback
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers.event import (
+ async_call_later,
+ async_track_state_change_event,
+ async_track_time_interval,
+)
+from homeassistant.helpers.restore_state import RestoreEntity
+from .travel_calculator import TravelCalculator, TravelStatus
+
+from .calibration import CalibrationState
+from .cover_calibration import CalibrationMixin
+from .const import (
+ CONF_ENDPOINT_RUNON_TIME,
+ CONF_MIN_MOVEMENT_TIME,
+ CONF_TILT_MODE,
+ CONF_TILT_STARTUP_DELAY,
+ CONF_TILT_TIME_CLOSE,
+ CONF_TILT_TIME_OPEN,
+ CONF_TRAVEL_STARTUP_DELAY,
+ CONF_TRAVEL_TIME_CLOSE,
+ CONF_TRAVEL_TIME_OPEN,
+)
+from .tilt_strategies.planning import (
+ calculate_pre_step_delay,
+ extract_coupled_tilt,
+ extract_coupled_travel,
+ has_travel_pre_step,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CoverTimeBased(CalibrationMixin, CoverEntity, RestoreEntity):
+ """Time-based cover with position tracking."""
+
+ def __init__(
+ self,
+ device_id,
+ name,
+ tilt_strategy,
+ travel_time_close,
+ travel_time_open,
+ tilt_time_close,
+ tilt_time_open,
+ travel_startup_delay,
+ tilt_startup_delay,
+ endpoint_runon_time,
+ min_movement_time,
+ tilt_open_switch=None,
+ tilt_close_switch=None,
+ tilt_stop_switch=None,
+ ):
+ """Initialize the cover."""
+ self._unique_id = device_id
+
+ self._tilt_strategy = tilt_strategy
+ self._travel_time_close = travel_time_close
+ self._travel_time_open = travel_time_open
+ self._tilting_time_close = tilt_time_close
+ self._tilting_time_open = tilt_time_open
+ self._travel_startup_delay = travel_startup_delay
+ self._tilt_startup_delay = tilt_startup_delay
+ self._endpoint_runon_time = endpoint_runon_time
+ self._min_movement_time = min_movement_time
+ self._tilt_open_switch_id = tilt_open_switch
+ self._tilt_close_switch_id = tilt_close_switch
+ self._tilt_stop_switch_id = tilt_stop_switch
+
+ if name:
+ self._name = name
+ else:
+ self._name = device_id
+
+ self._config_entry_id: str | None = None
+ self._calibration: CalibrationState | None = None
+ self._unsubscribe_auto_updater = None
+ self._delay_task = None
+ self._startup_delay_task = None
+ self._last_command = None
+ self._tilt_restore_target: int | None = None
+ self._tilt_restore_active: bool = False
+ self._pending_travel_target: int | None = None
+ self._pending_travel_command: str | None = None
+ self._pending_tilt_target: int | None = None
+ self._pending_tilt_command: str | None = None
+ self._triggered_externally = False
+ self._self_initiated_movement = True
+ self._state = True
+ self._pending_switch = {}
+ self._pending_switch_timers = {}
+ self._state_listener_unsubs = []
+
+ self.travel_calc = TravelCalculator(
+ self._travel_time_close,
+ self._travel_time_open,
+ )
+ if self._tilting_time_close is not None and self._tilting_time_open is not None:
+ self.tilt_calc = TravelCalculator(
+ self._tilting_time_close,
+ self._tilting_time_open,
+ )
+
+ def _log(self, msg, *args):
+ """Log a debug message prefixed with the entity ID."""
+ _LOGGER.debug("(%s) " + msg, self.entity_id, *args)
+
+ # -----------------------------------------------------------------------
+ # Lifecycle
+ # -----------------------------------------------------------------------
+
+ async def async_added_to_hass(self):
+ """Only cover's position and tilt matters."""
+ old_state = await self.async_get_last_state()
+ self._log("async_added_to_hass :: oldState %s", old_state)
+ pos = (
+ old_state.attributes.get(ATTR_CURRENT_POSITION)
+ if old_state is not None
+ else None
+ )
+ if old_state is not None and self.travel_calc is not None and pos is not None:
+ self.travel_calc.set_position(int(pos))
+
+ tilt_pos = old_state.attributes.get(ATTR_CURRENT_TILT_POSITION)
+ if self._has_tilt_support() and tilt_pos is not None:
+ self.tilt_calc.set_position(int(tilt_pos))
+
+ # Register state change listeners for switch entities
+ for attr in (
+ "_open_switch_entity_id",
+ "_close_switch_entity_id",
+ "_stop_switch_entity_id",
+ "_tilt_open_switch_id",
+ "_tilt_close_switch_id",
+ "_tilt_stop_switch_id",
+ ):
+ entity_id = getattr(self, attr, None)
+ if entity_id:
+ self._state_listener_unsubs.append(
+ async_track_state_change_event(
+ self.hass,
+ [entity_id],
+ self._async_switch_state_changed,
+ )
+ )
+
+ async def async_will_remove_from_hass(self):
+ """Clean up when entity is removed."""
+ self.stop_auto_updater()
+ for unsub in self._state_listener_unsubs:
+ unsub()
+ self._state_listener_unsubs.clear()
+ for timer in self._pending_switch_timers.values():
+ timer()
+ self._pending_switch_timers.clear()
+ if self._calibration is not None:
+ if (
+ self._calibration.timeout_task
+ and not self._calibration.timeout_task.done()
+ ):
+ self._calibration.timeout_task.cancel()
+ if (
+ self._calibration.automation_task
+ and not self._calibration.automation_task.done()
+ ):
+ self._calibration.automation_task.cancel()
+ self._calibration = None
+
+ # -----------------------------------------------------------------------
+ # Properties
+ # -----------------------------------------------------------------------
+
+ @property
+ def name(self):
+ """Return the name of the cover."""
+ return self._name
+
+ @property
+ def unique_id(self):
+ """Return the unique id."""
+ return "cover_timebased_uuid_" + self._unique_id
+
+ @property
+ def device_class(self):
+ """Return the device class of the cover."""
+ return None
+
+ @property
+ def available(self) -> bool:
+ """Return True if the cover is properly configured and available."""
+ return len(self._get_missing_configuration()) == 0
+
+ @property
+ def assumed_state(self):
+ """Return True because covers can be stopped midway."""
+ return True
+
+ @property
+ def supported_features(self) -> CoverEntityFeature:
+ """Flag supported features."""
+ supported_features = (
+ CoverEntityFeature.OPEN
+ | CoverEntityFeature.CLOSE
+ | CoverEntityFeature.STOP
+ | CoverEntityFeature.SET_POSITION
+ )
+
+ if self._has_tilt_support():
+ supported_features |= (
+ CoverEntityFeature.OPEN_TILT
+ | CoverEntityFeature.CLOSE_TILT
+ | CoverEntityFeature.STOP_TILT
+ | CoverEntityFeature.SET_TILT_POSITION
+ )
+
+ return supported_features
+
+ @property
+ def current_cover_position(self) -> int | None:
+ """Return the current position of the cover."""
+ return self.travel_calc.current_position()
+
+ @property
+ def current_cover_tilt_position(self) -> int | None:
+ """Return the current tilt of the cover."""
+ if self._has_tilt_support():
+ return self.tilt_calc.current_position()
+ return None
+
+ @property
+ def is_opening(self):
+ """Return if the cover is opening or not."""
+ return (
+ self.travel_calc.is_traveling()
+ and self.travel_calc.travel_direction == TravelStatus.DIRECTION_UP
+ ) or (
+ self._has_tilt_support()
+ and self.tilt_calc.is_traveling()
+ and self.tilt_calc.travel_direction == TravelStatus.DIRECTION_UP
+ )
+
+ @property
+ def is_closing(self):
+ """Return if the cover is closing or not."""
+ return (
+ self.travel_calc.is_traveling()
+ and self.travel_calc.travel_direction == TravelStatus.DIRECTION_DOWN
+ ) or (
+ self._has_tilt_support()
+ and self.tilt_calc.is_traveling()
+ and self.tilt_calc.travel_direction == TravelStatus.DIRECTION_DOWN
+ )
+
+ @property
+ def is_closed(self):
+ """Return if the cover is closed."""
+ if not self._has_tilt_support():
+ return self.travel_calc.is_closed()
+
+ return self.travel_calc.is_closed() and self.tilt_calc.is_closed()
+
+ @property
+ def extra_state_attributes(self):
+ """Return the device state attributes."""
+ attr = {}
+ if self._tilt_strategy is not None:
+ attr[CONF_TILT_MODE] = self._tilt_strategy.name
+ if self._travel_time_close is not None:
+ attr[CONF_TRAVEL_TIME_CLOSE] = self._travel_time_close
+ if self._travel_time_open is not None:
+ attr[CONF_TRAVEL_TIME_OPEN] = self._travel_time_open
+ if self._tilting_time_close is not None:
+ attr[CONF_TILT_TIME_CLOSE] = self._tilting_time_close
+ if self._tilting_time_open is not None:
+ attr[CONF_TILT_TIME_OPEN] = self._tilting_time_open
+ if self._travel_startup_delay is not None:
+ attr[CONF_TRAVEL_STARTUP_DELAY] = self._travel_startup_delay
+ if self._tilt_startup_delay is not None:
+ attr[CONF_TILT_STARTUP_DELAY] = self._tilt_startup_delay
+ if self._endpoint_runon_time is not None:
+ attr[CONF_ENDPOINT_RUNON_TIME] = self._endpoint_runon_time
+ if self._min_movement_time is not None:
+ attr[CONF_MIN_MOVEMENT_TIME] = self._min_movement_time
+ if self._calibration is not None:
+ attr["calibration_active"] = True
+ attr["calibration_attribute"] = self._calibration.attribute
+ if self._calibration.final_step:
+ attr["calibration_final_step"] = True
+ elif self._calibration.step_count > 0:
+ attr["calibration_step"] = self._calibration.step_count
+ return attr
+
+ # -----------------------------------------------------------------------
+ # Public HA service handlers
+ # -----------------------------------------------------------------------
+
+ async def async_close_cover(self, **kwargs):
+ """Close the cover fully."""
+ self._require_configured()
+ self._log("async_close_cover")
+ if self.is_opening:
+ self._log("async_close_cover :: currently opening, stopping first")
+ await self.async_stop_cover()
+ await self._async_move_to_endpoint(target=0)
+
+ async def async_open_cover(self, **kwargs):
+ """Open the cover fully."""
+ self._require_configured()
+ self._log("async_open_cover")
+ if self.is_closing:
+ self._log("async_open_cover :: currently closing, stopping first")
+ await self.async_stop_cover()
+ await self._async_move_to_endpoint(target=100)
+
+ async def async_stop_cover(self, **kwargs):
+ """Turn the device stop."""
+ self._require_configured()
+ self._log("async_stop_cover")
+ tilt_restore_was_active = self._tilt_restore_active
+ tilt_pre_step_was_active = (
+ self._pending_travel_target is not None
+ or self._pending_tilt_target is not None
+ )
+ self._cancel_startup_delay_task()
+ self._cancel_delay_task()
+ self._handle_stop()
+ if self._has_tilt_support():
+ self._tilt_strategy.snap_trackers_to_physical(
+ self.travel_calc, self.tilt_calc
+ )
+ if not self._triggered_externally:
+ await self._send_stop()
+ if (
+ tilt_restore_was_active or tilt_pre_step_was_active
+ ) and self._has_tilt_motor():
+ await self._send_tilt_stop()
+ self.async_write_ha_state()
+ self._last_command = None
+
+ async def async_close_cover_tilt(self, **kwargs):
+ """Tilt the cover fully closed."""
+ self._log("async_close_cover_tilt")
+ await self._async_move_tilt_to_endpoint(target=0)
+
+ async def async_open_cover_tilt(self, **kwargs):
+ """Tilt the cover fully open."""
+ self._log("async_open_cover_tilt")
+ await self._async_move_tilt_to_endpoint(target=100)
+
+ async def async_set_cover_position(self, **kwargs):
+ """Move the cover to a specific position."""
+ self._require_configured()
+ if ATTR_POSITION in kwargs:
+ position = kwargs[ATTR_POSITION]
+ self._log("async_set_cover_position: %d", position)
+ await self.set_position(position)
+
+ async def async_set_cover_tilt_position(self, **kwargs):
+ """Move the cover tilt to a specific position."""
+ if ATTR_TILT_POSITION in kwargs:
+ position = kwargs[ATTR_TILT_POSITION]
+ self._log("async_set_cover_tilt_position: %d", position)
+ await self.set_tilt_position(position)
+
+ async def set_known_position(self, **kwargs):
+ """Set the cover to a known position (0=closed, 100=open)."""
+ position = kwargs[ATTR_POSITION]
+ self._handle_stop()
+ self.travel_calc.set_position(position)
+ if self._has_tilt_support():
+ self._tilt_strategy.snap_trackers_to_physical(
+ self.travel_calc, self.tilt_calc
+ )
+ self.async_write_ha_state()
+
+ async def set_known_tilt_position(self, **kwargs):
+ """Set the tilt to a known position (0=closed, 100=open)."""
+ if not self._has_tilt_support():
+ return
+ position = kwargs[ATTR_TILT_POSITION]
+ self.tilt_calc.set_position(position)
+ self.async_write_ha_state()
+
+ # -----------------------------------------------------------------------
+ # Movement orchestration
+ # -----------------------------------------------------------------------
+
+ async def _async_move_to_endpoint(self, target):
+ """Move cover to an endpoint (0=fully closed, 100=fully open)."""
+ self._self_initiated_movement = not self._triggered_externally
+ await self._abandon_active_lifecycle()
+
+ closing = target == 0
+ command = SERVICE_CLOSE_COVER if closing else SERVICE_OPEN_COVER
+ opposite_command = SERVICE_OPEN_COVER if closing else SERVICE_CLOSE_COVER
+
+ # Check startup delay conflicts BEFORE position check, since during
+ # startup delay the position hasn't started changing yet.
+ if self._startup_delay_task and not self._startup_delay_task.done():
+ if self._last_command == opposite_command:
+ self._log(
+ "_async_move_to_endpoint :: direction change, cancelling startup delay"
+ )
+ self._cancel_startup_delay_task()
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ self._last_command = None
+ return
+ else:
+ self._log(
+ "_async_move_to_endpoint :: startup delay already active, not restarting"
+ )
+ return
+
+ current = self.travel_calc.current_position()
+ if current is not None and current == target:
+ # Resync: send command + endpoint run-on even though tracker
+ # says we're already there. Physical cover may need resyncing.
+ self._cancel_delay_task()
+ self._last_command = command
+ await self._async_handle_command(command)
+ if self._endpoint_runon_time is not None and self._endpoint_runon_time > 0:
+ self._delay_task = self.hass.async_create_task(
+ self._delayed_stop(self._endpoint_runon_time)
+ )
+ else:
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ return
+
+ relay_was_on = self._cancel_delay_task()
+ if relay_was_on:
+ await self._async_handle_command(SERVICE_STOP_COVER)
+
+ if current is None:
+ # Position unknown — assume opposite endpoint so full travel occurs
+ current = 100 if closing else 0
+ self.travel_calc.update_position(current)
+
+ travel_distance = abs(target - current)
+ travel_time = self._require_travel_time(closing)
+ movement_time = (travel_distance / 100.0) * travel_time
+
+ self._log(
+ "_async_move_to_endpoint :: target=%d, travel_distance=%f%%, movement_time=%fs",
+ target,
+ travel_distance,
+ movement_time,
+ )
+
+ self._last_command = command
+
+ tilt_target = None
+ pre_step_delay = 0.0
+ if not self._triggered_externally:
+ # Only plan tilt for self-initiated movements — external movements
+ # can't control relay sequencing (the relay is already on).
+ current_tilt = (
+ self.tilt_calc.current_position() if self._tilt_strategy else None
+ )
+ tilt_target, pre_step_delay, started = await self._plan_tilt_for_travel(
+ target, command, current, current_tilt
+ )
+ if started:
+ return
+
+ await self._async_handle_command(command)
+ coupled_calc = self.tilt_calc if tilt_target is not None else None
+ self._begin_movement(
+ target,
+ tilt_target,
+ self.travel_calc,
+ coupled_calc,
+ self._travel_startup_delay,
+ pre_step_delay,
+ )
+
+ async def _async_move_tilt_to_endpoint(self, target):
+ """Move tilt to an endpoint (0=fully closed, 100=fully open)."""
+ await self._abandon_active_lifecycle()
+
+ closing = target == 0
+ command = SERVICE_CLOSE_COVER if closing else SERVICE_OPEN_COVER
+ opposite_command = SERVICE_OPEN_COVER if closing else SERVICE_CLOSE_COVER
+
+ if self._startup_delay_task and not self._startup_delay_task.done():
+ if self._last_command == opposite_command:
+ self._log(
+ "_async_move_tilt_to_endpoint :: direction change, cancelling startup delay"
+ )
+ self._cancel_startup_delay_task()
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ if (
+ self._tilt_strategy is not None
+ and self._tilt_strategy.uses_tilt_motor
+ ):
+ await self._send_tilt_stop()
+ else:
+ self._log(
+ "_async_move_tilt_to_endpoint :: startup delay already active, not restarting"
+ )
+ return
+
+ relay_was_on = self._cancel_delay_task()
+ if relay_was_on:
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ if self._tilt_strategy is not None and self._tilt_strategy.uses_tilt_motor:
+ await self._send_tilt_stop()
+
+ self._stop_travel_if_traveling()
+
+ current_tilt = self.tilt_calc.current_position()
+ if current_tilt is not None and current_tilt == target:
+ return
+
+ if current_tilt is None:
+ current_tilt = 100 if closing else 0
+ self.tilt_calc.update_position(current_tilt)
+
+ tilt_distance = abs(target - current_tilt)
+ tilt_time = self._tilting_time_close if closing else self._tilting_time_open
+ movement_time = (tilt_distance / 100.0) * tilt_time
+
+ travel_target = None
+ pre_step_delay = 0.0
+ needs_travel_pre_step = False
+ if self._tilt_strategy is not None:
+ current_pos = self.travel_calc.current_position()
+ if current_pos is not None:
+ steps = self._tilt_strategy.plan_move_tilt(
+ target, current_pos, current_tilt
+ )
+ travel_target = extract_coupled_travel(steps)
+ pre_step_delay = calculate_pre_step_delay(
+ steps, self._tilt_strategy, self.tilt_calc, self.travel_calc
+ )
+ if self._tilt_strategy.uses_tilt_motor and has_travel_pre_step(steps):
+ needs_travel_pre_step = True
+
+ self._log(
+ "_async_move_tilt_to_endpoint :: target=%d, tilt_distance=%f%%,"
+ " movement_time=%fs, travel_pos=%s, travel_pre_step=%s",
+ target,
+ tilt_distance,
+ movement_time,
+ travel_target if travel_target is not None else "N/A",
+ needs_travel_pre_step,
+ )
+
+ if needs_travel_pre_step and travel_target is not None:
+ await self._start_travel_pre_step(travel_target, target, command)
+ return
+
+ self._last_command = command
+ if self._tilt_strategy is not None and self._tilt_strategy.uses_tilt_motor:
+ if closing:
+ await self._send_tilt_close()
+ else:
+ await self._send_tilt_open()
+ else:
+ await self._async_handle_command(command)
+ self._begin_movement(
+ target,
+ travel_target,
+ self.tilt_calc,
+ self.travel_calc,
+ self._tilt_startup_delay,
+ pre_step_delay,
+ )
+
+ async def set_position(self, position):
+ """Move cover to a designated position."""
+ self._self_initiated_movement = not self._triggered_externally
+ await self._abandon_active_lifecycle()
+ current = self.travel_calc.current_position()
+ target = position
+ self._log(
+ "set_position :: current: %s, target: %d",
+ current if current is not None else "None",
+ target,
+ )
+
+ if current is None:
+ # Position unknown — assume opposite endpoint so full travel occurs
+ closing = target <= 50
+ command = SERVICE_CLOSE_COVER if closing else SERVICE_OPEN_COVER
+ current = 100 if closing else 0
+ self.travel_calc.update_position(current)
+ elif target < current:
+ command = SERVICE_CLOSE_COVER
+ elif target > current:
+ command = SERVICE_OPEN_COVER
+ else:
+ return
+
+ closing = command == SERVICE_CLOSE_COVER
+
+ should_proceed, is_direction_change = await self._handle_pre_movement_checks(
+ command
+ )
+ if not should_proceed:
+ return
+
+ if is_direction_change and self.travel_calc.is_traveling():
+ self._log("set_position :: stopping active travel movement")
+ self.travel_calc.stop()
+ self.stop_auto_updater()
+ if self._has_tilt_support() and self.tilt_calc.is_traveling():
+ self.tilt_calc.stop()
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ current = self.travel_calc.current_position()
+ if target == current:
+ return
+
+ relay_was_on = self._cancel_delay_task()
+ if relay_was_on:
+ await self._async_handle_command(SERVICE_STOP_COVER)
+
+ travel_time = self._require_travel_time(closing)
+ movement_time = (abs(target - current) / 100.0) * travel_time
+
+ if self._is_movement_too_short(movement_time, target, current, "set_position"):
+ return
+
+ self._last_command = command
+
+ current_tilt = (
+ self.tilt_calc.current_position() if self._tilt_strategy else None
+ )
+ tilt_target, pre_step_delay, started = await self._plan_tilt_for_travel(
+ target, command, current, current_tilt
+ )
+ if started:
+ return
+
+ await self._async_handle_command(command)
+ coupled_calc = self.tilt_calc if tilt_target is not None else None
+ self._begin_movement(
+ target,
+ tilt_target,
+ self.travel_calc,
+ coupled_calc,
+ self._travel_startup_delay,
+ pre_step_delay,
+ )
+
+ async def set_tilt_position(self, position):
+ """Move cover tilt to a designated position."""
+ await self._abandon_active_lifecycle()
+ current = self.tilt_calc.current_position()
+ target = position
+ self._log(
+ "set_tilt_position :: current: %s, target: %d",
+ current if current is not None else "None",
+ target,
+ )
+
+ if current is None:
+ closing = target <= 50
+ command = SERVICE_CLOSE_COVER if closing else SERVICE_OPEN_COVER
+ current = 100 if closing else 0
+ self.tilt_calc.update_position(current)
+ elif target < current:
+ command = SERVICE_CLOSE_COVER
+ elif target > current:
+ command = SERVICE_OPEN_COVER
+ else:
+ return
+
+ closing = command == SERVICE_CLOSE_COVER
+
+ should_proceed, is_direction_change = await self._handle_pre_movement_checks(
+ command
+ )
+ if not should_proceed:
+ return
+
+ if is_direction_change:
+ if self.tilt_calc.is_traveling():
+ self.tilt_calc.stop()
+ if self.travel_calc.is_traveling():
+ self.travel_calc.stop()
+ self.stop_auto_updater()
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ if self._tilt_strategy is not None and self._tilt_strategy.uses_tilt_motor:
+ await self._send_tilt_stop()
+ current = self.tilt_calc.current_position()
+ if target == current:
+ return
+
+ relay_was_on = self._cancel_delay_task()
+ if relay_was_on:
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ if self._tilt_strategy is not None and self._tilt_strategy.uses_tilt_motor:
+ await self._send_tilt_stop()
+
+ if not is_direction_change:
+ self._stop_travel_if_traveling()
+
+ tilt_time = self._tilting_time_close if closing else self._tilting_time_open
+ movement_time = (abs(target - current) / 100.0) * tilt_time
+
+ travel_target = None
+ pre_step_delay = 0.0
+ needs_travel_pre_step = False
+ if self._tilt_strategy is not None:
+ current_pos = self.travel_calc.current_position()
+ if current is not None and current_pos is not None:
+ steps = self._tilt_strategy.plan_move_tilt(target, current_pos, current)
+ travel_target = extract_coupled_travel(steps)
+ pre_step_delay = calculate_pre_step_delay(
+ steps, self._tilt_strategy, self.tilt_calc, self.travel_calc
+ )
+ if self._tilt_strategy.uses_tilt_motor and has_travel_pre_step(steps):
+ needs_travel_pre_step = True
+
+ if self._is_movement_too_short(
+ movement_time, target, current, "set_tilt_position"
+ ):
+ return
+
+ if needs_travel_pre_step and travel_target is not None:
+ await self._start_travel_pre_step(travel_target, target, command)
+ return
+
+ self._last_command = command
+
+ if self._tilt_strategy is not None and self._tilt_strategy.uses_tilt_motor:
+ if closing:
+ await self._send_tilt_close()
+ else:
+ await self._send_tilt_open()
+ else:
+ await self._async_handle_command(command)
+ self._begin_movement(
+ target,
+ travel_target,
+ self.tilt_calc,
+ self.travel_calc,
+ self._tilt_startup_delay,
+ pre_step_delay,
+ )
+
+ async def _plan_tilt_for_travel(
+ self, target: int, command: str, current_pos, current_tilt
+ ) -> tuple[int | None, float, bool]:
+ """Plan tilt coupling for a travel movement.
+
+ Returns (tilt_target, pre_step_delay, started_pre_step).
+ If started_pre_step is True, the caller should return immediately
+ because _start_tilt_pre_step has taken over the movement lifecycle.
+ """
+ tilt_target = None
+ pre_step_delay = 0.0
+ self._tilt_restore_target = None
+
+ if self._tilt_strategy is None:
+ return tilt_target, pre_step_delay, False
+
+ if current_pos is None or current_tilt is None:
+ return tilt_target, pre_step_delay, False
+
+ steps = self._tilt_strategy.plan_move_position(
+ target, current_pos, current_tilt
+ )
+ tilt_target = extract_coupled_tilt(steps)
+ pre_step_delay = calculate_pre_step_delay(
+ steps, self._tilt_strategy, self.tilt_calc, self.travel_calc
+ )
+
+ # Dual motor: tilt to safe position first, then travel
+ if (
+ tilt_target is not None
+ and self._tilt_strategy.uses_tilt_motor
+ and current_tilt != tilt_target
+ ):
+ if target in (0, 100):
+ restore = target
+ elif self._tilt_strategy.allows_tilt_at_position(target):
+ restore = current_tilt
+ else:
+ restore = tilt_target # stay at safe position
+ await self._start_tilt_pre_step(tilt_target, target, command, restore)
+ return tilt_target, pre_step_delay, True
+
+ # Dual motor: pre-step skipped, but still snap tilt to endpoint
+ if (
+ tilt_target is not None
+ and self._tilt_strategy.uses_tilt_motor
+ and target in (0, 100)
+ and current_tilt != target
+ ):
+ self._tilt_restore_target = target
+
+ # Shared motor with restore: save tilt for post-travel restore
+ if (
+ tilt_target is not None
+ and self._tilt_strategy.restores_tilt
+ and not self._tilt_strategy.uses_tilt_motor
+ and target not in (0, 100)
+ ):
+ self._tilt_restore_target = current_tilt
+
+ return tilt_target, pre_step_delay, False
+
+ async def _handle_pre_movement_checks(self, command):
+ """Handle startup delay conflicts and relay delay before a movement.
+
+ Returns (should_proceed, is_direction_change).
+ """
+ is_direction_change = (
+ self._last_command is not None and self._last_command != command
+ )
+
+ # If startup delay active for same direction, don't restart
+ if self._startup_delay_task and not self._startup_delay_task.done():
+ if not is_direction_change:
+ self._log(
+ "_handle_pre_movement_checks :: startup delay active, skipping"
+ )
+ return False, is_direction_change
+ self._log(
+ "_handle_pre_movement_checks :: direction change, cancelling startup delay"
+ )
+ self._cancel_startup_delay_task()
+ await self._async_handle_command(SERVICE_STOP_COVER)
+
+ return True, is_direction_change
+
+ def _is_movement_too_short(self, movement_time, target, current, label):
+ """Check if movement time is below minimum. Returns True if movement should be skipped."""
+ is_to_endpoint = target in (0, 100)
+ if (
+ self._min_movement_time is not None
+ and self._min_movement_time > 0
+ and not is_to_endpoint
+ and movement_time < self._min_movement_time
+ ):
+ _LOGGER.info(
+ "%s :: movement too short (%fs < %fs), ignoring - from %d%% to %d%%",
+ label,
+ movement_time,
+ self._min_movement_time,
+ current,
+ target,
+ )
+ self.async_write_ha_state()
+ return True
+ return False
+
+ def _require_configured(self) -> None:
+ """Raise if the cover is not properly configured."""
+ missing = self._get_missing_configuration()
+ if missing:
+ raise HomeAssistantError(
+ f"Cover not configured: missing {', '.join(missing)}. "
+ "Please configure using the Cover Time Based card."
+ )
+
+ def _require_travel_time(self, closing: bool) -> float:
+ """Return travel time for the given direction, or raise if not configured."""
+ travel_time = self._travel_time_close if closing else self._travel_time_open
+ if travel_time is None:
+ raise HomeAssistantError(
+ "Travel time not configured. Please configure travel times "
+ "using the Cover Time Based card."
+ )
+ return travel_time
+
+ def _are_entities_configured(self) -> bool:
+ """Return True if the required input entities are configured.
+
+ Subclasses override this to check their specific entity IDs.
+ """
+ return True
+
+ def _get_missing_configuration(self) -> list[str]:
+ """Return list of missing configuration items."""
+ missing = []
+ if not self._are_entities_configured():
+ missing.append("input entities")
+ if self._travel_time_close is None and self._travel_time_open is None:
+ missing.append("travel times")
+ return missing
+
+ def _has_tilt_support(self):
+ """Return if cover has tilt support."""
+ return self._tilt_strategy is not None and hasattr(self, "tilt_calc")
+
+ # -----------------------------------------------------------------------
+ # Movement tracking
+ # -----------------------------------------------------------------------
+
+ def _begin_movement(
+ self,
+ target,
+ coupled_target,
+ primary_calc,
+ coupled_calc,
+ startup_delay,
+ pre_step_delay: float = 0.0,
+ ):
+ """Start position tracking on primary and optionally coupled calculator.
+
+ Begins travel on the primary calculator toward `target`, and if a
+ coupled_target is provided, also starts the coupled calculator.
+ Then starts the auto updater. Honors motor startup delay if configured.
+
+ If pre_step_delay > 0, the coupled calculator is a pre-step that must
+ complete before the primary starts (e.g. tilt-before-travel in
+ sequential mode). The primary calculator's start is offset by this
+ delay so its position stays put until the pre-step finishes.
+ """
+
+ def start():
+ primary_calc.start_travel(target, delay=pre_step_delay)
+ if coupled_target is not None:
+ coupled_calc.start_travel(int(coupled_target))
+ self.start_auto_updater()
+
+ self._start_movement(startup_delay, start)
+
+ def _start_movement(self, startup_delay, start_callback):
+ """Start position tracking, optionally after a motor startup delay.
+
+ If startup_delay is set, the relay is already ON but the motor hasn't
+ started moving yet. We wait for the delay, then begin tracking.
+ Otherwise we start tracking immediately.
+ """
+ if startup_delay and startup_delay > 0:
+ self._startup_delay_task = self.hass.async_create_task(
+ self._execute_with_startup_delay(startup_delay, start_callback)
+ )
+ else:
+ start_callback()
+
+ async def _execute_with_startup_delay(self, startup_delay, start_callback):
+ """Wait for motor startup delay, then start position tracking."""
+ self._log(
+ "_execute_with_startup_delay :: waiting %fs before starting position tracking",
+ startup_delay,
+ )
+ try:
+ await sleep(startup_delay)
+ self._log(
+ "_execute_with_startup_delay :: startup delay complete, starting position tracking"
+ )
+ start_callback()
+ self._startup_delay_task = None
+ except asyncio.CancelledError:
+ self._log("_execute_with_startup_delay :: startup delay cancelled")
+ self._startup_delay_task = None
+ raise
+
+ def _cancel_delay_task(self):
+ """Cancel any active delay task."""
+ if self._delay_task is not None and not self._delay_task.done():
+ self._log("_cancel_delay_task :: cancelling active delay task")
+ self._delay_task.cancel()
+ self._delay_task = None
+ return True
+ return False
+
+ def _cancel_startup_delay_task(self):
+ """Cancel any active startup delay task."""
+ if self._startup_delay_task is not None and not self._startup_delay_task.done():
+ self._log(
+ "_cancel_startup_delay_task :: cancelling active startup delay task"
+ )
+ self._startup_delay_task.cancel()
+ self._startup_delay_task = None
+
+ def start_auto_updater(self):
+ """Start the autoupdater to update HASS while cover is moving."""
+ self._log("start_auto_updater")
+ if self._unsubscribe_auto_updater is None:
+ self._log("init _unsubscribe_auto_updater")
+ interval = timedelta(seconds=0.1)
+ self._unsubscribe_auto_updater = async_track_time_interval(
+ self.hass, self.auto_updater_hook, interval
+ )
+
+ @callback
+ def auto_updater_hook(self, _now):
+ """Call for the autoupdater."""
+ self.async_schedule_update_ha_state()
+ if self.position_reached():
+ self._log("auto_updater_hook :: position_reached")
+ self.stop_auto_updater()
+ self.hass.async_create_task(self.auto_stop_if_necessary())
+
+ def stop_auto_updater(self):
+ """Stop the autoupdater."""
+ self._log("stop_auto_updater")
+ if self._unsubscribe_auto_updater is not None:
+ self._unsubscribe_auto_updater()
+ self._unsubscribe_auto_updater = None
+
+ def position_reached(self):
+ """Return if cover has reached its final position."""
+ return self.travel_calc.position_reached() and (
+ not self._has_tilt_support() or self.tilt_calc.position_reached()
+ )
+
+ # -----------------------------------------------------------------------
+ # Movement lifecycle (auto-stop, pre-step, restore)
+ # -----------------------------------------------------------------------
+
+ async def auto_stop_if_necessary(self):
+ """Do auto stop if necessary."""
+ if self.position_reached():
+ self._log(
+ "auto_stop_if_necessary :: position reached (self_initiated=%s)",
+ self._self_initiated_movement,
+ )
+ self.travel_calc.stop()
+ if self._has_tilt_support():
+ self.tilt_calc.stop()
+
+ if not self._self_initiated_movement:
+ # Movement was triggered externally — just stop tracking,
+ # don't send relay commands.
+ self._log(
+ "auto_stop_if_necessary :: external movement, skipping relay stop"
+ )
+ if self._tilt_strategy is not None:
+ self._tilt_strategy.snap_trackers_to_physical(
+ self.travel_calc, self.tilt_calc
+ )
+ self._last_command = None
+ return
+
+ if self._tilt_restore_active:
+ self._log("auto_stop_if_necessary :: tilt restore complete")
+ self._tilt_restore_active = False
+ if self._has_tilt_motor():
+ await self._send_tilt_stop()
+ else:
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ if self._tilt_strategy is not None:
+ self._tilt_strategy.snap_trackers_to_physical(
+ self.travel_calc, self.tilt_calc
+ )
+ self._last_command = None
+ return
+
+ if self._pending_travel_target is not None:
+ # Tilt pre-step complete — start travel phase
+ self._log("auto_stop_if_necessary :: tilt pre-step complete")
+ await self._start_pending_travel()
+ return
+
+ if self._pending_tilt_target is not None:
+ # Travel pre-step complete — start tilt phase
+ self._log("auto_stop_if_necessary :: travel pre-step complete")
+ await self._start_pending_tilt()
+ return
+
+ if self._tilt_strategy is not None:
+ self._tilt_strategy.snap_trackers_to_physical(
+ self.travel_calc, self.tilt_calc
+ )
+
+ if self._tilt_restore_target is not None:
+ # Travel just completed — start tilt restore phase
+ await self._start_tilt_restore()
+ return
+
+ current_travel = self.travel_calc.current_position()
+ if (
+ self._endpoint_runon_time is not None
+ and self._endpoint_runon_time > 0
+ and current_travel in (0, 100)
+ ):
+ self._log(
+ "auto_stop_if_necessary :: at endpoint (position=%d),"
+ " delaying relay stop by %fs",
+ current_travel,
+ self._endpoint_runon_time,
+ )
+ self._delay_task = self.hass.async_create_task(
+ self._delayed_stop(self._endpoint_runon_time)
+ )
+ else:
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ self._last_command = None
+
+ async def _delayed_stop(self, delay):
+ """Stop the relay after a delay."""
+ self._log("_delayed_stop :: waiting %fs before stopping relay", delay)
+ try:
+ await sleep(delay)
+ self._log("_delayed_stop :: delay complete, stopping relay")
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ self._last_command = None
+ self._delay_task = None
+ except asyncio.CancelledError:
+ self._log("_delayed_stop :: delay cancelled")
+ self._delay_task = None
+ raise
+
+ async def _abandon_active_lifecycle(self):
+ """Abandon any active multi-phase tilt lifecycle (pre-step, restore).
+
+ Called at the start of every movement method. If a tilt restore or
+ tilt pre-step is in progress, stops all hardware and calculators.
+ Always clears the pending restore target so it won't fire after
+ the next travel completes.
+ """
+ was_restoring = self._tilt_restore_active
+ was_pre_stepping = (
+ self._pending_travel_target is not None
+ or self._pending_tilt_target is not None
+ )
+
+ # Always clear multi-phase state
+ self._tilt_restore_target = None
+ self._tilt_restore_active = False
+ self._pending_travel_target = None
+ self._pending_travel_command = None
+ self._pending_tilt_target = None
+ self._pending_tilt_command = None
+
+ if not was_restoring and not was_pre_stepping:
+ return
+
+ self._log(
+ "_abandon_active_lifecycle :: abandoning %s",
+ "tilt restore" if was_restoring else "pre-step",
+ )
+
+ self._cancel_startup_delay_task()
+
+ if self.travel_calc.is_traveling():
+ self.travel_calc.stop()
+ if self._has_tilt_support() and self.tilt_calc.is_traveling():
+ self.tilt_calc.stop()
+ self.stop_auto_updater()
+
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ if self._has_tilt_motor() and not self._triggered_externally:
+ await self._send_tilt_stop()
+
+ def _stop_travel_if_traveling(self):
+ """Stop cover movement if it's currently traveling."""
+ if self.travel_calc.is_traveling():
+ self._log("_stop_travel_if_traveling :: stopping cover movement")
+ self.travel_calc.stop()
+ if self._has_tilt_support() and self.tilt_calc.is_traveling():
+ self._log("_stop_travel_if_traveling :: also stopping tilt")
+ self.tilt_calc.stop()
+
+ def _handle_stop(self):
+ """Handle stop"""
+ self._tilt_restore_target = None
+ self._tilt_restore_active = False
+ self._pending_travel_target = None
+ self._pending_travel_command = None
+ self._pending_tilt_target = None
+ self._pending_tilt_command = None
+
+ if self.travel_calc.is_traveling():
+ self._log("_handle_stop :: button stops cover movement")
+ self.travel_calc.stop()
+ self.stop_auto_updater()
+
+ if self._has_tilt_support() and self.tilt_calc.is_traveling():
+ self._log("_handle_stop :: button stops tilt movement")
+ self.tilt_calc.stop()
+ self.stop_auto_updater()
+
+ async def _start_tilt_pre_step(
+ self, tilt_target, travel_target, travel_command, restore_target
+ ):
+ """Move tilt to safe position before travel (dual_motor).
+
+ Sends the tilt motor command and starts tilt_calc. When tilt reaches
+ target, auto_stop_if_necessary will call _start_pending_travel to
+ begin the actual cover travel.
+ """
+ current_tilt = self.tilt_calc.current_position()
+ self._log(
+ "_start_tilt_pre_step :: tilt %s→%d, pending travel→%d (%s)",
+ current_tilt,
+ tilt_target,
+ travel_target,
+ travel_command,
+ )
+ self._pending_travel_target = travel_target
+ self._pending_travel_command = travel_command
+ self._tilt_restore_target = restore_target
+
+ closing_tilt = tilt_target < current_tilt
+ if not self._triggered_externally:
+ if closing_tilt:
+ await self._send_tilt_close()
+ else:
+ await self._send_tilt_open()
+
+ self.tilt_calc.start_travel(tilt_target)
+ self.start_auto_updater()
+
+ async def _start_pending_travel(self):
+ """Start travel after tilt pre-step completes (dual_motor).
+
+ Called by auto_stop_if_necessary when tilt_calc reaches the safe
+ position. Stops the tilt motor, sends the travel command, and starts
+ tracking with travel_calc.
+ """
+ target = self._pending_travel_target
+ command = self._pending_travel_command
+ assert target is not None and command is not None
+ self._pending_travel_target = None
+ self._pending_travel_command = None
+
+ self._log(
+ "_start_pending_travel :: starting travel to %d (%s)",
+ target,
+ command,
+ )
+
+ # Stop tilt motor
+ await self._send_tilt_stop()
+
+ # Send travel command and start tracking
+ await self._async_handle_command(command)
+ self._last_command = command
+ self._begin_movement(
+ target,
+ None,
+ self.travel_calc,
+ None,
+ self._travel_startup_delay,
+ )
+
+ async def _start_travel_pre_step(self, travel_target, tilt_target, tilt_command):
+ """Move cover to allowed position before tilt (dual_motor).
+
+ Sends the travel motor command and starts travel_calc. When travel
+ reaches target, auto_stop_if_necessary will call _start_pending_tilt
+ to begin the actual tilt movement.
+ """
+ current_pos = self.travel_calc.current_position()
+ self._log(
+ "_start_travel_pre_step :: travel %s→%d, pending tilt→%d (%s)",
+ current_pos,
+ travel_target,
+ tilt_target,
+ tilt_command,
+ )
+ self._pending_tilt_target = tilt_target
+ self._pending_tilt_command = tilt_command
+
+ closing = travel_target < current_pos
+ command = SERVICE_CLOSE_COVER if closing else SERVICE_OPEN_COVER
+ self._last_command = command
+ await self._async_handle_command(command)
+
+ self._begin_movement(
+ travel_target,
+ None,
+ self.travel_calc,
+ None,
+ self._travel_startup_delay,
+ )
+
+ async def _start_pending_tilt(self):
+ """Start tilt after travel pre-step completes (dual_motor).
+
+ Called by auto_stop_if_necessary when travel_calc reaches the
+ allowed position. Stops the travel motor, sends the tilt command,
+ and starts tracking with tilt_calc.
+ """
+ target = self._pending_tilt_target
+ command = self._pending_tilt_command
+ assert target is not None and command is not None
+ self._pending_tilt_target = None
+ self._pending_tilt_command = None
+
+ self._log(
+ "_start_pending_tilt :: starting tilt to %d (%s)",
+ target,
+ command,
+ )
+
+ # Stop travel motor
+ await self._async_handle_command(SERVICE_STOP_COVER)
+
+ # Send tilt command and start tracking
+ closing_tilt = command == SERVICE_CLOSE_COVER
+ if closing_tilt:
+ await self._send_tilt_close()
+ else:
+ await self._send_tilt_open()
+ self._last_command = command
+ self._begin_movement(
+ target,
+ None,
+ self.tilt_calc,
+ None,
+ self._tilt_startup_delay,
+ )
+
+ async def _start_tilt_restore(self):
+ """Restore tilt to its pre-movement position.
+
+ For dual_motor: stops travel motor, starts tilt motor.
+ For shared motor (inline): reverses main motor direction.
+ """
+ restore_target = self._tilt_restore_target
+ self._tilt_restore_target = None
+ if restore_target is None:
+ return
+
+ current_tilt = self.tilt_calc.current_position()
+ if current_tilt is None or current_tilt == restore_target:
+ self._log(
+ "_start_tilt_restore :: no restore needed (current=%s, target=%s)",
+ current_tilt,
+ restore_target,
+ )
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ self._last_command = None
+ return
+
+ self._log(
+ "_start_tilt_restore :: restoring tilt from %d%% to %d%%",
+ current_tilt,
+ restore_target,
+ )
+
+ closing = restore_target < current_tilt
+
+ if self._tilt_strategy.uses_tilt_motor:
+ # Dual motor: stop travel, start tilt motor
+ await self._async_handle_command(SERVICE_STOP_COVER)
+ if closing:
+ await self._send_tilt_close()
+ else:
+ await self._send_tilt_open()
+ else:
+ # Shared motor (inline): reverse main motor direction
+ command = SERVICE_CLOSE_COVER if closing else SERVICE_OPEN_COVER
+ await self._async_handle_command(command)
+
+ self.tilt_calc.start_travel(restore_target)
+ self._tilt_restore_active = True
+ self.start_auto_updater()
+
+ # -----------------------------------------------------------------------
+ # Relay command dispatch
+ # -----------------------------------------------------------------------
+
+ async def _async_handle_command(self, command, *_args):
+ cmd = command
+ if command == SERVICE_CLOSE_COVER:
+ cmd = "CLOSE"
+ self._state = False
+ self._last_command = command
+ if not self._triggered_externally:
+ await self._send_close()
+ elif command == SERVICE_OPEN_COVER:
+ cmd = "OPEN"
+ self._state = True
+ self._last_command = command
+ if not self._triggered_externally:
+ await self._send_open()
+ elif command == SERVICE_STOP_COVER:
+ cmd = "STOP"
+ self._state = True
+ if not self._triggered_externally:
+ await self._send_stop()
+
+ self._log("_async_handle_command :: %s", cmd)
+ self.async_write_ha_state()
+
+ @abstractmethod
+ async def _send_open(self) -> None:
+ """Send the open command to the underlying device."""
+
+ @abstractmethod
+ async def _send_close(self) -> None:
+ """Send the close command to the underlying device."""
+
+ @abstractmethod
+ async def _send_stop(self) -> None:
+ """Send the stop command to the underlying device."""
+
+ async def _raw_direction_command(self, command: str) -> None:
+ """Execute a raw direction command (for calibration screen buttons).
+
+ Sets _last_command / _last_tilt_direction and sends relay commands.
+ Override in subclasses that need stop-before-direction-change
+ (e.g. toggle mode where opposite-direction = stop, not reverse).
+ """
+ if command == "open":
+ self._last_command = SERVICE_OPEN_COVER
+ await self._send_open()
+ elif command == "close":
+ self._last_command = SERVICE_CLOSE_COVER
+ await self._send_close()
+ elif command == "stop":
+ await self._send_stop()
+ self._last_command = None
+ elif command == "tilt_open":
+ await self._send_tilt_open()
+ elif command == "tilt_close":
+ await self._send_tilt_close()
+ elif command == "tilt_stop":
+ await self._send_tilt_stop()
+
+ # -----------------------------------------------------------------------
+ # Tilt motor relay commands (dual_motor only)
+ # -----------------------------------------------------------------------
+
+ def _has_tilt_motor(self) -> bool:
+ """Return True if a dedicated tilt motor is configured (dual_motor mode)."""
+ return (
+ self._tilt_strategy is not None
+ and self._tilt_strategy.uses_tilt_motor
+ and bool(self._tilt_open_switch_id and self._tilt_close_switch_id)
+ )
+
+ async def _send_tilt_open(self) -> None:
+ """Send open to the tilt motor (bypasses position tracker)."""
+ if self._switch_is_on(self._tilt_close_switch_id):
+ self._mark_switch_pending(self._tilt_close_switch_id, 1)
+ self._mark_switch_pending(self._tilt_open_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+
+ async def _send_tilt_close(self) -> None:
+ """Send close to the tilt motor (bypasses position tracker)."""
+ if self._switch_is_on(self._tilt_open_switch_id):
+ self._mark_switch_pending(self._tilt_open_switch_id, 1)
+ self._mark_switch_pending(self._tilt_close_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+
+ async def _send_tilt_stop(self) -> None:
+ """Send stop to the tilt motor (bypasses position tracker)."""
+ if self._switch_is_on(self._tilt_open_switch_id):
+ self._mark_switch_pending(self._tilt_open_switch_id, 1)
+ if self._switch_is_on(self._tilt_close_switch_id):
+ self._mark_switch_pending(self._tilt_close_switch_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ if self._tilt_stop_switch_id:
+ self._mark_switch_pending(self._tilt_stop_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_stop_switch_id},
+ False,
+ )
+
+ # -----------------------------------------------------------------------
+ # Switch echo filtering
+ # -----------------------------------------------------------------------
+
+ def _switch_is_on(self, entity_id) -> bool:
+ """Check if a switch entity is currently on."""
+ state = self.hass.states.get(entity_id)
+ return state is not None and state.state == "on"
+
+ def _mark_switch_pending(self, entity_id, expected_transitions):
+ """Mark a switch as having pending echo transitions to ignore."""
+ self._pending_switch[entity_id] = (
+ self._pending_switch.get(entity_id, 0) + expected_transitions
+ )
+ self._log(
+ "_mark_switch_pending :: %s pending=%d",
+ entity_id,
+ self._pending_switch[entity_id],
+ )
+
+ # Cancel any existing timeout for this switch
+ if entity_id in self._pending_switch_timers:
+ self._pending_switch_timers[entity_id]()
+
+ # Safety timeout: clear pending after 5 seconds
+ @callback
+ def _clear_pending(_now):
+ if entity_id in self._pending_switch:
+ self._log("_mark_switch_pending :: timeout clearing %s", entity_id)
+ del self._pending_switch[entity_id]
+ self._pending_switch_timers.pop(entity_id, None)
+
+ self._pending_switch_timers[entity_id] = async_call_later(
+ self.hass, 5, _clear_pending
+ )
+
+ async def _async_switch_state_changed(self, event):
+ """Handle state changes on monitored switch entities."""
+ entity_id = event.data.get("entity_id")
+ new_state = event.data.get("new_state")
+ old_state = event.data.get("old_state")
+
+ if new_state is None or old_state is None:
+ return
+
+ new_val = new_state.state
+ old_val = old_state.state
+
+ self._log(
+ "_async_switch_state_changed :: %s: %s -> %s (pending=%s)",
+ entity_id,
+ old_val,
+ new_val,
+ self._pending_switch.get(entity_id, 0),
+ )
+
+ # Skip attribute-only updates (same state string, only attributes
+ # changed). Must run before echo filtering so that position updates
+ # on a moving wrapped cover don't consume pending echo counts.
+ if old_val == new_val:
+ return
+
+ # Echo filtering: if this switch has pending echoes, decrement and skip
+ if self._pending_switch.get(entity_id, 0) > 0:
+ self._pending_switch[entity_id] -= 1
+ if self._pending_switch[entity_id] <= 0:
+ del self._pending_switch[entity_id]
+ # Cancel the safety timeout
+ timer = self._pending_switch_timers.pop(entity_id, None)
+ if timer:
+ timer()
+ self._log(
+ "_async_switch_state_changed :: echo filtered, remaining=%s",
+ self._pending_switch.get(entity_id, 0),
+ )
+ return
+
+ # Skip external state handling during calibration — calibration drives
+ # the motors directly and must not be interfered with.
+ if self._calibration is not None:
+ self._log("_async_switch_state_changed :: calibration active, skipping")
+ return
+
+ # External state change (physical button / remote / HA button).
+ # Delegate to mode-specific handlers which start/stop position
+ # tracking normally via async_open_cover / async_close_cover etc.
+ is_tilt = entity_id in (
+ self._tilt_open_switch_id,
+ self._tilt_close_switch_id,
+ self._tilt_stop_switch_id,
+ )
+ self._triggered_externally = True
+ try:
+ if is_tilt:
+ await self._handle_external_tilt_state_change(
+ entity_id, old_val, new_val
+ )
+ else:
+ await self._handle_external_state_change(entity_id, old_val, new_val)
+ finally:
+ self._triggered_externally = False
+
+ # -----------------------------------------------------------------------
+ # External state change handlers
+ # -----------------------------------------------------------------------
+
+ async def _handle_external_tilt_state_change(self, entity_id, old_val, new_val):
+ """Handle external state change on tilt switches (dual_motor).
+
+ Tilt switches use pulse-mode behavior. The ON signal (rising edge)
+ is the button press. The OFF transition is just button release.
+ """
+ if new_val != "on":
+ return
+
+ if entity_id == self._tilt_open_switch_id:
+ self._log(
+ "_handle_external_tilt_state_change :: external tilt open pulse detected"
+ )
+ await self.async_open_cover_tilt()
+ elif entity_id == self._tilt_close_switch_id:
+ self._log(
+ "_handle_external_tilt_state_change :: external tilt close pulse detected"
+ )
+ await self.async_close_cover_tilt()
+ elif entity_id == self._tilt_stop_switch_id:
+ self._log(
+ "_handle_external_tilt_state_change :: external tilt stop pulse detected"
+ )
+ await self.async_stop_cover()
+
+ async def _handle_external_state_change(self, entity_id, old_val, new_val):
+ """Handle external state change. Override in subclasses for mode-specific behavior."""
diff --git a/custom_components/cover_time_based/cover_calibration.py b/custom_components/cover_time_based/cover_calibration.py
new file mode 100644
index 0000000..0dc9dc8
--- /dev/null
+++ b/custom_components/cover_time_based/cover_calibration.py
@@ -0,0 +1,439 @@
+"""Calibration mixin for time-based cover entities."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from asyncio import sleep
+from typing import TYPE_CHECKING, Any
+
+from homeassistant.const import (
+ SERVICE_CLOSE_COVER,
+ SERVICE_OPEN_COVER,
+)
+from homeassistant.exceptions import HomeAssistantError
+
+from .calibration import CalibrationState
+
+if TYPE_CHECKING:
+ from homeassistant.core import HomeAssistant
+
+ from .travel_calculator import TravelCalculator
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CalibrationMixin:
+ """Mixin providing calibration functionality for CoverTimeBased."""
+
+ if TYPE_CHECKING:
+ hass: HomeAssistant
+ _calibration: CalibrationState | None
+ _tilt_strategy: Any
+ _travel_time_close: float | None
+ _travel_time_open: float | None
+ _tilting_time_close: float | None
+ _tilting_time_open: float | None
+ current_cover_position: int | None
+ current_cover_tilt_position: int | None
+ travel_calc: TravelCalculator
+ tilt_calc: TravelCalculator
+
+ async def _async_handle_command(self, _command: str, *_args: Any) -> None: ...
+ async def _send_stop(self) -> None: ...
+ def async_write_ha_state(self) -> None: ...
+
+ async def start_calibration(self, **kwargs):
+ """Start a calibration test for the given attribute."""
+ attribute = kwargs["attribute"]
+ timeout = kwargs["timeout"]
+ direction = kwargs.get("direction") # "open", "close", or None (auto)
+
+ if self._calibration is not None:
+ raise HomeAssistantError("Calibration already in progress")
+
+ # Validate BEFORE creating state
+ if attribute in ("tilt_time_close", "tilt_time_open"):
+ if (
+ self._tilt_strategy is not None
+ and not self._tilt_strategy.can_calibrate_tilt()
+ ):
+ raise HomeAssistantError(
+ "Tilt time calibration not available for this tilt mode"
+ )
+
+ if attribute == "travel_startup_delay":
+ if not (self._travel_time_close or self._travel_time_open):
+ raise HomeAssistantError(
+ "Travel time must be configured before calibrating startup delay"
+ )
+
+ if attribute == "tilt_startup_delay":
+ if not (self._tilting_time_close or self._tilting_time_open):
+ raise HomeAssistantError(
+ "Tilt time must be configured before calibrating startup delay"
+ )
+
+ # Create state only after validation passes
+ self._calibration = CalibrationState(attribute=attribute, timeout=timeout)
+ self._calibration.timeout_task = self.hass.async_create_task(
+ self._calibration_timeout()
+ )
+
+ # Dispatch to appropriate test type
+ if attribute in (
+ "travel_time_close",
+ "travel_time_open",
+ "tilt_time_close",
+ "tilt_time_open",
+ ):
+ await self._start_simple_time_test(attribute, direction)
+ elif attribute in ("travel_startup_delay", "tilt_startup_delay"):
+ await self._start_overhead_test(attribute, direction)
+ elif attribute == "min_movement_time":
+ self._calibration.move_command = self._resolve_direction(
+ direction, self.current_cover_position
+ )
+ self._calibration.automation_task = self.hass.async_create_task(
+ self._run_min_movement_pulses()
+ )
+
+ self.async_write_ha_state()
+
+ @staticmethod
+ def _resolve_direction(direction, position):
+ """Resolve move command from explicit direction or current position."""
+ if direction == "close":
+ return SERVICE_CLOSE_COVER
+ if direction == "open":
+ return SERVICE_OPEN_COVER
+ # Auto-detect from position
+ if position is not None and position < 50:
+ return SERVICE_OPEN_COVER
+ return SERVICE_CLOSE_COVER
+
+ async def _start_simple_time_test(self, attribute, direction):
+ """Start a simple travel/tilt time test by moving the cover."""
+ assert self._calibration is not None
+ if direction:
+ self._calibration.move_command = self._resolve_direction(direction, None)
+ elif "close" in attribute:
+ self._calibration.move_command = SERVICE_CLOSE_COVER
+ else:
+ self._calibration.move_command = SERVICE_OPEN_COVER
+ await self._async_handle_command(self._calibration.move_command)
+
+ async def _start_overhead_test(self, attribute, direction):
+ """Start automated step test for motor overhead."""
+ assert self._calibration is not None
+ from .calibration import (
+ CALIBRATION_OVERHEAD_STEPS,
+ CALIBRATION_TILT_OVERHEAD_STEPS,
+ )
+
+ is_tilt = "tilt" in attribute
+
+ if not is_tilt:
+ position = self.current_cover_position
+ move_command = self._resolve_direction(direction, position)
+ if move_command == SERVICE_OPEN_COVER:
+ travel_time = self._travel_time_open or self._travel_time_close
+ else:
+ travel_time = self._travel_time_close or self._travel_time_open
+ num_steps = CALIBRATION_OVERHEAD_STEPS
+ # Zero startup delay during test so tracker doesn't compensate
+ self._calibration.saved_startup_delay = self._travel_startup_delay
+ self._travel_startup_delay = None
+ else:
+ position = self.current_cover_tilt_position
+ move_command = self._resolve_direction(direction, position)
+ if move_command == SERVICE_OPEN_COVER:
+ travel_time = self._tilting_time_open or self._tilting_time_close
+ else:
+ travel_time = self._tilting_time_close or self._tilting_time_open
+ num_steps = CALIBRATION_TILT_OVERHEAD_STEPS
+ # Zero startup delay during test so tracker doesn't compensate
+ self._calibration.saved_startup_delay = self._tilt_startup_delay
+ self._tilt_startup_delay = None
+
+ assert travel_time is not None
+ _LOGGER.debug(
+ "overhead test: position=%s, direction=%s, travel_time=%.2f",
+ position,
+ move_command,
+ travel_time,
+ )
+
+ total_divisions = num_steps + 2
+ step_pct = 100 // total_divisions
+ step_duration = travel_time * step_pct / 100
+ self._calibration.step_duration = step_duration
+ self._calibration.move_command = move_command
+
+ self._calibration.automation_task = self.hass.async_create_task(
+ self._run_overhead_steps(step_duration, num_steps, step_pct, is_tilt)
+ )
+
+ async def _run_overhead_steps(self, _step_duration, num_steps, step_pct, is_tilt):
+ """Execute stepped moves then one continuous move for overhead test.
+
+ Phase 1: num_steps stepped moves using the travel calculator's
+ position tracking (same timing as normal operation). After each
+ step, force-set position to compensate for motor startup delay.
+ Phase 2: Continuous move for the remaining distance.
+ The user calls stop_calibration when the cover reaches the endpoint.
+ """
+ assert self._calibration is not None
+ from .calibration import CALIBRATION_STEP_PAUSE
+
+ move_command = self._calibration.move_command
+ assert move_command is not None
+ closing = move_command == SERVICE_CLOSE_COVER
+ calc = self.tilt_calc if is_tilt else self.travel_calc
+
+ try:
+ # Phase 1: Stepped moves using travel calculator timing
+ for i in range(num_steps):
+ pct = (i + 1) * step_pct
+ target = (100 - pct) if closing else pct
+
+ self._calibration.step_count = i + 1
+ self.async_write_ha_state()
+
+ _LOGGER.debug(
+ "overhead step %d/%d: target=%d%%",
+ i + 1,
+ num_steps,
+ target,
+ )
+ calc.start_travel(target)
+ await self._async_handle_command(move_command)
+
+ # Wait for travel calculator to say position reached
+ while calc.current_position() != target:
+ await sleep(0.05)
+
+ await self._send_stop()
+ calc.stop()
+
+ # Force position — motor fell short due to startup delay
+ calc.set_position(target)
+
+ if i < num_steps - 1:
+ await sleep(CALIBRATION_STEP_PAUSE)
+
+ # Pause before continuous phase
+ await sleep(CALIBRATION_STEP_PAUSE)
+
+ # Phase 2: Continuous move for remaining distance
+ _LOGGER.debug(
+ "overhead test: starting continuous phase for remaining distance"
+ )
+ self._calibration.final_step = True
+ self.async_write_ha_state()
+ self._calibration.continuous_start = time.monotonic()
+ await self._async_handle_command(move_command)
+
+ # Wait indefinitely until user calls stop_calibration
+ while True:
+ await sleep(1.0)
+ except asyncio.CancelledError:
+ pass
+
+ async def _run_min_movement_pulses(self):
+ """Send increasingly longer pulses until user sees movement."""
+ assert self._calibration is not None
+ assert self._calibration.move_command is not None
+ from .calibration import (
+ CALIBRATION_MIN_MOVEMENT_START,
+ CALIBRATION_MIN_MOVEMENT_INCREMENT,
+ CALIBRATION_MIN_MOVEMENT_INITIAL_PAUSE,
+ CALIBRATION_STEP_PAUSE,
+ )
+
+ move_command = self._calibration.move_command
+ pulse_duration = CALIBRATION_MIN_MOVEMENT_START
+
+ try:
+ # Give user time to prepare stop_calibration call
+ _LOGGER.debug(
+ "min_movement: waiting %.0fs before first pulse",
+ CALIBRATION_MIN_MOVEMENT_INITIAL_PAUSE,
+ )
+ await sleep(CALIBRATION_MIN_MOVEMENT_INITIAL_PAUSE)
+
+ while True:
+ self._calibration.last_pulse_duration = pulse_duration
+ self._calibration.step_count += 1
+
+ step_start = time.monotonic()
+ await self._async_handle_command(move_command)
+ elapsed = time.monotonic() - step_start
+ await sleep(max(0, pulse_duration - elapsed))
+ await self._send_stop()
+ self.async_write_ha_state()
+
+ await sleep(CALIBRATION_STEP_PAUSE)
+ pulse_duration += CALIBRATION_MIN_MOVEMENT_INCREMENT
+ except asyncio.CancelledError:
+ pass
+
+ async def _calibration_timeout(self):
+ """Handle calibration timeout."""
+ assert self._calibration is not None
+ try:
+ await sleep(self._calibration.timeout)
+ _LOGGER.warning(
+ "Calibration timed out after %fs for attribute '%s'",
+ self._calibration.timeout,
+ self._calibration.attribute,
+ )
+ # Cancel automation task if running
+ if (
+ self._calibration.automation_task is not None
+ and not self._calibration.automation_task.done()
+ ):
+ self._calibration.automation_task.cancel()
+ await self._send_stop()
+ self._calibration = None
+ self.async_write_ha_state()
+ except asyncio.CancelledError:
+ _LOGGER.debug("_calibration_timeout :: cancelled")
+
+ async def stop_calibration(self, **kwargs):
+ """Stop an in-progress calibration test."""
+ if self._calibration is None:
+ raise HomeAssistantError("No calibration in progress")
+
+ cancel = kwargs.get("cancel", False)
+
+ # Cancel timeout task
+ if (
+ self._calibration.timeout_task is not None
+ and not self._calibration.timeout_task.done()
+ ):
+ self._calibration.timeout_task.cancel()
+
+ # Cancel automation task
+ if (
+ self._calibration.automation_task is not None
+ and not self._calibration.automation_task.done()
+ ):
+ self._calibration.automation_task.cancel()
+
+ # Stop the motor
+ await self._send_stop()
+
+ result = {}
+ if not cancel:
+ value = self._calculate_calibration_result()
+ result["attribute"] = self._calibration.attribute
+ result["value"] = value
+
+ # For successful completion, update the tracked position to
+ # reflect where the cover ended up (at an endpoint).
+ self._set_position_after_calibration(self._calibration)
+
+ # Restore startup delay that was zeroed during overhead test
+ if self._calibration.saved_startup_delay is not None:
+ attr = self._calibration.attribute
+ if "tilt" in attr:
+ self._tilt_startup_delay = self._calibration.saved_startup_delay
+ else:
+ self._travel_startup_delay = self._calibration.saved_startup_delay
+
+ self._calibration = None
+ self.async_write_ha_state()
+ return result
+
+ def _set_position_after_calibration(self, calibration):
+ """Update tracked position after successful calibration.
+
+ For travel/tilt time and startup delay tests, the cover has
+ reached an endpoint. For min_movement_time the cover only nudged
+ slightly so we leave the tracked position unchanged.
+ """
+ move_command = calibration.move_command
+ if not move_command or calibration.attribute == "min_movement_time":
+ return
+
+ is_tilt = "tilt" in calibration.attribute
+ if is_tilt and not hasattr(self, "tilt_calc"):
+ return
+ calc = self.tilt_calc if is_tilt else self.travel_calc
+
+ # Cover ended at the endpoint in the direction of travel
+ endpoint = 0 if move_command == SERVICE_CLOSE_COVER else 100
+
+ _LOGGER.debug(
+ "calibration: resetting %s position to %d",
+ "tilt" if is_tilt else "travel",
+ endpoint,
+ )
+ calc.set_position(endpoint)
+
+ def _calculate_calibration_result(self):
+ """Calculate the calibration result based on attribute type."""
+ assert self._calibration is not None
+ attribute = self._calibration.attribute
+
+ if "travel_time" in attribute or "tilt_time" in attribute:
+ elapsed = time.monotonic() - self._calibration.started_at
+ return round(elapsed, 1)
+
+ if attribute in ("travel_startup_delay", "tilt_startup_delay"):
+ closing = self._calibration.move_command == SERVICE_CLOSE_COVER
+ if attribute == "travel_startup_delay":
+ if closing:
+ total_time = self._travel_time_close or self._travel_time_open
+ else:
+ total_time = self._travel_time_open or self._travel_time_close
+ else:
+ if closing:
+ total_time = self._tilting_time_close or self._tilting_time_open
+ else:
+ total_time = self._tilting_time_open or self._tilting_time_close
+
+ if not total_time:
+ _LOGGER.warning(
+ "Startup delay calibration requires travel/tilt time to be set first"
+ )
+ return 0.0
+ step_count = self._calibration.step_count
+ continuous_start = self._calibration.continuous_start
+ if continuous_start is None:
+ _LOGGER.warning(
+ "Overhead calibration stopped before continuous phase started"
+ )
+ return 0.0
+ continuous_time = time.monotonic() - continuous_start
+ # Subtract pulse overhead from continuous phase start for
+ # pulse/toggle modes (the ON command includes a relay pulse
+ # that doesn't contribute to motor travel time).
+ pulse_time = getattr(self, "_pulse_time", None)
+ if pulse_time:
+ continuous_time -= pulse_time
+ # Each step covers 1/10 of travel; remaining depends on step count
+ expected_remaining = (1.0 - step_count / 10.0) * total_time
+ overhead = (continuous_time - expected_remaining) / step_count
+ _LOGGER.debug(
+ "overhead calculation: total_time=%.2f, step_count=%d, "
+ "continuous_time=%.2f, expected_remaining=%.2f, overhead=%.4f",
+ total_time,
+ step_count,
+ continuous_time,
+ expected_remaining,
+ overhead,
+ )
+ return round(max(0, overhead), 2)
+
+ if attribute == "min_movement_time":
+ if self._calibration.last_pulse_duration is None:
+ _LOGGER.warning(
+ "Min movement calibration stopped before any pulses sent"
+ )
+ return 0.0
+ return round(self._calibration.last_pulse_duration, 2)
+
+ raise ValueError(f"Unexpected calibration attribute: {attribute}")
diff --git a/custom_components/cover_time_based/cover_pulse_mode.py b/custom_components/cover_time_based/cover_pulse_mode.py
new file mode 100644
index 0000000..adb7002
--- /dev/null
+++ b/custom_components/cover_time_based/cover_pulse_mode.py
@@ -0,0 +1,198 @@
+"""Momentary pulse mode cover."""
+
+import asyncio
+from asyncio import sleep
+
+from .cover_switch import SwitchCoverTimeBased
+
+
+class PulseModeCover(SwitchCoverTimeBased):
+ """Cover controlled by momentary pulse relays (pulse mode).
+
+ In pulse mode, the direction switch is turned ON for a short pulse
+ (pulse_time seconds) then turned OFF. The motor controller latches
+ on the ON edge — the OFF is just relay cleanup.
+
+ The send methods return immediately after the ON edge so that position
+ tracking starts from the moment the motor begins moving. The pulse
+ completion (sleep + turn_off) runs in the background.
+ """
+
+ def __init__(self, pulse_time, **kwargs):
+ super().__init__(**kwargs)
+ self._pulse_time = pulse_time
+
+ def _get_missing_configuration(self) -> list[str]:
+ """Return list of missing configuration items."""
+ missing = super()._get_missing_configuration()
+ if not self._stop_switch_entity_id:
+ missing.append("stop switch")
+ if self._has_tilt_motor() and not self._tilt_stop_switch_id:
+ missing.append("tilt stop switch")
+ return missing
+
+ async def _complete_pulse(self, entity_id):
+ """Complete a relay pulse by turning OFF after pulse_time."""
+ try:
+ await sleep(self._pulse_time)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": entity_id},
+ False,
+ )
+ except asyncio.CancelledError:
+ pass
+
+ async def _send_open(self) -> None:
+ if self._switch_is_on(self._close_switch_entity_id):
+ self._mark_switch_pending(self._close_switch_entity_id, 1)
+ self._mark_switch_pending(self._open_switch_entity_id, 2)
+ if self._stop_switch_entity_id is not None:
+ if self._switch_is_on(self._stop_switch_entity_id):
+ self._mark_switch_pending(self._stop_switch_entity_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+ if self._stop_switch_entity_id is not None:
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._stop_switch_entity_id},
+ False,
+ )
+ # Motor controller latches on ON edge; complete pulse in background
+ self.hass.async_create_task(self._complete_pulse(self._open_switch_entity_id))
+
+ async def _send_close(self) -> None:
+ if self._switch_is_on(self._open_switch_entity_id):
+ self._mark_switch_pending(self._open_switch_entity_id, 1)
+ self._mark_switch_pending(self._close_switch_entity_id, 2)
+ if self._stop_switch_entity_id is not None:
+ if self._switch_is_on(self._stop_switch_entity_id):
+ self._mark_switch_pending(self._stop_switch_entity_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ if self._stop_switch_entity_id is not None:
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._stop_switch_entity_id},
+ False,
+ )
+ # Motor controller latches on ON edge; complete pulse in background
+ self.hass.async_create_task(self._complete_pulse(self._close_switch_entity_id))
+
+ async def _send_stop(self) -> None:
+ if self._switch_is_on(self._close_switch_entity_id):
+ self._mark_switch_pending(self._close_switch_entity_id, 1)
+ if self._switch_is_on(self._open_switch_entity_id):
+ self._mark_switch_pending(self._open_switch_entity_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+ if self._stop_switch_entity_id is not None:
+ self._mark_switch_pending(self._stop_switch_entity_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._stop_switch_entity_id},
+ False,
+ )
+ # Motor stops on ON edge; complete pulse in background
+ self.hass.async_create_task(
+ self._complete_pulse(self._stop_switch_entity_id)
+ )
+
+ # --- Tilt motor relay commands ---
+
+ async def _send_tilt_open(self) -> None:
+ if self._switch_is_on(self._tilt_close_switch_id):
+ self._mark_switch_pending(self._tilt_close_switch_id, 1)
+ self._mark_switch_pending(self._tilt_open_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ self.hass.async_create_task(self._complete_pulse(self._tilt_open_switch_id))
+
+ async def _send_tilt_close(self) -> None:
+ if self._switch_is_on(self._tilt_open_switch_id):
+ self._mark_switch_pending(self._tilt_open_switch_id, 1)
+ self._mark_switch_pending(self._tilt_close_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ self.hass.async_create_task(self._complete_pulse(self._tilt_close_switch_id))
+
+ async def _send_tilt_stop(self) -> None:
+ if self._switch_is_on(self._tilt_open_switch_id):
+ self._mark_switch_pending(self._tilt_open_switch_id, 1)
+ if self._switch_is_on(self._tilt_close_switch_id):
+ self._mark_switch_pending(self._tilt_close_switch_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ if self._tilt_stop_switch_id:
+ self._mark_switch_pending(self._tilt_stop_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_stop_switch_id},
+ False,
+ )
+ self.hass.async_create_task(self._complete_pulse(self._tilt_stop_switch_id))
diff --git a/custom_components/cover_time_based/cover_switch.py b/custom_components/cover_time_based/cover_switch.py
new file mode 100644
index 0000000..4bf5e70
--- /dev/null
+++ b/custom_components/cover_time_based/cover_switch.py
@@ -0,0 +1,48 @@
+"""Abstract base for covers controlled via switch entities."""
+
+import logging
+
+from .cover_base import CoverTimeBased
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class SwitchCoverTimeBased(CoverTimeBased):
+ """Abstract base for covers controlled via switch entities."""
+
+ def __init__(
+ self,
+ open_switch_entity_id,
+ close_switch_entity_id,
+ stop_switch_entity_id=None,
+ **kwargs,
+ ):
+ super().__init__(**kwargs)
+ self._open_switch_entity_id = open_switch_entity_id
+ self._close_switch_entity_id = close_switch_entity_id
+ self._stop_switch_entity_id = stop_switch_entity_id
+
+ def _are_entities_configured(self) -> bool:
+ """Return True if open and close switch entities are configured."""
+ return bool(self._open_switch_entity_id and self._close_switch_entity_id)
+
+ async def _handle_external_state_change(self, entity_id, old_val, new_val):
+ """Handle external state change in pulse mode.
+
+ In pulse mode, the ON signal is the button press (rising edge).
+ The OFF transition is just the button release and is ignored.
+
+ Toggle mode overrides this with its own edge detection.
+ """
+ if new_val != "on":
+ return
+
+ if entity_id == self._open_switch_entity_id:
+ self._log("_handle_external_state_change :: external open pulse detected")
+ await self.async_open_cover()
+ elif entity_id == self._close_switch_entity_id:
+ self._log("_handle_external_state_change :: external close pulse detected")
+ await self.async_close_cover()
+ elif entity_id == self._stop_switch_entity_id:
+ self._log("_handle_external_state_change :: external stop pulse detected")
+ await self.async_stop_cover()
diff --git a/custom_components/cover_time_based/cover_switch_mode.py b/custom_components/cover_time_based/cover_switch_mode.py
new file mode 100644
index 0000000..2dea306
--- /dev/null
+++ b/custom_components/cover_time_based/cover_switch_mode.py
@@ -0,0 +1,129 @@
+"""Latching relay (switch) mode cover."""
+
+import logging
+
+from .cover_switch import SwitchCoverTimeBased
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class SwitchModeCover(SwitchCoverTimeBased):
+ """Cover controlled by latching relays (switch mode).
+
+ In switch mode, the direction switch stays ON for the entire duration
+ of the movement. _send_stop turns both direction switches OFF.
+ """
+
+ async def _handle_external_state_change(self, entity_id, old_val, new_val):
+ """Handle external state change in switch (latching) mode.
+
+ ON = relay is driving the motor → start tracking.
+ OFF = relay released → stop tracking.
+ """
+ if entity_id == self._open_switch_entity_id:
+ if new_val == "on":
+ _LOGGER.debug("_handle_external_state_change :: external open detected")
+ await self.async_open_cover()
+ elif new_val == "off":
+ _LOGGER.debug(
+ "_handle_external_state_change :: external open switch off, stopping"
+ )
+ await self.async_stop_cover()
+ elif entity_id == self._close_switch_entity_id:
+ if new_val == "on":
+ _LOGGER.debug(
+ "_handle_external_state_change :: external close detected"
+ )
+ await self.async_close_cover()
+ elif new_val == "off":
+ _LOGGER.debug(
+ "_handle_external_state_change :: external close switch off, stopping"
+ )
+ await self.async_stop_cover()
+
+ async def _handle_external_tilt_state_change(self, entity_id, old_val, new_val):
+ """Handle external tilt state change in switch (latching) mode.
+
+ ON = tilt relay is driving the motor → start tilt tracking.
+ OFF = tilt relay released → stop tilt tracking.
+ """
+ if entity_id == self._tilt_open_switch_id:
+ if new_val == "on":
+ _LOGGER.debug(
+ "_handle_external_tilt_state_change :: external tilt open detected"
+ )
+ await self.async_open_cover_tilt()
+ elif new_val == "off":
+ _LOGGER.debug(
+ "_handle_external_tilt_state_change :: external tilt open off, stopping"
+ )
+ await self.async_stop_cover()
+ elif entity_id == self._tilt_close_switch_id:
+ if new_val == "on":
+ _LOGGER.debug(
+ "_handle_external_tilt_state_change :: external tilt close detected"
+ )
+ await self.async_close_cover_tilt()
+ elif new_val == "off":
+ _LOGGER.debug(
+ "_handle_external_tilt_state_change :: external tilt close off, stopping"
+ )
+ await self.async_stop_cover()
+ elif entity_id == self._tilt_stop_switch_id:
+ if new_val == "on":
+ _LOGGER.debug(
+ "_handle_external_tilt_state_change :: external tilt stop detected"
+ )
+ await self.async_stop_cover()
+
+ async def _send_open(self) -> None:
+ if self._switch_is_on(self._close_switch_entity_id):
+ self._mark_switch_pending(self._close_switch_entity_id, 1)
+ self._mark_switch_pending(self._open_switch_entity_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+
+ async def _send_close(self) -> None:
+ if self._switch_is_on(self._open_switch_entity_id):
+ self._mark_switch_pending(self._open_switch_entity_id, 1)
+ self._mark_switch_pending(self._close_switch_entity_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+
+ async def _send_stop(self) -> None:
+ if self._switch_is_on(self._close_switch_entity_id):
+ self._mark_switch_pending(self._close_switch_entity_id, 1)
+ if self._switch_is_on(self._open_switch_entity_id):
+ self._mark_switch_pending(self._open_switch_entity_id, 1)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
diff --git a/custom_components/cover_time_based/cover_toggle_mode.py b/custom_components/cover_time_based/cover_toggle_mode.py
new file mode 100644
index 0000000..7d421ef
--- /dev/null
+++ b/custom_components/cover_time_based/cover_toggle_mode.py
@@ -0,0 +1,305 @@
+"""Toggle mode cover."""
+
+import asyncio
+import logging
+import time
+from asyncio import sleep
+
+from homeassistant.const import (
+ SERVICE_CLOSE_COVER,
+ SERVICE_OPEN_COVER,
+)
+
+from .cover_switch import SwitchCoverTimeBased
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ToggleModeCover(SwitchCoverTimeBased):
+ """Cover controlled by toggle-style relays (toggle mode).
+
+ In toggle mode, the motor controller toggles state on each pulse.
+ A second pulse on the same direction button stops the motor.
+ _send_stop therefore re-presses the last-used direction button.
+
+ The send methods return immediately after the ON edge so that position
+ tracking starts from the moment the motor begins moving. The pulse
+ completion (sleep + turn_off) runs in the background.
+ """
+
+ def __init__(self, pulse_time, **kwargs):
+ super().__init__(**kwargs)
+ self._pulse_time = pulse_time
+ self._last_external_toggle_time = {}
+ self._last_tilt_direction = None
+
+ async def _complete_pulse(self, entity_id):
+ """Complete a relay pulse by turning OFF after pulse_time."""
+ try:
+ await sleep(self._pulse_time)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": entity_id},
+ False,
+ )
+ except asyncio.CancelledError:
+ pass
+
+ async def async_stop_cover(self, **kwargs):
+ """Stop the cover, only sending relay command if it was active."""
+ was_active = (
+ self.is_opening
+ or self.is_closing
+ or (self._startup_delay_task and not self._startup_delay_task.done())
+ or (self._delay_task and not self._delay_task.done())
+ )
+ tilt_restore_was_active = self._tilt_restore_active
+ tilt_pre_step_was_active = self._pending_travel_target is not None
+ self._cancel_startup_delay_task()
+ self._cancel_delay_task()
+ self._handle_stop()
+ if self._tilt_strategy is not None:
+ self._tilt_strategy.snap_trackers_to_physical(
+ self.travel_calc, self.tilt_calc
+ )
+ if not self._triggered_externally and was_active:
+ await self._send_stop()
+ if (
+ tilt_restore_was_active or tilt_pre_step_was_active
+ ) and self._has_tilt_motor():
+ await self._send_tilt_stop()
+ self.async_write_ha_state()
+ self._last_command = None
+ self._last_tilt_direction = None
+
+ # --- External state change handlers ---
+
+ async def _handle_external_state_change(self, entity_id, old_val, new_val):
+ """Handle external state change in toggle mode.
+
+ Only the rising edge (OFF→ON) is interesting — this is the button
+ press. The ON→OFF transition is just the relay releasing and is ignored.
+
+ A debounce prevents double-triggering for momentary switches that
+ produce OFF->ON->OFF per click.
+ """
+ if new_val != "on":
+ return
+
+ now = time.monotonic()
+ last = self._last_external_toggle_time.get(entity_id, 0)
+ debounce_window = self._pulse_time + 0.5
+ if now - last < debounce_window:
+ self._log(
+ "_handle_external_state_change :: debounced toggle on %s",
+ entity_id,
+ )
+ return
+ self._last_external_toggle_time[entity_id] = now
+
+ if entity_id == self._open_switch_entity_id:
+ self._log("_handle_external_state_change :: external open toggle detected")
+ await self.async_open_cover()
+ elif entity_id == self._close_switch_entity_id:
+ self._log("_handle_external_state_change :: external close toggle detected")
+ await self.async_close_cover()
+
+ async def _handle_external_tilt_state_change(self, entity_id, old_val, new_val):
+ """Handle external tilt state change in toggle mode.
+
+ Only reacts on rising edge (OFF→ON). Same debounce as travel handler.
+ If tilt is already moving, treat any toggle as stop.
+ """
+ if new_val != "on":
+ return
+
+ now = time.monotonic()
+ last = self._last_external_toggle_time.get(entity_id, 0)
+ debounce_window = self._pulse_time + 0.5
+ if now - last < debounce_window:
+ self._log(
+ "_handle_external_tilt_state_change :: debounced toggle on %s",
+ entity_id,
+ )
+ return
+ self._last_external_toggle_time[entity_id] = now
+
+ if entity_id == self._tilt_open_switch_id:
+ if self.tilt_calc.is_traveling():
+ self._log(
+ "_handle_external_tilt_state_change ::"
+ " tilt open toggle while traveling, stopping"
+ )
+ await self.async_stop_cover()
+ else:
+ self._log(
+ "_handle_external_tilt_state_change :: external tilt open toggle detected"
+ )
+ await self.async_open_cover_tilt()
+ elif entity_id == self._tilt_close_switch_id:
+ if self.tilt_calc.is_traveling():
+ self._log(
+ "_handle_external_tilt_state_change ::"
+ " tilt close toggle while traveling, stopping"
+ )
+ await self.async_stop_cover()
+ else:
+ self._log(
+ "_handle_external_tilt_state_change :: external tilt close toggle detected"
+ )
+ await self.async_close_cover_tilt()
+
+ # --- Raw direction commands (calibration screen) ---
+
+ async def _raw_direction_command(self, command: str) -> None:
+ """In toggle mode, opposite-direction = stop, not reverse.
+
+ To change direction: stop first, wait for pulse, then send new direction.
+ """
+ if command in ("open", "close"):
+ opposite = SERVICE_CLOSE_COVER if command == "open" else SERVICE_OPEN_COVER
+ if self._last_command == opposite:
+ await self._send_stop()
+ await sleep(self._pulse_time)
+ elif command in ("tilt_open", "tilt_close"):
+ opposite_dir = "close" if command == "tilt_open" else "open"
+ if self._last_tilt_direction == opposite_dir:
+ await self._send_tilt_stop()
+ await sleep(self._pulse_time)
+ await super()._raw_direction_command(command)
+
+ # --- Internal relay commands ---
+
+ async def _send_open(self) -> None:
+ if self._switch_is_on(self._close_switch_entity_id):
+ self._mark_switch_pending(self._close_switch_entity_id, 1)
+ self._mark_switch_pending(self._open_switch_entity_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+ # Motor controller acts on ON edge; complete pulse in background
+ self.hass.async_create_task(self._complete_pulse(self._open_switch_entity_id))
+
+ async def _send_close(self) -> None:
+ if self._switch_is_on(self._open_switch_entity_id):
+ self._mark_switch_pending(self._open_switch_entity_id, 1)
+ self._mark_switch_pending(self._close_switch_entity_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ # Motor controller acts on ON edge; complete pulse in background
+ self.hass.async_create_task(self._complete_pulse(self._close_switch_entity_id))
+
+ async def _send_stop(self) -> None:
+ if self._last_command == SERVICE_CLOSE_COVER:
+ self._mark_switch_pending(self._close_switch_entity_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._close_switch_entity_id},
+ False,
+ )
+ # Motor toggles on ON edge; complete pulse in background
+ self.hass.async_create_task(
+ self._complete_pulse(self._close_switch_entity_id)
+ )
+ elif self._last_command == SERVICE_OPEN_COVER:
+ self._mark_switch_pending(self._open_switch_entity_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._open_switch_entity_id},
+ False,
+ )
+ # Motor toggles on ON edge; complete pulse in background
+ self.hass.async_create_task(
+ self._complete_pulse(self._open_switch_entity_id)
+ )
+ else:
+ self._log("_send_stop :: toggle mode with no last command, skipping")
+
+ # --- Tilt motor relay commands ---
+
+ async def _send_tilt_open(self) -> None:
+ if self._switch_is_on(self._tilt_close_switch_id):
+ self._mark_switch_pending(self._tilt_close_switch_id, 1)
+ self._mark_switch_pending(self._tilt_open_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ self.hass.async_create_task(self._complete_pulse(self._tilt_open_switch_id))
+ self._last_tilt_direction = "open"
+
+ async def _send_tilt_close(self) -> None:
+ if self._switch_is_on(self._tilt_open_switch_id):
+ self._mark_switch_pending(self._tilt_open_switch_id, 1)
+ self._mark_switch_pending(self._tilt_close_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_off",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ self.hass.async_create_task(self._complete_pulse(self._tilt_close_switch_id))
+ self._last_tilt_direction = "close"
+
+ async def _send_tilt_stop(self) -> None:
+ if self._last_tilt_direction == "close":
+ self._mark_switch_pending(self._tilt_close_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_close_switch_id},
+ False,
+ )
+ self.hass.async_create_task(
+ self._complete_pulse(self._tilt_close_switch_id)
+ )
+ elif self._last_tilt_direction == "open":
+ self._mark_switch_pending(self._tilt_open_switch_id, 2)
+ await self.hass.services.async_call(
+ "homeassistant",
+ "turn_on",
+ {"entity_id": self._tilt_open_switch_id},
+ False,
+ )
+ self.hass.async_create_task(self._complete_pulse(self._tilt_open_switch_id))
+ else:
+ self._log(
+ "_send_tilt_stop :: toggle mode with no last tilt direction, skipping"
+ )
+ self._last_tilt_direction = None
diff --git a/custom_components/cover_time_based/cover_wrapped.py b/custom_components/cover_time_based/cover_wrapped.py
new file mode 100644
index 0000000..d0ca338
--- /dev/null
+++ b/custom_components/cover_time_based/cover_wrapped.py
@@ -0,0 +1,110 @@
+"""Cover that wraps an existing cover entity."""
+
+import logging
+
+from homeassistant.helpers.event import async_track_state_change_event
+
+from .cover_base import CoverTimeBased
+
+_LOGGER = logging.getLogger(__name__)
+
+# Cover states that indicate movement
+_OPENING = "opening"
+_CLOSING = "closing"
+_MOVING_STATES = {_OPENING, _CLOSING}
+
+
+class WrappedCoverTimeBased(CoverTimeBased):
+ """A cover that delegates open/close/stop to an underlying cover entity."""
+
+ def __init__(
+ self,
+ cover_entity_id,
+ **kwargs,
+ ):
+ super().__init__(**kwargs)
+ self._cover_entity_id = cover_entity_id
+
+ async def async_added_to_hass(self):
+ """Register state listener for the wrapped cover entity."""
+ await super().async_added_to_hass()
+ if self._cover_entity_id:
+ self._state_listener_unsubs.append(
+ async_track_state_change_event(
+ self.hass,
+ [self._cover_entity_id],
+ self._async_switch_state_changed,
+ )
+ )
+
+ def _are_entities_configured(self) -> bool:
+ """Return True if the wrapped cover entity is configured."""
+ return bool(self._cover_entity_id)
+
+ async def _handle_external_state_change(self, entity_id, old_val, new_val):
+ """Handle state changes on the wrapped cover entity.
+
+ Unlike switch-based covers, a wrapped cover's state transitions
+ are explicit — we mirror whatever the inner cover is doing.
+ This handles start, stop, AND direction changes (opening→closing).
+ """
+ if new_val == _OPENING:
+ self._log("_handle_external_state_change :: wrapped cover opening")
+ await self.async_open_cover()
+ elif new_val == _CLOSING:
+ self._log("_handle_external_state_change :: wrapped cover closing")
+ await self.async_close_cover()
+ elif old_val in _MOVING_STATES:
+ # Was moving, now stopped
+ self._log("_handle_external_state_change :: wrapped cover stopped")
+ await self.async_stop_cover()
+
+ async def _send_open(self) -> None:
+ # If the wrapped cover is currently closing, the open command produces
+ # two state transitions (closing→open, then open→opening).
+ state = self.hass.states.get(self._cover_entity_id)
+ expected = 2 if state and state.state == _CLOSING else 1
+ self._mark_switch_pending(self._cover_entity_id, expected)
+ await self.hass.services.async_call(
+ "cover", "open_cover", {"entity_id": self._cover_entity_id}, False
+ )
+
+ async def _send_close(self) -> None:
+ # If the wrapped cover is currently opening, the close command produces
+ # two state transitions (opening→open, then open→closing).
+ state = self.hass.states.get(self._cover_entity_id)
+ expected = 2 if state and state.state == _OPENING else 1
+ self._mark_switch_pending(self._cover_entity_id, expected)
+ await self.hass.services.async_call(
+ "cover", "close_cover", {"entity_id": self._cover_entity_id}, False
+ )
+
+ async def _send_stop(self) -> None:
+ self._mark_switch_pending(self._cover_entity_id, 1)
+ await self.hass.services.async_call(
+ "cover", "stop_cover", {"entity_id": self._cover_entity_id}, False
+ )
+
+ # --- Tilt motor relay commands ---
+
+ def _has_tilt_motor(self) -> bool:
+ """Wrapped covers use the cover entity for tilt commands."""
+ return self._tilt_strategy is not None and self._tilt_strategy.uses_tilt_motor
+
+ async def _send_tilt_open(self) -> None:
+ self._mark_switch_pending(self._cover_entity_id, 1)
+ await self.hass.services.async_call(
+ "cover", "open_cover_tilt", {"entity_id": self._cover_entity_id}, False
+ )
+
+ async def _send_tilt_close(self) -> None:
+ self._mark_switch_pending(self._cover_entity_id, 1)
+ await self.hass.services.async_call(
+ "cover", "close_cover_tilt", {"entity_id": self._cover_entity_id}, False
+ )
+
+ async def _send_tilt_stop(self) -> None:
+ self._mark_switch_pending(self._cover_entity_id, 1)
+ await self.hass.services.async_call(
+ "cover", "stop_cover_tilt", {"entity_id": self._cover_entity_id}, False
+ )
diff --git a/custom_components/cover_time_based/frontend/cover-time-based-card.js b/custom_components/cover_time_based/frontend/cover-time-based-card.js
new file mode 100644
index 0000000..87c0428
--- /dev/null
+++ b/custom_components/cover_time_based/frontend/cover-time-based-card.js
@@ -0,0 +1,1804 @@
+/**
+ * Cover Time Based Configuration Card
+ *
+ * A Lovelace card for configuring and calibrating cover_time_based entities.
+ * Uses HA built-in elements (ha-entity-picker, ha-textfield, ha-checkbox,
+ * ha-button) for consistent look and feel.
+ *
+ * All user-visible strings are translatable. Translations are embedded below.
+ */
+
+import {
+ LitElement,
+ html,
+ css,
+} from "https://unpkg.com/lit-element@2.4.0/lit-element.js?module";
+
+const DOMAIN = "cover_time_based";
+
+// Embedded translations — keys are flattened dotted paths.
+// English is the default; other languages override specific keys.
+const EN = {
+ "header": "Cover Time Based Configuration",
+ "loading": "Loading...",
+ "saving": "Saving...",
+ "save_failed": "Save failed — value reverted",
+ "confirm_cancel_calibration": "A calibration is running. Cancel it and continue?",
+ "create_new": "+ Create new cover entity",
+ "yaml_warning": "This entity uses YAML configuration and cannot be configured from this card. Please migrate to the UI: Settings \u2192 Devices & Services \u2192 Helpers \u2192 Create Helper \u2192 Cover Time Based.",
+ "tabs.device": "Device",
+ "tabs.calibration": "Calibration",
+ "control_mode.label": "Control Mode",
+ "control_mode.wrapped": "Wrap an existing cover entity",
+ "control_mode.switch": "Switch (latching)",
+ "control_mode.pulse": "Pulse (momentary)",
+ "control_mode.toggle": "Toggle (same button)",
+ "control_mode.pulse_time": "Pulse time",
+ "entities.cover_entity": "Cover Entity",
+ "entities.switch_entities": "Switch Entities",
+ "entities.open_switch": "Open switch",
+ "entities.close_switch": "Close switch",
+ "entities.stop_switch": "Stop switch",
+ "tilt.label": "Tilt Mode",
+ "tilt.none": "Not supported",
+ "tilt.sequential": "Closes then tilts",
+ "tilt.dual_motor": "Separate tilt motor",
+ "tilt.inline": "Tilts inline with travel",
+ "tilt_motor.label": "Tilt Motor",
+ "tilt_motor.open_switch": "Tilt open switch",
+ "tilt_motor.close_switch": "Tilt close switch",
+ "tilt_motor.stop_switch": "Tilt stop switch",
+ "tilt_motor.safe_position": "Safe tilt position",
+ "tilt_motor.safe_position_helper": "Tilt moves here before travel (100 = fully open)",
+ "tilt_motor.max_allowed_position": "Max tilt allowed position (optional)",
+ "tilt_motor.max_allowed_helper": "Tilt only allowed when cover position is at or below this value (0 = closed, 100 = open)",
+ "timing.attribute_header": "Attribute",
+ "timing.travel_attribute_header": "Travel Attribute",
+ "timing.tilt_attribute_header": "Tilt Attribute",
+ "timing.value_header": "Value",
+ "timing.not_set": "Not set",
+ "timing.travel_time_close": "Travel time (close)",
+ "timing.travel_time_open": "Travel time (open)",
+ "timing.travel_startup_delay": "Travel startup delay",
+ "timing.tilt_time_close": "Tilt time (close)",
+ "timing.tilt_time_open": "Tilt time (open)",
+ "timing.tilt_startup_delay": "Tilt startup delay",
+ "timing.min_movement_time": "Minimum movement time",
+ "timing.endpoint_runon_time": "Endpoint run-on time",
+ "position.label": "Current Position",
+ "position.helper": "Move cover to a known endpoint, then set position.",
+ "position.unknown": "Unknown",
+ "position.open": "Fully open",
+ "position.closed": "Fully closed",
+ "position.closed_tilt_open": "Fully closed, tilt open",
+ "position.closed_tilt_closed": "Fully closed, tilt closed",
+ "calibration.label": "Timing Calibration",
+ "calibration.attribute_label": "Attribute",
+ "calibration.start": "Start",
+ "calibration.active": "Calibration Active",
+ "calibration.step": "Step {step}",
+ "calibration.final_step": "Final step",
+ "calibration.cancel": "Cancel",
+ "calibration.finish": "Finish",
+ "calibration.set_position_first": "Set position to start calibration.",
+ "controls.cover_label": "Cover",
+ "controls.tilt_label": "Tilt",
+ "controls.open": "Open",
+ "controls.stop": "Stop",
+ "controls.close": "Close",
+ "controls.tilt_open": "Tilt open",
+ "controls.tilt_stop": "Tilt stop",
+ "controls.tilt_close": "Tilt close",
+ "hints.sequential.travel_time_close": "Start with cover fully open. Click Finish when the cover is fully closed, before the slats start tilting.",
+ "hints.sequential.travel_time_open": "Start with cover closed and slats open. Click Finish when the cover is fully open.",
+ "hints.sequential.tilt_time_close": "Start with cover closed but slats open. Click Finish when the slats are fully closed.",
+ "hints.sequential.tilt_time_open": "Start with cover and slats closed. Click Finish when the slats are open.",
+ "hints.dual_motor.travel_time_close": "Start with cover open and slats in safe position. Click Finish when the cover is fully closed.",
+ "hints.dual_motor.travel_time_open": "Start with cover closed and slats in safe position. Click Finish when the cover is fully open.",
+ "hints.dual_motor.tilt_time_close": "Start with cover closed and slats open. Click Finish when the slats are fully closed.",
+ "hints.dual_motor.tilt_time_open": "Start with both cover and slats closed. Click Finish when the slats are fully open.",
+ "hints.inline.travel_time_close": "Start with both cover and slats fully open. Click Finish when both are fully closed.",
+ "hints.inline.travel_time_open": "Start with both cover and slats fully closed. Click Finish when both are fully open.",
+ "hints.inline.tilt_time_close": "Start with slats fully open. Click Finish when the slats are fully closed.",
+ "hints.inline.tilt_time_open": "Start with slats fully closed. Click Finish when the slats are fully open.",
+ "hints.none.travel_time_close": "Click Finish when the cover is fully closed.",
+ "hints.none.travel_time_open": "Click Finish when the cover is fully open.",
+ "hints.min_movement_time": "Click Finish as soon as you notice the cover moving.",
+};
+
+const TRANSLATIONS = {
+ en: EN,
+ pt: {
+ "header": "Configuração de Estore Baseado em Tempo",
+ "loading": "A carregar...",
+ "saving": "A guardar...",
+ "save_failed": "Falha ao guardar — valor revertido",
+ "confirm_cancel_calibration": "Existe uma calibração em curso. Cancelar e continuar?",
+ "create_new": "+ Criar nova entidade de estore",
+ "yaml_warning": "Esta entidade utiliza configuração YAML e não pode ser configurada a partir deste cartão. Por favor, migre para a interface gráfica: Definições > Dispositivos e Serviços > Auxiliares > Criar Auxiliar > Estore Baseado em Tempo.",
+ "tabs.device": "Dispositivo",
+ "tabs.calibration": "Calibração",
+ "control_mode.label": "Modo de Controlo",
+ "control_mode.wrapped": "Encapsular uma entidade de estore existente",
+ "control_mode.switch": "Interruptor (travamento)",
+ "control_mode.pulse": "Pulso (momentâneo)",
+ "control_mode.toggle": "Alternar (mesmo botão)",
+ "control_mode.pulse_time": "Duração do pulso",
+ "entities.cover_entity": "Entidade de Estore",
+ "entities.switch_entities": "Entidades de Interruptor",
+ "entities.open_switch": "Interruptor de abrir",
+ "entities.close_switch": "Interruptor de fechar",
+ "entities.stop_switch": "Interruptor de parar",
+ "tilt.label": "Inclinação",
+ "tilt.none": "Não suportado",
+ "tilt.sequential": "Fecha e depois inclina",
+ "tilt.dual_motor": "Motor de inclinação separado",
+ "tilt.inline": "Inclina durante o deslocamento",
+ "tilt_motor.label": "Motor de Inclinação",
+ "tilt_motor.open_switch": "Interruptor de abrir inclinação",
+ "tilt_motor.close_switch": "Interruptor de fechar inclinação",
+ "tilt_motor.stop_switch": "Interruptor de parar inclinação",
+ "tilt_motor.safe_position": "Posição de inclinação segura",
+ "tilt_motor.safe_position_helper": "A inclinação move-se para aqui antes do deslocamento (100 = totalmente aberto)",
+ "tilt_motor.max_allowed_position": "Posição máxima permitida de inclinação (opcional)",
+ "tilt_motor.max_allowed_helper": "A inclinação só é permitida quando a posição do estore está neste valor ou abaixo (0 = fechado, 100 = aberto)",
+ "timing.attribute_header": "Atributo",
+ "timing.travel_attribute_header": "Atributo",
+ "timing.tilt_attribute_header": "Atributo",
+ "timing.value_header": "Valor",
+ "timing.not_set": "Não definido",
+ "timing.travel_time_close": "Tempo de deslocamento (fechar)",
+ "timing.travel_time_open": "Tempo de deslocamento (abrir)",
+ "timing.travel_startup_delay": "Atraso de arranque do deslocamento",
+ "timing.tilt_time_close": "Tempo de inclinação (fechar)",
+ "timing.tilt_time_open": "Tempo de inclinação (abrir)",
+ "timing.tilt_startup_delay": "Atraso de arranque da inclinação",
+ "timing.min_movement_time": "Tempo mínimo de movimento",
+ "timing.endpoint_runon_time": "Tempo de sobrecurso nos extremos",
+ "position.label": "Posição Atual",
+ "position.helper": "Mova o estore para um extremo conhecido e defina a posição.",
+ "position.unknown": "Desconhecida",
+ "position.open": "Totalmente aberto",
+ "position.closed": "Totalmente fechado",
+ "position.closed_tilt_open": "Totalmente fechado, inclinação aberta",
+ "position.closed_tilt_closed": "Totalmente fechado, inclinação fechada",
+ "calibration.label": "Calibração de Temporização",
+ "calibration.attribute_label": "Atributo",
+ "calibration.start": "Iniciar",
+ "calibration.active": "Calibração Ativa",
+ "calibration.step": "Passo {step}",
+ "calibration.final_step": "Passo final",
+ "calibration.cancel": "Cancelar",
+ "calibration.finish": "Concluir",
+ "calibration.set_position_first": "Defina a posição para iniciar a calibração.",
+ "controls.cover_label": "Estore",
+ "controls.tilt_label": "Inclinação",
+ "controls.open": "Abrir",
+ "controls.stop": "Parar",
+ "controls.close": "Fechar",
+ "controls.tilt_open": "Inclinar abrir",
+ "controls.tilt_stop": "Inclinar parar",
+ "controls.tilt_close": "Inclinar fechar",
+ "hints.sequential.travel_time_close": "Comece com o estore totalmente aberto. Clique em Concluir quando o estore estiver totalmente fechado, antes de as lâminas começarem a inclinar.",
+ "hints.sequential.travel_time_open": "Comece com o estore fechado e as lâminas abertas. Clique em Concluir quando o estore estiver totalmente aberto.",
+ "hints.sequential.tilt_time_close": "Comece com o estore fechado mas as lâminas abertas. Clique em Concluir quando as lâminas estiverem totalmente fechadas.",
+ "hints.sequential.tilt_time_open": "Comece com o estore e as lâminas fechados. Clique em Concluir quando as lâminas estiverem abertas.",
+ "hints.dual_motor.travel_time_close": "Comece com o estore aberto e as lâminas na posição segura. Clique em Concluir quando o estore estiver totalmente fechado.",
+ "hints.dual_motor.travel_time_open": "Comece com o estore fechado e as lâminas na posição segura. Clique em Concluir quando o estore estiver totalmente aberto.",
+ "hints.dual_motor.tilt_time_close": "Comece com o estore fechado e as lâminas abertas. Clique em Concluir quando as lâminas estiverem totalmente fechadas.",
+ "hints.dual_motor.tilt_time_open": "Comece com o estore e as lâminas fechados. Clique em Concluir quando as lâminas estiverem totalmente abertas.",
+ "hints.inline.travel_time_close": "Comece com o estore e as lâminas totalmente abertos. Clique em Concluir quando ambos estiverem totalmente fechados.",
+ "hints.inline.travel_time_open": "Comece com o estore e as lâminas totalmente fechados. Clique em Concluir quando ambos estiverem totalmente abertos.",
+ "hints.inline.tilt_time_close": "Comece com as lâminas totalmente abertas. Clique em Concluir quando as lâminas estiverem totalmente fechadas.",
+ "hints.inline.tilt_time_open": "Comece com as lâminas totalmente fechadas. Clique em Concluir quando as lâminas estiverem totalmente abertas.",
+ "hints.none.travel_time_close": "Clique em Concluir quando o estore estiver totalmente fechado.",
+ "hints.none.travel_time_open": "Clique em Concluir quando o estore estiver totalmente aberto.",
+ "hints.min_movement_time": "Clique em Concluir assim que notar o estore a mover-se.",
+ },
+ pl: {
+ "header": "Konfiguracja rolet sterowanych czasowo",
+ "loading": "Ładowanie...",
+ "saving": "Zapisywanie...",
+ "save_failed": "Zapis nie powiódł się — wartość przywrócona",
+ "confirm_cancel_calibration": "Kalibracja jest w toku. Anulować ją i kontynuować?",
+ "create_new": "+ Utwórz nową encję rolety",
+ "yaml_warning": "Ta encja używa konfiguracji YAML i nie może być konfigurowana z tej karty. Proszę przeprowadzić migrację do interfejsu użytkownika: Ustawienia > Urządzenia i usługi > Pomocniki > Utwórz pomocnik > Roleta sterowana czasowo.",
+ "tabs.device": "Urządzenie",
+ "tabs.calibration": "Kalibracja",
+ "control_mode.label": "Tryb sterowania",
+ "control_mode.wrapped": "Opakuj istniejącą encję rolety",
+ "control_mode.switch": "Przełącznik (zatrzaskowy)",
+ "control_mode.pulse": "Impuls (chwilowy)",
+ "control_mode.toggle": "Przełączanie (ten sam przycisk)",
+ "control_mode.pulse_time": "Czas impulsu",
+ "entities.cover_entity": "Encja rolety",
+ "entities.switch_entities": "Encje przełączników",
+ "entities.open_switch": "Przełącznik otwierania",
+ "entities.close_switch": "Przełącznik zamykania",
+ "entities.stop_switch": "Przełącznik zatrzymania",
+ "tilt.label": "Nachylenie",
+ "tilt.none": "Nieobsługiwane",
+ "tilt.sequential": "Najpierw zamyka, potem nachyla",
+ "tilt.dual_motor": "Osobny silnik nachylenia",
+ "tilt.inline": "Nachylenie w trakcie ruchu",
+ "tilt_motor.label": "Silnik nachylenia",
+ "tilt_motor.open_switch": "Przełącznik otwierania nachylenia",
+ "tilt_motor.close_switch": "Przełącznik zamykania nachylenia",
+ "tilt_motor.stop_switch": "Przełącznik zatrzymania nachylenia",
+ "tilt_motor.safe_position": "Bezpieczna pozycja nachylenia",
+ "tilt_motor.safe_position_helper": "Nachylenie przesuwa się tu przed ruchem (100 = w pełni otwarte)",
+ "tilt_motor.max_allowed_position": "Maks. dozwolona pozycja nachylenia (opcjonalna)",
+ "tilt_motor.max_allowed_helper": "Nachylenie dozwolone tylko gdy pozycja rolety wynosi tyle lub mniej (0 = zamknięta, 100 = otwarta)",
+ "timing.attribute_header": "Atrybut",
+ "timing.travel_attribute_header": "Atrybut",
+ "timing.tilt_attribute_header": "Atrybut",
+ "timing.value_header": "Wartość",
+ "timing.not_set": "Nieustawione",
+ "timing.travel_time_close": "Czas ruchu (zamykanie)",
+ "timing.travel_time_open": "Czas ruchu (otwieranie)",
+ "timing.travel_startup_delay": "Opóźnienie startu ruchu",
+ "timing.tilt_time_close": "Czas nachylenia (zamykanie)",
+ "timing.tilt_time_open": "Czas nachylenia (otwieranie)",
+ "timing.tilt_startup_delay": "Opóźnienie startu nachylenia",
+ "timing.min_movement_time": "Minimalny czas ruchu",
+ "timing.endpoint_runon_time": "Czas dobiegu na krańcach",
+ "position.label": "Aktualna pozycja",
+ "position.helper": "Przesuń roletę do znanego krańca, a następnie ustaw pozycję.",
+ "position.unknown": "Nieznana",
+ "position.open": "W pełni otwarta",
+ "position.closed": "W pełni zamknięta",
+ "position.closed_tilt_open": "W pełni zamknięta, nachylenie otwarte",
+ "position.closed_tilt_closed": "W pełni zamknięta, nachylenie zamknięte",
+ "calibration.label": "Kalibracja czasowa",
+ "calibration.attribute_label": "Atrybut",
+ "calibration.start": "Rozpocznij",
+ "calibration.active": "Kalibracja aktywna",
+ "calibration.step": "Krok {step}",
+ "calibration.final_step": "Krok końcowy",
+ "calibration.cancel": "Anuluj",
+ "calibration.finish": "Zakończ",
+ "calibration.set_position_first": "Ustaw pozycję, aby rozpocząć kalibrację.",
+ "controls.cover_label": "Roleta",
+ "controls.tilt_label": "Nachylenie",
+ "controls.open": "Otwórz",
+ "controls.stop": "Zatrzymaj",
+ "controls.close": "Zamknij",
+ "controls.tilt_open": "Otwórz nachylenie",
+ "controls.tilt_stop": "Zatrzymaj nachylenie",
+ "controls.tilt_close": "Zamknij nachylenie",
+ "hints.sequential.travel_time_close": "Zacznij z roletą w pełni otwartą. Kliknij Zakończ, gdy roleta jest w pełni zamknięta, zanim listwy zaczną się nachylać.",
+ "hints.sequential.travel_time_open": "Zacznij z zamkniętą roletą i otwartymi listwami. Kliknij Zakończ, gdy roleta jest w pełni otwarta.",
+ "hints.sequential.tilt_time_close": "Zacznij z zamkniętą roletą, ale otwartymi listwami. Kliknij Zakończ, gdy listwy są w pełni zamknięte.",
+ "hints.sequential.tilt_time_open": "Zacznij z zamkniętą roletą i zamkniętymi listwami. Kliknij Zakończ, gdy listwy są otwarte.",
+ "hints.dual_motor.travel_time_close": "Zacznij z otwartą roletą i listwami w bezpiecznej pozycji. Kliknij Zakończ, gdy roleta jest w pełni zamknięta.",
+ "hints.dual_motor.travel_time_open": "Zacznij z zamkniętą roletą i listwami w bezpiecznej pozycji. Kliknij Zakończ, gdy roleta jest w pełni otwarta.",
+ "hints.dual_motor.tilt_time_close": "Zacznij z zamkniętą roletą i otwartymi listwami. Kliknij Zakończ, gdy listwy są w pełni zamknięte.",
+ "hints.dual_motor.tilt_time_open": "Zacznij z zamkniętą roletą i zamkniętymi listwami. Kliknij Zakończ, gdy listwy są w pełni otwarte.",
+ "hints.inline.travel_time_close": "Zacznij z roletą i listwami w pełni otwartymi. Kliknij Zakończ, gdy obie są w pełni zamknięte.",
+ "hints.inline.travel_time_open": "Zacznij z roletą i listwami w pełni zamkniętymi. Kliknij Zakończ, gdy obie są w pełni otwarte.",
+ "hints.inline.tilt_time_close": "Zacznij z listwami w pełni otwartymi. Kliknij Zakończ, gdy listwy są w pełni zamknięte.",
+ "hints.inline.tilt_time_open": "Zacznij z listwami w pełni zamkniętymi. Kliknij Zakończ, gdy listwy są w pełni otwarte.",
+ "hints.none.travel_time_close": "Kliknij Zakończ, gdy roleta jest w pełni zamknięta.",
+ "hints.none.travel_time_open": "Kliknij Zakończ, gdy roleta jest w pełni otwarta.",
+ "hints.min_movement_time": "Kliknij Zakończ, gdy tylko zauważysz ruch rolety.",
+ },
+};
+
+// Timing attributes shown in calibration dropdown and timing table.
+// Keys are config attribute names; values are translation keys.
+const TIMING_ATTRIBUTES = [
+ ["travel_time_close", "timing.travel_time_close"],
+ ["travel_time_open", "timing.travel_time_open"],
+ ["travel_startup_delay", "timing.travel_startup_delay"],
+ ["tilt_time_close", "timing.tilt_time_close"],
+ ["tilt_time_open", "timing.tilt_time_open"],
+ ["tilt_startup_delay", "timing.tilt_startup_delay"],
+ ["min_movement_time", "timing.min_movement_time"],
+];
+
+const ATTRIBUTE_TO_CONFIG = {
+ travel_time_close: "travel_time_close",
+ travel_time_open: "travel_time_open",
+ tilt_time_close: "tilt_time_close",
+ tilt_time_open: "tilt_time_open",
+ travel_startup_delay: "travel_startup_delay",
+ tilt_startup_delay: "tilt_startup_delay",
+ min_movement_time: "min_movement_time",
+};
+
+class CoverTimeBasedCard extends LitElement {
+ static get properties() {
+ return {
+ hass: { type: Object },
+ _selectedEntity: { type: String },
+ _config: { type: Object },
+ _loading: { type: Boolean },
+ _saving: { type: Boolean },
+ _activeTab: { type: String },
+ _knownPosition: { type: String },
+ _loadError: { type: String },
+ _saveError: { type: Boolean },
+ };
+ }
+
+ constructor() {
+ super();
+ this._selectedEntity = "";
+ this._config = null;
+ this._loading = false;
+ this._saving = false;
+ this._saveError = false;
+ this._activeTab = "device";
+ this._knownPosition = "unknown";
+ this._helpersLoaded = false;
+ }
+
+ // --- Translation support ---
+
+ _t(key, replacements) {
+ const lang = this.hass?.language || "en";
+ const strings = TRANSLATIONS[lang] || EN;
+ let str = strings[key] || EN[key] || key;
+ if (replacements) {
+ for (const [k, v] of Object.entries(replacements)) {
+ str = str.replace(`{${k}}`, v);
+ }
+ }
+ return str;
+ }
+
+ // --- Lifecycle ---
+
+ _getScrollParent() {
+ let el = this;
+ while (el) {
+ el = el.parentElement || el.getRootNode()?.host;
+ if (el && el.scrollTop > 0) return el;
+ }
+ return document.scrollingElement || document.documentElement;
+ }
+
+ async performUpdate() {
+ const scroller = this._getScrollParent();
+ const scrollTop = scroller?.scrollTop ?? 0;
+ await super.performUpdate();
+ if (scroller) scroller.scrollTop = scrollTop;
+ }
+
+ async connectedCallback() {
+ super.connectedCallback();
+ if (!this._helpersLoaded) {
+ this._helpersLoaded = true;
+
+ // ha-entity-picker is lazy-loaded and may only live in a scoped
+ // registry. Force HA to load the module by triggering the config
+ // editor of a card that uses it (same pattern as Mushroom cards).
+ if (!customElements.get("ha-entity-picker")) {
+ try {
+ const helpers = await window.loadCardHelpers();
+ // Create an entities card instance so we can access its class
+ const c = await helpers.createCardElement({
+ type: "entities",
+ entities: [],
+ });
+ // The static getConfigElement() imports the editor module,
+ // which in turn imports ha-entity-picker and registers it.
+ if (c?.constructor?.getConfigElement) {
+ await c.constructor.getConfigElement();
+ }
+ } catch (_) {
+ // best-effort
+ }
+ }
+
+ // Wait for the element to be defined (with timeout).
+ if (!customElements.get("ha-entity-picker")) {
+ try {
+ await Promise.race([
+ customElements.whenDefined("ha-entity-picker"),
+ new Promise((_, reject) =>
+ setTimeout(() => reject(new Error("timeout")), 10000)
+ ),
+ ]);
+ } catch (_) {
+ console.warn(
+ "[cover-time-based-card] ha-entity-picker not available"
+ );
+ }
+ }
+
+ this.requestUpdate();
+ }
+
+ // Load entity list from full registry (includes config_entry_id)
+ this._loadEntityList();
+ }
+
+ updated(changedProperties) {
+ }
+
+ async _loadEntityList() {
+ if (!this.hass) return;
+ try {
+ const entries = await this.hass.callWS({
+ type: "config/entity_registry/list",
+ });
+ this._configEntryEntities = entries
+ .filter((e) => e.platform === "cover_time_based" && e.config_entry_id)
+ .map((e) => e.entity_id);
+ this.requestUpdate();
+ } catch (err) {
+ console.error("Failed to load entity registry:", err);
+ this._configEntryEntities = [];
+ }
+ }
+
+ disconnectedCallback() {
+ super.disconnectedCallback();
+ if (this._autoSaveTimer) clearTimeout(this._autoSaveTimer);
+ if (this._isCalibrating()) {
+ this._onStopCalibration(true);
+ }
+ }
+
+ setConfig(_config) {
+ // No user-configurable options
+ }
+
+ getCardSize() {
+ return 8;
+ }
+
+ getGridOptions() {
+ return { columns: "full", min_columns: 6, min_rows: 4 };
+ }
+
+ // --- Data fetching ---
+
+ async _loadConfig() {
+ if (!this._selectedEntity || !this.hass) return;
+ this._loading = true;
+ this._loadError = null;
+ try {
+ this._config = await this.hass.callWS({
+ type: "cover_time_based/get_config",
+ entity_id: this._selectedEntity,
+ });
+ } catch (err) {
+ console.error("Failed to load config:", err);
+ this._config = null;
+ this._loadError = this._t("yaml_warning");
+ }
+ this._loading = false;
+ }
+
+ _updateLocal(updates) {
+ this._config = { ...this._config, ...updates };
+ this._scheduleAutoSave();
+ }
+
+ _scheduleAutoSave() {
+ if (this._autoSaveTimer) clearTimeout(this._autoSaveTimer);
+ this._autoSaveTimer = setTimeout(() => this._autoSave(), 500);
+ }
+
+ async _autoSave() {
+ if (!this._selectedEntity || !this.hass || !this._config) return;
+ this._saving = true;
+ this._saveError = false;
+ try {
+ const { entry_id, ...fields } = this._config;
+ await this.hass.callWS({
+ type: "cover_time_based/update_config",
+ ...fields,
+ entity_id: this._selectedEntity,
+ });
+ } catch (err) {
+ console.error("Failed to save config:", err);
+ this._saveError = true;
+ await this._loadConfig();
+ setTimeout(() => { this._saveError = false; }, 3000);
+ }
+ this._saving = false;
+ }
+
+ // --- Entity helpers ---
+
+ _getEntityState() {
+ if (!this._selectedEntity || !this.hass) return null;
+ return this.hass.states[this._selectedEntity];
+ }
+
+ _isCalibrating() {
+ if (this._calibratingOverride === false) return false;
+ if (this._calibratingOverride === true) return true;
+ const state = this._getEntityState();
+ return state?.attributes?.calibration_active === true;
+ }
+
+ _getCalibrationHint() {
+ const select = this.shadowRoot?.querySelector("#cal-attribute");
+ const attr = select?.value;
+ const pos = this._knownPosition;
+ const c = this._config;
+ const tiltMode = c?.tilt_mode || "none";
+
+ // Startup delay uses the same hint as the corresponding direction
+ let effectiveAttr = attr;
+ if (attr === "travel_startup_delay") {
+ effectiveAttr = pos === "open" ? "travel_time_close" : "travel_time_open";
+ } else if (attr === "tilt_startup_delay") {
+ effectiveAttr = (pos === "closed_tilt_open" || pos === "open")
+ ? "tilt_time_close" : "tilt_time_open";
+ }
+
+ if (attr === "min_movement_time") {
+ return this._t("hints.min_movement_time");
+ }
+
+ return this._t(`hints.${tiltMode}.${effectiveAttr}`);
+ }
+
+ _hasRequiredEntities(c) {
+ if (!c) return false;
+ if (c.control_mode === "wrapped") {
+ if (!c.cover_entity_id) return false;
+ } else if (c.control_mode === "pulse") {
+ if (!c.open_switch_entity_id || !c.close_switch_entity_id || !c.stop_switch_entity_id) return false;
+ } else {
+ if (!c.open_switch_entity_id || !c.close_switch_entity_id) return false;
+ }
+ // Dual motor tilt requires tilt entities to be complete
+ if (c.tilt_mode === "dual_motor" && c.control_mode !== "wrapped") {
+ if (!c.tilt_open_switch || !c.tilt_close_switch) return false;
+ if (c.control_mode === "pulse" && !c.tilt_stop_switch) return false;
+ }
+ return true;
+ }
+
+ // --- Event handlers ---
+
+ _onEntityChange(e) {
+ const newValue = e.detail?.value || e.target?.value || "";
+ this._selectedEntity = newValue;
+ this._config = null;
+ if (this._selectedEntity) {
+ this._loadConfig();
+ }
+ }
+
+ _onControlModeChange(e) {
+ const mode = e.target.value;
+ const updates = { control_mode: mode };
+ // Clear irrelevant entities when switching modes
+ if (mode === "wrapped") {
+ updates.open_switch_entity_id = null;
+ updates.close_switch_entity_id = null;
+ updates.stop_switch_entity_id = null;
+ } else {
+ updates.cover_entity_id = null;
+ }
+ if (mode !== "pulse") {
+ updates.stop_switch_entity_id = null;
+ updates.tilt_stop_switch = null;
+ }
+ this._updateLocal(updates);
+ }
+
+ _onPulseTimeChange(e) {
+ const val = parseFloat(e.target.value);
+ if (!isNaN(val) && val >= 0.1) {
+ this._updateLocal({ pulse_time: val });
+ }
+ }
+
+ _onSwitchEntityChange(field, e) {
+ const value = e.detail?.value || e.target?.value || null;
+ this._updateLocal({ [field]: value || null });
+ }
+
+ _filterNonTimeBased = (stateObj) => {
+ const entry = this.hass.entities[stateObj.entity_id];
+ return !entry || entry.platform !== DOMAIN;
+ };
+
+ _onCoverEntityChange(e) {
+ const value = e.detail?.value || e.target?.value || null;
+ this._updateLocal({ cover_entity_id: value || null });
+ }
+
+ _onTiltModeChange(e) {
+ const mode = e.target.value;
+ if (mode === "none") {
+ this._updateLocal({
+ tilt_time_close: null,
+ tilt_time_open: null,
+ tilt_startup_delay: null,
+ tilt_mode: "none",
+ // Clear dual-motor fields
+ safe_tilt_position: null,
+ max_tilt_allowed_position: null,
+ tilt_open_switch: null,
+ tilt_close_switch: null,
+ tilt_stop_switch: null,
+ });
+ } else {
+ const updates = { tilt_mode: mode };
+ if (mode === "sequential") {
+ // Clear dual-motor fields when switching to sequential
+ updates.safe_tilt_position = null;
+ updates.max_tilt_allowed_position = null;
+ updates.tilt_open_switch = null;
+ updates.tilt_close_switch = null;
+ updates.tilt_stop_switch = null;
+ } else if (mode === "dual_motor") {
+ // Default safe_tilt_position to 100 (fully open)
+ if (this._config.safe_tilt_position == null) {
+ updates.safe_tilt_position = 100;
+ }
+ // Default max_tilt_allowed_position to 0 (fully closed)
+ if (this._config.max_tilt_allowed_position == null) {
+ updates.max_tilt_allowed_position = 0;
+ }
+ } else if (mode === "inline") {
+ // Clear dual-motor fields when switching to inline
+ updates.safe_tilt_position = null;
+ updates.max_tilt_allowed_position = null;
+ updates.tilt_open_switch = null;
+ updates.tilt_close_switch = null;
+ updates.tilt_stop_switch = null;
+ }
+ this._updateLocal(updates);
+ }
+ }
+
+ async _onStartCalibration() {
+ const attrSelect = this.shadowRoot.querySelector("#cal-attribute");
+
+ const data = {
+ entity_id: this._selectedEntity,
+ attribute: attrSelect.value,
+ timeout: 300,
+ };
+
+ // Don't send an explicit direction — the server derives the correct
+ // direction from the attribute name (e.g. travel_time_close → close,
+ // tilt_time_open → open). The position-based guess here was redundant
+ // for travel and actively wrong for tilt from closed_tilt_open.
+
+ this._calibratingAttribute = attrSelect.value;
+ this._calibratingOverride = undefined;
+
+ try {
+ await this.hass.callWS({
+ type: `${DOMAIN}/start_calibration`,
+ ...data,
+ });
+ this._knownPosition = "unknown";
+ this._calibratingOverride = true;
+ this.requestUpdate();
+ } catch (err) {
+ console.error("Start calibration failed:", err);
+ const msg = err?.message || String(err);
+ alert(`Calibration failed: ${msg}`);
+ }
+ }
+
+ async _onStopCalibration(cancel = false) {
+ this._knownPosition = "unknown";
+ this._calibratingOverride = false;
+ this.requestUpdate();
+ try {
+ const result = await this.hass.callWS({
+ type: "cover_time_based/stop_calibration",
+ entity_id: this._selectedEntity,
+ cancel,
+ });
+ if (!cancel && result?.attribute) {
+ const configKey = ATTRIBUTE_TO_CONFIG[result.attribute];
+ if (configKey) this._updateLocal({ [configKey]: result.value });
+ }
+ } catch (err) {
+ console.error("Stop calibration failed:", err);
+ }
+ }
+
+ _hasTiltMotor() {
+ const c = this._config;
+ if (!c || c.tilt_mode !== "dual_motor") return false;
+ if (c.control_mode === "wrapped") return true;
+ if (c.control_mode === "pulse")
+ return !!(c.tilt_open_switch && c.tilt_close_switch && c.tilt_stop_switch);
+ return !!(c.tilt_open_switch && c.tilt_close_switch);
+ }
+
+ async _onCoverCommand(command) {
+ const cmdMap = {
+ open_cover: "open",
+ close_cover: "close",
+ stop_cover: "stop",
+ tilt_open: "tilt_open",
+ tilt_close: "tilt_close",
+ tilt_stop: "tilt_stop",
+ };
+ this._knownPosition = "unknown";
+ try {
+ await this.hass.callWS({
+ type: `${DOMAIN}/raw_command`,
+ entity_id: this._selectedEntity,
+ command: cmdMap[command],
+ });
+ } catch (err) {
+ console.error(`Cover ${command} failed:`, err);
+ }
+ }
+
+ async _onPositionPresetChange(value) {
+ this._knownPosition = value;
+ if (value === "unknown") return;
+
+ const tiltMode = this._config?.tilt_mode || "none";
+ const hasTilt = tiltMode !== "none";
+
+ // Determine position and tilt values from preset
+ let position, tiltPosition;
+ switch (value) {
+ case "open":
+ position = 100; // HA convention: 100 = fully open
+ tiltPosition = hasTilt ? 100 : null;
+ break;
+ case "closed":
+ // Position+tilt both closed
+ position = 0;
+ tiltPosition = hasTilt ? 0 : null;
+ break;
+ case "closed_tilt_open":
+ position = 0;
+ tiltPosition = 100;
+ break;
+ case "closed_tilt_closed":
+ position = 0;
+ tiltPosition = 0;
+ break;
+ }
+
+ try {
+ await this.hass.callService(DOMAIN, "set_known_position", {
+ entity_id: this._selectedEntity,
+ position,
+ });
+ if (tiltPosition != null) {
+ await this.hass.callService(DOMAIN, "set_known_tilt_position", {
+ entity_id: this._selectedEntity,
+ tilt_position: tiltPosition,
+ });
+ }
+ this.updateComplete.then(() => {
+ const select = this.shadowRoot.querySelector("#cal-attribute");
+ if (select) {
+ const firstEnabled = [...select.options].find((o) => !o.disabled);
+ if (firstEnabled) select.value = firstEnabled.value;
+ }
+ this.requestUpdate();
+ });
+ } catch (err) {
+ console.error("Reset position failed:", err);
+ }
+ }
+
+ _onCreateNew() {
+ // Navigate to helpers/add with domain param — HA auto-opens the config flow
+ window.history.pushState(
+ null,
+ "",
+ `/config/helpers/add?domain=${DOMAIN}`
+ );
+ window.dispatchEvent(new Event("location-changed"));
+ }
+
+ // --- Rendering ---
+
+ render() {
+ if (!this.hass) return html``;
+ return html`
+
+
+
+ ${this._renderEntityPicker()}
+ ${this._selectedEntity && this._config
+ ? this._renderConfigSections()
+ : ""}
+ ${this._loadError
+ ? html`
${this._loadError}
`
+ : ""}
+ ${this._loading
+ ? html`
+ ${this._t("loading")}
+
`
+ : ""}
+
+
{
+ const newEntity = e.detail?.value || "";
+ if (newEntity === this._selectedEntity) return;
+ if (this._isCalibrating()) {
+ if (!confirm(this._t("confirm_cancel_calibration"))) {
+ const current = this._selectedEntity;
+ const picker = e.target;
+ picker.value = current;
+ requestAnimationFrame(() => {
+ picker.value = current;
+ });
+ this.requestUpdate();
+ return;
+ }
+ if (this._isCalibrating()) {
+ this._onStopCalibration(true);
+ }
+ }
+ this._selectedEntity = newEntity;
+ this._config = null;
+ this._loadError = null;
+ this._knownPosition = "unknown";
+ this._calibratingOverride = undefined;
+ this._activeTab = "device";
+ if (this._selectedEntity) this._loadConfig();
+ }}
+ >
+
{
+ e.preventDefault();
+ this._onCreateNew();
+ }}>${this._t("create_new")}
+
+
+
+
+ ${this._getEntityState()?.attributes?.friendly_name ||
+ this._selectedEntity}
+
+ ${this._selectedEntity}
+
+
+
+
+
+
+
+ ${this._activeTab === "device"
+ ? html`
+
+ `
+ : html`
+ ${calibrating ? "" : this._renderPositionReset()}
+ ${this._renderCalibration(calibrating)}
+ ${this._renderTimingTable(c)}
+ `}
+
+ ${this._saving
+ ? html`${this._t("saving")}
`
+ : ""}
+ ${this._saveError
+ ? html`${this._t("save_failed")}
`
+ : ""}
+ `;
+ }
+
+ _renderControlMode(c) {
+ const mode = c.control_mode || "switch";
+ const showPulseTime = mode === "pulse" || mode === "toggle";
+
+ return html`
+
+
${this._t("control_mode.label")}
+
+ ${showPulseTime
+ ? html`
+
+
+
+ `
+ : ""}
+
+
+
+ `;
+ }
+
+ return html`
+
+
${this._t("entities.switch_entities")}
+
+
+ this._onSwitchEntityChange("open_switch_entity_id", e)}
+ >
+
+ this._onSwitchEntityChange("close_switch_entity_id", e)}
+ >
+ ${c.control_mode === "pulse" ? html`
+
+ this._onSwitchEntityChange("stop_switch_entity_id", e)}
+ >
+ ` : ""}
+
+
+
${this._t("tilt.label")}
+
+
+
${this._t("tilt_motor.label")}
+ ${c.control_mode !== "wrapped" ? html`
+
+
+ this._onSwitchEntityChange("tilt_open_switch", e)}
+ >
+
+ this._onSwitchEntityChange("tilt_close_switch", e)}
+ >
+ ${c.control_mode === "pulse" ? html`
+
+ this._onSwitchEntityChange("tilt_stop_switch", e)}
+ >
+ ` : ""}
+
+ ` : ""}
+
+ {
+ const v = parseInt(e.target.value);
+ if (!isNaN(v) && v >= 0 && v <= 100) {
+ this._updateLocal({ safe_tilt_position: v });
+ }
+ }}
+ >
+ {
+ const v = e.target.value.trim();
+ this._updateLocal({
+ max_tilt_allowed_position: v === "" ? null : parseInt(v),
+ });
+ }}
+ >
+
+
+ | ${this._t(labelKey)} |
+
+ {
+ const v = e.target.value.trim();
+ this._updateLocal({ [key]: v === "" ? null : parseFloat(v) });
+ }}
+ />s
+ |
+
+ `;
+ }
+
+ _renderTimingTable(c) {
+ const hasTiltTimes = c.tilt_mode === "sequential" || c.tilt_mode === "dual_motor" || c.tilt_mode === "inline";
+
+ const travelRows = [
+ ["timing.travel_time_close", "travel_time_close", c.travel_time_close, 0.1],
+ ["timing.travel_time_open", "travel_time_open", c.travel_time_open, 0.1],
+ ["timing.travel_startup_delay", "travel_startup_delay", c.travel_startup_delay],
+ ["timing.min_movement_time", "min_movement_time", c.min_movement_time],
+ ["timing.endpoint_runon_time", "endpoint_runon_time", c.endpoint_runon_time],
+ ];
+
+ const tiltRows = [
+ ["timing.tilt_time_close", "tilt_time_close", c.tilt_time_close, 0.1],
+ ["timing.tilt_time_open", "tilt_time_open", c.tilt_time_open, 0.1],
+ ["timing.tilt_startup_delay", "tilt_startup_delay", c.tilt_startup_delay],
+ ];
+
+ return html`
+
+
+
+
+ | ${this._t("timing.travel_attribute_header")} |
+ ${this._t("timing.value_header")} |
+
+
+
+ ${travelRows.map((row) => this._renderTimingRow(row))}
+
+
+ ${hasTiltTimes ? html`
+
+
+
+ | ${this._t("timing.tilt_attribute_header")} |
+ ${this._t("timing.value_header")} |
+
+
+
+ ${tiltRows.map((row) => this._renderTimingRow(row))}
+
+
+ ` : ""}
+
+
${this._t("position.label")}
+
+ ${this._t("position.helper")}
+
+ ${!this._hasTiltMotor() ? html`
+
+ this._onCoverCommand("open_cover")}>
+
+
+ this._onCoverCommand("stop_cover")}>
+
+
+ this._onCoverCommand("close_cover")}>
+
+
+
+ ` : html`
+
+
+ ${this._t("controls.cover_label")}
+ this._onCoverCommand("open_cover")}>
+
+
+ this._onCoverCommand("stop_cover")}>
+
+
+ this._onCoverCommand("close_cover")}>
+
+
+
+
+ ${this._t("controls.tilt_label")}
+ this._onCoverCommand("tilt_open")}>
+
+
+ this._onCoverCommand("tilt_stop")}>
+
+
+ this._onCoverCommand("tilt_close")}>
+
+
+
+
+ `}
+
+
+
+
+ ${this._t("calibration.active")}
+
+
+
${calLabel}
+ ${attrs.calibration_final_step
+ ? html`
${this._t("calibration.final_step")}`
+ : attrs.calibration_step
+ ? html`
${this._t("calibration.step", { step: attrs.calibration_step })}`
+ : ""}
+
+ this._onStopCalibration(true)}
+ >${this._t("calibration.cancel")}
+ this._onStopCalibration(false)}
+ >${this._t("calibration.finish")}
+
+
+
+
${this._t("calibration.label")}
+
+ ${this._knownPosition === "unknown"
+ ? html`
+ ${this._t("calibration.set_position_first")}
+
`
+ : html`
+ ${this._getCalibrationHint()}
+
`}
+