iq-scm / openhab-homekit-bridge

Bridging OpenHAB items to the HomeKit Accessory Protocol

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)