pyheatlink 0.1.0__tar.gz

pyheatlink-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sslivins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyheatlink-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pyheatlink
+Version: 0.1.0
+Summary: Async Python client for HeatLink, the local controller for Mitsubishi mini-split heads
+Author-email: Stefan Slivinski <sslivins@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sslivins/pyheatlink
+Project-URL: Bug Tracker, https://github.com/sslivins/pyheatlink/issues
+Project-URL: Firmware, https://github.com/sslivins/heatlink
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Home Automation
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: tests
+Requires-Dist: pytest>=8.3.4; extra == "tests"
+Requires-Dist: pytest-asyncio>=0.25.3; extra == "tests"
+Requires-Dist: pytest-cov>=5.0.0; extra == "tests"
+Requires-Dist: ruff>=0.6.0; extra == "tests"
+Requires-Dist: mypy>=1.10.0; extra == "tests"
+Dynamic: license-file
+
+# pyheatlink
+
+Async Python client for [HeatLink](https://github.com/sslivins/heatlink), the
+local Wi-Fi controller for Mitsubishi mini-split heads (CN105). It talks to each
+head's HTTP API on your LAN, with no cloud involved. The
+[Home Assistant integration](https://github.com/sslivins/hass-heatlink) is built on it.
+
+Needs HeatLink firmware 1.5 or newer (the first version with `/api/info`).
+
+## Install
+
+```bash
+pip install pyheatlink
+```
+
+## Usage
+
+```python
+import asyncio
+import aiohttp
+from pyheatlink import HeatLinkClient, Feature
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        head = HeatLinkClient("192.168.1.151", session, token="hlt1_...")
+
+        info = await head.get_info()            # public, no token needed
+        print(info.name, info.fw, info.group)
+
+        s = await head.get_settings()
+        print(s.power, s.mode, s.temperature, s.room_temperature)
+
+        await head.set_climate(mode="heat", temperature=21)
+
+        if info.has(Feature.REMOTE_TEMP):
+            await head.set_remote_temp(20.5, ttl_s=600)   # resend before it expires
+
+asyncio.run(main())
+```
+
+### Tokens
+
+Create an integration token in the head's web UI (**Settings → API Access → Integration tokens**)
+with the scope you need:
+
+| Scope     | Allows |
+|-----------|--------|
+| `read`    | every read |
+| `control` | climate changes and the remote temperature feed |
+| `admin`   | off-at-setpoint, Tandem, updates, restart, diagnostics |
+
+Heads sharing an outdoor unit can mint tokens for each other, so one token is
+enough to set up the whole group:
+
+```python
+group = await head.get_group()
+for peer in group.members:
+    grant = await head.create_peer_token(peer.ip, peer.uid)
+    print(peer.name, grant.token)   # same scope as `head`'s token
+```
+
+### Discovery
+
+Heads advertise `_mmhvac._tcp.local.` over mDNS with their `uid` in the TXT
+record (`pyheatlink.const.ZEROCONF_TYPE`).
+
+## API
+
+| Method | Endpoint | Scope |
+|--------|----------|-------|
+| `get_info()` | `GET /api/info` | none |
+| `get_house_summary()` | `GET /api/house/summary` | none |
+| `get_settings()` | `GET /api/settings` | read |
+| `get_status()` | `GET /api/status` | read |
+| `get_capabilities()` | `GET /api/capabilities` | read |
+| `get_park()` | `GET /api/park` | read |
+| `get_group()` | `GET /api/group` (includes Tandem) | read |
+| `get_sensors()` | `GET /api/sensors` | read |
+| `get_events(since, limit)` | `GET /api/events` | read |
+| `get_update()` / `get_ota_status()` | `GET /api/update`, `/api/ota/status` | read |
+| `set_climate(power, mode, temperature, fan, vane, wide_vane)` | `POST /api/settings` | control |
+| `set_remote_temp(temp, ttl_s)` / `clear_remote_temp()` | `POST /api/remote-temp` | control |
+| `set_park(...)` | `POST /api/park` | admin |
+| `set_tandem(...)` | `POST /api/group/slice` | admin |
+| `install_update()`, `restart()`, `reset_diag(counter)` | | admin |
+| `request_ticket(uid)`, `redeem_ticket(ticket)`, `create_peer_token(host, uid)` | `/api/tokens/*` | token |
+
+All models are frozen dataclasses that tolerate missing or unknown fields; the
+full payload is kept in `.raw`.
+
+Errors all derive from `HeatLinkError`:
+
+| Exception | When |
+|-----------|------|
+| `HeatLinkConnectionError` | unreachable, timed out, or unreadable reply |
+| `HeatLinkAuthError` | 401: missing, wrong or revoked token |
+| `HeatLinkScopeError` | 403: token scope too low |
+| `HeatLinkConflictError` | 409: refused in the current state (e.g. a room sensor owns the temperature) |
+| `HeatLinkRateLimitError` | 429: locked out after failed attempts |
+| `HeatLinkUnsupportedError` | firmware older than 1.5 |
+| `HeatLinkResponseError` | any other HTTP error (`.status`, `.message`) |
+
+Calls on one client never overlap, and each has a timeout (default 10 s).
+
+## Command line
+
+```bash
+pyheatlink 192.168.1.151 info
+pyheatlink 192.168.1.151 --token hlt1_... set --mode heat --temp 21
+pyheatlink 192.168.1.151 remote-temp 20.5 --ttl 600
+pyheatlink 192.168.1.151 remote-temp clear
+```
+
+`HEATLINK_TOKEN` in the environment works too.
+
+## Development
+
+```bash
+pip install -e .[tests]
+ruff check src tests && ruff format --check src tests
+mypy src/pyheatlink
+pytest --cov=src/pyheatlink
+```
+
+Tests run against a local fake head serving responses captured from real
+firmware (`tests/fixtures`).
+
+Releases are automatic: merging to `main` publishes the version in
+`pyproject.toml` to PyPI and bumps the patch version.

pyheatlink-0.1.0/README.md

@@ -0,0 +1,129 @@
+# pyheatlink
+
+Async Python client for [HeatLink](https://github.com/sslivins/heatlink), the
+local Wi-Fi controller for Mitsubishi mini-split heads (CN105). It talks to each
+head's HTTP API on your LAN, with no cloud involved. The
+[Home Assistant integration](https://github.com/sslivins/hass-heatlink) is built on it.
+
+Needs HeatLink firmware 1.5 or newer (the first version with `/api/info`).
+
+## Install
+
+```bash
+pip install pyheatlink
+```
+
+## Usage
+
+```python
+import asyncio
+import aiohttp
+from pyheatlink import HeatLinkClient, Feature
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        head = HeatLinkClient("192.168.1.151", session, token="hlt1_...")
+
+        info = await head.get_info()            # public, no token needed
+        print(info.name, info.fw, info.group)
+
+        s = await head.get_settings()
+        print(s.power, s.mode, s.temperature, s.room_temperature)
+
+        await head.set_climate(mode="heat", temperature=21)
+
+        if info.has(Feature.REMOTE_TEMP):
+            await head.set_remote_temp(20.5, ttl_s=600)   # resend before it expires
+
+asyncio.run(main())
+```
+
+### Tokens
+
+Create an integration token in the head's web UI (**Settings → API Access → Integration tokens**)
+with the scope you need:
+
+| Scope     | Allows |
+|-----------|--------|
+| `read`    | every read |
+| `control` | climate changes and the remote temperature feed |
+| `admin`   | off-at-setpoint, Tandem, updates, restart, diagnostics |
+
+Heads sharing an outdoor unit can mint tokens for each other, so one token is
+enough to set up the whole group:
+
+```python
+group = await head.get_group()
+for peer in group.members:
+    grant = await head.create_peer_token(peer.ip, peer.uid)
+    print(peer.name, grant.token)   # same scope as `head`'s token
+```
+
+### Discovery
+
+Heads advertise `_mmhvac._tcp.local.` over mDNS with their `uid` in the TXT
+record (`pyheatlink.const.ZEROCONF_TYPE`).
+
+## API
+
+| Method | Endpoint | Scope |
+|--------|----------|-------|
+| `get_info()` | `GET /api/info` | none |
+| `get_house_summary()` | `GET /api/house/summary` | none |
+| `get_settings()` | `GET /api/settings` | read |
+| `get_status()` | `GET /api/status` | read |
+| `get_capabilities()` | `GET /api/capabilities` | read |
+| `get_park()` | `GET /api/park` | read |
+| `get_group()` | `GET /api/group` (includes Tandem) | read |
+| `get_sensors()` | `GET /api/sensors` | read |
+| `get_events(since, limit)` | `GET /api/events` | read |
+| `get_update()` / `get_ota_status()` | `GET /api/update`, `/api/ota/status` | read |
+| `set_climate(power, mode, temperature, fan, vane, wide_vane)` | `POST /api/settings` | control |
+| `set_remote_temp(temp, ttl_s)` / `clear_remote_temp()` | `POST /api/remote-temp` | control |
+| `set_park(...)` | `POST /api/park` | admin |
+| `set_tandem(...)` | `POST /api/group/slice` | admin |
+| `install_update()`, `restart()`, `reset_diag(counter)` | | admin |
+| `request_ticket(uid)`, `redeem_ticket(ticket)`, `create_peer_token(host, uid)` | `/api/tokens/*` | token |
+
+All models are frozen dataclasses that tolerate missing or unknown fields; the
+full payload is kept in `.raw`.
+
+Errors all derive from `HeatLinkError`:
+
+| Exception | When |
+|-----------|------|
+| `HeatLinkConnectionError` | unreachable, timed out, or unreadable reply |
+| `HeatLinkAuthError` | 401: missing, wrong or revoked token |
+| `HeatLinkScopeError` | 403: token scope too low |
+| `HeatLinkConflictError` | 409: refused in the current state (e.g. a room sensor owns the temperature) |
+| `HeatLinkRateLimitError` | 429: locked out after failed attempts |
+| `HeatLinkUnsupportedError` | firmware older than 1.5 |
+| `HeatLinkResponseError` | any other HTTP error (`.status`, `.message`) |
+
+Calls on one client never overlap, and each has a timeout (default 10 s).
+
+## Command line
+
+```bash
+pyheatlink 192.168.1.151 info
+pyheatlink 192.168.1.151 --token hlt1_... set --mode heat --temp 21
+pyheatlink 192.168.1.151 remote-temp 20.5 --ttl 600
+pyheatlink 192.168.1.151 remote-temp clear
+```
+
+`HEATLINK_TOKEN` in the environment works too.
+
+## Development
+
+```bash
+pip install -e .[tests]
+ruff check src tests && ruff format --check src tests
+mypy src/pyheatlink
+pytest --cov=src/pyheatlink
+```
+
+Tests run against a local fake head serving responses captured from real
+firmware (`tests/fixtures`).
+
+Releases are automatic: merging to `main` publishes the version in
+`pyproject.toml` to PyPI and bumps the patch version.

pyheatlink-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyheatlink"
+version = "0.1.0"
+description = "Async Python client for HeatLink, the local controller for Mitsubishi mini-split heads"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+  { name = "Stefan Slivinski", email = "sslivins@gmail.com" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Home Automation",
+    "Framework :: AsyncIO",
+    "Typing :: Typed"
+]
+dependencies = [
+    "aiohttp>=3.9.0"
+]
+
+[project.optional-dependencies]
+tests = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.25.3",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.6.0",
+    "mypy>=1.10.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/sslivins/pyheatlink"
+"Bug Tracker" = "https://github.com/sslivins/pyheatlink/issues"
+"Firmware" = "https://github.com/sslivins/heatlink"
+
+[project.scripts]
+pyheatlink = "pyheatlink.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pyheatlink = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

pyheatlink-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyheatlink-0.1.0/src/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-0.1.0/src/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())