OpenHAB HomeKit Bridge

OpenHAB HomeKit Bridge bridges openHAB items to Apple´s HomeKit Accessory Protocol. It is based on hap-nodejs.

Watch the demo video here and Siri controlling roller shutters here.

Prerequisites

openHAB server running with at least one Switch item configured
node.js 0.12.x, 4.0.x or 4.1.x
an iOS device running iOS 8 or 9
an iOS app for modifying the HomeKit database (like elgato eve)
this repository

Install the OpenHAB HomeKit Bridge:

On non OS X systems install the avahi library:

sudo apt-get install avahi-daemon libavahi-compat-libdnssd-dev
Install the node module dependencies:

npm update

Create a custom sitemap which lists all items you want to control with HomeKit:

sitemap demo label="HomeKit" {
  # Lightbulb (On/Off), SwitchItem is always a lightbulb. See Frames for outlets.
  Switch item=DemoSwitch label="Toggle Switch"

  # Dimmer items (On/Off, Brightness)
  Slider item=DimmedLight label="Dimmed Light" switchSupport

  # RGB light items (On/Off, Brightness, Hue, Saturation)
  Colorpicker item=RGBLight icon="slider"

  # Rollershutter/Blinds
  Switch item=Shutter_GF_Living

  # Temperature sensor, value is taken from label
  Text item=Temperature_GF_Living label="Livingroom [%.1f °C]"

  Frame label="outlet" icon="outlet" { # Outlets must be configured in a Frame.
    Switch item=Outlet_GF_Living label="Radio"
  }

}


The following mapping of openHAB items and HomeKit items apply:

openHAB item | sitemap item | HomeKit item | Functions
-------------|--------------|--------------|----------
Switch | Switch | Lightbulb | On/Off
Dimmer | Slider | Lightbulb | On/Off, Brightness
Color | Colorpicker | Lightbulb | On/Off, Brightness, Hue, Saturation
Rollershutter | Switch | Rollershutter | Opening state 0% - 100%
Number | Text | Temperature | temp in °C
Switch | Frame* + Switch | Outlet | On/Off

\* The Frame must be tagged with `label=outlet` and/or `icon=outlet` to let the bridge pick up its Switch items as outlets.

##### Run OpenHAB HomeKit Bridge
This connects to OpenHAB at 192.168.0.99 on port 8080 and loads all items from a sitemap named 'demo.sitemap':

`npm start -- --name "myOpenHAB-Bridge" --server 192.1.0.99:8080 --sitemap demo`

###### Command line options:

<dl>
<dt>-n, --name</dt>
<dd>The name of the bridge as shown in the HomeKit database. _This option is mandatory._ </dd>
<dt>-s, --server</dt>
<dd>The network address and port of the OpenHAB server as ```ip:port```. Defaults to 127.0.0.1:8080</dd>
<dt>-p, --pincode</dt>
<dd>The pincode used for the bridge accessory. Defaults to 031-45-154.</dd>
<dt>-m, --sitemap</dt>
<dd>The name of the sitemap to load all items from. Items must not be nested in frames or groups. Defaults to 'homekit'.</dd>
</dl>

To access the bridge from an iOS device (9.0+) use Apples [HomeKit Catalog 2.0](https://developer.apple.com/library/ios/samplecode/HomeKitCatalog/Introduction/Intro.html) demo application or a vendor app like elgato´s eve (see _Prerequisites_). Use the predefined pin code _031-45-154_ to add the bridge as an accessory.

You may use the `start.sh.template` to create your own simple start up script. This gives you at least simple logging output and debugging possibilities in case the bridge runs in the background.

##### Running Tests

To execute unit tests run

`npm test`

To produce test coverage output run

`npm run-script coverage`

##### Known issues
* iOS HomeKit may not delete the bridge properly from its database. In this case the bridge can neither be connected nor added again. Delete the _persist_ folder and restart the bridge with a new name using the 'name' option.

##### Backlog/ToDo
* Distinguish between switches and lights when adding SwitchItems -> see [Issue 29](https://github.com/htreu/OpenHAB-HomeKit-Bridge/issues/29)
* Implement Rollershutter -> see [Issue 7](https://github.com/htreu/OpenHAB-HomeKit-Bridge/issues/7)