docs

ChangeLog.md

@@ -1,3 +1,10 @@
+# next (tbd)
+## Buf Fixes
+* fix potentially invalid settings picked up from environment variables
+## Features
+* tbd
+
+
 # 22.4 (2022-09-18)
 ## Bug Fixes
 * fix some smaller glitches (short argument names, compilation on small devices, argument help)

README.md

@@ -11,6 +11,7 @@ ebusd is a daemon for handling communication with eBUS devices connected to a
 [![Release](https://img.shields.io/github/v/release/john30/ebusd)](https://github.com/john30/ebusd/releases/latest)
 [![GitHub Discussions](https://img.shields.io/github/discussions/john30/ebusd)](https://github.com/john30/ebusd/discussions)
 [![Sponsors](https://img.shields.io/github/sponsors/john30)](https://github.com/sponsors/john30)
+[![Donate](https://img.shields.io/badge/donate-pp.me/ebusd-blue)](https://paypal.me/ebusd)
 
 Features
 --------
@@ -18,7 +19,7 @@ Features
 The main features of the daemon are:
 
  * use one of these device connections:
-   * USB serial
+   * serial (via USB or integrated UART)
    * TCP
    * UDP
    * enhanced ebusd protocol allowing arbitration to be done directly by the hardware, e.g. for recent
@@ -42,7 +43,7 @@ The main features of the daemon are:
  * publish received data to [MQTT topics](https://github.com/john30/ebusd/wiki/3.3.-MQTT-client) and vice versa (if authorized)
  * announce [message definitions and status by MQTT](https://github.com/john30/ebusd/wiki/MQTT-integration) to e.g. integrate with [Home Assistant](https://www.home-assistant.io/) using [MQTT Discovery](https://www.home-assistant.io/docs/mqtt/discovery/)
  * support MQTT publish to [Azure IoT hub](https://docs.microsoft.com/en-us/azure/iot-hub/) (see [MQTT integration](https://github.com/john30/ebusd/wiki/MQTT-integration))
- * publish message data to KNX groups and answer to read requests from KNX
+ * act as a [KNX device]((https://github.com/john30/ebusd/wiki/3.4.-KNX-device)) by publishing received data to KNX groups and answer to read/write requests from KNX, i.e. build an eBUS-KNX bridge
  * [user authentication](https://github.com/john30/ebusd/wiki/3.1.-TCP-client-commands#auth) via [ACL file](https://github.com/john30/ebusd/wiki/2.-Run#daemon-options) for access control to certain messages
 
 
@@ -56,7 +57,7 @@ or pick the [package from the Alpine Linux repository](https://pkgs.alpinelinux.
 build it yourself, or use a docker image (see below).
 
 Building ebusd from the source requires the following packages and/or features:
- * autoconf (>=2.63) + automake (>=1.11) or cmake
+ * autoconf (>=2.63) + automake (>=1.11) or cmake (>=3.7.1)
  * g++ with C++11 support (>=4.8.1)
  * make
  * kernel with pselect or ppoll support

contrib/etc/ebusd/knx.cfg

@@ -1,8 +1,7 @@
-# Configuration file for ebusd KNX integration with knxd (https://github.com/knxd/knxd).
+# Configuration file for ebusd KNX integration with KNXnet/IP and/or [knxd](https://github.com/knxd/knxd).
 
 # Use this file with ebusd to establish a bridge between KNX and eBUS for a set of messages.
-# The commandline options to ebusd should contain e.g.:
-# --knxurl=ip:localhost --knxint=/etc/ebusd/knx.cfg
+# The commandline options to ebusd need to include "--knxurl=..." in order to activate KNX support.
 
 # Currently only reading from and writing to group addresses as defined here is supported.
 # Setting the addresses via ETS is not (yet) possible as well as setting the physical address.
@@ -52,21 +51,21 @@ global/scan = 9/5
 #   - D1C, D2B, D2C, FLT, FLR: 2 octet, signed float, DPT 9.*
 #   - EXP, EXR: 4 octet, signed float, DPT 14.*
 #
-# note: the float conversion from ebus to KNX may loose precision due to the KNX DPT 9 not being able to carry more than
+# note: the float conversion from eBUS to KNX may lose precision due to the KNX DPT 9 not being able to carry more than
 # two digits after the decimal point and having a mantissa of only 11 bits.
 # Consequently, when writing a 2-octet float to ebusd, a consecutive read on the same group address is likely to reveal
 # a different value if it was using more than two digits after the decimal point or exceeding the KNX float mantissa
 # range, e.g.:
-# - an ebus D2B value of 10.004 will read as 10.00 2-octet float on KNX,
-# - an ebus UIN with divisor 100 (like heating curve) value of 655.34 will read as 655.04 2-octet float on KNX,
-# - writing a KNX 2-octet float value of 12.34 to an ebus UIN with divisor 10 will actually write 12.3 and read as 12.3.
+# - an eBUS D2B value of 10.004 will read as 10.00 2-octet float on KNX,
+# - an eBUS UIN with divisor 100 (like heating curve) value of 655.34 will read as 655.04 2-octet float on KNX,
+# - writing a KNX 2-octet float value of 12.34 to an eBUS UIN with divisor 10 will actually write 12.3 and read as 12.3.
 #
-# note: writing to ebus via KNX currently is only possible if the ebus message contains a single field respectively at
+# note: writing to eBUS via KNX currently is only possible if the eBUS message contains a single field respectively at
 # most one non-ignored field. this is due to otherwise the value to be set for the other fields would have to be
 # determined first which is mostly not possible. Group associations to write messages not fulfilling this requirement
 # are silently ignored.
 #
 # note: the mapping for reads/writes from KNX is done as follows:
-# - for KNX read, the precedence on picking the ebus message is: active read, passive read+write.
-# - for KNX write, the precedence on picking the ebus message is: active write only.
+# - for KNX read, the precedence on picking the eBUS message is: active read, passive read+write.
+# - for KNX write, the precedence on picking the eBUS message is: active write only.
 broadcast/datetime/outsidetemp = 9/10

src/lib/knx/knxd.h

@@ -24,6 +24,10 @@
 
 namespace ebusd {
 
+/** @file lib/knx/knxd.h
+ * KNXd based implementation of the @a KnxConnection interface.
+ */
+
 /**
  * A KnxConnection based on libeibclient using the group communication interface of the connected KNXd.
  * Unfortunately, this does not allow acting as a KNX device, i.e. enter programming mode and make individual address

src/lib/knx/knxnet.h

@@ -39,6 +39,10 @@
 
 namespace ebusd {
 
+/** @file lib/knx/knxnet.h
+ * KNXnet/IP implementation of the @a KnxConnection interface based on UDP multicast.
+ */
+
 using std::string;
 
 // 16 bit unsigned big endian