homebridge-knx Version 0.4

KNX platform shim for homebridge. This cannot run stand-alone in node!

Please also visit homebridge github homepage first.

Latest to homebridge-knx changes can be found in the CHANGELOG.md

This can only be used with homebridge >=1.0 and Node >=10.19.0

Prerequisites

This node module requires either

• a running (and properly configured) knx daemon (knxd). You can find the latest version here.
• another KNX router which can be reached by KNX multicasts.

I cannot support the knxd. Please address issues directly at the knxd issue pages. It might help to search the existing issues, as your problem might have been solved already.

Installation and running

• Install homebridge first, from https://homebridge.io/;
• Once you have your instance running (without any devices yet), go to the Plugins tab and type knx in the search box
• homebridge-knx should be within the top five hits (yes, there are alternatives), please check the name before installing
• Then put the configuration file knx_config.json into ~/.homebridge (or another folder to your liking, but it should be reaadable and writable by user homebridge or group homebridge which is created by the homebridge installer), and adapt them to your needs (knxd address and some test devices in knx_config.json)
• Eliminate everything (especially all group addresses) that might harm your KNX installation. Sending bus telegrams to your alarm device might wake the neighbourhood unpleasantly!
• If you used the dfeault paths (~/.homebridge/knx_config.json) you can just restart homebridge using the GUI
• If you didn't, or want to use child bridges for more accessories (than 149) you need to configure homebridge (using the GUI e.g.). The following sample is from my test installation

{
    "bridge": {
        "name": "Homebridge 17AF",
        "username": "0E:0B:9B:24:17:AD",
        "port": 51485,
        "pin": "880-83-869",
        "advertiser": "avahi"
    },
    "accessories": [],
    "platforms": [
        {
            "name": "Config",
            "port": 8581,
            "auth": "form",
            "theme": "auto",
            "tempUnits": "c",
            "lang": "en",
            "platform": "config"
        },
        {
            "name": "KNX",
            "platform": "KNX",
            "config_path": "/home/pi/homebridge/dg-knx_config.json"
        },
        {
            "name": "KNX",
            "platform": "KNX",
            "config_path": "/home/pi/homebridge/og-knx_config.json",
            "_bridge": {
                "username": "0E:0B:9B:24:17:00",
                "port": 51490
            }
        }
    ]
}

Assumptions

Without using a special handler (add-in) for the service, homebridge-knx assumes the following:

knx_config.json

See the complete Doc!.

Add-ins

Add-in (aka "handlers") can change the default behavior. See the article

Happy testing!

Changelog

0.4.3

• merged PR #198 (Update WindowCoveringTilt.js) by @EyeOfTheStorm
• merged PR #204 (Update GarageDoorOpenerAdvanced.js) by @christof-fersch
• fix knxd DPT type conversion, was overrun by #194 (Fixes for knxjs integration) in the case that handlers with KNXObjects were present.
• accordingly update GiraJalousieActuator
• removed the documentation of the built-in web server, as the most functionality is either gone (restart homebridge) and/or covered by the homebridge GUI now (webserver is still there but will be removed)

0.4.2

• fix undefined variable name

0.4.1

• bump dependency versions

0.4.0

• enable child bridge mode by providing a path (absolute) to a configuration file:
  Example in the config file (e.g. in Homebridge GUI):

    "platforms": [
        {
            "name": "Config",
            "port": 8581,
            "platform": "config"
        },
        {
            "name": "KNX",
            "platform": "KNX",
            "config_path": "/home/pi/homebridge/some-knx_config.json"
        },
        {
            "name": "KNX",
            "platform": "KNX",
            "config_path": "/home/pi/homebridge/another-knx_config.json",
            "_bridge": {
                "username": "0E:0B:9B:24:17:00",
                "port": 51490
            }
        }
    ]

• quite a while back @jendrik found some issues and fixed them. They have been in the master branch ever since but not properly honored or published in a release. PR #194 also contain sthe fixes for using knxjs instead of the eibd module to talk to other KNX routers than knxd

0.3.27

