moat-link-knx 0.20.0__tar.gz

moat_link_knx-0.20.0/LICENSE.txt

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) Matthias Urlichs

moat_link_knx-0.20.0/Makefile

@@ -0,0 +1,14 @@
+#!/usr/bin/make -f
+
+PACKAGE = moat-link-knx
+MAKEINCL ?= $(shell python3 -mmoat src path)/make/py
+
+ifneq ($(wildcard $(MAKEINCL)),)
+include $(MAKEINCL)
+# availabe via http://github.com/smurfix/sourcemgr
+
+else
+%:
+	@echo "Please fix 'python3 -mmoat src path'."
+	@exit 1
+endif

moat_link_knx-0.20.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: moat-link-knx
+Version: 0.20.0
+Summary: KNX bus connector for MoaT-Link
+Author-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AnyIO
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.2
+Requires-Dist: asyncclick~=8.3
+Requires-Dist: attrs
+Requires-Dist: moat-util~=0.63.0
+Requires-Dist: moat-link~=0.8.0
+Requires-Dist: moat-lib-config~=0.2.0
+Requires-Dist: moat-lib-xknx~=3.15.0
+Dynamic: license-file
+
+# KNX bus connector
+
+% start synopsis
+Connects MoaT-Link to a KNX bus via XKNX/KNXnet/IP tunneling.
+% end synopsis
+
+% start main
+
+This module bridges MoaT-Link values and KNX group addresses, in both
+directions, via the XKNX library.  It replaces the legacy
+``moat-kv-knx`` package.
+
+## Quick start
+
+1. Configure a KNX gateway:
+
+   ```shell
+   moat link knx myhouse add -h 10.0.0.1
+   ```
+
+2. Map a group address to a MoaT-Link path:
+
+   ```shell
+   moat link knx myhouse at 1/2/3 add -t in -m Bool -s dest .data.lamp.kitchen
+   ```
+
+3. Run the connector:
+
+   ```shell
+   moat link knx myhouse monitor
+   ```
+
+## Deprecation
+
+This package supersedes ``moat-kv-knx``.  The address tree now lives in
+MoaT-Link under the ``knx.<NAME>`` prefix; group addresses are stored as
+the three integer components of an ``a/b/c`` address.
+
+% end main

moat_link_knx-0.20.0/README.md

@@ -0,0 +1,39 @@
+# KNX bus connector
+
+% start synopsis
+Connects MoaT-Link to a KNX bus via XKNX/KNXnet/IP tunneling.
+% end synopsis
+
+% start main
+
+This module bridges MoaT-Link values and KNX group addresses, in both
+directions, via the XKNX library.  It replaces the legacy
+``moat-kv-knx`` package.
+
+## Quick start
+
+1. Configure a KNX gateway:
+
+   ```shell
+   moat link knx myhouse add -h 10.0.0.1
+   ```
+
+2. Map a group address to a MoaT-Link path:
+
+   ```shell
+   moat link knx myhouse at 1/2/3 add -t in -m Bool -s dest .data.lamp.kitchen
+   ```
+
+3. Run the connector:
+
+   ```shell
+   moat link knx myhouse monitor
+   ```
+
+## Deprecation
+
+This package supersedes ``moat-kv-knx``.  The address tree now lives in
+MoaT-Link under the ``knx.<NAME>`` prefix; group addresses are stored as
+the three integer components of an ``a/b/c`` address.
+
+% end main

moat_link_knx-0.20.0/debian/changelog

@@ -0,0 +1,11 @@
+moat-link-knx (0.20.0-1) unstable; urgency=medium
+
+  * New release for 26.1.18
+
+ -- Matthias Urlichs <matthias@urlichs.de>  Wed, 03 Jun 2026 18:52:40 +0200
+
+moat-link-knx (0.0.1-1) unstable; urgency=medium
+
+  * Initial release.
+
+ -- Matthias Urlichs <matthias@urlichs.de>  Mon, 01 Jun 2026 12:00:00 +0200

moat_link_knx-0.20.0/debian/control

@@ -0,0 +1,24 @@
+Source: moat-link-knx
+Maintainer: Matthias Urlichs <matthias@urlichs.de>
+Section: python
+Priority: optional
+Build-Depends: dh-python, python3-all, debhelper (>= 13),
+  python3-setuptools,
+  python3-wheel,
+Standards-Version: 3.9.6
+Homepage: https://github.com/M-o-a-T/moat
+X-DH-Compat: 13
+
+Package: moat-link-knx
+Architecture: all
+Depends: ${misc:Depends}, ${python3:Depends},
+  moat-util,
+  moat-link,
+  moat-lib-xknx,
+Recommends:
+  python3-trio (>= 0.22),
+Description: KNX bus connector for MoaT-Link
+ Bridges MoaT-Link values to and from KNX group addresses via the
+ XKNX library and a KNXnet/IP tunneling connection.
+ .
+ Part of the MoaT ecosystem for distributed home automation.

