feat: UI-first architecture with config flow, card, calibration, tilt strategies, and state monitoring

.github/workflows/tests.yml

@@ -0,0 +1,48 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    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: |
+          pip install homeassistant
+          pip install pytest pytest-asyncio pytest-homeassistant-custom-component
+
+      - 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: pip install ruff
+
+      - name: Check formatting
+        run: ruff format --check .
+
+      - name: Check linting
+        run: ruff check .

.gitignore

@@ -6,4 +6,4 @@
 
 __pycache__/
 
-*.iml
+*.iml.coverage

CHANGELOG.md

@@ -1,3 +1,30 @@
+## Unreleased
+
+### Features
+
+- **External state monitoring:** Detects physical switch presses and keeps the position tracker in sync with actual motor state. Supports all input modes (switch, pulse, toggle) 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.
+- **Tilt switch monitoring:** Monitors tilt switch entities for external changes in all modes (pulse, switch, toggle).
+- **Translatable frontend card:** All card strings externalized to `strings.json` with `_t()` helper. Translations for English, Portuguese, and Polish included.
+- **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)
+- 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% (478 tests)
+
+### Bug Fixes
+
+- 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

custom_components/cover_time_based/__init__.py

@@ -0,0 +1,58 @@
+"""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 .websocket_api import async_register_websocket_api
+
+_LOGGER = logging.getLogger(__name__)
+
+DOMAIN = "cover_time_based"
+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)

custom_components/cover_time_based/calibration.py

@@ -0,0 +1,43 @@
+"""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
+    step_duration: float | None = None
+    last_pulse_duration: float | None = None
+    continuous_start: float | None = None
+    move_command: str | None = None
+    timeout_task: Task | None = field(default=None, repr=False)
+    automation_task: Task | None = field(default=None, repr=False)

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 = 1
+
+    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)