tilblechschmidt/homebridge-knx

KNX platform shim for homebridge

homebridge-knx Version 0.3

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 the new homebridge >=0.4.28 and Node >=6.0.0

Prerequisites

This node module requires a running (and properly configured) knx daemon (knxd). You can find the latest version here.
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, see there; nfarina recommends a global install as super user. It's a server tool, so we can safely assume that the person that installes it is sufficiently priviledged to do so. sudo npm install -g homebridge
• then install this package to <any> directory you want; If you installed homebridge globally I recommend to do so with homebridge-knx: sudo npm install -g homebridge-knx
• configure homebridge and its plugins. You might start by copying the KNX-sample-config.json to a new folder .homebridge in your user folder (on a default installation raspberry, it's /home/pi) and rename it to config.json
• Then put the configuration fileknx_config.json into ~/.homebridge, and adapt them to your needs (knxd address and some test devices in knx_config.json). You do not need a platform section in config.jsonany more!
• Eliminate everything (especially all group addresses) that might harm your KNX installation. Sending bus telegrams to your alarm device might wake the neighbourhood unpleasantly!
• when done, start homebridge with homebridge. If you have chosen a local install, go to the homebridge folder and do a bin/homebridge --plugin-path <any>/homebridge-knx with the path to the homebridge-knx installation.

Assumptions

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

HomeKit type	KNX addresses DPT
Boolean	DPT1
Integer	DPT5
Percentage	DPT5.001
Float	DPT9

knx_config.json

See the complete Doc!.

Add-ins

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

Happy testing!

Removing stale accessories from homebridge cache

The new (well, 1/2016) API of homebridge allows homebridge to cache the accessories for platforms that can add or remove accessories during runtime. As a next step in evolution, homebridge-knx already connects to that API.

Allow homebridge-knx to start the webserver by adding "AllowWebserver":true, at the beginning of your knx_config.json!

As a consequence remain devices, that homebridge-knx does not reconnnect to at start-up, stale and unreachable in HomeKit. To remove those shadows from HomeKit, use the little web server at <your-homebridge>:18081/list. You might change the web server port with "WebserverPort":18082 or whatever port suits you.

Clicking on the delete from cache link will only remove the devices from the current homebridge instance and their cache, not from the knx_config.json, that means they will be rediscovered upon next startup as new device in the default room!

Looking up service types and characteristics

If you have the webserver enabled (see above), you can get an auto-generated web-page with all the service types and their characteristics from homebridge. See the links at the bottom of your server's list page.

Killing homebridge

This is for debugging of your knx_config.json only. If you need homebridge to restart, you can use the setting "AllowKillHomebridge":true in your knx_config.json (right on top where the knxd properties are).
You'll get a new link at the bottom of the page at <your-homebridge>:18081/list that will homebridge-knx to throw an exception ("Committed_Suicide") which then causes homebridge to fail.
You should remove this setting after completing your knx_config.json for security reasons!

homebridge-knx's Issues

Example config for JalousieActuator

As it appears, there is some interest in the StupidJalousieActuator addin which implements a very rudimentary open-loop control system for shutters/blinds without a position query functionality.

Currently, I've got no time at hand to polish and merge it into the upstream plugin but for anybody else who's interested here is a config sample:

{
    "knxd_ip": "127.0.0.1",
    "knxd_port": 6720,
    "AllowWebserver": true,
    "WebserverPort": 18082,
    "Devices": [
        {
            "DeviceName": "Bathroom",
            "Services": [
                {
                    "ServiceType": "WindowCovering",
                    "Handler": "StupidJalousieActuator",
                    "ServiceName": "Shutter",
                    "Characteristics": [
                        {
                            "Type": "TargetPosition"
                        },
                        {
                            "Type": "CurrentPosition"
                        },
                        {
                            "Type": "PositionState"
                        }
                    ],
                    "KNXObjects": [
                        {
                            "Type": "ShortPress",
                            "Set": [
                                "3/7/0"
                            ],
                            "Listen": [
                                "3/7/0",
                                "3/4/3"
                            ],
                            "DPT": "DPT1"
                        },
                        {
                            "Type": "LongPress",
                            "Set": [
                                "3/7/1"
                            ],
                            "Listen": [
                                "3/7/1",
                                "3/4/2"
                            ],
                            "DPT": "DPT1"
                        }
                    ],
                    "LocalConstants": {
                        "TravelTime": 20
                    },
                }
            ],
        }
    ]
}