moat_link_knx-0.20.0/debian/rules

@@ -0,0 +1,10 @@
+#!/usr/bin/make -f
+
+export PYBUILD_NAME=moat-link-knx
+%:
+	dh $@ --with python3 --buildsystem=pybuild
+
+override_dh_auto_install:
+	dh_auto_install
+	install -D -m 644 systemd/moat-link-knx@.service \
+		debian/moat-link-knx/usr/lib/systemd/system/moat-link-knx@.service

moat_link_knx-0.20.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [ "setuptools", "wheel",]
+
+[project]
+classifiers = [
+	"Intended Audience :: Developers",
+	"Programming Language :: Python :: 3",
+	"Framework :: AsyncIO",
+	"Framework :: Trio",
+	"Framework :: AnyIO",
+	"Development Status :: 4 - Beta",
+	]
+dependencies = [
+	"anyio ~= 4.2",
+	"asyncclick ~= 8.3",
+	"attrs",
+	"moat-util ~= 0.63.0",
+	"moat-link ~= 0.8.0",
+	"moat-lib-config ~= 0.2.0",
+	"moat-lib-xknx ~= 3.15.0",
+	]
+version = "0.20.0"
+keywords = [ "MoaT",]
+requires-python = ">=3.13"
+name = "moat-link-knx"
+description = "KNX bus connector for MoaT-Link"
+readme = "README.md"
+
+[[project.authors]]
+name = "Matthias Urlichs"
+email = "matthias@urlichs.de"
+
+[project.urls]
+homepage = "https://m-o-a-t.org"
+repository = "https://github.com/M-o-a-T/moat"
+
+[tool.setuptools]
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.yaml"]

moat_link_knx-0.20.0/setup.cfg

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

moat_link_knx-0.20.0/src/moat/link/knx/__init__.py

@@ -0,0 +1,9 @@
+"""KNX bus connector for MoaT-Link."""
+
+from __future__ import annotations
+
+from moat.lib.config import register as _register
+
+__all__: list[str] = []
+
+_register(__name__)

moat_link_knx-0.20.0/src/moat/link/knx/_cfg.yaml

@@ -0,0 +1,5 @@
+prefix: !P knx
+server_default:
+  port: 3671
+poll: 10
+count: true

moat_link_knx-0.20.0/src/moat/link/knx/_main.py

