pyheatlink 0.1.0__py3-none-any.whl

pyheatlink/__init__.py

@@ -0,0 +1,76 @@
+"""Async client for HeatLink, the local controller for Mitsubishi mini-split heads."""
+
+from .client import HeatLinkClient
+from .const import Feature, Mode, Power, Scope
+from .errors import (
+    HeatLinkAuthError,
+    HeatLinkConflictError,
+    HeatLinkConnectionError,
+    HeatLinkError,
+    HeatLinkNotFoundError,
+    HeatLinkRateLimitError,
+    HeatLinkResponseError,
+    HeatLinkScopeError,
+    HeatLinkUnsupportedError,
+)
+from .models import (
+    Capabilities,
+    Event,
+    EventLog,
+    Group,
+    GroupMember,
+    HouseSummary,
+    Info,
+    OtaStatus,
+    ParkConfig,
+    ParkStatus,
+    RemoteTemp,
+    RemoteTempLease,
+    RoomSensor,
+    Sensors,
+    Settings,
+    Status,
+    Tandem,
+    TandemMember,
+    Ticket,
+    TokenGrant,
+    UpdateInfo,
+)
+
+__all__ = [
+    "Capabilities",
+    "Event",
+    "EventLog",
+    "Feature",
+    "Group",
+    "GroupMember",
+    "HeatLinkAuthError",
+    "HeatLinkClient",
+    "HeatLinkConflictError",
+    "HeatLinkConnectionError",
+    "HeatLinkError",
+    "HeatLinkNotFoundError",
+    "HeatLinkRateLimitError",
+    "HeatLinkResponseError",
+    "HeatLinkScopeError",
+    "HeatLinkUnsupportedError",
+    "HouseSummary",
+    "Info",
+    "Mode",
+    "OtaStatus",
+    "ParkConfig",
+    "ParkStatus",
+    "Power",
+    "RemoteTemp",
+    "RemoteTempLease",
+    "RoomSensor",
+    "Scope",
+    "Sensors",
+    "Settings",
+    "Status",
+    "Tandem",
+    "TandemMember",
+    "Ticket",
+    "TokenGrant",
+    "UpdateInfo",
+]

pyheatlink/__main__.py

