Developer Setup

Developer Setup

Prerequisites

Before you begin development, ensure you have the following installed:

Required Tools

• Python 3.11+ - The integration requires Python 3.11 or higher
• Git - Version control
• Home Assistant Core - For testing the integration
• pip - Python package manager

Recommended Tools

• GitHub CLI (gh) - Required for automated releases
• jq - Required for release script (JSON parsing)
• Visual Studio Code or PyCharm - Recommended IDEs with Home Assistant support

Installation (macOS)

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install python@3.11 git gh jq

# Verify installations
python3 --version
git --version
gh --version
jq --version

Getting Started

1. Clone the Repository

git clone https://github.com/jrhubott/adaptive-cover.git
cd adaptive-cover

2. Run Initial Setup

The setup script installs development dependencies and configures pre-commit hooks:

./scripts/setup

This script will:

• Install Python development dependencies (ruff, pre-commit, etc.)
• Set up pre-commit hooks for automatic linting
• Configure your development environment

3. Verify Setup

# Check linting works
./scripts/lint

# Verify pre-commit hooks are installed
pre-commit run --all-files

Project Structure

adaptive-cover/
├── custom_components/adaptive_cover_pro/
│   ├── __init__.py              # Integration entry point
│   ├── coordinator.py           # Data coordinator (orchestrator, ~1,477 lines)
│   ├── calculation.py           # Position calculations (pure, 0 HA imports)
│   ├── config_flow.py           # Configuration UI
│   ├── config_types.py          # CoverConfig typed dataclass
│   ├── sun.py                   # Solar calculations (pure, 0 HA imports)
│   ├── engine/                  # Next-gen calculation engine
│   │   ├── sun_geometry.py      # SunGeometry dataclass
│   │   └── covers/
│   │       └── venetian.py      # VenetianCoverCalculation (dual-axis)
│   ├── managers/                # Extracted coordinator responsibilities
│   │   ├── manual_override.py   # Manual override detection & tracking
│   │   ├── grace_period.py      # Per-command + startup grace periods
│   │   ├── motion.py            # Motion sensor timeout tracking
│   │   ├── position_verification.py  # Periodic position verification
│   │   └── cover_command.py     # Cover service calls & delta checks
│   ├── state/                   # HA boundary layer (state providers)
│   │   ├── climate_provider.py  # Reads climate/weather/presence entities
│   │   ├── cover_provider.py    # CoverProvider — reads cover entity state
│   │   ├── snapshot.py          # SunSnapshot, CoverStateSnapshot dataclasses
│   │   └── sun_provider.py      # Reads astral location from HA
│   ├── pipeline/                # Override priority chain
│   │   ├── registry.py          # Evaluates handlers in priority order
│   │   ├── types.py             # PipelineContext, PipelineResult, DecisionStep
│   │   ├── handler.py           # OverrideHandler base class
│   │   └── handlers/            # 8 priority handlers
│   │       ├── force_override.py    # Priority 100
│   │       ├── wind.py              # Priority 95 (stub)
│   │       ├── motion_timeout.py    # Priority 80
│   │       ├── manual_override.py   # Priority 70
│   │       ├── climate.py           # Priority 50
│   │       ├── solar.py             # Priority 40
│   │       ├── cloud_suppression.py # Priority 35 (stub)
│   │       └── default.py           # Priority 0
│   ├── diagnostics/             # Diagnostic data builder
│   │   └── builder.py           # DiagnosticsBuilder + DiagnosticContext
│   ├── services/                # Service layer
│   │   └── configuration_service.py
│   ├── sensor.py                # Sensor platform
│   ├── switch.py                # Switch platform
│   ├── binary_sensor.py         # Binary sensor platform
│   ├── button.py                # Button platform
│   ├── entity_base.py           # Base entity classes
│   ├── helpers.py               # Utility functions
│   ├── const.py                 # Constants
│   ├── enums.py                 # Type-safe enumerations
│   ├── geometry.py              # Geometric utilities
│   ├── position_utils.py        # Position conversion utilities
│   ├── config_context_adapter.py # Logging adapter
│   ├── manifest.json            # Integration metadata
│   └── translations/            # i18n files
├── tests/                       # Unit tests (751 tests)
│   ├── conftest.py              # Shared fixtures
│   ├── test_calculation.py      # Core calculation tests
│   ├── test_geometric_accuracy.py
│   ├── test_sill_height.py
│   ├── test_control_state_reason.py
│   ├── test_position_explanation.py
│   ├── test_position_limits.py
│   ├── test_inverse_state.py
│   ├── test_manual_override.py
│   ├── test_motion_control.py
│   ├── test_force_override_sensors.py
│   ├── test_startup_grace_period.py
│   ├── test_delta_position.py
│   ├── test_interpolation.py
│   ├── test_helpers.py
│   ├── test_time_window_sensor.py
│   ├── test_coordinator_logging.py
│   ├── test_managers/           # Manager unit tests
│   ├── test_pipeline/           # Pipeline handler tests
│   ├── test_state/              # State provider tests
│   ├── test_engine/             # Engine module tests
│   └── test_diagnostics/        # Diagnostics builder tests
├── scripts/
├── docs/
├── release_notes/
├── notebooks/
├── CLAUDE.md
├── HANDOFF.md
├── README.md
└── pyproject.toml