@@ -0,0 +1,373 @@
+"""
+Command-line interface for moat.link.knx.
+
+Mirrors :mod:`moat.link.metrics` but with KNX-specific argument
+parsing: the ``at`` sub-group takes a KNX ``a/b/c`` group address that
+is decoded to a 3-element integer subpath.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import asyncclick as click
+
+from moat.util import NotGiven, yprint
+from moat.lib.path import Path
+from moat.lib.run import AliasedGroup, attr_args
+from moat.link._data import data_get, node_attr
+from moat.link.announce import as_service
+from moat.link.client import Link
+
+from .model import group_subpath
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _server_path(obj) -> Path:
+    """Return the link path of the currently-selected KNX server."""
+    return obj.knx_prefix + Path.build((obj.knx_name,))
+
+
+async def _require_server(obj) -> dict[str, Any]:
+    """Fetch the data stored at the server entry, or raise.
+
+    Raises:
+        click.UsageError: if the entry is missing or not a mapping.
+    """
+    try:
+        data = await obj.conn.d_get(_server_path(obj))
+    except KeyError:
+        raise click.UsageError(f"Server {obj.knx_name!r} does not exist.") from None
+    if not isinstance(data, dict):
+        raise click.UsageError(f"Server {obj.knx_name!r} has no configuration.")
+    return data
+
+
+@click.group(
+    cls=AliasedGroup,
+    name="knx",
+    short_help="Manage KNX gateways.",
+    invoke_without_command=True,
+    help="""\
+        Manager for KNX bus gateways.
+
+        \b
+        Use '… knx -' to list all entries.
+        Use '… knx NAME' to show details of a single entry.
+        """,
+)
+@click.argument("name", type=str, nargs=1)
+@click.pass_context
+async def cli(ctx, name: str) -> None:
+    """Dispatch to a server- or address-specific subcommand."""
+    obj = ctx.obj
+    cfg = obj.cfg["link"]
+    obj.conn = await ctx.with_async_resource(Link(cfg))
+    obj.knx_cfg = obj.cfg.link.knx
+    obj.knx_prefix = obj.knx_cfg.prefix
+    obj.knx_name = name
+
+    if name == "-":
+        if ctx.invoked_subcommand is not None:
+            raise click.BadParameter(
+                "The name '-' triggers a list and precludes subcommands.",
+            )
+        cnt = 0
+        async with obj.conn.d_walk(obj.knx_prefix, min_depth=1, max_depth=1) as mon:
+            async for p, _d in mon:
+                cnt += 1
+                print(p[-1], file=obj.stdout)
+        if not cnt and obj.debug:
+            print("no entries", file=sys.stderr)
+        return
+
+    if ctx.invoked_subcommand is None:
+        try:
+            data = await obj.conn.d_get(_server_path(obj))
+        except KeyError:
+            raise click.UsageError(
+                f"Server {obj.knx_name!r} does not exist.",
+            ) from None
+        srv = data.get("server", {}) if isinstance(data, dict) else {}
+        cnt = 0
+        if isinstance(srv, dict):
+            for k in ("host", "port"):
+                v = srv.get(k)
+                if v is not None:
+                    cnt += 1
+                    print(f"server {k} {v}", file=obj.stdout)
+        if not cnt and obj.debug:
+            print("exists, no data", file=sys.stderr)
+
+
+@cli.command("--help", hidden=True)
+@click.pass_context
+def _cli_help(ctx) -> None:
+    """Workaround so ``cli NAME --help`` produces help text."""
+    print(cli.get_help(ctx))
+
+
+def _server_options(proc):
+    """Decorate ``add``/``set`` with the server-config options."""
+    proc = click.option(
+        "-p",
+        "--port",
+        type=int,
+        default=None,
+        help="Port of the KNX/IP gateway (default 3671).",
+    )(proc)
+    proc = click.option(
+        "-h",
+        "--host",
+        type=str,
+        default=None,
+        help="Host name or IP of the KNX/IP gateway.",
+    )(proc)
+    return proc
+
+
+@cli.command(short_help="Add a KNX gateway")
+@_server_options
+@click.option("-f", "--force", is_flag=True, help="Allow replacing an existing gateway.")
+@click.pass_obj
+async def add(obj, host, port, force) -> None:
+    """Add a KNX gateway."""
+    path = _server_path(obj)
+    if not force:
+        try:
+            await obj.conn.d_get(path)
+        except KeyError:
+            pass
+        else:
+            raise click.UsageError(
+                f"Gateway {obj.knx_name!r} already exists. Use --force or 'set'.",
+            )
+
+    srv: dict[str, Any] = {}
+    if host is not None:
+        srv["host"] = host
+    if port is not None:
+        srv["port"] = port
+    await obj.conn.d_set(path, {"server": srv})
+
+
+@cli.command("set", short_help="Modify a KNX gateway")
+@_server_options
+@click.pass_obj
+async def set_(obj, host, port) -> None:
+    """Modify a KNX gateway.
+
+    Pass ``-`` as a value (where applicable) to clear an existing setting.
+    """
+    data = await _require_server(obj)
+    srv = data.get("server", {})
+    if not isinstance(srv, dict):
+        srv = {}
+
+    if host is not None:
+        if host == "-":
+            srv.pop("host", None)
+        else:
+            srv["host"] = host
+    if port is not None:
+        srv["port"] = port
+    data["server"] = srv
+
+    await obj.conn.d_set(_server_path(obj), data)
+
+
+@cli.command("delete", short_help="Delete a KNX gateway")
+@click.option("-r", "--recursive", is_flag=True, help="Also remove all entries below.")
+@click.pass_obj
+async def delete_(obj, recursive: bool) -> None:
+    """Delete a KNX gateway.
+
+    Without ``--recursive`` the gateway entry itself is removed but its
+    child group-address entries are kept (they become orphans).
+    """
+    path = _server_path(obj)
+    args: dict[str, Any] = {}
+    if recursive:
+        args["rec"] = True
+    res = await obj.conn.d.delete(path, **args)
+    if getattr(obj, "meta", False):
+        yprint(res[0], stream=obj.stdout)
+
+
+@cli.command("dump")
+@click.option("-l", "--one-line", is_flag=True, help="Single line per entry")
+@click.pass_obj
+async def dump_(obj, one_line: bool) -> None:
+    """Emit a gateway's (sub)state as a list / YAML file."""
+    path = _server_path(obj)
+    if not one_line:
+        await data_get(obj.conn, path, recursive=True, out=obj.stdout)
+        return
+    async with obj.conn.d_walk(path) as mon:
+        async for p, d in mon:
+            print(f"{path + p} {d}", file=obj.stdout)
+
+
+@cli.group(
+    "at",
+    invoke_without_command=True,
+    short_help="create/show/delete an entry",
+)
+@click.argument("group", type=str, nargs=1)
+@click.pass_context
+async def at_cli(ctx, group: str) -> None:
+    """Manage a single KNX group-address entry under a gateway.
+
+    GROUP is a KNX group address in ``a/b/c`` form.  It is translated to
+    the integer subpath ``a:b:c`` below the gateway.
+    """
+    obj = ctx.obj
+    try:
+        sub = group_subpath(group)
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from None
+    try:
+        await obj.conn.d_get(_server_path(obj))
+    except KeyError:
+        raise click.UsageError(
+            "Create the gateway before assigning group addresses to it!",
+        ) from None
+    obj.knx_subpath = sub
+    if ctx.invoked_subcommand is None:
+        await data_get(
+            obj.conn,
+            _server_path(obj) + sub,
+            recursive=False,
+            out=obj.stdout,
+        )
+
+
+@at_cli.command("--help", hidden=True)
+@click.pass_context
+def _at_help(ctx) -> None:
+    """Workaround so ``at GROUP --help`` produces help text."""
+    print(at_cli.get_help(ctx))
+
+
+@at_cli.command("dump")
+@click.option("-l", "--one-line", is_flag=True, help="Single line per entry")
+@click.pass_obj
+async def dump_at(obj, one_line: bool) -> None:
+    """Emit a subtree as a list / YAML file."""
+    path = _server_path(obj) + obj.knx_subpath
+    if not one_line:
+        await data_get(obj.conn, path, recursive=True, out=obj.stdout)
+        return
+    async with obj.conn.d_walk(path) as mon:
+        async for p, d in mon:
+            print(f"{path + p} {d}", file=obj.stdout)
+
+
+@at_cli.command("add", short_help="Add an entry")
+@attr_args
+@click.option("-f", "--force", is_flag=True, help="Allow replacing an existing entry.")
+@click.option(
+    "-t",
+    "--type",
+    "typ",
+    type=click.Choice(["in", "out"]),
+    required=True,
+    help="Direction: 'in' (KNX→Link) or 'out' (Link→KNX).",
+)
+@click.option(
+    "-m",
+    "--mode",
+    required=True,
+    help="XKNX data-point type, e.g. 'binary' or 'Bool'.",
+)
+@click.pass_obj
+async def add_at(obj, typ, mode, force, **kw) -> None:
+    """Add a group-address mapping.
+
+    \b
+    GROUP: a KNX ``a/b/c`` group address. Required.
+
+    For ``type=in`` the ``dest`` attribute must specify the
+    destination MoaT-Link path; for ``type=out`` the ``src``
+    attribute must specify the source path.  Use the ``-s``
+    option to set them, e.g. ``-s dest .my.path``.
+
+    For ``type=out`` you may additionally set ``state`` to a
+    MoaT-Link path that tracks the last observed bus state.
+    Commands whose timestamp is older than the recorded state
+    are then suppressed (useful on startup).
+    """
+    sub: Path = obj.knx_subpath
+    path = _server_path(obj) + sub
+
+    if not force:
+        try:
+            await obj.conn.d_get(path)
+        except KeyError:
+            pass
+        else:
+            raise click.UsageError("This entry already exists. Use '--force' or 'set'.")
+
+    val: dict[str | None, Any] = {"type": typ, "mode": mode}
+    res, _meta = await node_attr(obj, path, val=val, **kw)
+
+    required = "dest" if typ == "in" else "src"
+    if not isinstance(res, dict) or res.get(required) is None:
+        raise click.UsageError(
+            f"For type={typ!r} you must set the {required!r} attribute, "
+            f"e.g. `-s {required} .some.path`.",
+        )
+
+    if getattr(obj, "meta", False):
+        yprint(res, stream=obj.stdout)
+
+
+@at_cli.command("delete")
+@click.pass_obj
+async def delete_at(obj) -> None:
+    """Remove a group-address mapping from the gateway."""
+    path = _server_path(obj) + obj.knx_subpath
+    try:
+        await obj.conn.d_get(path)
+    except KeyError:
+        raise click.UsageError("This entry doesn't exist.") from None
+    await obj.conn.d_set(path, NotGiven)
+
+
+@at_cli.command("set")
+@attr_args
+@click.pass_obj
+async def set_at(obj, **kw) -> None:
+    """Modify a group-address mapping."""
+    if not any(kw.get(x) for x in ("vars_", "eval_", "path_")):
+        return
+    path = _server_path(obj) + obj.knx_subpath
+    res, _meta = await node_attr(obj, path, **kw)
+    if getattr(obj, "meta", False):
+        yprint(res, stream=obj.stdout)
+
+
+@cli.command()
+@click.option("-l", "--local-ip", default=None, help="Force this local IP address.")
+@click.option("-i", "--initial", is_flag=True, help="Push existing outgoing states.")
+@click.pass_obj
+async def monitor(obj, local_ip, initial) -> None:
+    """Stand-alone task to talk to a single KNX gateway."""
+    from .task import task  # noqa: PLC0415
+
+    async with as_service(obj) as srv:
+        await task(
+            obj.conn,
+            obj.knx_cfg,
+            obj.knx_name,
+            local_ip=local_ip,
+            initial=initial,
+            task_status=srv,
+        )

