KNXyz

KNXyz provides KNXnet/IP clients and .knxproj loading across Rust, Python, and Node.js.

KNXyz is under active development. The examples below describe the source in this repository, and a published package can be built from different source under the same version number, so a registry install may not match them.

Install

These install the most recent published release of each package, which the badges above name:

cargo add knxyz

pip install knxyz

npm install @knxyz/knx

The published npm package's entry point is TypeScript source, so plain node cannot import it from node_modules. Run it through a TypeScript-aware loader such as tsx, or through a bundler, or build from a source checkout.

To run the examples below, build from a source checkout instead. See Running from source.

Usage

KNXyz includes KNXnet/IP clients and .knxproj loading.

Read a group value over KNXnet/IP

Connect to a KNXnet/IP interface on your network and read a group value. Use your own interface address in place of the placeholder host.

Rust

use knxyz::ip::{DptId, Interpreted, TunnelClient};
use knxyz::GroupAddress;
use std::net::ToSocketAddrs;
use std::time::Duration;

let addr = "knxip.example:3671".to_socket_addrs()?.next().expect("resolve interface");
let mut client = TunnelClient::connect(addr).await?;
let reading = client
    .group_read(
        "1/0/0".parse::<GroupAddress>()?,
        DptId::new(9, 1),
        Duration::from_secs(3),
    )
    .await?;
match reading.interpret()? {
    Interpreted::Value(value) => println!("{value:?}"),
    Interpreted::Disposition { field, disposition } => println!("{field}: {disposition:?}"),
}
client.disconnect().await?;

discover_gateways() finds KNXnet/IP interfaces on the local network.

See examples/ for the full runnable examples in each language.

Host values

The Python and Node bindings turn a host value into a JSON document under one shared policy.

An omitted item composes as the row's zero default, so an explicit empty object asks for every declared item at its zero default and write(ga, {}, "9.001") transmits 0.0 degree C. An explicit None / null is a different request: where the row declares an invalid marker, it asks for that marker.

A host value the document cannot carry faithfully is refused before any document, frame or socket work exists, so a refused call sends nothing at all. What is carried is a null, a boolean, a string, a finite number, an array and a string-keyed record. A set, a Map, a Decimal, an arbitrary object, a class instance whose state hides behind its prototype, a function, an array hole, a cycle and a structure past 1 of the boundary's 3 resource bounds - the node count it visits, the nesting depth it descends and the traversal count it charges, each a count of charged steps rather than a measure of what 1 step costs - are refused with host/non-finite-number, host/unrepresentable-value, host/circular-structure or host/value-too-complex, in both languages.

.knxproj loading

Load group addresses and topology from .knxproj files.

Python

from knxyz import load_knxproj

project = load_knxproj("project.knxproj")
print(len(project.group_addresses))

Node.js

import { loadKnxproj } from "@knxyz/knx";

const project = loadKnxproj("project.knxproj");
console.log(project.groupAddresses.length);

Rust

let project = knxyz::knxproj::import_knxproj("project.knxproj")?;
println!("{} group addresses", project.group_addresses.len());

Documentation

• Architecture
• Examples

License

KNXyz is released under the MIT license. See LICENSE.