Contributing EN

Contributing

Sprache: English · Deutsch

Thanks for your interest in contributing to the Gardena Smart System integration for Home Assistant! Bug reports, feature requests, and pull requests are all welcome.

Development Setup

1. Clone the repository:

   git clone https://github.com/kayloehmann/ha-gardena-smart-system.git
   cd ha-gardena-smart-system

2. Create a virtual environment and activate it:

   python -m venv .venv
   source .venv/bin/activate

3. Install dependencies (including the bundled client libraries in editable mode):

   pip install -e ./aiogardenasmart -e ./aioautomower
   pip install pytest pytest-asyncio pytest-cov pytest-homeassistant-custom-component mypy ruff

Running Tests

pytest -q

With coverage:

pytest --cov --cov-report=term-missing

Linting

ruff check custom_components/ tests/
ruff format --check custom_components/ tests/

Type Checking

The integration targets mypy --strict:

mypy custom_components/gardena_smart_system/

Pull Requests

• Create a feature branch from main.
• Include tests for new functionality.
• Ensure all CI checks pass (lint, tests, mypy, hassfest).
• Keep PRs focused — one feature or fix per PR.
• Follow the existing translation workflow: when adding user-visible strings, update strings.json and run the translation tooling for the 31 supported locales.

Architecture

The integration supports two Husqvarna APIs via separate coordinators:

• Gardena Smart System API — coordinator.py + GardenaCoordinator
• Automower Connect API — automower_coordinator.py + AutomowerCoordinator

Both inherit from base_coordinator.py, which implements the WebSocket-first behavior, rate-limit backoff, circuit breaker, watchdog, and API-budget tracking shared across both APIs.

Entity platforms are split by API type:

• Gardena: sensor.py, binary_sensor.py, valve.py, switch.py, lawn_mower.py, event.py …
• Automower: automower_sensor.py, automower_binary_sensor.py, automower_lawn_mower.py, automower_switch.py, automower_select.py, automower_number.py, automower_device_tracker.py, automower_calendar.py, automower_button.py, automower_event.py …

Both APIs use WebSocket for real-time updates with REST polling as a fallback. See API Rate Limits for the detailed call patterns.

Quality Targets

The integration aims at the Home Assistant Integration Quality Scale Platinum level:

• 99 % test coverage across the test suite
• mypy --strict passes with zero errors on all source files
• PEP 561 compliant (py.typed markers)
• Full async codebase — no blocking I/O in the event loop
• Diagnostics with sensitive-data redaction
• Translated exceptions for all user-facing errors

---

Thanks again — see also the GitHub repository and the issue tracker.