search

scantineau / knx2mqtt

Gateway between KNX bus interfaces and MQTT
MIT License
1 stars 0 forks source link

readme

knx2mqtt

Written and (C) 2015 Oliver Wagner owagner@tellerulam.com

Provided under the terms of the MIT license.

Overview

knx2mqtt is a gateway between a KNX bus interface and MQTT. It receives group telegrams and publishes them as MQTT topics, and similarily subscribes to MQTT topics and converts them into KNX group writes.

It's intended as a building block in heterogenous smart home environments where an MQTT message broker is used as the centralized message bus. See https://github.com/mqtt-smarthome for a rationale and architectural overview.

Dependencies

Build Status Automatically built jars can be downloaded from the release page on GitHub at https://github.com/scantineau/knx2mqtt/releases

EIBD

The Calimero library is able to directly talk to EIBnet/IP gateways or routers. However, knx2mqtt can be used in conjunction with eibd if eibd is run as an EIBnet/IP server with option "-S". Note that this is not the same as eibd's proprietary TCP protocol which by default uses TCP port 6720.

Topics

knx2mqtt uses the group address hierarchy as defined in ETS4 for topics. The group addresses are translated to hierarchical group names if a ETS4 project file is specifed. Example

knx/set/Keller/Beleuchtung/Kellerflur Schalten

A special topic is prefix/connected. It holds an enum value which denotes whether the adapter is currently running (1) and connected to the KNX bus (2). It's set to 0 on disconnect using a MQTT will.

MQTT Message format

The message format generated is a JSON encoded object with the following members:

DPT Definitions and Project files

The interpretation of KNX values is not specified as part of the wire protocol, but done by the device configuration. It is therefore important for knx2mqtt to know about the datapoint definition of a group address.

The easiest way to archieve this is to specify a ETS4 exported project file (.knxproj). knx2mqtt will read and parse this both for the group address names and data point types. A multi-level approach to determining the data point type is used, with the ultimate fallback being the data size in bits. It is recommended to always define DPTs in your ETS4 projects, notably when converting ETS3 projects.

Special treatment is given to boolean DPTs: Instead of translating them into their textual representations, they are transfered (and accepted) as numeric "0" and "1" values.

Since the parsing of parsing of the ETS4 project file is a memory- and CPU intensive process, the parsed information is stored in a cache file (the project file with the suffix ".cache"). The cache file is completely optional; if it's not present, older than the project file or incompatible with this version of knx2mqtt, it's simply ignored and the usual project file parsing takes place.

Usage

Configuration options can either be specified on the command line, or as system properties (or environment, see Docker) with the prefix "knx2mqtt". Examples:

java -jar knx2mqtt.jar knx.ip=127.0.0.1

java -Dknxmqtt.knx.ip=127.0.0.1 -jar knx2mqtt.jar

Available options:

When running knx2mqtt on a server class machine, it makes sense to limit the memory usage to 128MB using the java options

-Xmx128M

Docker

Build dockerized kn2mqtt with

docker build -t knx2mqtt .

Start container with

docker run --env knx2mqtt_mqtt_server='tcp://192.168.1.13:1883' --env knx2mqtt_knx_ip='192.168.1.118' -t knx2mqtt

docker-compose file :

version: '3'
services:
  knx2mqtt:
    image: scantineau/knx2mqtt
    env_file:
      - knx2mqtt.env
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /path/to/config:/knx2mqtt/config/:ro
      - /path/to/data:/knx2mqtt/data/

See also

Changelog