python-daikin-itm 0.1.0__tar.gz

python_daikin_itm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robbin Janssen
+
+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.

python_daikin_itm-0.1.0/PKG-INFO

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: python-daikin-itm
+Version: 0.1.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-email: Robbin Janssen <robbinjanssen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: aiohttp>=3.9.0
+Maintainer: Robbin Janssen
+Maintainer-email: Robbin Janssen <robbinjanssen@gmail.com>
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/robbinjanssen/python-daikin-itm
+Project-URL: Repository, https://github.com/robbinjanssen/python-daikin-itm
+Project-URL: Documentation, https://github.com/robbinjanssen/python-daikin-itm
+Project-URL: Bug Tracker, https://github.com/robbinjanssen/python-daikin-itm/issues
+Project-URL: Changelog, https://github.com/robbinjanssen/python-daikin-itm/releases
+Description-Content-Type: text/markdown
+
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE)
+
+[![GitHub Activity][commits-shield]][commits-url]
+[![PyPi Downloads][downloads-shield]][downloads-url]
+[![GitHub Last Commit][last-commit-shield]][commits-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+
+[![Code Coverage][codecov-shield]][codecov-url]
+
+[![Build Status][build-shield]][build-url]
+
+Asynchronous Python client for the Daikin intelligent Touch Manager (iTM).
+
+## About
+
+A Python package to control the indoor units connected to a Daikin
+**intelligent Touch Manager (iTM)** locally. It speaks the protocol of the iTM's
+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).
+
+## Installation
+
+```bash
+pip install python-daikin-itm
+```
+
+## Datasets
+
+### Unit
+
+This object represents the current state of an indoor unit, as shown on the
+iTM's operation panel. `fetch_units()` returns them by unit name.
+
+| Variable | Type | Description |
+| :------- | :--- | :---------- |
+| `name` | string | The name of the unit in the iTM, e.g. `1:1-04`. |
+| `power` | string | The raw on/off option as the iTM shows it, e.g. `Start`, `Stop` or a setback option. `None` when unknown. |
+| `running` | boolean | `True` when the unit is started; setback counts as not running. `None` when unknown. |
+| `state_icon` | integer | The raw state icon value of the unit. |
+| `setpoint` | integer | The current setpoint in °C. |
+| `setpoint_range` | tuple | The setpoints the unit accepts, in °C. |
+| `room_temperature` | float | The room temperature in °C, `None` when the unit doesn't report one. |
+| `mode` | string | The normalized operation mode (see below), `None` when unknown. |
+| `mode_label` | string | The operation mode as the iTM shows it (localized). |
+| `fan_icon` | integer | The raw fan speed icon. |
+| `fan_speed` | string | The fan speed (see below), `None` when unknown. |
+| `error_code` | string | The malfunction code the iTM shows, `None` when there is none. |
+| `filter_sign` | boolean | Whether the iTM shows the filter cleaning sign. |
+| `setback` | boolean | Property: whether the unit is in setback. |
+
+### Capabilities
+
+This object represents the static facts about a unit: its identity (from the
+iTM's Details screen) and what its settings dialog offers. Read it once with
+`fetch_capabilities()`; it doesn't change while running.
+
+| Variable | Type | Description |
+| :------- | :--- | :---------- |
+| `name` | string | The name of the unit in the iTM. |
+| `mode_labels` | dict | Normalized mode to the label as the iTM shows it, in the dialog's order. |
+| `fan_speed` | boolean | Whether the fan speed of this unit can be changed. |
+| `point_id` | string | The iTM management point ID, e.g. `105`. |
+| `address` | string | The bus address (`port:address`), e.g. `1:1-04`. Stable, survives renames. |
+| `unit_type` | string | The unit type as the iTM shows it. |
+| `description` | string | Free text set in the iTM for this unit. |
+| `zones` | tuple | The zone paths the unit belongs to. |
+| `modes` | tuple | Property: the normalized modes the unit offers. |
+| `key` | string | Property: a stable identifier, the bus address when known, else the name. |
+
+The fields from the Details screen (`point_id` to `zones`) are `None` (or empty)
+when the iTM doesn't show them.
+
+#### Operation modes
+
+The iTM shows localized mode labels. The client normalizes the ones it knows to
+`heat`, `cool`, `fan`, `dry` and `auto`; the original label stays available in
+`mode_label` / `mode_labels`. Which modes a unit offers depends on the unit, see
+`Capabilities.modes`.
+
+#### Fan speeds
+
+`FAN_SPEEDS` holds the fan speeds: `low`, `medium`, `high` and `auto`. Check
+`Capabilities.fan_speed` to see whether a unit lets you change it.
+
+## Usage
+
+```python
+import asyncio
+
+from daikin_itm import ItmClient
+
+
+async def main() -> None:
+    """Show example on using the iTM client."""
+    async with ItmClient(
+        "192.168.1.10",
+        "<your-username>",
+        "<your-password>",
+        zone_path=("Alles", "Binnendeel"),
+    ) as client:
+        units = await client.fetch_units()
+        for unit in units.values():
+            print(f"{unit.name}: {unit.mode} {unit.setpoint} °C, room {unit.room_temperature} °C")
+
+        capabilities = await client.fetch_capabilities()
+        for name, caps in capabilities.items():
+            print(f"{name} ({caps.key}): modes {caps.modes}, fan control: {caps.fan_speed}")
+
+        # Each write returns the unit as read back once the change shows.
+        unit = await client.set_setpoint("1:1-04", 21)
+
+        # Power, mode and fan speed can be combined in one write.
+        unit = await client.apply("1:1-04", power=True, mode="heat", fan_speed="low")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Client
+
+The host may be `"host"`, `"host:port"` or a full `http://` / `https://` URL.
+The other constructor arguments are keyword-only:
+
+| Argument | Default | Description |
+| :------- | :------ | :---------- |
+| `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`). |
+| `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. |
+| `confirm_interval` | `2.0` | Seconds between those reads. |
+| `timeout` | `30.0` | Timeout of each HTTP request in seconds. |
+
+### Methods
+
+| Method | Description |
+| :----- | :---------- |
+| `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`. |
+| `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. |
+| `set_mode(unit, mode, *, confirm=True)` | Change the operation mode. |
+| `set_fan_speed(unit, fan_speed, *, confirm=True)` | Change the fan speed. |
+| `release_saved_session()` | Log out a session a previous run left behind; returns `True` if there was one. Every call does this before logging in. A saved token the iTM answers with an HTTP error or an unreadable reply is dropped (with a warning) and left to the iTM's own timeout. |
+
+By default, a write returns the `Unit` as read back once a fresh read shows the
+change (or raises `ItmCommandError` after `confirm_timeout`). With
+`confirm=False` it returns `None` right after the write; the next write to the
+same unit first waits until that change shows, so it can't overtake it.
+
+### Sessions
+
+The iTM allows one web session at a time, so every call logs in, does its work
+and logs out. The page token is handed to a `SessionStore` after every reply,
+so a session left behind by a crash can be released on the next run. A store is
+any object with two coroutines:
+
+```python
+class SessionStore(Protocol):
+    async def load(self) -> str | None: ...
+    async def save(self, token: str | None) -> None: ...
+```
+
+- `MemorySessionStore()` (the default) keeps the token in memory.
+- `FileSessionStore(path, host)` keeps it in an owner-only file and only hands
+  it back for the host it belongs to, so a killed process can still release its
+  session on the next run.
+
+### Exceptions
+
+| Exception | Description |
+| :-------- | :---------- |
+| `ItmError` | Base class for everything this library raises. |
+| `ProtocolError` | A reply could not be decoded (not an iTM reply, or an unknown layout). |
+| `LoginRejected` | The iTM refused the login: wrong credentials, or another web session is active. |
+| `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. |
+| `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`.
+
+## Things to know about the iTM
+
+- **One web session at a time.** While a client is logged in, every other login
+  (including a browser) is refused. The library therefore never keeps a session
+  open: every call logs in, works and logs out, also on errors and
+  cancellation. If a logout isn't confirmed, the latest page token is kept in the
+  `SessionStore` so the next run can release the session. The CLI writes the
+  token to a file after every reply, so a session left behind by a crash is
+  released on the next run. The Home Assistant integration writes it to
+  `.storage` only once a session has lasted 10 s, and then after every reply, to
+  spare SD cards: a crash during a normal 1-2 s poll leaves the session to the
+  iTM's own timeout.
+- **Replies are deltas** against what the iTM believes the client shows, and it
+  never echoes a value the client picked itself. Verify a change in a *fresh*
+  session (the client does this for every write).
+- **Setpoint changes are ignored while a unit is stopped** (the client refuses
+  them).
+- **Changes take 3-8 s to reach a unit** over the Daikin bus. Every write waits
+  until a fresh read shows the new value (up to `confirm_timeout`), so the next
+  change can't overtake it; a change sent while the previous one is still
+  pending can get lost.
+- Power, mode and fan speed go through the unit's settings dialog (tick the
+  item, set it, OK, confirm "Instelling uitvoeren?" with *Ja*), so they can be
+  combined in one write. The setpoint uses the operation panel's spinner plus a
+  `TIMER` commit. All four are verified on the real device.
+- Indoor units store settings in memory with a limited number of writes
+  (Daikin: max ~7000 changes per unit per year). Don't automate setpoints in
+  tight loops; the client spaces writes per unit (`min_write_interval`, 5 s).
+- If the iTM's web UI version changes after a firmware update, the client adopts
+  the version the iTM reports and logs a warning.
+
+## Security notes
+
+- **The iTM's login is weak by design.** Its web UI sends the username plus an
+  unsalted SHA-256 of the password, without a server nonce, and over plain HTTP
+  by default. Anyone who can see the traffic can replay it to log in. This
+  client can't change the device's protocol, and it has to log in for every
+  call (the iTM allows only one session, so it can't stay logged in). Put the
+  iTM and the machine running this client on an isolated network segment, use a
+  dedicated iTM account for it, and use an `https://…` address if your iTM
+  offers HTTPS (the host accepts a full URL).
+- Replies are treated as untrusted: the decoder rejects anything that doesn't
+  fit the reply (hostile element counts, reads past the end) and replies over
+  1 MB.
+- The CLI keeps the session token in `~/.cache/daikin-itm/` (owner-only, per
+  host) and strips control characters from everything it prints.
+
+## CLI
+
+The package installs an `itm` command for debugging. Credentials come from the
+environment, or from `--creds` pointing at a JSON file with `username` and
+`password` fields (a 1Password JSON export). Set the iTM's address with `--host`
+or `ITM_HOST`.
+
+```bash
+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
+                          # 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
+itm power 1:1-09 on
+itm mode 1:1-04 heat      # heat / cool / fan / dry / auto, as offered by the unit
+itm fan 1:1-04 low        # low / medium / high / auto
+```
+
+## Protocol notes
+
+`POST /cmd/`, body `snD=<hex>`: 32-char page token, then screen ID, part ID,
+event type, data type (shorts), a number (int), an int array and a string.
+Numbers are big-endian hex, strings are a length plus raw characters. Login:
+screen 1203, part 4, string `%04d len(user) + user + sha256hex(password)`.
+Replies: new token, then screen updates with part updates (labels, combobox
+values, icon panels…). Screens used: 1 icon view (part 6 icon panel, 2 = go
+down), 4 operation panel (9 on/off, 11 setpoint). A setpoint change is a
+selection on screen 4 followed by a `TIMER` event on screen 4. Power/mode/fan
+use the settings dialog (screen 7): tick 2/17/28, radio 3/4, mode combobox 18,
+fan up 29 (icon 31: 3009 low, 3011 medium, 3013 high, 3015 auto), OK 5, then
+CLICK on the confirm dialog's ID. See `daikin_itm/protocol.py`.
+
+## Contributing
+
+This is an active open-source project. We are always open to people who want to
+use the code or contribute to it.
+
+We've set up a separate document for our
+[contribution guidelines](CONTRIBUTING.md).
+
+Thank you for being involved! :heart_eyes:
+
+## Setting up development environment
+
+This Python project is fully managed using the [uv][uv] package manager.
+
+You need at least:
+
+- Python 3.11+
+- [uv][uv-install]
+
+Install all packages, including all development requirements:
+
+```bash
+uv sync
+```
+
+uv creates a virtual environment in `.venv` and installs all necessary
+packages in it. Run commands in it with `uv run`.
+
+Set up the pre-commit checks with [prek][prek]:
+
+```bash
+uv run prek install
+```
+
+*Now you're all set to get started!*
+
+All changes are linted and tested with each commit. You can run all checks
+and tests manually, using the following command:
+
+```bash
+uv run prek run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+uv run pytest
+```
+
+No iTM is needed for the tests: `tests/fake_itm.py` simulates the behaviour that
+matters (single session, delta replies, ignored setpoints on stopped units),
+and `tests/fixtures/` holds replies captured from a real device.
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Robbin Janssen
+
+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.
+
+<!-- MARKDOWN LINKS & IMAGES -->
+[build-shield]: https://github.com/robbinjanssen/python-daikin-itm/actions/workflows/tests.yaml/badge.svg
+[build-url]: https://github.com/robbinjanssen/python-daikin-itm/actions/workflows/tests.yaml
+[commits-shield]: https://img.shields.io/github/commit-activity/y/robbinjanssen/python-daikin-itm.svg
+[commits-url]: https://github.com/robbinjanssen/python-daikin-itm/commits/main
+[codecov-shield]: https://codecov.io/gh/robbinjanssen/python-daikin-itm/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/robbinjanssen/python-daikin-itm
+[downloads-shield]: https://img.shields.io/pypi/dm/python-daikin-itm
+[downloads-url]: https://pypistats.org/packages/python-daikin-itm
+[issues-shield]: https://img.shields.io/github/issues/robbinjanssen/python-daikin-itm.svg
+[issues-url]: https://github.com/robbinjanssen/python-daikin-itm/issues
+[license-shield]: https://img.shields.io/github/license/robbinjanssen/python-daikin-itm.svg
+[last-commit-shield]: https://img.shields.io/github/last-commit/robbinjanssen/python-daikin-itm.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[pypi]: https://pypi.org/project/python-daikin-itm/
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/python-daikin-itm
+[releases-shield]: https://img.shields.io/github/release/robbinjanssen/python-daikin-itm.svg
+[releases]: https://github.com/robbinjanssen/python-daikin-itm/releases
+[stars-shield]: https://img.shields.io/github/stars/robbinjanssen/python-daikin-itm.svg
+[stars-url]: https://github.com/robbinjanssen/python-daikin-itm/stargazers
+
+[prek]: https://prek.j178.dev
+[uv]: https://docs.astral.sh/uv/
+[uv-install]: https://docs.astral.sh/uv/getting-started/installation/