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:

* 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:

-n, --name

The name of the bridge as shown in the HomeKit database. _This option is mandatory._

-s, --server

The network address and port of the OpenHAB server as ```ip:port```. Defaults to 127.0.0.1:8080

-p, --pincode

The pincode used for the bridge accessory. Defaults to 031-45-154.

-m, --sitemap

The name of the sitemap to load all items from. Items must not be nested in frames or groups. Defaults to 'homekit'.

To access the bridge from an iOS device (9.0+) use Apples HomeKit Catalog 2.0 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
• Implement Rollershutter -> see Issue 7