python-daikin-itm 0.1.0__tar.gz → 1.0.0__tar.gz

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: python-daikin-itm
-Version: 0.1.0
+Version: 1.0.0
 Summary: Asynchronous Python client for the Daikin intelligent Touch Manager (iTM).
 Keywords: async,client,daikin,itm,intelligent touch manager,hvac
-Author: Robbin Janssen, Robin Mulder
+Author: Robbin Janssen
 Author-email: Robbin Janssen <robbinjanssen@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -52,8 +52,6 @@ A Python package to control the indoor units connected to a Daikin
 built-in web UI, so it needs no cloud service and no extra hardware: only
 network access to the iTM and a user account on it.
 
-Based on the original work by Robin Mulder (Exonet).
-
 Used by the Home Assistant integration
 [home-assistant-daikin-itm](https://github.com/robbinjanssen/home-assistant-daikin-itm).
 
@@ -135,7 +133,7 @@ async def main() -> None:
         "192.168.1.10",
         "<your-username>",
         "<your-password>",
-        zone_path=("Alles", "Binnendeel"),
+        zone_path=("Building", "Indoor units"),
     ) as client:
         units = await client.fetch_units()
         for unit in units.values():
@@ -165,7 +163,7 @@ The other constructor arguments are keyword-only:
 | :------- | :------ | :---------- |
 | `session` | `None` | An `aiohttp.ClientSession` to use; the client creates (and closes) its own otherwise. |
 | `store` | `MemorySessionStore()` | Where to keep the page token, see [Sessions](#sessions). |
-| `zone_path` | `("Alles", "Binnendeel")` | The zone path in the iTM's icon view that contains the indoor units (`DEFAULT_ZONE_PATH`). |
+| `zone_path` | `()` | The path of zone names in the iTM's icon view to the zone that contains the indoor units, e.g. `("Building", "Indoor units")`. The default (`DEFAULT_ZONE_PATH`) is the top level; use `list_zones()` to find the path. |
 | `commit_delay` | `3.0` | Seconds between a setpoint change and its commit, like the web UI. |
 | `min_write_interval` | `5.0` | Minimum seconds between two writes to the same unit. |
 | `confirm_timeout` | `30.0` | Seconds to wait for a fresh read to show a change. |
@@ -179,7 +177,7 @@ The other constructor arguments are keyword-only:
 | `fetch_units()` | Read every unit in the zone path, returns `dict[str, Unit]` by name. |
 | `fetch_unit(name)` | Read a single unit (cheaper than `fetch_units()`). |
 | `fetch_capabilities()` | Read every unit's identity and the modes and fan control it offers, returns `dict[str, Capabilities]`. This costs four requests per unit, so do it once rather than on every poll. |
-| `list_zones(path=())` | The names of the zones and units at a path, for discovery: `list_zones()` for the top level, `list_zones(("Alles",))` for what's inside `Alles`. |
+| `list_zones(path=())` | The names of the zones and units at a path, for discovery: `list_zones()` for the top level, `list_zones(("Building",))` for what's inside `Building`. |
 | `set_setpoint(unit, value, *, confirm=True)` | Change a unit's setpoint. Refused while the unit is stopped (the iTM ignores it then) or when the value is outside `setpoint_range`. |
 | `apply(unit, *, power=None, mode=None, fan_speed=None, confirm=True)` | Change power, mode and/or fan speed in one write. The request is compared with the unit as read in the write session: only what differs is sent, and a unit that already is in the requested state is returned without writing anything. |
 | `set_power(unit, on, *, confirm=True)` | Start or stop a unit. |
@@ -220,6 +218,7 @@ class SessionStore(Protocol):
 | `SessionEnded` | The iTM ended the session (it answered with a LOGOUT update), e.g. because the token was stale. |
 | `VersionMismatch` | The iTM expects another web UI version string (subclass of `SessionEnded`); carries it in `.version`. |
 | `ItmCommandError` | The iTM answered a command with a dialog, the UI was not as expected, or a change was not confirmed in time. |
+| `SetpointOutOfRange` | The unit does not accept the setpoint (subclass of `ItmCommandError`). The allowed setpoints depend on the unit and its operation mode; the ones it accepts now are in `.allowed`. |
 | `ZoneNotFound` | A zone of the zone path is not there (subclass of `ItmCommandError`); the names that are there are in `.available`. |
 
 Network errors are raised as `aiohttp.ClientError` or `TimeoutError`.
@@ -282,8 +281,9 @@ or `ITM_HOST`.
 export ITM_HOST=192.168.1.10
 export ITM_USERNAME=... ITM_PASSWORD=...  # or: --creds creds.json
 itm zones                 # top-level zones
-itm zones Alles           # zones/units inside "Alles"
-itm status                # all units in Alles/Binnendeel (--zone to change); descriptions are
+itm zones Building        # zones/units inside "Building"
+itm --zone "Building/Indoor units" status
+                          # all units in that zone (default: the top level); descriptions are
                           # cached in ~/.cache/daikin-itm/units.json (--refresh to re-read them)
 itm caps                  # modes / fan control per unit
 itm setpoint 1:1-04 21    # each write returns once the unit shows the change

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/README.md

@@ -23,8 +23,6 @@ A Python package to control the indoor units connected to a Daikin
 built-in web UI, so it needs no cloud service and no extra hardware: only
 network access to the iTM and a user account on it.
 
-Based on the original work by Robin Mulder (Exonet).
-
 Used by the Home Assistant integration
 [home-assistant-daikin-itm](https://github.com/robbinjanssen/home-assistant-daikin-itm).
 
@@ -106,7 +104,7 @@ async def main() -> None:
         "192.168.1.10",
         "<your-username>",
         "<your-password>",
-        zone_path=("Alles", "Binnendeel"),
+        zone_path=("Building", "Indoor units"),
     ) as client:
         units = await client.fetch_units()
         for unit in units.values():
@@ -136,7 +134,7 @@ The other constructor arguments are keyword-only:
 | :------- | :------ | :---------- |
 | `session` | `None` | An `aiohttp.ClientSession` to use; the client creates (and closes) its own otherwise. |
 | `store` | `MemorySessionStore()` | Where to keep the page token, see [Sessions](#sessions). |
-| `zone_path` | `("Alles", "Binnendeel")` | The zone path in the iTM's icon view that contains the indoor units (`DEFAULT_ZONE_PATH`). |
+| `zone_path` | `()` | The path of zone names in the iTM's icon view to the zone that contains the indoor units, e.g. `("Building", "Indoor units")`. The default (`DEFAULT_ZONE_PATH`) is the top level; use `list_zones()` to find the path. |
 | `commit_delay` | `3.0` | Seconds between a setpoint change and its commit, like the web UI. |
 | `min_write_interval` | `5.0` | Minimum seconds between two writes to the same unit. |
 | `confirm_timeout` | `30.0` | Seconds to wait for a fresh read to show a change. |
@@ -150,7 +148,7 @@ The other constructor arguments are keyword-only:
 | `fetch_units()` | Read every unit in the zone path, returns `dict[str, Unit]` by name. |
 | `fetch_unit(name)` | Read a single unit (cheaper than `fetch_units()`). |
 | `fetch_capabilities()` | Read every unit's identity and the modes and fan control it offers, returns `dict[str, Capabilities]`. This costs four requests per unit, so do it once rather than on every poll. |
-| `list_zones(path=())` | The names of the zones and units at a path, for discovery: `list_zones()` for the top level, `list_zones(("Alles",))` for what's inside `Alles`. |
+| `list_zones(path=())` | The names of the zones and units at a path, for discovery: `list_zones()` for the top level, `list_zones(("Building",))` for what's inside `Building`. |
 | `set_setpoint(unit, value, *, confirm=True)` | Change a unit's setpoint. Refused while the unit is stopped (the iTM ignores it then) or when the value is outside `setpoint_range`. |
 | `apply(unit, *, power=None, mode=None, fan_speed=None, confirm=True)` | Change power, mode and/or fan speed in one write. The request is compared with the unit as read in the write session: only what differs is sent, and a unit that already is in the requested state is returned without writing anything. |
 | `set_power(unit, on, *, confirm=True)` | Start or stop a unit. |
@@ -191,6 +189,7 @@ class SessionStore(Protocol):
 | `SessionEnded` | The iTM ended the session (it answered with a LOGOUT update), e.g. because the token was stale. |
 | `VersionMismatch` | The iTM expects another web UI version string (subclass of `SessionEnded`); carries it in `.version`. |
 | `ItmCommandError` | The iTM answered a command with a dialog, the UI was not as expected, or a change was not confirmed in time. |
+| `SetpointOutOfRange` | The unit does not accept the setpoint (subclass of `ItmCommandError`). The allowed setpoints depend on the unit and its operation mode; the ones it accepts now are in `.allowed`. |
 | `ZoneNotFound` | A zone of the zone path is not there (subclass of `ItmCommandError`); the names that are there are in `.available`. |
 
 Network errors are raised as `aiohttp.ClientError` or `TimeoutError`.
@@ -253,8 +252,9 @@ or `ITM_HOST`.
 export ITM_HOST=192.168.1.10
 export ITM_USERNAME=... ITM_PASSWORD=...  # or: --creds creds.json
 itm zones                 # top-level zones
-itm zones Alles           # zones/units inside "Alles"
-itm status                # all units in Alles/Binnendeel (--zone to change); descriptions are
+itm zones Building        # zones/units inside "Building"
+itm --zone "Building/Indoor units" status
+                          # all units in that zone (default: the top level); descriptions are
                           # cached in ~/.cache/daikin-itm/units.json (--refresh to re-read them)
 itm caps                  # modes / fan control per unit
 itm setpoint 1:1-04 21    # each write returns once the unit shows the change

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/daikin_itm/__init__.py

@@ -13,6 +13,7 @@ from .exceptions import (
     LoginRejected,
     ProtocolError,
     SessionEnded,
+    SetpointOutOfRange,
     VersionMismatch,
     ZoneNotFound,
 )
@@ -31,6 +32,7 @@ __all__ = [
     "ProtocolError",
     "SessionEnded",
     "SessionStore",
+    "SetpointOutOfRange",
     "Unit",
     "VersionMismatch",
     "ZoneNotFound",

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/daikin_itm/cli.py

@@ -234,11 +234,19 @@ async def _run(args: argparse.Namespace) -> None:
 def _parser() -> argparse.ArgumentParser:
     """Build the argument parser."""
     p = argparse.ArgumentParser(prog="itm", description=(__doc__ or "").splitlines()[0])
-    p.add_argument("--host", default=os.environ.get("ITM_HOST", "10.50.3.46"))
+    p.add_argument(
+        "--host",
+        default=os.environ.get("ITM_HOST"),
+        help="address of the iTM (default: $ITM_HOST)",
+    )
     p.add_argument(
         "--creds", help="JSON file with username/password fields (1Password export)"
     )
-    p.add_argument("--zone", help="zone path to the units, e.g. 'Alles/Binnendeel'")
+    p.add_argument(
+        "--zone",
+        help="zone path to the units, e.g. 'Building/Indoor units' "
+        "(default: the top level)",
+    )
     p.add_argument(
         "--session-file",
         help=f"where to keep the session token (default: per host in {CACHE_DIR})",
@@ -251,7 +259,7 @@ def _parser() -> argparse.ArgumentParser:
         help="re-read descriptions instead of using the cache",
     )
     z = sub.add_parser("zones", help="list zones/units at a path")
-    z.add_argument("path", nargs="?", help="e.g. 'Alles'")
+    z.add_argument("path", nargs="?", help="e.g. 'Building'")
     s = sub.add_parser("setpoint", help="change a unit's setpoint")
     s.add_argument("unit")
     s.add_argument("value", type=int)
@@ -279,7 +287,10 @@ def main(argv: Sequence[str] | None = None) -> None:
         argv: The arguments, defaults to the ones the process was started with.
 
     """
-    args = _parser().parse_args(argv)
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if not args.host:
+        parser.error("set the iTM's address with --host or ITM_HOST")
 
     async def runner() -> None:
         task = asyncio.current_task()

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/daikin_itm/client.py

@@ -29,6 +29,7 @@ from .exceptions import (
     LoginRejected,
     ProtocolError,
     SessionEnded,
+    SetpointOutOfRange,
     VersionMismatch,
     ZoneNotFound,
 )
@@ -95,7 +96,9 @@ ICON_BTN_TOP, ICON_BTN_DOWN, ICON_BTN_UP, ICON_PANEL = 1, 2, 3, 6
 ICON_ID_ZONE = 1000
 LOGIN_BUTTON = 4
 
-DEFAULT_ZONE_PATH = ("Alles", "Binnendeel")
+# The top level of the icon view. Most iTMs group the units in zones; pass the path
+# of zone names to them, see list_zones().
+DEFAULT_ZONE_PATH: tuple[str, ...] = ()
 
 _T = TypeVar("_T")
 
@@ -807,8 +810,7 @@ class ItmClient:
                     raise ItmCommandError(msg)
                 nums = list(current.setpoint_range)
                 if value not in nums:
-                    msg = f"{unit}: setpoint {value} outside allowed range {nums}"
-                    raise ItmCommandError(msg)
+                    raise SetpointOutOfRange(unit, value, current.setpoint_range)
                 if current.setpoint == value:
                     return current
                 await s.choose(P_SETPOINT, nums.index(value))

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/daikin_itm/exceptions.py

@@ -59,3 +59,27 @@ class ZoneNotFound(ItmCommandError):  # noqa: N818 - public API name
         super().__init__(f"{zone!r} not found here; available: {available}")
         self.zone = zone
         self.available = available
+
+
+class SetpointOutOfRange(ItmCommandError):  # noqa: N818 - public API name
+    """The unit does not accept the setpoint; carries the setpoints it does accept.
+
+    The allowed setpoints depend on the unit and its operation mode, so they may have
+    changed since the unit was last read.
+    """
+
+    def __init__(self, unit: str, value: int, allowed: tuple[int, ...]) -> None:
+        """Initialize the error.
+
+        Args:
+        ----
+            unit: The name of the unit.
+            value: The setpoint that was asked for.
+            allowed: The setpoints the unit accepts now, as read while writing.
+
+        """
+        msg = f"{unit}: setpoint {value} outside allowed range {list(allowed)}"
+        super().__init__(msg)
+        self.unit = unit
+        self.value = value
+        self.allowed = allowed

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/daikin_itm/models.py

@@ -85,7 +85,7 @@ class Capabilities:
     point_id: str | None = None  # iTM management point ID, e.g. "105"
     # Bus port:address, e.g. "1:1-04"; stable, survives renames.
     address: str | None = None
-    unit_type: str | None = None  # e.g. "Binnendeel"
+    unit_type: str | None = None  # e.g. "Indoor unit", in the iTM's language
     description: str | None = None  # free text set in the iTM
     zones: tuple[str, ...] = field(default_factory=tuple)  # zone paths of the unit
 

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-daikin-itm"
-version = "0.1.0"
+version = "1.0.0"
 description = "Asynchronous Python client for the Daikin intelligent Touch Manager (iTM)."
 license = "MIT"
 license-files = ["LICENSE"]
@@ -31,9 +31,6 @@ dependencies = ["aiohttp>=3.9.0"]
 name = "Robbin Janssen"
 email = "robbinjanssen@gmail.com"
 
-[[project.authors]]
-name = "Robin Mulder"
-
 [[project.maintainers]]
 name = "Robbin Janssen"
 email = "robbinjanssen@gmail.com"

{python_daikin_itm-0.1.0 → python_daikin_itm-1.0.0}/pyproject.toml.orig

@@ -1,12 +1,9 @@
 [project]
 name = "python-daikin-itm"
 # The version is set from the release tag by the release workflow.
-version = "0.1.0"
+version = "1.0.0"
 description = "Asynchronous Python client for the Daikin intelligent Touch Manager (iTM)."
-authors = [
-    { name = "Robbin Janssen", email = "robbinjanssen@gmail.com" },
-    { name = "Robin Mulder" },
-]
+authors = [{ name = "Robbin Janssen", email = "robbinjanssen@gmail.com" }]
 maintainers = [{ name = "Robbin Janssen", email = "robbinjanssen@gmail.com" }]
 license = "MIT"
 license-files = ["LICENSE"]