aiocomexio

Asyncio-native Python client for the Comexio IO-Server, a local building-automation controller.

No dependency on Home Assistant or any other framework — usable as a standalone library. It will provide the communication layer of the homeassistant-comexio integration.

Status: pre-alpha. The code is being moved over from the integration step by step. So far: admin login, read access (including live values of physical IOs), value writes, the Web-IO lifecycle, marker / KNX object management and function plan editing — plans, elements, wires, block instance settings, run / stop (ComexioClient), admin page scraping (aiocomexio.scrape), config parsing (aiocomexio.config), KNX DPT tables (aiocomexio.knx), Web-IO command builders (aiocomexio.webio), function plan rendering (with block settings in the hover text) and diffing (aiocomexio.function_plan) and the block-type reference catalog that resolves Comexio catalog ids per server by stable key (aiocomexio.reference_catalog). The API may still change.

Installation

pip install aiocomexio

Usage

The client works on an aiohttp.ClientSession you create and close yourself. session_kwargs() gives it the settings Comexio needs (a cookie jar that keeps the admin login for an IP-address host, a request timeout; progress_log_interval=10 adds a "still waiting" log line for slow requests). Give every client its own session: login() clears the session's cookie jar. Value writes (set_marker_value, set_io_value, set_knx_value) go through Comexio's /api/ with a separate API user: pass api_username / api_password to the client. Every call either returns data or raises a ComexioError subclass (ComexioAuthenticationError, ComexioConnectionError, ComexioResponseError, ComexioDataError, ComexioRequestRejectedError for a write the server refused, ComexioCreatedWithoutIdError for a create the server confirmed but whose id could not be read back — the object exists, do not create it again). One exception: the value setters raise a plain ValueError, which is not a ComexioError, for a non-finite float (nan, inf) before sending anything — catch it separately if your values can be non-finite.

import asyncio

import aiohttp

from aiocomexio import ComexioClient, session_kwargs
from aiocomexio.config import parse_config


async def main() -> None:
    host = "192.168.0.20"
    async with aiohttp.ClientSession(**session_kwargs()) as session:
        client = ComexioClient(host, "admin", "secret", session=session)
        await client.login()
        raw = await client.get_raw_config()
        config = parse_config(raw.variables, io_types=raw.io_types, io_input_types=raw.io_input_types)
        print(len(config["markers"]), "markers on Comexio", raw.comexio_version)


asyncio.run(main())

Development

pip install -e ".[dev]"
pre-commit install

ruff check .            # lint
ruff format --check .   # formatting check; drop --check to auto-format
mypy                    # strict type check (src/aiocomexio)
pytest                  # tests

License

MIT