ihcctl 0.2.0__py3-none-any.whl

ihcctl-0.2.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: ihcctl
+Version: 0.2.0
+Summary: Python library and CLI for local Zehnder IHC control
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: bleak>=0.22
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# ihcctl
+
+`ihcctl` is a Python library and CLI for local Zehnder IHC controller control
+over Bluetooth Low Energy. Normal use does not require a cloud service.
+
+The distribution is `ihcctl`; the Python import namespace remains
+`zehnder_ihc`; the CLI command is `ihcctl`.
+
+## Install
+
+For the CLI, prefer pipx:
+
+```bash
+pipx install ihcctl
+ihcctl --help
+```
+
+Alternatively install into a Python environment:
+
+```bash
+python -m pip install ihcctl
+```
+
+The first public release, `ihcctl` 0.2.0, is prepared but not yet published.
+Until public publication and verification, these are the intended future
+commands rather than a current PyPI installation path.
+
+## Python library and CLI
+
+Use `import zehnder_ihc` or import public classes directly:
+
+```python
+from zehnder_ihc import IHCClient
+```
+
+The CLI requires a Bluetooth address and an externally stored identity file.
+Do not commit it or share it with Home Assistant.
+
+```bash
+ihcctl --help
+ihcctl register --help
+```
+
+Registration requires physical IHC confirmation. The help commands do not
+contact hardware. Do not keep the CLI connected while Home Assistant polls the
+same controller.
+
+## Home Assistant
+
+The custom integration uses the same `zehnder_ihc` library internally. During
+this preparation phase its `manifest.json` deliberately retains the existing
+local direct-wheel requirement; it has not switched to `ihcctl`.
+
+Only after a verified public PyPI release will a separately authorized change
+pin it to `ihcctl==0.2.0`. Do not manually install, uninstall, or remove
+packages in a Home Assistant container.
+
+The optional Schedule Manager resource is:
+
+```yaml
+url: /zehnder_ihc/frontend/zehnder-ihc-schedule-card.js
+type: module
+```
+
+## Development / fallback workflow
+
+`tools/start-local-pypi.sh` and local pypiserver remain development/fallback
+tools. They are not the normal workflow for new CLI users or the intended
+production Home Assistant workflow after public PyPI migration. Existing Home
+Assistant deployments still need the current local wheel until the later
+manifest migration succeeds.
+
+For repository work, use the existing test extra:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[test]"
+python -m pytest -q
+```
+
+Tests use sanitized frames and fake BLE backends; they do not contact IHC
+hardware or perform writes.
+
+## Publishing
+
+Maintainers must read [the publishing guide](docs/publishing-pypi.md). Local
+readiness never publishes:
+
+```bash
+tools/release-pypi.sh --check
+```
+
+TestPyPI and production PyPI require separate explicit authorization.
+
+## Safety
+
+Phase-1 research is frozen. Never commit client identities, `ihc-client*.json`,
+or files under `phase1-private/`. Hardware-changing tests need explicit
+approval and protocol-level readback where possible.

ihcctl-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+zehnder_ihc/__init__.py,sha256=etpICo-W5voec7WEaWGJIFFjMow5kh_MY-SBh-_PEkQ,1601
+zehnder_ihc/backup.py,sha256=VxpE5iNZUNUyYe8bfN4IhAkW26iUBIQ4fY1Kz7dEM7Y,13096
+zehnder_ihc/bleak_backend.py,sha256=MQ2xx_wRDrc4YbUU9anlqqWE1qPh63TmxlBpQtkK84U,2700
+zehnder_ihc/cli.py,sha256=s3D8_uE7HJNj28jJJDDyAcr3axS0ha9KyC-P3mDDMB8,25624
+zehnder_ihc/client.py,sha256=RkvxqMnwi-9fROlieaa9TYkCUfuGy3B-erbM9sEV8TU,48930
+zehnder_ihc/errors.py,sha256=aPIqDPLrLY0JwGZK_z-cbYIie9aS1Wi-3_lOMgLcxZk,3421
+zehnder_ihc/framing.py,sha256=7XCywGPLycoFEJvLdG-6xcREl7L46TXTEpYLyEkX1DA,1375
+zehnder_ihc/identity.py,sha256=bfJgyiRvoQqsPPSYcnSoQm-Jc6qtLNyoz_O0TRgcz7U,2086
+zehnder_ihc/models.py,sha256=6Z6MnVYA4xO3kdzyzHjs_vXp2u6QjpNIZCp3khouN1M,3479
+zehnder_ihc/mutations.py,sha256=_Bpe7YSeh7FT3LUu7_g1hettI-j9aSIUbkrgd-5ikGE,2561
+zehnder_ihc/protocol.py,sha256=FnM-wW5fAug51tk0ASojDCmIf1FfDG5y28v6BiiUXCc,19776
+zehnder_ihc/restore.py,sha256=qhp064lSA-6EVFc1GteFSZ5ENvbnkzn5qhN7NTeTauM,12147
+zehnder_ihc/transport.py,sha256=WGGE2jdgcQfdROpIQNCKc61mV89slQAuFnOmcibtme0,6373
+ihcctl-0.2.0.dist-info/METADATA,sha256=0lEeRTnNP1G8TYhzmMAuZ0hD6MpYXtP5qa53bV8GgvY,3054
+ihcctl-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ihcctl-0.2.0.dist-info/entry_points.txt,sha256=guH5eXAm0th1yOOCPSwktzImVlJi3CbZt66ZzCgnIcY,48
+ihcctl-0.2.0.dist-info/top_level.txt,sha256=clCOa7CNlJ6qCf-jYWZTomtZeiKLyg9QxznpjOnCY4I,12
+ihcctl-0.2.0.dist-info/RECORD,,

ihcctl-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ihcctl-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ihcctl = zehnder_ihc.cli:main

ihcctl-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zehnder_ihc

zehnder_ihc/__init__.py

@@ -0,0 +1,66 @@
+"""Public Zehnder IHC client API."""
+
+from .bleak_backend import BleakBackend
+from .backup import BackupDayplanV1, BackupSourceDeviceV1, BackupWeekplanV1, ScheduleBackupV1
+from .client import IHCClient
+from .errors import (
+    ActivePlanDeletionError,
+    AmbiguousPlanNameError,
+    BackupDeviceMismatchError,
+    BackupValidationError,
+    IndeterminateRegistrationError,
+    PlanNotFoundError,
+    PlanReferencedError,
+)
+from .identity import Identity
+from .models import (
+    Dayplan,
+    DayplanQuickHeating,
+    DayplanTransition,
+    OperatingMode,
+    ScheduleInventory,
+    ScheduleState,
+    Status,
+    Weekday,
+    Weekplan,
+)
+from .restore import (
+    ScheduleRestoreActionKindV1,
+    ScheduleRestoreActionV1,
+    ScheduleRestoreExecutionStepV1,
+    ScheduleRestoreMappingV1,
+    ScheduleRestorePlanV1,
+)
+from .transport import BLETransport
+
+__all__ = [
+    "BLETransport",
+    "BleakBackend",
+    "ActivePlanDeletionError",
+    "AmbiguousPlanNameError",
+    "BackupDayplanV1",
+    "BackupDeviceMismatchError",
+    "BackupSourceDeviceV1",
+    "BackupValidationError",
+    "BackupWeekplanV1",
+    "Dayplan",
+    "DayplanQuickHeating",
+    "DayplanTransition",
+    "IHCClient",
+    "Identity",
+    "IndeterminateRegistrationError",
+    "OperatingMode",
+    "PlanNotFoundError",
+    "PlanReferencedError",
+    "ScheduleInventory",
+    "ScheduleBackupV1",
+    "ScheduleRestoreActionKindV1",
+    "ScheduleRestoreActionV1",
+    "ScheduleRestoreExecutionStepV1",
+    "ScheduleRestoreMappingV1",
+    "ScheduleRestorePlanV1",
+    "ScheduleState",
+    "Status",
+    "Weekday",
+    "Weekplan",
+]

zehnder_ihc/backup.py

@@ -0,0 +1,280 @@
+"""Versioned logical schedule-backup models."""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+import re
+from typing import ClassVar
+
+from .errors import BackupValidationError
+from .models import DayplanQuickHeating, DayplanTransition, ScheduleState, Weekday
+
+_BLUETOOTH_ADDRESS = re.compile(r"^[0-9A-Fa-f]{2}(?::[0-9A-Fa-f]{2}){5}$")
+_TIMESTAMP = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z$")
+
+
+def _error(reason: str) -> BackupValidationError:
+    return BackupValidationError(reason)
+
+
+def _require_object(value: object, path: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise _error(f"{path} must be an object")
+    return value
+
+
+def _require_fields(value: dict[str, object], expected: set[str], path: str) -> None:
+    missing = expected - value.keys()
+    unknown = value.keys() - expected
+    if missing:
+        raise _error(f"{path} is missing required field {sorted(missing)[0]!r}")
+    if unknown:
+        raise _error(f"{path} contains unknown field {sorted(unknown)[0]!r}")
+
+
+def _require_string(value: object, path: str, *, non_empty: bool = False) -> str:
+    if not isinstance(value, str):
+        raise _error(f"{path} must be a string")
+    if non_empty and not value:
+        raise _error(f"{path} must not be empty")
+    return value
+
+
+def _require_integer(value: object, path: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise _error(f"{path} must be an integer")
+    return value
+
+
+def _format_created_at(value: datetime) -> str:
+    rendered = (
+        f"{value.year:04d}-{value.month:02d}-{value.day:02d}T"
+        f"{value.hour:02d}:{value.minute:02d}:{value.second:02d}"
+    )
+    if value.microsecond:
+        rendered += f".{value.microsecond:06d}"
+    return rendered + "Z"
+
+
+@dataclass(frozen=True)
+class BackupSourceDeviceV1:
+    """The normalized Bluetooth address bound to one backup."""
+
+    bluetooth_address: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.bluetooth_address, str) or not _BLUETOOTH_ADDRESS.fullmatch(self.bluetooth_address):
+            raise _error("source_device.bluetooth_address must be a Bluetooth MAC address")
+        object.__setattr__(self, "bluetooth_address", self.bluetooth_address.upper())
+
+
+@dataclass(frozen=True)
+class BackupDayplanV1:
+    """One logical Dayplan without a device ID."""
+
+    key: str
+    name: str
+    transitions: tuple[DayplanTransition, ...]
+    quick_heating: DayplanQuickHeating | None
+
+    def __post_init__(self) -> None:
+        _require_string(self.key, "dayplan.key", non_empty=True)
+        _require_string(self.name, "dayplan.name")
+        if not isinstance(self.transitions, tuple):
+            raise _error("dayplan.transitions must be a tuple")
+        if not all(isinstance(item, DayplanTransition) for item in self.transitions):
+            raise _error("dayplan.transitions must contain DayplanTransition values")
+        if self.quick_heating is not None and not isinstance(self.quick_heating, DayplanQuickHeating):
+            raise _error("dayplan.quick_heating must be a DayplanQuickHeating or None")
+
+
+@dataclass(frozen=True)
+class BackupWeekplanV1:
+    """One logical Weekplan without a device ID."""
+
+    key: str
+    name: str
+    assignments: tuple[str, str, str, str, str, str, str]
+
+    def __post_init__(self) -> None:
+        _require_string(self.key, "weekplan.key", non_empty=True)
+        _require_string(self.name, "weekplan.name")
+        if not isinstance(self.assignments, tuple) or len(self.assignments) != len(Weekday):
+            raise _error("weekplan.assignments must contain exactly seven Dayplan keys")
+        for assignment in self.assignments:
+            _require_string(assignment, "weekplan.assignment", non_empty=True)
+
+
+@dataclass(frozen=True)
+class ScheduleBackupV1:
+    """A complete logical schedule backup in format version 1."""
+
+    FORMAT: ClassVar[str] = "zehnder-ihc-schedule-backup"
+    VERSION: ClassVar[int] = 1
+    created_at: datetime
+    source_device: BackupSourceDeviceV1
+    dayplans: tuple[BackupDayplanV1, ...]
+    weekplans: tuple[BackupWeekplanV1, ...]
+    active_weekplan: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.created_at, datetime) or self.created_at.tzinfo is not timezone.utc:
+            raise _error("created_at must be a timezone-aware UTC timestamp")
+        if not isinstance(self.source_device, BackupSourceDeviceV1):
+            raise _error("source_device must be a BackupSourceDeviceV1")
+        if not isinstance(self.dayplans, tuple) or not all(isinstance(item, BackupDayplanV1) for item in self.dayplans):
+            raise _error("dayplans must be a tuple of BackupDayplanV1 values")
+        if not isinstance(self.weekplans, tuple) or not all(isinstance(item, BackupWeekplanV1) for item in self.weekplans):
+            raise _error("weekplans must be a tuple of BackupWeekplanV1 values")
+        _require_string(self.active_weekplan, "active_weekplan", non_empty=True)
+        dayplan_keys = [item.key for item in self.dayplans]
+        weekplan_keys = [item.key for item in self.weekplans]
+        if len(dayplan_keys) != len(set(dayplan_keys)):
+            raise _error("dayplan keys must be unique")
+        if len(weekplan_keys) != len(set(weekplan_keys)):
+            raise _error("weekplan keys must be unique")
+        dayplan_key_set = set(dayplan_keys)
+        for weekplan in self.weekplans:
+            if any(item not in dayplan_key_set for item in weekplan.assignments):
+                raise _error("weekplan assignments must reference declared Dayplan keys")
+        if self.active_weekplan not in set(weekplan_keys):
+            raise _error("active_weekplan must reference a declared Weekplan key")
+
+    @property
+    def format(self) -> str:
+        """Return the fixed v1 document format identifier."""
+        return self.FORMAT
+
+    @property
+    def version(self) -> int:
+        """Return the fixed v1 document version."""
+        return self.VERSION
+
+    def to_dict(self) -> dict[str, object]:
+        """Return the canonical JSON-compatible backup representation."""
+        return {
+            "format": self.FORMAT, "version": self.VERSION, "created_at": _format_created_at(self.created_at),
+            "source_device": {"bluetooth_address": self.source_device.bluetooth_address},
+            "dayplans": [{"key": plan.key, "name": plan.name,
+                          "transitions": [{"minute_of_day": item.minute_of_day, "state": item.state.name} for item in plan.transitions],
+                          "quick_heating": None if plan.quick_heating is None else {"start_minute": plan.quick_heating.start_minute, "type_code": plan.quick_heating.type_code, "duration_minutes": plan.quick_heating.duration_minutes}}
+                         for plan in self.dayplans],
+            "weekplans": [{"key": plan.key, "name": plan.name, "assignments": list(plan.assignments)} for plan in self.weekplans],
+            "active_weekplan": self.active_weekplan,
+        }
+
+    @classmethod
+    def from_dict(cls, value: object) -> "ScheduleBackupV1":
+        """Validate one JSON-compatible backup representation."""
+        try:
+            document = _require_object(value, "backup")
+            _require_fields(document, {"format", "version", "created_at", "source_device", "dayplans", "weekplans", "active_weekplan"}, "backup")
+            if document["format"] != cls.FORMAT:
+                raise _error("backup.format is unsupported")
+            if _require_integer(document["version"], "backup.version") != cls.VERSION:
+                raise _error("backup.version is unsupported")
+            return cls(_parse_created_at(document["created_at"]), _parse_source_device(document["source_device"]), _parse_dayplans(document["dayplans"]), _parse_weekplans(document["weekplans"]), _require_string(document["active_weekplan"], "backup.active_weekplan", non_empty=True))
+        except BackupValidationError:
+            raise
+        except (TypeError, ValueError) as error:
+            raise _error(str(error)) from error
+
+    def to_json(self) -> str:
+        """Return canonical JSON for this backup."""
+        return json.dumps(self.to_dict(), ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+
+    @classmethod
+    def from_json(cls, value: str | bytes) -> "ScheduleBackupV1":
+        """Parse and validate one JSON backup document."""
+        if not isinstance(value, (str, bytes)):
+            raise _error("backup JSON must be text or bytes")
+        try:
+            parsed = json.loads(value, object_pairs_hook=_reject_duplicate_keys, parse_constant=_reject_non_finite)
+        except (TypeError, ValueError, UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise _error(f"invalid backup JSON: {error}") from error
+        return cls.from_dict(parsed)
+
+
+def _parse_created_at(value: object) -> datetime:
+    timestamp = _require_string(value, "backup.created_at")
+    if not _TIMESTAMP.fullmatch(timestamp):
+        raise _error("backup.created_at must be a UTC ISO-8601 timestamp ending in Z")
+    try:
+        return datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+    except ValueError as error:
+        raise _error("backup.created_at is invalid") from error
+
+
+def _parse_source_device(value: object) -> BackupSourceDeviceV1:
+    source = _require_object(value, "backup.source_device")
+    _require_fields(source, {"bluetooth_address"}, "backup.source_device")
+    return BackupSourceDeviceV1(_require_string(source["bluetooth_address"], "backup.source_device.bluetooth_address"))
+
+
+def _parse_dayplans(value: object) -> tuple[BackupDayplanV1, ...]:
+    if not isinstance(value, list):
+        raise _error("backup.dayplans must be an array")
+    return tuple(_parse_dayplan(item, index) for index, item in enumerate(value))
+
+
+def _parse_dayplan(value: object, index: int) -> BackupDayplanV1:
+    path = f"backup.dayplans[{index}]"
+    plan = _require_object(value, path)
+    _require_fields(plan, {"key", "name", "transitions", "quick_heating"}, path)
+    transitions_value = plan["transitions"]
+    if not isinstance(transitions_value, list):
+        raise _error(f"{path}.transitions must be an array")
+    transitions = tuple(_parse_transition(item, path, item_index) for item_index, item in enumerate(transitions_value))
+    return BackupDayplanV1(_require_string(plan["key"], f"{path}.key", non_empty=True), _require_string(plan["name"], f"{path}.name"), transitions, _parse_quick_heating(plan["quick_heating"], path))
+
+
+def _parse_transition(value: object, dayplan_path: str, index: int) -> DayplanTransition:
+    path = f"{dayplan_path}.transitions[{index}]"
+    transition = _require_object(value, path)
+    _require_fields(transition, {"minute_of_day", "state"}, path)
+    try:
+        return DayplanTransition(_require_integer(transition["minute_of_day"], f"{path}.minute_of_day"), ScheduleState[_require_string(transition["state"], f"{path}.state")])
+    except (KeyError, ValueError) as error:
+        raise _error(f"{path} is invalid: {error}") from error
+
+
+def _parse_quick_heating(value: object, dayplan_path: str) -> DayplanQuickHeating | None:
+    if value is None:
+        return None
+    path = f"{dayplan_path}.quick_heating"
+    quick = _require_object(value, path)
+    _require_fields(quick, {"start_minute", "type_code", "duration_minutes"}, path)
+    try:
+        return DayplanQuickHeating(_require_integer(quick["start_minute"], f"{path}.start_minute"), _require_integer(quick["type_code"], f"{path}.type_code"), _require_integer(quick["duration_minutes"], f"{path}.duration_minutes"))
+    except ValueError as error:
+        raise _error(f"{path} is invalid: {error}") from error
+
+
+def _parse_weekplans(value: object) -> tuple[BackupWeekplanV1, ...]:
+    if not isinstance(value, list):
+        raise _error("backup.weekplans must be an array")
+    return tuple(_parse_weekplan(item, index) for index, item in enumerate(value))
+
+
+def _parse_weekplan(value: object, index: int) -> BackupWeekplanV1:
+    path = f"backup.weekplans[{index}]"
+    plan = _require_object(value, path)
+    _require_fields(plan, {"key", "name", "assignments"}, path)
+    assignments_value = plan["assignments"]
+    if not isinstance(assignments_value, list):
+        raise _error(f"{path}.assignments must be an array")
+    assignments = tuple(_require_string(item, f"{path}.assignments[{item_index}]", non_empty=True) for item_index, item in enumerate(assignments_value))
+    return BackupWeekplanV1(_require_string(plan["key"], f"{path}.key", non_empty=True), _require_string(plan["name"], f"{path}.name"), assignments)  # type: ignore[arg-type]
+
+
+def _reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise _error(f"duplicate JSON object member {key!r}")
+        result[key] = value
+    return result
+
+
+def _reject_non_finite(value: str) -> None:
+    raise _error(f"non-finite JSON value {value!r} is not supported")

zehnder_ihc/bleak_backend.py

@@ -0,0 +1,70 @@
+"""Bleak implementation of the IHC BLE backend boundary."""
+
+import asyncio
+from collections.abc import Callable
+
+WRITE_UUID = "2456e1b9-26e2-8f83-e744-f34f01e9d702"
+NOTIFY_UUID = "2456e1b9-26e2-8f83-e744-f34f01e9d703"
+
+
+class BleakBackend:
+    """Connect one known IHC and expose its verified GATT characteristics."""
+
+    def __init__(self, client_factory=None, *, find_device=None, device=None) -> None:
+        if client_factory is None or find_device is None:
+            from bleak import BleakClient, BleakScanner
+
+            client_factory = BleakClient
+            find_device = BleakScanner.find_device_by_address
+        self._client_factory = client_factory
+        self._find_device = find_device
+        self._device = device
+        self._client = None
+
+    async def connect(self, address: str, notification_handler: Callable[[bytes], None]) -> None:
+        """Find, connect and subscribe to the IHC notification characteristic."""
+        device = self._device or await self._find_device(address)
+        if device is None:
+            raise ConnectionError(f"IHC not found: {address}")
+        self._client = self._client_factory(device)
+        try:
+            await self._client.connect()
+            await self._client.start_notify(
+                NOTIFY_UUID, lambda _sender, value: notification_handler(bytes(value))
+            )
+        except asyncio.CancelledError:
+            try:
+                await self.close()
+            except BaseException:
+                pass
+            raise
+        except Exception as error:
+            try:
+                await self.close()
+            except BaseException:
+                pass
+            raise ConnectionError("IHC Bluetooth connection failed") from error
+
+    async def close(self) -> None:
+        """Stop notifications and release the active BLE client."""
+        client = self._client
+        self._client = None
+        if client is None:
+            return
+        if client.is_connected:
+            try:
+                await client.stop_notify(NOTIFY_UUID)
+            finally:
+                await client.disconnect()
+
+    async def write(self, value: bytes, *, response: bool) -> None:
+        """Write one value to the verified IHC write characteristic."""
+        if self._client is None:
+            raise ConnectionError("IHC is not connected")
+        await self._client.write_gatt_char(WRITE_UUID, value, response=response)
+
+    async def read_notify(self) -> bytes:
+        """Read d703 to acknowledge notification flow control."""
+        if self._client is None:
+            raise ConnectionError("IHC is not connected")
+        return bytes(await self._client.read_gatt_char(NOTIFY_UUID))