• @CyberChris79 found a breaking change in HAP-nodeJS (the HAP protocol implementation which homebridge is build on) which broke the tiny web server that can display HAP Services and such (see https://github.com/snowdd1/homebridge-knx#looking-up-service-types-and-characteristics) Note to self: the webserver implementation is ugly and has grown too much for kind-of inline code in index.js

0.3.26

• @giase82 updated the ThermostatMode handler in #169 to be able to update the Bus value also from HomeKit
• Found another glitch in the knxaccess.js library where KNXJS was used even if it was not specified (regression from 0.3.24)

0.3.25

• martijndierkx contributed an MDTJalousieActuator handler in PR #167 - Big thanks to him!
• I updated the SimpleGarageDoor handler to accept two new local constants: "ResetOpenDoorContactTime" and "ResetCloseDoorContactTime" in Milliseconds if you want to issue an KNX "0" after a givin time, in case you don't want or must not have a relay powered all the time. Fixes German issue 65 from homebridge-knx-de at [https://github.com/snowdd1/homebridge-knx-de/issues/65]
• And I updated the handler API doc to reflect the changes from v0.3.21; Actually the SimpleGarageDoor handler uses the new init event.

0.3.24

• patched configuration to default to knxd again. Fixes #162. See also changed documentation in knx_config.json.md

0.3.23

• With PR #160 Luehrsen added the ability to have local add-in directories. I hope that you all still continue to share your add-ins ("handler"s) via PRs here, so that all of us can benefit from the developments.
• Homebridge made a leap to version 1.0.0 - with bracking changes:
  • you all need to change your config.json and add the KNX platform manually! See updated sample file https://github.com/snowdd1/homebridge-knx/blob/master/KNX-sample-config.json and issue #163
  • node version needs to be at least 10.0 now!
• Dependency bump to current versions

0.3.22

• thanks to Paul's PR #152, now knxd is not mandatory any more. Documentation will follow!
• And he also fixed the typo in the GarageDoorAdvanced handler in #158.

0.3.21

• new call hooks for custom handlers. Invented by ctschach, the custom handlers now get informed when the service is ready
  • onServiceInit()
    and when all devices are loaded and initialized
  • onHomeKitReady()

0.3.20

• thanks to hints in #149 I found another glitch in the dimmer handler, which was there for ... well, let's settle for "a long time" :-)

0.3.19

• new feature: EIBHomeControl contributed a simple security system handler.

0.3.18

• bugfix for shutter state (opening/closing) being shown in home app reversed (yes, home app now uses the PositionState value in ios12.1+)

0.3.17

• bugfix for an issue in which external KNX switching off of a dimmable light was not recognized by the dimmer handler. Thanks to Michael for his PR 136

0.3.16

• bugfix for a scaling issue with the new handler in 0.3.15

0.3.15

• new handler for Dimmers to avoid Apple's Home(c) app's disastrous handling of On and Brightness events. Thanks dlt- for pointing that out. I rewrote it to make it more customizable, and to avoid flickering of the slider in the app due to knx responses.
• new Readme design :-)

0.3.14

• fix bug #122 with wrongly spelled service reference in custom API
• fix bug #123 with missing integer typer UINT12 and UINT32 which are now used in Homekit(c) types
• bump dependencies to actual versions

0.3.13

• bump required packages to new versions:
  • node-eibd to 0.3.9 (regression!)
  • debug to 3.1.0

0.3.12

• changed logging of KNX value changes: type INFO changed to DEBUG to avoid filling the logs, #93
• commented out the code stub throwing an exception at homebridge start, #89
• allow Reverse keyword for UINT8 homekit types that have only 0,1 as valid values (treat as boolean) #91 Had to be skipped for complete rework of data value validation in HAP-nodeJS v.0.4.32 and beyond
• The parameter "AllowWebserver" now has a companion "WebserverPort" if you want to use something different than 18081 (or want to run two instances in parallel as I did)
• requires homebridge 0.4.28
• merged fix from gkuehn001 for true/false vs. 1/0 responses from Siri and home app for OneWaySwitch handler

