Bridging OpenHAB items to the HomeKit Accessory Protocol
JavaScript Shell
Latest commit 38afaae Oct 24, 2016 @htreu committed on GitHub Let npm update install the latest hap-nodejs version

README.MD

Build Status Coverage Status Codacy Badge

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