XKNX Toolkit

https://github.com/xknx/xknxtoolkit
Admin
XKNX Toolkit is a desktop application and Python library suite for working with KNX home and...
Tokens:34,576
Snippets:262
Trust Score:8.3
License:GPL-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Programmatic access with CatalogService

Source: https://github.com/xknx/xknxtoolkit/blob/master/apps/knx-gui/docs/catalog.md

Python example showing how to open/create a catalog database, import a .knxprod file, list products, and get an application. The CatalogService owns the engine and .knxprod store.

```python
from pathlib import Path
from xknxmono.catalog import CatalogService

catalog = CatalogService(
    Path("catalog.db")
)  # opens/creates; owns the engine + .knxprod store

added_path = catalog.import_knxprod(Path("device.knxprod").read_bytes())

products = catalog.list_products()  # product-first view (what add_device needs)
app = catalog.get_application(application_id)  # parsed, IR-backed Application
```

--------------------------------

### Install xknx-project

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/project/docs/index.mdx

Install the xknx-project package from PyPI.

```bash
pip install xknx-project
```

--------------------------------

### Install xknx-catalog

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/catalog/docs/index.mdx

Install the xknx-catalog package from PyPI.

```bash
pip install xknx-catalog
```

--------------------------------

### Install xknx-product with pip

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/product/docs/index.mdx

Install the library using pip.

```bash
pip install xknx-product
```

--------------------------------

### Install XKNX Toolkit packages via pip

Source: https://github.com/xknx/xknxtoolkit/blob/master/website/content/docs/(start)/index.mdx

Install the individual packages you need via pip. The example shows separate pip install commands for xknx-models, xknx-product, xknx-project, and xknx-keys.

```bash
pip install xknx-models
pip install xknx-product
pip install xknx-project
pip install xknx-keys
```

--------------------------------

### Install xknx-keyring with pip

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/keyring/docs/index.mdx

Install the xknx-keyring package using pip. This is the first step before using the library.

```bash
pip install xknx-keyring
```

--------------------------------

### Install XKNX Toolkit Debian package on Debian/Ubuntu

Source: https://github.com/xknx/xknxtoolkit/blob/master/website/content/handbook/(start)/index.mdx

Installs the .deb package using dpkg and then launches the application. Requires kernel 5.4+, glibc 2.31+, and a display server.

```bash
sudo dpkg -i xknx-toolkit_amd64.deb
xknx-toolkit
```

--------------------------------

### Run XKNX Toolkit GUI from source

Source: https://github.com/xknx/xknxtoolkit/blob/master/README.md

Install dependencies and launch the XKNX Toolkit GUI from source. Requires Python >= 3.12 and uv.

```bash
uv sync
uv run python -m knx_gui.main
```

--------------------------------

### Install xknxmono packages

Source: https://github.com/xknx/xknxtoolkit/blob/master/README.md

Install the standalone Python libraries under the xknxmono namespace for independent use outside the GUI.

```bash
pip install xknx-models xknx-product xknx-catalog xknx-project xknx-keyring
```

--------------------------------

### Install xknx-models with pip

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/models/docs/index.mdx

Install the xknx-models package using pip.

```bash
pip install xknx-models
```

--------------------------------

### Start HTTP server

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/catalog/docs/index.mdx

Start the REST API server on http://localhost:8000. Interactive API docs are available at /docs.

```bash
xknxcatalog
# or
uvicorn xknxmono.catalog.http.app:app --reload
```

--------------------------------

### Install XKNX Toolkit RPM package on Fedora/RHEL

Source: https://github.com/xknx/xknxtoolkit/blob/master/website/content/handbook/(start)/index.mdx

Installs the .rpm package using rpm and then launches the application. Requires kernel 5.4+, glibc 2.31+, and a display server.

```bash
sudo rpm -i xknx-toolkit.x86_64.rpm
xknx-toolkit
```

--------------------------------

### Archive structure example

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/product/docs/index.mdx

Shows the expected layout of a .knxprod archive as described in the documentation.

```text
knx_master.xml
M-XXXX/
  Catalog.xml
  Hardware.xml
  M-XXXX_A-<id>.xml   (one per application program)
  M-XXXX.signature    (optional)
```

--------------------------------

### Usage example: ProductArchive and parse_archive

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/product/docs/index.mdx

Demonstrates opening a .knxprod archive with ProductArchive to access XMLs and parsing the full archive into typed application objects.

```python
from xknxmono.product import ProductArchive, parse_archive

# Open from a file path or bytes
with ProductArchive("device.knxprod") as archive:
    mfr_id = next(iter(archive.manufacturer_ids))
    catalog_xml = archive.get_catalog_xml(mfr_id)
    hardware_xml = archive.get_hardware_xml(mfr_id)
    app_xmls = archive.get_application_xmls(mfr_id)

# Parse the full archive into typed application objects
applications = parse_archive("device.knxprod")
for app in applications:
    print(app.name, [p.name for p in app.parameters])
```