@@ -0,0 +1,87 @@
+"""Small command-line tool: ``pyheatlink HOST [--token T] COMMAND``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import dataclasses
+import json
+import os
+import sys
+from typing import Any
+
+from .client import HeatLinkClient
+from .errors import HeatLinkError
+
+_READS = {
+    "info": "get_info",
+    "summary": "get_house_summary",
+    "settings": "get_settings",
+    "status": "get_status",
+    "capabilities": "get_capabilities",
+    "park": "get_park",
+    "group": "get_group",
+    "sensors": "get_sensors",
+    "events": "get_events",
+    "update": "get_update",
+    "ota": "get_ota_status",
+}
+
+
+def _dump(obj: Any) -> str:
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        raw = getattr(obj, "raw", None)
+        obj = raw if raw else dataclasses.asdict(obj)
+    return json.dumps(obj, indent=2, default=list, ensure_ascii=False)
+
+
+async def _run(args: argparse.Namespace) -> int:
+    async with HeatLinkClient(args.host, token=args.token, timeout=args.timeout) as client:
+        if args.command in _READS:
+            result = await getattr(client, _READS[args.command])()
+        elif args.command == "set":
+            await client.set_climate(
+                power=None if args.power is None else args.power == "on",
+                mode=args.mode,
+                temperature=args.temp,
+                fan=args.fan,
+            )
+            result = await client.get_settings()
+        elif args.command == "remote-temp":
+            result = (
+                await client.clear_remote_temp()
+                if args.value == "clear"
+                else await client.set_remote_temp(float(args.value), args.ttl)
+            )
+        else:  # pragma: no cover - argparse rejects anything else
+            return 2
+    print(_dump(result))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="pyheatlink", description=__doc__)
+    p.add_argument("host")
+    p.add_argument("--token", default=os.environ.get("HEATLINK_TOKEN"))
+    p.add_argument("--timeout", type=float, default=10.0)
+    sub = p.add_subparsers(dest="command", required=True)
+    for name in _READS:
+        sub.add_parser(name)
+    s = sub.add_parser("set")
+    s.add_argument("--power", choices=["on", "off"])
+    s.add_argument("--mode")
+    s.add_argument("--temp", type=float)
+    s.add_argument("--fan")
+    r = sub.add_parser("remote-temp")
+    r.add_argument("value", help="degrees C, or 'clear'")
+    r.add_argument("--ttl", type=int, default=600)
+    args = p.parse_args(argv)
+    try:
+        return asyncio.run(_run(args))
+    except (HeatLinkError, ValueError) as err:
+        print(f"error: {err}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyheatlink/client.py

@@ -0,0 +1,374 @@
+"""Async HTTP client for one HeatLink head."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any, Self
+
+import aiohttp
+
+from .const import (
+    DEFAULT_PORT,
+    DEFAULT_TIMEOUT,
+    DIAG_COUNTERS,
+    REMOTE_TEMP_TTL_DEFAULT,
+    REMOTE_TEMP_TTL_MAX,
+    REMOTE_TEMP_TTL_MIN,
+)
+from .errors import (
+    HeatLinkAuthError,
+    HeatLinkConflictError,
+    HeatLinkConnectionError,
+    HeatLinkNotFoundError,
+    HeatLinkRateLimitError,
+    HeatLinkResponseError,
+    HeatLinkScopeError,
+    HeatLinkUnsupportedError,
+)
+from .models import (
+    Capabilities,
+    EventLog,
+    Group,
+    HouseSummary,
+    Info,
+    OtaStatus,
+    ParkConfig,
+    RemoteTempLease,
+    Sensors,
+    Settings,
+    Status,
+    Tandem,
+    Ticket,
+    TokenGrant,
+    UpdateInfo,
+)
+
+_STATUS_ERRORS: dict[int, type[HeatLinkResponseError]] = {
+    401: HeatLinkAuthError,
+    403: HeatLinkScopeError,
+    404: HeatLinkNotFoundError,
+    409: HeatLinkConflictError,
+    429: HeatLinkRateLimitError,
+}
+
+
+def _base_url(host: str, port: int) -> str:
+    host = host.strip().rstrip("/")
+    if "://" in host:
+        return host
+    if ":" in host and not host.startswith("["):
+        if host.count(":") > 1:
+            host = f"[{host}]"
+        else:
+            return f"http://{host}"
+    return f"http://{host}" if port == DEFAULT_PORT else f"http://{host}:{port}"
+
+
+def _drop_none(**kwargs: Any) -> dict[str, Any]:
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+class HeatLinkClient:
+    """Talks to one head over its local HTTP API.
+
+    Calls on one client never overlap (the firmware's HTTP server is small),
+    and each has a hard timeout. Pass a shared ``aiohttp.ClientSession``
+    (Home Assistant's, for instance); otherwise the client makes its own and
+    closes it in :meth:`close`.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        token: str | None = None,
+        port: int = DEFAULT_PORT,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.host = host
+        self.token = token
+        self._base = _base_url(host, port)
+        self._session = session
+        self._own_session = session is None
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._lock = asyncio.Lock()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._own_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    @property
+    def base_url(self) -> str:
+        return self._base
+
+    # ── transport ──────────────────────────────────────────────────────
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+        auth: bool = True,
+    ) -> Any:
+        """Send one request and return the decoded JSON body (or ``None``)."""
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+            self._own_session = True
+        headers = {"Accept": "application/json"}
+        if auth and self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        url = f"{self._base}{path}"
+        async with self._lock:
+            try:
+                async with self._session.request(
+                    method,
+                    url,
+                    json=dict(body) if body is not None else None,
+                    params=dict(params) if params else None,
+                    headers=headers,
+                    timeout=self._timeout,
+                ) as resp:
+                    text = await resp.text()
+                    status = resp.status
+            except TimeoutError as err:
+                raise HeatLinkConnectionError(f"Timed out talking to {self.host}") from err
+            except aiohttp.ClientError as err:
+                raise HeatLinkConnectionError(f"Can't reach {self.host}: {err}") from err
+
+        if status >= 400:
+            raise _STATUS_ERRORS.get(status, HeatLinkResponseError)(status, _error_message(text))
+        if not text.strip():
+            return None
+        try:
+            return json.loads(text)
+        except ValueError as err:
+            raise HeatLinkConnectionError(f"Unreadable reply from {self.host}") from err
+
+    async def _get(self, path: str, **kw: Any) -> dict[str, Any]:
+        return _obj(await self.request("GET", path, **kw))
+
+    async def _post(self, path: str, body: Mapping[str, Any] | None = None, **kw: Any) -> Any:
+        return await self.request("POST", path, body=body if body is not None else {}, **kw)
+
+    # ── identity (no auth) ─────────────────────────────────────────────
+
+    async def get_info(self) -> Info:
+        """Identity, auth state and feature flags. Needs no token.
+
+        Raises :class:`HeatLinkUnsupportedError` for firmware older than 1.5,
+        which has no ``/api/info``.
+        """
+        try:
+            return Info.from_dict(await self._get("/api/info", auth=False))
+        except HeatLinkNotFoundError as err:
+            raise HeatLinkUnsupportedError(
+                f"{self.host} runs firmware without /api/info (needs 1.5 or newer)"
+            ) from err
+
+    async def get_house_summary(self) -> HouseSummary:
+        return HouseSummary.from_dict(await self._get("/api/house/summary", auth=False))
+
+    # ── reads ──────────────────────────────────────────────────────────
+
+    async def get_settings(self) -> Settings:
+        return Settings.from_dict(await self._get("/api/settings"))
+
+    async def get_status(self) -> Status:
+        return Status.from_dict(await self._get("/api/status"))
+
+    async def get_capabilities(self) -> Capabilities:
+        return Capabilities.from_dict(await self._get("/api/capabilities"))
+
+    async def get_park(self) -> ParkConfig:
+        return ParkConfig.from_dict(await self._get("/api/park"))
+
+    async def get_group(self) -> Group:
+        return Group.from_dict(await self._get("/api/group"))
+
+    async def get_sensors(self) -> Sensors:
+        return Sensors.from_dict(await self._get("/api/sensors"))
+
+    async def get_events(self, since: int = 0, limit: int = 100) -> EventLog:
+        return EventLog.from_dict(
+            await self._get("/api/events", params={"since": since, "limit": limit})
+        )
+
+    async def get_update(self) -> UpdateInfo:
+        return UpdateInfo.from_dict(await self._get("/api/update"))
+
+    async def get_ota_status(self) -> OtaStatus:
+        return OtaStatus.from_dict(await self._get("/api/ota/status"))
+
+    # ── control (control scope) ────────────────────────────────────────
+
+    async def set_climate(
+        self,
+        *,
+        power: bool | None = None,
+        mode: str | None = None,
+        temperature: float | None = None,
+        fan: str | None = None,
+        vane: str | None = None,
+        wide_vane: str | None = None,
+    ) -> None:
+        """Change any mix of climate settings in one call.
+
+        Setting ``mode`` also turns the head on unless ``power=False`` is
+        passed with it, in which case the mode is stored and the head stays
+        off.
+        """
+        body = _drop_none(
+            mode=mode.upper() if mode is not None else None,
+            power=None if power is None else ("ON" if power else "OFF"),
+            temperature=temperature,
+            fan=fan.upper() if fan is not None else None,
+            vane=vane.upper() if vane is not None else None,
+            wideVane=wide_vane,
+        )
+        if not body:
+            raise ValueError("set_climate needs at least one setting")
+        await self._post("/api/settings", body)
+
+    async def turn_on(self) -> None:
+        await self.set_climate(power=True)
+
+    async def turn_off(self) -> None:
+        await self.set_climate(power=False)
+
+    async def set_remote_temp(
+        self, temp: float, ttl_s: int = REMOTE_TEMP_TTL_DEFAULT
+    ) -> RemoteTempLease:
+        """Feed the unit a room temperature (°C) from an outside sensor.
+
+        The head uses it until ``ttl_s`` runs out, so send it again before
+        then to keep the feed going. Raises :class:`HeatLinkConflictError`
+        while a paired room sensor is feeding the head.
+        """
+        if not REMOTE_TEMP_TTL_MIN <= ttl_s <= REMOTE_TEMP_TTL_MAX:
+            raise ValueError(f"ttl_s must be {REMOTE_TEMP_TTL_MIN}-{REMOTE_TEMP_TTL_MAX}")
+        return RemoteTempLease.from_dict(
+            _obj(await self._post("/api/remote-temp", {"temp": temp, "ttl_s": ttl_s}))
+        )
+
+    async def clear_remote_temp(self) -> RemoteTempLease:
+        """End the remote temperature feed now."""
+        return RemoteTempLease.from_dict(_obj(await self._post("/api/remote-temp", {"temp": None})))
+
+    # ── admin ──────────────────────────────────────────────────────────
+
+    async def set_park(
+        self,
+        *,
+        enabled: bool | None = None,
+        delta_c: float | None = None,
+        min_off_s: int | None = None,
+        probe_enabled: bool | None = None,
+        probe_interval_s: int | None = None,
+        probe_duration_s: int | None = None,
+    ) -> ParkConfig:
+        """Change off-at-setpoint settings. Returns the applied config."""
+        body = _drop_none(
+            enabled=enabled,
+            delta_c=delta_c,
+            min_off_s=min_off_s,
+            probe_enabled=probe_enabled,
+            probe_interval_s=probe_interval_s,
+            probe_duration_s=probe_duration_s,
+        )
+        if not body:
+            raise ValueError("set_park needs at least one setting")
+        return ParkConfig.from_dict(_obj(await self._post("/api/park", body)))
+
+    async def set_tandem(
+        self,
+        *,
+        enabled: bool | None = None,
+        min_slice_s: int | None = None,
+        max_slice_s: int | None = None,
+        settle_s: int | None = None,
+    ) -> Tandem:
+        """Change Tandem (heat/cool time-slicing) for the whole outdoor unit."""
+        body = _drop_none(
+            enabled=enabled, min_slice_s=min_slice_s, max_slice_s=max_slice_s, settle_s=settle_s
+        )
+        if not body:
+            raise ValueError("set_tandem needs at least one setting")
+        return Tandem.from_dict(_obj(await self._post("/api/group/slice", body)))
+
+    async def install_update(self) -> None:
+        """Start installing the latest firmware. Watch :meth:`get_ota_status`."""
+        await self._post("/api/update/install")
+
+    async def restart(self) -> None:
+        await self._post("/api/system/restart")
+
+    async def reset_diag(self, counter: str) -> None:
+        """Reset a diagnostic counter: ``brownout``, ``wifi-drops`` or ``vin-min``."""
+        if counter not in DIAG_COUNTERS:
+            raise ValueError(f"counter must be one of {', '.join(DIAG_COUNTERS)}")
+        await self._post(f"/api/diag/reset-{counter}")
+
+    # ── token tickets ──────────────────────────────────────────────────
+
+    async def request_ticket(self, uid: str) -> Ticket:
+        """Ask this head for a ticket that mints a token on group peer ``uid``.
+
+        Needs an integration token; the new token gets the same scope.
+        """
+        return Ticket.from_dict(_obj(await self._post("/api/tokens/ticket", {"uid": uid})))
+
+    async def redeem_ticket(self, ticket: Ticket) -> TokenGrant:
+        """Turn a ticket from a peer into a token on this head. Needs no auth."""
+        return TokenGrant.from_dict(
+            _obj(
+                await self._post(
+                    "/api/tokens/redeem",
+                    {"ticket": ticket.ticket, "label": ticket.label},
+                    auth=False,
+                )
+            )
+        )
+
+    async def create_peer_token(self, peer_host: str, uid: str) -> TokenGrant:
+        """Mint a token on group peer ``uid`` at ``peer_host`` using this head's token."""
+        ticket = await self.request_ticket(uid)
+        peer = HeatLinkClient(
+            peer_host,
+            self._session,
+            timeout=self._timeout.total or DEFAULT_TIMEOUT,
+        )
+        return await peer.redeem_ticket(ticket)
+
+
+def _obj(data: Any) -> dict[str, Any]:
+    if isinstance(data, dict):
+        return data
+    raise HeatLinkConnectionError("Expected a JSON object in the reply")
+
+
+def _error_message(text: str) -> str:
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return text.strip()[:200]
+    if isinstance(data, dict) and isinstance(data.get("error"), str):
+        return str(data["error"])
+    return text.strip()[:200]