moat_link_knx-0.20.0/src/moat/link/knx/model.py

@@ -0,0 +1,192 @@
+"""
+Node model for the KNX bus connector.
+
+The tree mirrors the MoaT-Link subtree under the configured prefix.
+Each server entry is keyed by its name; below it the tree branches
+along the three integer components of a KNX group address
+(``main``/``middle``/``sub``).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from attrs import define
+
+from moat.util import NotGiven
+from moat.lib.path import Path
+from moat.lib.xknx.telegram import GroupAddress
+from moat.link.node import Node
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from moat.lib.rpc import Key
+
+    from collections.abc import Mapping
+    from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def parse_group(addr: str) -> tuple[int, int, int]:
+    """Parse a KNX ``a/b/c`` group address into a 3-tuple of integers.
+
+    Args:
+        addr: A KNX group address string, e.g. ``"1/2/3"``.
+
+    Returns:
+        ``(main, middle, sub)`` as a 3-tuple of ``int``.
+
+    Raises:
+        ValueError: if *addr* is not a valid 3-part group address.
+    """
+    if addr.count("/") != 2:
+        raise ValueError(f"Not a 3-part KNX group address: {addr!r}")
+    ga = GroupAddress(addr)
+    main, middle, sub = ga.main, ga.middle, ga.sub
+    if main is None or middle is None or sub is None:
+        raise ValueError(f"Not a 3-part KNX group address: {addr!r}")
+    return (main, middle, sub)
+
+
+def group_subpath(addr: str) -> Path:
+    """Return *addr* as a 3-element :class:`~moat.lib.path.Path`."""
+    return Path.build(parse_group(addr))
+
+
+@define
+class KnxEntry(Node):
+    """A single KNX group-address mapping.
+
+    Maps one KNX group address to a MoaT-Link source/destination path.
+    The stored configuration is a dict with these keys:
+
+    * ``type``: ``"in"`` (KNX → Link) or ``"out"`` (Link → KNX).
+    * ``mode``: XKNX data-point type, e.g. ``"binary"`` or ``"Bool"``.
+    * ``src``: source path (for ``type=out``).
+    * ``dest``: destination path (for ``type=in``).
+    * ``state``: optional path (``type=out`` only) that holds the last
+      observed bus state.  If newer than the command at ``src``, the
+      command is treated as stale and not forwarded.
+    * ``idem``: optional idempotency flag (default ``True``).
+    """
+
+    @property
+    def type_(self) -> str | None:
+        """``in`` or ``out`` direction, or ``None`` if unset."""
+        d = self.data_
+        return d.get("type") if isinstance(d, dict) else None
+
+    @property
+    def mode(self) -> str | None:
+        """XKNX data-point type name, or ``None`` if unset."""
+        d = self.data_
+        return d.get("mode") if isinstance(d, dict) else None
+
+    @property
+    def src(self) -> Path | None:
+        """Source path (for ``type=out``), or ``None``."""
+        d = self.data_
+        s = d.get("src") if isinstance(d, dict) else None
+        return s if s is None else Path.build(s)
+
+    @property
+    def dest(self) -> Path | None:
+        """Destination path (for ``type=in``), or ``None``."""
+        d = self.data_
+        s = d.get("dest") if isinstance(d, dict) else None
+        return s if s is None else Path.build(s)
+
+    @property
+    def state(self) -> Path | None:
+        """Last-observed-bus-state path (for ``type=out``), or ``None``.
+
+        If set, this path's stored timestamp is compared with the
+        command's timestamp; commands older than the recorded state are
+        suppressed.
+        """
+        d = self.data_
+        s = d.get("state") if isinstance(d, dict) else None
+        return s if s is None else Path.build(s)
+
+    @property
+    def idem(self) -> bool:
+        """Whether to skip writes when the value is unchanged."""
+        d = self.data_ if self.data_ is not NotGiven else {}
+        if not isinstance(d, dict):
+            return True
+        return bool(d.get("idem", True))
+
+    def is_complete(self) -> bool:
+        """Whether this entry has a complete configuration."""
+        t = self.type_
+        if t == "in":
+            return self.mode is not None and self.dest is not None
+        if t == "out":
+            return self.mode is not None and self.src is not None
+        return False
+
+
+@define
+class KnxMiddle(Node):
+    """Intermediate ``middle`` group-address node; children are :class:`KnxEntry`."""
+
+    def add_child(self, item: Key) -> KnxEntry:
+        """Create child entries as :class:`KnxEntry`."""
+        if item in self._sub:
+            raise ValueError("exists")
+        self._sub[item] = s = KnxEntry()
+        return s
+
+
+@define
+class KnxMain(Node):
+    """Intermediate ``main`` group-address node; children are :class:`KnxMiddle`."""
+
+    def add_child(self, item: Key) -> KnxMiddle:
+        """Create child entries as :class:`KnxMiddle`."""
+        if item in self._sub:
+            raise ValueError("exists")
+        self._sub[item] = s = KnxMiddle()
+        return s
+
+
+@define
+class KnxServer(Node):
+    """One KNX server (gateway) in the configuration tree.
+
+    Children at the integer ``main`` level branch out into
+    middle/sub levels and finally into :class:`KnxEntry` leaves.
+    """
+
+    def add_child(self, item: Key) -> KnxMain:
+        """Create child entries as :class:`KnxMain`."""
+        if item in self._sub:
+            raise ValueError("exists")
+        self._sub[item] = s = KnxMain()
+        return s
+
+    @property
+    def cfg(self) -> Mapping[str, Any]:
+        """Server-level config dict (``host``/``port``)."""
+        d = self.data_
+        if d is NotGiven or not isinstance(d, dict):
+            return {}
+        s = d.get("server", {})
+        return s if isinstance(s, dict) else {}
+
+
+@define
+class KnxRoot(Node):
+    """Root of the KNX configuration tree.
+
+    Children are :class:`KnxServer` nodes.
+    """
+
+    def add_child(self, item: Key) -> KnxServer:
+        """Create child servers as :class:`KnxServer`."""
+        if item in self._sub:
+            raise ValueError("exists")
+        self._sub[item] = s = KnxServer()
+        return s

moat_link_knx-0.20.0/src/moat/link/knx/task.py

@@ -0,0 +1,141 @@
+"""
+Main supervisor task for the KNX connector.
+
+Connects to a single KNX gateway and monitors the MoaT-Link
+configuration subtree for one server.  Spawns / cancels per-entry
+workers as entries appear or change.
+"""
+
+from __future__ import annotations
+
+import anyio
+import logging
+
+from moat.util import combine_dict
+from moat.lib.path import Path
+from moat.lib.xknx import XKNX
+from moat.lib.xknx.io import ConnectionConfig, ConnectionType
+from moat.lib.xknx.telegram import GroupAddress
+
+from .model import KnxEntry, KnxServer
+from .worker import run_in, run_out
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from anyio.abc import TaskStatus
+
+    from moat.link.client import LinkSender
+
+    from collections.abc import Mapping
+
+logger = logging.getLogger(__name__)
+
+
+async def task(
+    link: LinkSender,
+    cfg: Mapping,
+    server_name: str,
+    *,
+    local_ip: str | None = None,
+    initial: bool | None = None,
+    task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORED,
+) -> None:
+    """Run the KNX connector for one gateway.
+
+    Args:
+        link: an active MoaT-Link sender.
+        cfg: the ``link.knx`` configuration section.
+        server_name: the server entry name inside the config subtree.
+        local_ip: optional local IP override for the gateway connection.
+        initial: if true, push existing outgoing states / pull inputs on
+            startup. Defaults to ``True`` on input.
+        task_status: task-status for ``tg.start``.
+    """
+    prefix = Path.build(cfg["prefix"])
+    server_path = prefix / server_name
+
+    server_data = await link.d_get(server_path)
+    if not isinstance(server_data, dict):
+        server_data = {}
+    srv_cfg = combine_dict(
+        server_data.get("server", {}),
+        cfg.get("server_default", {}),
+    )
+
+    add: dict = {}
+    if local_ip is not None:
+        add["local_ip"] = local_ip
+
+    ccfg = ConnectionConfig(
+        connection_type=ConnectionType.TUNNELING,
+        gateway_ip=srv_cfg["host"],
+        gateway_port=srv_cfg.get("port", 3671),
+        **add,
+    )
+
+    async with XKNX(connection_config=ccfg) as srv, anyio.create_task_group() as tg:
+        workers: dict[Path, anyio.CancelScope] = {}
+
+        def _cancel(p: Path) -> None:
+            sc = workers.pop(p, None)
+            if sc is not None:
+                sc.cancel()
+
+        async def _start(p: Path, entry: KnxEntry) -> None:
+            nonlocal initial
+
+            _cancel(p)
+            if not entry.is_complete():
+                logger.warning("Incomplete entry at %s, skipping", p)
+                return
+            if len(p) != 3 or not all(isinstance(x, int) for x in p):
+                logger.warning("Entry %s is not at a 3-element group address", p)
+                return
+            main, middle, sub = (int(p[0]), int(p[1]), int(p[2]))
+            addr = GroupAddress((main << 11) | (middle << 8) | sub)
+
+            runner = run_in if entry.type_ == "in" else run_out
+            if initial is None:
+                initial = entry.type_ == "in"
+
+            async def _run(
+                *,
+                task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORED,
+            ) -> None:
+                with anyio.CancelScope() as sc:
+                    workers[p] = sc
+                    task_status.started()
+                    assert initial is not None  ## typing *sigh*
+                    try:
+                        await runner(link, srv, entry, addr, p, initial=initial)
+                    except Exception:
+                        logger.exception("Worker for %s failed", p)
+
+            await tg.start(_run)
+
+        async with link.d_watch(
+            server_path,
+            subtree=True,
+            mark=True,
+            cls=KnxServer,
+        ) as mon:
+            task_status.started()
+
+            async for msg in mon:
+                if msg is None:
+                    continue
+                p, _data = msg
+                if not p:
+                    continue
+
+                node = mon.nodes.get(p)
+                if isinstance(node, KnxEntry):
+                    if node.is_complete():
+                        await _start(p, node)
+                    else:
+                        _cancel(p)
+                else:
+                    _cancel(p)
+
+        tg.cancel_scope.cancel()

moat_link_knx-0.20.0/src/moat/link/knx/worker.py

@@ -0,0 +1,190 @@
+"""
+Per-entry workers for the KNX bus connector.
+
+Each worker drives a single :class:`~moat.link.knx.model.KnxEntry`.
+``type=in`` workers watch the KNX bus for incoming telegrams and
+publish the decoded value to MoaT-Link; ``type=out`` workers watch a
+MoaT-Link value and forward changes onto the bus.
+"""
+
+from __future__ import annotations
+
+import anyio
+import logging
+
+from moat.util import NotGiven
+from moat.lib.xknx.devices import BinarySensor, ExposeSensor, Sensor, Switch
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from moat.lib.path import Path
+    from moat.lib.xknx import XKNX
+    from moat.lib.xknx.telegram import GroupAddress
+    from moat.link.client import LinkSender
+    from moat.link.meta import MsgMeta
+
+    from .model import KnxEntry
+
+logger = logging.getLogger(__name__)
+
+
+def _make_in_device(srv: XKNX, addr: GroupAddress, mode: str, name: str, cb):
+    """Build the XKNX device used by a ``type=in`` worker."""
+    args: dict = dict(
+        xknx=srv,
+        group_address_state=addr,
+        name=name,
+        device_updated_cb=cb,
+    )
+    if mode == "binary":
+        return BinarySensor(ignore_internal_state=True, **args), lambda d: d.is_on()
+    dev = Sensor(value_type=mode, **args)
+    return dev, lambda d: d.sensor_value.value
+
+
+def _make_out_device(srv: XKNX, addr: GroupAddress, mode: str, name: str):
+    """Build the XKNX device used by a ``type=out`` worker."""
+    args: dict = dict(xknx=srv, group_address=addr, name=name)
+    if mode == "binary":
+        sw = Switch(**args)
+
+        async def set_val(dev, val):
+            if val:
+                await dev.set_on()
+            else:
+                await dev.set_off()
+
+        return sw, set_val, lambda d: d.state
+
+    dev = ExposeSensor(value_type=mode, **args)
+
+    async def set_val(dev, val):
+        await dev.set(val)
+
+    return dev, set_val, lambda d: d.sensor_value.value
+
+
+async def run_in(
+    link: LinkSender,
+    srv: XKNX,
+    entry: KnxEntry,
+    addr: GroupAddress,
+    subpath: Path,
+    *,
+    initial: bool = False,
+) -> None:
+    """Forward KNX bus telegrams to a MoaT-Link destination.
+
+    Args:
+        link: Active MoaT-Link sender.
+        srv: Connected XKNX gateway.
+        entry: Configuration entry for this address.
+        addr: Group address to listen on.
+        subpath: Path of this entry relative to the server (for naming).
+        initial: If true, request the current value on startup.
+    """
+    mode = entry.mode
+    dest = entry.dest
+    if mode is None or dest is None:
+        return
+
+    name = f"{mode}." + ".".join(str(x) for x in subpath)
+    evt = anyio.Event()
+
+    def _cb(_dev) -> None:
+        evt.set()
+
+    device, get_val = _make_in_device(srv, addr, mode, name, _cb)
+    srv.devices.async_add(device)
+    try:
+        if initial:
+            await device.sync()
+        while True:
+            await evt.wait()
+            evt = anyio.Event()
+            await link.d_set(dest, get_val(device))
+    finally:
+        srv.devices.async_remove(device)
+
+
+async def run_out(
+    link: LinkSender,
+    srv: XKNX,
+    entry: KnxEntry,
+    addr: GroupAddress,
+    subpath: Path,
+    *,
+    initial: bool = False,
+) -> None:
+    """Forward MoaT-Link source updates onto the KNX bus.
+
+    If :attr:`~moat.link.knx.model.KnxEntry.state` is set, the data
+    stored at that path is consulted before the initial command is
+    forwarded: a command whose timestamp is older than the recorded state's
+    timestamp is suppressed.  This avoids re-sending a stale outgoing
+    command on startup when other bus actors changed the device state
+    in the meantime.
+
+    Args:
+        link: Active MoaT-Link sender.
+        srv: Connected XKNX gateway.
+        entry: Configuration entry for this address.
+        addr: Group address to write on.
+        subpath: Path of this entry relative to the server (for naming).
+        initial: If true, fetch the current MoaT-Link value on startup.
+    """
+    mode = entry.mode
+    src = entry.src
+    if mode is None or src is None:
+        return
+    state_path = entry.state
+
+    name = f"{mode}." + ".".join(str(x) for x in subpath)
+    device, set_val, _get_val = _make_out_device(srv, addr, mode, name)
+    srv.devices.async_add(device)
+    initial_phase = state_path is not None
+    try:
+        async with link.d_watch(src, meta=True, mark=initial_phase, state=initial or None) as wp:
+            async for msg in wp:
+                if msg is None:
+                    # End of initial-state replay; no more stale-suppression.
+                    initial_phase = False
+                    continue
+                raw, meta = msg
+                if raw is NotGiven:
+                    continue
+                if (
+                    initial_phase
+                    and state_path is not None
+                    and not await _state_allows(link, state_path, meta, subpath)
+                ):
+                    continue
+                await set_val(device, raw)
+    finally:
+        srv.devices.async_remove(device)
+
+
+async def _state_allows(
+    link: LinkSender,
+    state_path: Path,
+    cmd_meta: MsgMeta,
+    subpath: Path,
+) -> bool:
+    """Return True iff *cmd_meta* is at least as recent as *state_path*.
+
+    Missing state data is treated as "always allow".
+    """
+    try:
+        _data, state_meta = await link.d_get(state_path, meta=True)
+    except KeyError:
+        return True
+    if state_meta.timestamp > cmd_meta.timestamp:
+        logger.debug(
+            "Suppressing stale command at %s: state %r newer than cmd %r",
+            subpath,
+            state_meta.timestamp,
+            cmd_meta.timestamp,
+        )
+        return False
+    return True

moat_link_knx-0.20.0/src/moat_link_knx.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: moat-link-knx
+Version: 0.20.0
+Summary: KNX bus connector for MoaT-Link
+Author-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AnyIO
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.2
+Requires-Dist: asyncclick~=8.3
+Requires-Dist: attrs
+Requires-Dist: moat-util~=0.63.0
+Requires-Dist: moat-link~=0.8.0
+Requires-Dist: moat-lib-config~=0.2.0
+Requires-Dist: moat-lib-xknx~=3.15.0
+Dynamic: license-file
+
+# KNX bus connector
+
+% start synopsis
+Connects MoaT-Link to a KNX bus via XKNX/KNXnet/IP tunneling.
+% end synopsis
+
+% start main
+
+This module bridges MoaT-Link values and KNX group addresses, in both
+directions, via the XKNX library.  It replaces the legacy
+``moat-kv-knx`` package.
+
+## Quick start
+
+1. Configure a KNX gateway:
+
+   ```shell
+   moat link knx myhouse add -h 10.0.0.1
+   ```
+
+2. Map a group address to a MoaT-Link path:
+
+   ```shell
+   moat link knx myhouse at 1/2/3 add -t in -m Bool -s dest .data.lamp.kitchen
+   ```
+
+3. Run the connector:
+
+   ```shell
+   moat link knx myhouse monitor
+   ```
+
+## Deprecation
+
+This package supersedes ``moat-kv-knx``.  The address tree now lives in
+MoaT-Link under the ``knx.<NAME>`` prefix; group addresses are stored as
+the three integer components of an ``a/b/c`` address.
+
+% end main

moat_link_knx-0.20.0/src/moat_link_knx.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE.txt
+Makefile
+README.md
+pyproject.toml
+debian/changelog
+debian/control
+debian/rules
+src/moat/link/knx/__init__.py
+src/moat/link/knx/_cfg.yaml
+src/moat/link/knx/_main.py
+src/moat/link/knx/model.py
+src/moat/link/knx/task.py
+src/moat/link/knx/worker.py
+src/moat_link_knx.egg-info/PKG-INFO
+src/moat_link_knx.egg-info/SOURCES.txt
+src/moat_link_knx.egg-info/dependency_links.txt
+src/moat_link_knx.egg-info/requires.txt
+src/moat_link_knx.egg-info/top_level.txt
+systemd/moat-link-knx@.service

moat_link_knx-0.20.0/src/moat_link_knx.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moat_link_knx-0.20.0/src/moat_link_knx.egg-info/requires.txt

@@ -0,0 +1,7 @@
+anyio~=4.2
+asyncclick~=8.3
+attrs
+moat-lib-config~=0.2.0
+moat-lib-xknx~=3.15.0
+moat-link~=0.8.0
+moat-util~=0.63.0

moat_link_knx-0.20.0/src/moat_link_knx.egg-info/top_level.txt

@@ -0,0 +1 @@
+moat

moat_link_knx-0.20.0/systemd/moat-link-knx@.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=MoaT-Link KNX connector (%I)
+After=moat-link-server.service
+Requires=moat-link-server.service
+
+ConditionFileNotEmpty=/etc/moat/moat.yaml
+
+[Install]
+WantedBy=multi-user.target
+
+[Service]
+Type=notify
+ExecStart=/usr/bin/moat link knx %I monitor
+
+EnvironmentFile=-/etc/moat/link.env
+
+TimeoutSec=300
+WatchdogSec=10
+
+Restart=always
+RestartSec=30