XKNX - An asynchronous KNX library written in Python

Documentation

See documentation at: https://xknx.io/

Help

We need your help for testing and improving XKNX. For questions, feature requests, bug reports either open an issue, join the XKNX chat on Discord or write an email.

Development

You will need at least Python 3.11 in order to use XKNX.

Setting up your local environment:

1. Install uv
2. Create the environment: uv sync
3. Install the git hooks: uv run prek install

Dependencies are declared in pyproject.toml and pinned in uv.lock.

Testing

To run all linters, formatters and the type checker call uv run prek run --all-files

Unit tests are run with uv run pytest Running specific unit tests can be invoked by: uv run pytest -vv test/management_tests/procedures_test.py -k test_nm_individual_address_serial_number_write_fail Testing against another supported Python version: uv run --python 3.11 pytest

Home-Assistant

XKNX is the underlying library for the KNX integration in Home Assistant.

Example

"""Example for switching a light on and off."""

import asyncio

from xknx import XKNX
from xknx.devices import Light


async def main():
    """Connect to KNX/IP bus, switch on light, wait 2 seconds and switch it off again."""
    async with XKNX() as xknx:
        light = Light(
            xknx,
            name="TestLight",
            group_address_switch="1/0/9",
        )
        xknx.devices.async_add(light)

        await light.set_on()
        await asyncio.sleep(2)
        await light.set_off()


asyncio.run(main())

Attributions

Many thanks to Enertex Bayern GmbH, Weinzierl Engineering GmbH and MDT technologies GmbH for providing us a device to support testing and development of xknx.