pyheatlink/const.py

@@ -0,0 +1,86 @@
+"""Constants shared by the HeatLink HTTP API."""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+from typing import Final
+
+DEFAULT_PORT: Final = 80
+DEFAULT_TIMEOUT: Final = 10.0
+
+ZEROCONF_TYPE: Final = "_mmhvac._tcp.local."
+
+#: Highest /api/info ``api_version`` this library was written against.
+SUPPORTED_API_VERSION: Final = 1
+
+REMOTE_TEMP_TTL_MIN: Final = 60
+REMOTE_TEMP_TTL_MAX: Final = 3600
+REMOTE_TEMP_TTL_DEFAULT: Final = 600
+
+
+class Scope(StrEnum):
+    """Integration token scopes, weakest first."""
+
+    READ = "read"
+    CONTROL = "control"
+    ADMIN = "admin"
+
+
+class Feature(StrEnum):
+    """Feature flags reported in /api/info ``features``."""
+
+    TOKENS = "tokens"
+    TOKEN_TICKETS = "token_tickets"
+    EVENTS = "events"
+    HISTORY = "history"
+    PARK = "park"
+    ROOM_SENSORS = "room_sensors"
+    GROUP = "group"
+    TANDEM = "tandem"
+    REMOTE_TEMP = "remote_temp"
+    FAULT = "fault"
+    SHARED_FIELDS = "shared_fields"
+    MQTT_DISCOVERY_SWITCH = "mqtt_discovery_switch"
+
+
+class Power(StrEnum):
+    ON = "ON"
+    OFF = "OFF"
+
+
+class Mode(StrEnum):
+    HEAT = "HEAT"
+    DRY = "DRY"
+    COOL = "COOL"
+    FAN = "FAN"
+    AUTO = "AUTO"
+
+
+FAN_SPEEDS: Final = ("AUTO", "QUIET", "1", "2", "3", "4")
+VANE_POSITIONS: Final = ("AUTO", "1", "2", "3", "4", "5", "SWING")
+WIDE_VANE_POSITIONS: Final = ("<<", "<", "|", ">", ">>", "<>", "SWING")
+
+
+class EventCategory(IntEnum):
+    MODE = 0
+    POWER = 1
+    SETPOINT = 2
+    FAN = 3
+    GROUP = 4
+    MEMBERSHIP = 5
+    OTA = 6
+    NET = 7
+    UNIT = 8
+    FAULT = 9
+    SYSTEM = 10
+
+
+class EventActor(IntEnum):
+    SYSTEM = 0
+    WEB_UI = 1
+    HOME_ASSISTANT = 2
+    GROUP = 3
+    LOCAL = 4
+
+
+DIAG_COUNTERS: Final = ("brownout", "wifi-drops", "vin-min")

