/ README.md
README.md
1 knxd [](https://github.com/knxd/knxd/actions/workflows/ci.yml) 2 ==== 3 4 KNX is a very common building automation protocol which runs on dedicated 9600-baud wire as well as IP multicast. 5 ``knxd`` is an advanced router/gateway which runs on any Linux computer; it can talk to all known KNX interfaces. 6 7 # STOP if you install on Debian (or Ubuntu or …) 8 9 Debian/Ubuntu packaging has moved to the ``debian`` branch. Please use that 10 branch (by way of ``git checkout debian``) if you're following some (outdated …) 11 installation instructions for Debian, Ubuntu or their derivatives. 12 13 In the ``debian`` branch, this file contains build instructions for Debian. 14 15 # Stable version 16 17 This version should be OK for general use. 18 19 Check [the Wiki page](https://github.com/knxd/knxd/wiki) for other version(s) to use. 20 21 ## Known bugs 22 23 * ETS programming may or may not work out of the box. You might need to use the 24 `single` filter in front of your KNX interface. 25 26 ## Configuration 27 28 ### Daemon Configuration 29 30 Daemon configuration differs depending on whether you use systemd. 31 If "systemctl status" emits something reasonable, you are. 32 33 If you use Linux and systemd, the configuration file is ``/etc/knxd.conf``. 34 Socket activation is used for the default IP and Unix sockets (port 6720 35 and /run/knx, respectively). If not, the location of your configuration 36 file depends on your init system. 37 38 In ``knxd`` or ``knxd.conf``, KNXD\_OPTS can be set to either the legacy command line arguments, or the location of the new .ini (e.g. ``KNXD_OPTS=/etc/knxd.ini``) 39 40 ### New ".ini" configuration file 41 42 knxd is typically started with "knxd /etc/knxd.ini". 43 44 The file format is documented in "doc/inifile.rst". You might want to use 45 the program "/usr/lib/knxd\_args" to create it from previous versions' 46 command-line arguments. 47 48 ### Backward Compatibility 49 50 The default Unix socket is ``/run/knx``. 51 Old eibd clients may still use ``/tmp/eib`` to talk to knxd. 52 You need to either change their configuration, or add "-u /tmp/eib" 53 to knxd's options. 54 (This was the default for "-u" before version 0.11.) 55 56 ## New Features since 0.12 57 58 ### see https://github.com/knxd/knxd/blob/v0.12/README.md for earlier changes 59 60 * 0.14.41 61 62 * speed up CGI initial setup (a lot) 63 * support another USB interface 64 * found another uninitialized variable 65 66 * 0.14.39 67 68 * Fixed two problems with the "pace" filter that resulted in excessive 69 delays. 70 71 * 0.14.38 72 73 * knxd's udev rules were lost in the Debian branch. 74 Restored (to systemd subdir). 75 76 * 0.14.37 77 78 * Fix a memory leak in the FT12 driver 79 * fix the console rule in README 80 81 * 0.14.35 82 83 * Fixes for FreeBSD 84 85 * 0.14.34 86 87 * Cleanup: remove debian packaging, will be in a separate branch 88 89 * 0.14.33 90 91 * There is a new "retry" filter which controls closing and re-opening a 92 misbehaving driver. This filter is implicitly auto-inserted in front of 93 a driver. 94 95 * Internal: Driver errors are now signalled with "stopped(true)" instead 96 of "errored" which reduces code duplication. 97 98 * Default timeout for EMI acks increased to 2 seconds 99 Some USB interfaces manage to be abysmally slow 100 Also hopefully-fixed USB retry and shutdown handling so that the 101 "retry" filter can do its work. 102 103 * Replies from devices in programming mode are no longer retransmitted to 104 the originating interface. 105 106 * 0.14.32 107 108 * Tags no longer use a leading 'v'. 109 110 * udev rule for SATEL USB interface 111 112 * 0.14 113 114 * Code configuration 115 116 * There are no longer separate --enable-tpuarts and --enable-tpuarttcp 117 options. Instead, you control both with --enable-tpuart. (This is the 118 default anyway.) 119 120 * Configuration file 121 122 * includes a translator (knxd\_args) from options to config file 123 124 * All settings are still usable via the command line 125 126 * Complete stack refactored 127 128 * You may now use global filters. 129 130 * USB handling updated 131 132 * Most device-specific drivers are now split into a top part which 133 translates KNX packets to wire format (usually CEMI), and a bottom 134 part which transmits/receives the actual data. This enables extensive 135 code sharing; knxd also can use TCP connections instead of actual 136 serial devices. 137 138 * Startup sequencing fixed: KNX packets will not be routed 139 until all interfaces are ready. 140 141 Also, systemd will not be signalled until then. 142 143 * Configuration options to not start, or start and ignore failures of, 144 specific interfaces 145 146 * knxd will now retry setting up an interface 147 148 * use libfmt for sane and type-safe formatting of error and trace messages 149 150 * packet-level "logging" calls in various drivers have been removed 151 152 * logging packets is now done with the new "log" filter 153 154 * Logging of complete packets (inconsistently bit 1, 2, or 8 of the 155 tracing mask) has been removed 156 157 This also applies to global packet logging. 158 159 * Complain loudly (and early) if knxd needs -E / client-addrs=X.Y.Z:N 160 161 * knxd can restart links when they fail, or start to come up. 162 163 * Interfaces are now either used normally, or in bus monitor mode. 164 This is set in the configuration file / on the command line. 165 There is no longer a way to switch between these modes; 166 "knxtool busmonitor" will no longer change the state of any interface. 167 168 * Queuing and flow control 169 170 Previously, all drivers implemented their own queueing for 171 outgoing packets, resulting in duplicate code and hidden errors. 172 173 In v0.14, the main queueing system will pace packets for the slowest device. 174 If you don't want that, use the "queue" filter on the slow device(s). 175 176 All queues in individual drivers have been removed. 177 178 * EMI handling refactored 179 180 This eliminated some common code, found a couple of bugs, and lets us 181 use a common logging module (controlled by bit 0 of the tracing mask) 182 for comprehensive packet debugging. 183 184 0.12 185 186 * knxd was rewritten to use libev instead of pthsem. 187 188 * knxd now supports multiple interfaces, back-ends, and KNX packet filters. 189 190 ## History 191 192 This code is a fork of eibd 0.0.5 (from bcusdk) 193 https://www.auto.tuwien.ac.at/~mkoegler/index.php/bcusdk 194 195 For a (german only) history and discussion why knxd emerged, 196 please also see: [eibd(war bcusdk) Fork -> knxd](http://knx-user-forum.de/forum/öffentlicher-bereich/knx-eib-forum/39972-eibd-war-bcusdk-fork-knxd) 197 198 199 ## Building 200 201 When in doubt, please check out the branch corresponding to your Linux 202 distribution's flavor, and read this section there. 203 204 This part covers "manual" installation. 205 206 # first, install build tools and dependencies. You need git, autotools, and gcc/g++. 207 #: check your Linux distribution's documentation if you don't know how 208 # You also need a "knxd" user. 209 210 # get the source code 211 git clone https://github.com/knxd/knxd.git 212 213 # build+install knxd 214 cd knxd 215 git checkout main 216 sh bootstrap.sh 217 ./configure --help 218 ./configure --your-chosen-options 219 make -j$(nproc) 220 make install 221 cd .. 222 223 # Now switch to the "knxd" user and start the daemon. 224 225 If you would like to submit patches for Mac OSX or Windows, go ahead 226 and create a pull request, but please be prepared to maintain your code. 227 228 229 ### Adding a TPUART USB interface (serial, USB) 230 231 If you attach a (properly programmed) TUL (http://busware.de/tiki-index.php?page=TUL) to your computer, it'll show up as ``/dev/ttyACM0``. 232 This is a problem because (a) it's owned by root, thus knxd can't access it, and (b) if you ever add another serial interface that uses the same driver, knxd will use the wrong device. 233 234 Therefore, you do this: 235 236 * Run ``udevadm info --attribute-walk /sys/bus/usb/drivers/cdc_acm/*/tty/ttyACM0``. 237 238 We're interested in the third block. It contains a line ``ATTRS{manufacturer}=="busware.de"``. 239 Note the ``KERNELS=="something"`` line (your ``something`` will be different). 240 241 * Copy the following line to ``/etc/udev/rules.d/70-knxd.rules``: 242 243 ``` 244 ACTION=="add", SUBSYSTEM=="tty", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="204b", KERNELS=="something", SYMLINK+="knx1", OWNER="knxd" 245 ``` 246 247 Of course you need to replace the ``something`` with whatever ``udevadm`` displayed. 248 An example file should be in ``/lib/udev/rules.d/``. 249 250 * Run ``udevadm test /sys/bus/usb/drivers/cdc_acm/*/tty/ttyACM0``. 251 252 * verify that ``/dev/knx1`` exists and belongs to "knxd": 253 254 ``ls -lL /dev/knx1`` 255 256 * add ``-b tpuarts:/dev/knx1`` to the options in ``/etc/knxd.conf``. 257 258 If you have a second TPUART, repeat with "ttyACM1" and "knx2". 259 260 You'll have to update your rule if you ever plug your TPUART into a different USB port. 261 This is intentional. 262 263 264 ### Adding some other USB interface 265 266 These interfaces should be covered by the `udev` file knxd installs in 267 ``/lib/udev/rules.d``. Simply use ``-b usb:`` to talk to it, assuming you 268 don't have more than one. 269 270 If your interface isn't covered by our udev file, please add its vendor+product 271 and send us a patch. 272 273 274 ### Adding a TPUART (Pi HAT) interface to the Raspberry Pi 275 276 On the Raspberry Pi 2 and 3 the console is /dev/ttyAMA0. The udev line is: 277 278 ``` 279 ACTION=="add", SUBSYSTEM=="tty", KERNELS=="ttyAMA0", SYMLINK+="knx1", OWNER="knxd" 280 ``` 281 282 On the Raspberry Pi 4 the console is on /dev/ttyACM0. The udev line is: 283 284 ``` 285 ACTION=="add", SUBSYSTEM=="tty", KERNELS=="ttyACM0", SYMLINK+="knx1", OWNER="knxd" 286 ``` 287 288 This rule creates a symlink ``/dev/knx1`` which points to the console. The 289 knxd configuration will use that symlink. 290 291 On the Raspberry Pi 2 and 3 you need to disable the kernel's serial console. 292 Edit ``/boot/cmdline.txt`` and remove the ``console=ttyAMA0`` entry. Then reboot. 293 294 On the Raspberry Pi 3, the serial console is on ``ttyAMA1`` by default. 295 However, that is a software-driven serial port – the hardware serial 296 interface is used for Bluetooth on the Pi3. Varying CPU speed causes this 297 port to be somewhat unreliable. You should disable Bluetooth by adding 298 299 ``` 300 dtoverlay=pi3-disable-bt 301 ``` 302 303 to ``/boot/config.txt``, run ``systemctl disable hciuart``, and 304 reboot. The console and the TPUART module is now back on ``ttyAMA0``. 305 306 307 ## Migrating to 0.14 308 309 * If you build knxd yourself: install the ``libfmt-dev`` package, if 310 possible. 311 312 The knxd build process will try to download and build libfmt when that 313 package is not present. 314 315 * knxd is now configured with a .ini-style configuration file. 316 317 The old way of configuring knxd via a heap of position-dependent 318 arguments is still supported. 319 320 You can use ``/usr/lib/knxd_args <args-to-knxd>`` to emit a .ini file 321 that corresponds to your old list of arguments. 322 323 * Not configuring client addresses is now a hard error. Knxd will no longer 324 multiplex its clients onto its own address. 325 326 * knxd will not start routing any packets unless startup is successful on 327 all interfaces. 328 329 This means that it is now safe to use "socket activation" mode with 330 systemd. Previously, knxd might have lost the initial packets. 331 332 * knxd can now attach filters to a single interface, or to the core 333 (i.e. all packets get filtered). 334 335 * Tracing no longer logs the actual decoded contents of packet. 336 If you need that, use a "log" filter appropriately. 337 338 * knxd now transmits data synchronously, i.e. individual drivers no longer 339 buffer data for transmission. If you don't want that, use the "queue" 340 filter on slow interfaces. 341 342 ## Migrating to 0.12 343 344 * If you build knxd yourself: install the ``libev-dev`` package. 345 You no longer need the ``pthsem`` packages. 346 347 * You may need "-B single" in front of any "-b ipt:" or "-b usb:", esp. 348 when you need to program a device; normal use is often not affected. 349 knxd emits a warning 350 351 ``Message without destination. Use the single-node filter ('-B single')?`` 352 353 when it detects mis-addressed packets. 354 355 * You need "-e"; knxd no longer defaults to address 0.0.1. 356 357 * You need "-E" if you want to allow clients to connect (options -u -i -T). 358 As that's almost always the case, knxd will print a warning if this 359 option is missing. 360 361 * If you use knxtool's management tools (any command with "progmode" or 362 whose name starts with 'm'), please [open an issue](https://github.com/knxd/knxd/issues) 363 because knxd currently does not support these commands. 364 365 ## Migrating from ``eibd`` 366 367 * Before you build knxd: remove *any* traces of the old eibd installation 368 from ``/usr/local``, or wherever you installed it. 369 370 * The order of arguments is now significant. Among the "-D -T -R -S" arguments, ``-S`` must occur *last*. 371 Arguments which modify the behavior of an interface must be in front 372 of that interface. Global arguments (e.g. tracing the datagram router) 373 must be in front of the "-e" option. 374 375 * The 'groupswrite' etc. aliases are no longer installed by default. To 376 workaround, you can either add ``/usr/lib/knxd`` to your ``$PATH``, or 377 use ``knxtool groupswrite``. 378 379 * If you use Debian Jessie or another systemd-based distribution, 380 ``/lib/systemd/system/knxd.socket`` is used to open the "standard" 381 sockets on which knxd listens to clients. You no longer need your old 382 ``-i`` or ``-u`` options. 383 384 * knxd's Unix socket should never have been located in ``/tmp``; the 385 default is now ``/run/knx``. You can add a "-u /tmp/eib" (or whatever) 386 option if necessary, but it's better to fix the clients. 387 388 ## Contributions 389 390 * Contributions are *very* welcome 391 * Please use Github and create a pull request with your patches. 392 * Please see SubmittingPatches to correctly Sign-Off your code and add yourself to AUTHORS (`tools/list_AUTHORS > AUTHORS`) 393 * Adhere to our [coding conventions](https://github.com/knxd/knxd/wiki/CodingConventions). 394 * The git archive includes a helpful .vimrc file if you use VIM. 395 396 ### Compensation – personal statement 397 398 KNX development is not a simple matter and requires both time and dedicated 399 hardware for tests. The ETS software isn't exactly cheap, either, and 400 there is no free replacement. (I'd like to change that, but time is fleeting.) 401 402 Thus, wearing my hat as the (current) main author, I (Matthias Urlichs) 403 would like to ask you to consider contributing to knxd's development. 404 405 * [Github](https://github.com/sponsors/smurfix) 406 * [LiberaPay](https://liberapay.com/knxd/) 407 * Paypal: urlichs@m-u-it.de 408 * SEPA: DE34430609671145580100 @ GENODEM1GLS 409 * Ethereum: please ask 410 * Bitcoin: please don't waste power 411 412 I can issue a commercial invoice if required. 413 414 If you'd rather gift some hardware, please ask. 415 416 ## Community 417 418 * Code-related issues (aka "bugs") are on GitHub: https://github.com/knxd/knxd/issues 419 * For everything else there's a Google Groups forum on https://groups.google.com/forum/#!forum/knxd 420