--------------------------------

### Run development server with npm, pnpm, or yarn

Source: https://github.com/xknx/xknxtoolkit/blob/master/website/README.md

Start the development server using your preferred package manager. The server runs at http://localhost:3000.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

--------------------------------

### Run XKNX Toolkit AppImage on Linux

Source: https://github.com/xknx/xknxtoolkit/blob/master/website/content/handbook/(start)/index.mdx

Makes the AppImage executable and runs it. Works on most x86-64 distributions without installation.

```bash
chmod +x xknx-toolkit-x86_64.AppImage
./xknx-toolkit-x86_64.AppImage
```

--------------------------------

### Run common dev commands with uv

Source: https://github.com/xknx/xknxtoolkit/blob/master/CLAUDE.md

Common development commands for the repository. All Python commands must use `uv run`; do not activate the venv manually. `uv sync` installs only packages/* by default, so use `uv sync --all-packages` or run from inside apps/knx-gui to include it and imgui-bundle.

```bash
uv sync                             # Install dependencies (packages/* only - apps/knx-gui isn't
                                     # a root dependency, so plain `uv sync` never installs it or
                                     # imgui-bundle; use `uv sync --all-packages`, or run a command
                                     # from inside apps/knx-gui, which lazily syncs it)
uv run pytest                       # Run all package tests
uv run pytest packages/models       # Run tests for a single package
uv run ruff check                   # Lint
uv run ruff format                  # Format
uv run pyright                      # Type check (strict mode)

# Regenerate KNX XML schema bindings (requires XSD files in packages/models/src/xknxmono/models/schemas/)
cd packages/models/src && uvx --from "xsdata[cli]" xsdata generate --config ../.xsdata.xml xknxmono/models/schemas/
```

--------------------------------

### Populate catalog with generate-catalog CLI

Source: https://github.com/xknx/xknxtoolkit/blob/master/apps/knx-gui/docs/catalog.md

Command-line usage to import .knxprod files into the catalog. Run from the project root with uv.

```bash
uv run generate-catalog device1.knxprod device2.knxprod
```

--------------------------------

### Install XKNX Toolkit via Homebrew on macOS

Source: https://github.com/xknx/xknxtoolkit/blob/master/website/content/handbook/(start)/index.mdx

Installs the XKNX Toolkit application using the Homebrew cask. Requires macOS 13 Ventura or later.

```bash
brew install --cask xknx-toolkit
```

--------------------------------

### Load a device from a project (Python)

Source: https://github.com/xknx/xknxtoolkit/blob/master/apps/knx-gui/docs/architecture.md

Use this function to load a device from a project. It resolves the catalog application via the device's program reference, then builds a runtime Device with overrides applied inside __post_init__ via DynamicUI. The function expects a project_service, catalog_service, and device_row as arguments.

```python
def load_device(project_service, catalog_service, device_row):
    # 1. Resolve the catalog application via the device's program ref
    products = {
        p.hardware2program_ref_id: p.application_id
        for p in catalog_service.get_products()
    }
    app_id = products[device_row.hardware2program_ref_id]
    app = catalog_service.get_application(app_id)

    # 2. Build the runtime Device: overrides applied inside __post_init__ via DynamicUI
    device = Device(
        node_id=device_row.id,
        name=device_row.name,
        app=app,
        individual_address=project_service.individual_address(device_row.id),
        parameter_instance_refs=[...],  # from device_row.parameters
        module_instances=[...],  # from device_row.module_instances
        com_object_instance_refs=[...],  # from device_row.com_objects
    )
    return device
```

--------------------------------

### Set DATABASE_URL for HTTP server

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/catalog/docs/index.mdx

Override the default SQLite database path when starting the HTTP server.

```bash
DATABASE_URL=sqlite:////data/my-catalog.db xknxcatalog
```

--------------------------------

### Template substitution example

Source: https://github.com/xknx/xknxtoolkit/blob/master/packages/product/docs/knxprod/4-application.mdx

Shows how placeholders are resolved: {{ChNo}} from a TextArg and {{0}} from FunctionText produce the output string.

```text
Text="Channel {{ChNo}}: {{0}}"
TextArg ChNo="A", FunctionText="Dimming"
→ "Channel A: Dimming"
```

--------------------------------

### Example .po file content

Source: https://github.com/xknx/xknxtoolkit/blob/master/apps/knx-gui/docs/plugin.md

Shows the format of a .po translation file with msgid and msgstr entries for Dutch translations.

```text
msgid "My Panel"
msgstr "Mijn Paneel"

msgid "Do Thing"
msgstr "Doe Ding"
```
Tokens:
Raw