pyheatlink/errors.py

@@ -0,0 +1,48 @@
+"""Exceptions raised by pyheatlink."""
+
+from __future__ import annotations
+
+
+class HeatLinkError(Exception):
+    """Base class for every pyheatlink error."""
+
+
+class HeatLinkConnectionError(HeatLinkError):
+    """The head could not be reached, timed out, or sent an unreadable reply."""
+
+
+class HeatLinkResponseError(HeatLinkError):
+    """The head answered with an HTTP error status."""
+
+    def __init__(self, status: int, message: str = "") -> None:
+        self.status = status
+        self.message = message
+        super().__init__(f"HTTP {status}: {message}" if message else f"HTTP {status}")
+
+
+class HeatLinkAuthError(HeatLinkResponseError):
+    """401: the token is missing, wrong or revoked (or a ticket is invalid)."""
+
+
+class HeatLinkScopeError(HeatLinkResponseError):
+    """403: the token is valid but its scope doesn't allow this call."""
+
+
+class HeatLinkNotFoundError(HeatLinkResponseError):
+    """404: unknown endpoint (older firmware) or unknown target."""
+
+
+class HeatLinkConflictError(HeatLinkResponseError):
+    """409: the head refused because of its current state.
+
+    For example: a paired room sensor owns the room temperature, the head is
+    not in a group, or an update is already running.
+    """
+
+
+class HeatLinkRateLimitError(HeatLinkResponseError):
+    """429: locked out after too many failed attempts."""
+
+
+class HeatLinkUnsupportedError(HeatLinkError):
+    """The head's firmware doesn't advertise the feature this call needs."""