0.3.11

• tiny internal web server has new pages:
  • /availservices shows the services from hap-nodejs
  • /availcharacteristics shows the characteristics from hap-nodejs
  • these pages are linked
  • localization is prepared but not implemented yet
  • properties of the characteristics are listed but not explained

0.3.10-b

• Just pushing dependency to eibd to beyond 0.3.8, which was faulty (and it was my fault.)

0.3.10

• New Add-in

  • From the German knx-user-forum.de the idea of having a one-way switch to shut off central functions such as switching lights off all at once was voiced, so here it is: OneWaySwitch handler

• Ignore Option

  • For those who want to (for whatever reason) run multiple homebridge instances on the same machine whilst having them globally installed, now a file named **knx-ignore.txt** in the homebridge-configuration folder (of the respective instance, defaults to ~/.homebridge ) prevents the loading of homebridge-knx.

0.3.9

• New Add-in!
  • for CO2Sensors, thanks to Matevz Gacnik! He was so kind to put it in Issue 85 for me to publish it.
  • Translates definable limits to HomeKit specific status values. See the example in the code

0.3.8

• Documentation of knx_config.json changed: Recommend to place all services in a room into one device. Issue 83
  Thanks to Matevž Gačnik for pointing that out.
• Version bumped to 0.3.8 as npm does not like 0.3.7-a (no update on `npm update homebridge-knx, see #82)

0.3.7-a

• Fixed the dependency to homebridge, which was already somewhat futuristic:
  • Current is 0.4.16
  • Required 0.4.19
    did not work, fixed now.

0.3.7

• Enhancements
  • Does not send values to homekit that haven't changed. Might take some pressure from the Lightbulb with dimmer-going-havoc issue, though it doesn't solve it completely.

0.3.6

• Bugfixes

  • 79 Wrong assumption about FORMAT and UNIT of homekit types referring to PERCENTAGES

0.3.5-a

• Enhancements

  • 60 Experimental RBG light controller updated. Should now convert from HomeKit to RGB and from KNX RGB to Homekit HSB. Untested. Have no hardware.

0.3.5

• Enhancements

  • 72 Allow 16 bit addresses (extended address structure, might be incompatible with older devices; in case of doubt restrict your address range to (15/7/255) as in ETS 3 and before)

0.3.4

• Bugfixes

  • 66 Invalid values returned for enumerated-code characteristics

  • 67 Reverse keyword did not work at all

  • 69 group address validation is wrong

• New mini feature

  • new keyword "ValidValues" allows to restrict the options in homekit apps such as Apple's Home. Others might not yet support that (Elgato Eve 2.5.1 does not, e.g.)

0.3.3

• included new addins
  • WindowCoveringTilt by giase82/Christof
  • GiaseGarageDoorOpener by giase82/Christof
  • RGB light test addin
• some code cleaning
• Known Issues
  • Reverse not working reliably in some cases https://github.com/snowdd1/homebridge-knx/issues/67
  • Not filtering invalid responses before answering to homekit https://github.com/snowdd1/homebridge-knx/issues/66

0.3.2

• Fixed `-U <path> not being used for knx_config.json path
• added new getProperty() method to add-in API

0.3.1-a

Updated README only

0.3.1

maintenance/patch release

• Updated homebridge dependency to >=0.4.9, as an important bug has been fixed in that version, that especially KNX users with a lot of services (and we all have, don't we?) could affect.
• Updated eibd dependency to latest version 0.3.5
• Updated debug dependency to latest stable version 2.3.0
• Removed a legacy line of code that was never executed

0.3.0

initial release

Version numbering conventions

First digit - Major version; if =0 then software is assumed to be not production ready (in this case - it's open source non-commercial and therefore use at own risk!)
Second digit - Minor version number; Increase of minor version should not break compatibility, unless first digit was 0
Third digit - Patch number, unless first digit was 0; then minor version
Appendices - Sub-Patch; usually no code change; documentation changes only! Will usually not be published to NPM