Skip to content

Home

Jump to bottom
Marc Wollersheim edited this page Sep 27, 2020 · 47 revisions

-under construction

HAP-HomeMatic - WIKI

HAP-HomeMatic is a lightweight add-on for the CCU3 and Rasperrymatic to access your HomeMatic devices from HomeKit.

Note: If you are searching for a homebridge version, please find there the add-on homebridge-homematic.

Table of contents

Prerequisites

Supported Limits
CCU3 CCU2 model or older is not supported
Rasperrymatic No additional hardware/software is needed

Issues and not supported devices

  • For devices not supported yet
  • or s.th. is not working properly, please open an issue here.

Installation

Download the hap-homematicXXXXX.tar.gz file from latest release of HAP-HomeMatic and install it via system preferences in the HomeMatic/ Rasperymatic-WebUI. The add-on will install all other needed software dependencies and you will have a HomeKit button in your system preference page after a restart of the CCU. This may take a few minutes.

CCU-firewall

Please ensure, that your CCU-firewall allows/does not block the usage of the following needed ports:

  • 9874 -> Config WebUI
  • 9875 -> RPC event server
  • 9876 -> RPC event server CuxD (optional)
  • 9877..n HAP Instance 0 .. n

Getting started

  • With a click on the new HomeKit-Button in your CCU-systempreferences, who will be redirected to the HAP-Homematic-Config-Web-UI.
  • If you prefer to enter manually, try http://IP-of-homematic-raspi:9874/.

Once you have entered the site, an assistant will welcome you. 👍

HTTPS and CCU-User-Management

Nevertheless, if you are you are using HTTPS and/or CCU-User-Management, a first step should be:

  • Usage of HTTPS-version of your CCU-WebUI-page: Enable HTTPS also for the HAP-HomeMatic configuration page.
    HAP-HomeMatic will use the self-signed TLS-certificate from your CCU.
  • Usage of CCU-user-management as an optional AUTHENTIFICATION for HAP-HomeMatic: If option is turned on, you have to call as CCU-admin the configuration page from your CCU-WebUI-system preference page to use a valid session. Other users are excluded.
  • HTTPS-AUTH-Picture

Room concept

HAP, the Homekit Accessory Protocol, does not know a room concept. So when you add one or more devices to a bridge the will appear at the same room as the bridge in your HomeKit client application. Thereof the user experience will be very confused, once you have more than a few devices, you want to integrate.

To overcome, HAP-HomeMatic is concepted to fire up multiple bridges (so called HAP instances). In the next steps we will creating instances in HAP-HomeMatic, link each of them to a specific HomeMatic-room and integrate them afterwards as so called bridges within HomeKit in a iOS app (e.g. Apple Home or Eve) - meaning one bridge per room.

Creating HAP instances for each room

  • During the installation wizzard you may add a instance for each of your rooms, add theese instances to HomeKit and put them into rooms.

From this time on adding a new device to an instance will place this device into the same room as your HAP instance (so called Bridge within HomeKit).

To add an HAP instance,

  • choose Edit HomeKit instance in the left menubar and click on the New-button on the right bottom,
  • enter the room name to be appeared in HomeKit in the field HomeKit instance name,
  • assign the HomeMatic room from the drop-down field,
  • and repeat the last three steps for each room you want to use within your HomeKit app:
HAP instance picture
  • After pushing the Finish-button, the new instance will be created and appears in the HomeKit-Instances list. The PIN given here you will need in the next step within your iOS app:
HAP instance floor pictur

Adding HAP instance in HomeKit as a bridge

Our new room "Flur/floor" is now within HAP-HomeMatic as a HAP instance available.

  • On the receiver side, meaning in our HomeKit app like Home or Eve, we need to add the instance as a new so called bridge, recognized as a room within iOS:
Bridge steps1-3
  • Please enter under 5. the PIN given from your HomeKit-Instances list.
Bridge steps4-6

Devices

After we have integrated all for the moment needed instances with rooms through bridges to the HomeKit-app, we need to enable, that devices within a instance will be published to Homekit.

Publishing settings

Note: This can be also done later, clause-by-clause. It should not be done before the bridge is linked to HomeKit, otherwise each device needs to be mapped within HomeKit manually.

Publish settings

Mapping devices to instances

To add and map a device to a room (HAP instance, bridge),

  • choose Devices in the left menubar and click on the New-button on the right bottom,
  • change the device name to be appeared in HomeKit in the field HomeKit Device name,

Try to choose a self-speaking name. There is no need to indicate the room in the device name, as it will combine within iOS by HomeKit itself.

  • assign a Service from the context-sensitive drop-down field (please find the description of a Service below the selection),
  • select a Subytype of device from the context-sensitive drop-down field (if applicable, only appears, when more than 1 possibility is existing),
  • and last but not least, map to the room (HAP-instance) whereas it should appear in iOS and press Finish.

Note: It is possible to assign a device to more than 1 room/ instance by using the Add to another instance-button.

A few seconds later, the device should appear in the respective room within you iOS app. Congratulations 👍

  • Repeat this steps for each device in a room you want to use within your HomeKit app.
Device adding

Note: You can change the settings per device at any time, when you press the Edit-button beside each device in the list.

Variables

To add and map a CCU variable to a room (HAP instance, bridge),

  • choose Variables in the left menubar and click on the New-button on the right bottom.
Variables

In the upcoming pop-up
Variables

  • change the variable name to be appeared in HomeKit in the field HomeKit Name,

Try to choose a self-speaking name. There is no need to indicate the room in the device name, as it will combine within iOS by HomeKit itself.

  • assign a Service from the context-sensitive drop-down field (please find the description of a Service below the selection),
  • assign a Instance from the drop-down field to map to the correct room in HomeKit,
  • select a Subytype of device from the context-sensitive drop-down field (if applicable, only appears, when more than 1 possibility is existing)

Variable requery time

Variable requery time can be defined in minutes as the variable will be queried again to fetch a new data.

Factor

A Factor can be defined as well, as e.g. Eve wants kwH. The value of your variable will be multiplied with this factor, so here u are able to do the math. If HomeMatic counts in Wh, 1000 would be a good factor to apply in kwh.

Trigger

Due to the fact, that your ccu will not sent a message to hap when a variable will change its value, we have to build a helper. HAP will use a virtual key from your CCU for that helper. This key will be monitored by HAP. So HAP is able to detect when its time to reload the variables.
Variables trigger

  • Select a Virtual Key from CCU in the drop-down field, which is dedicated only for HAP-HomeMatic,
  • and check-mark Create/Update the CCU helper program.

The program to manage all this is build by HAP_HomeMatic automatically.
To validate in your CCU.WebUI, you will find afterwards a program called _hap_autotrigger_.

Presence detector

One good example of an variable could be presence (german: Anwesenheit). Some people are using for the detection the CCU Addon "HM-pdetect" in combination with a FritzBox.
Another popular possibility is the iOS-app PocketControl, which sets also a CCU variable with Geofencing support.

Nevertheless details of how to set a presence variable within the CCU is part of the different respective solutions. Within HAP-HomeMatic, any kind of a CCU variable could be used to connect to HomeKit, as described above.

Programs

To add and map a program to a room (HAP instance, bridge),

  • choose Programs in the left menubar and click on the New-button on the right bottom.
Programss

In the upcoming pop-up

  • change the HomeKit name to be appeared in HomeKit in the field HomeKit Name.

As always, try to choose a self-speaking name. There is no need to indicate the room in the device name, as it will combine within iOS by HomeKit itself.

  • Assign a Instance from the drop-down field, to map to the correct room in HomeKit.

Special devices

To add and map a special device to a room (HAP instance, bridge),

  • choose Special devices in the left menubar and click on the New-button on the right bottom.

In the following, you will find a non-exhausting list of different examples of next steps to configure special devices:

CCU Duty Cycle

In the upcoming pop-up
Duty Cycle

  • change the HomeKit Device name to be appeared in HomeKit, e.g. Duty Cycle CCU,
  • Select a Service HomeMaticSPCCUDutyCycleAccessory from the drop-down field and
  • map to the correct room in HomeKit by choosing the corresponding Instance.

Note: It is possible to assign a device to more than 1 room/ instance by using the Add to another instance-button.

CCU Temperature

In the upcoming pop-up
CCU Temp

  • change the HomeKit Device name to be appeared in HomeKit, e.g. CCU Core,
  • Select a Service HomeMaticSPCCUTempAccessory from the drop-down field and
  • map to the correct room in HomeKit by choosing the corresponding Instance.

FakeGato History

All generated Homekit devices will support FakeGato history (if there is a history option in Eve). But a history is only available if u are using the Eve app as a HomeKit controller. While using Eve, the configured [CCU Temperature)[#ccu-temperature) enables the following few as ab example:
CCU Temp iOS example

Multi channel push button

As in HomeKit no button to trigger events is existing, HAP-HomeMatic provides as a workaround a switch, which automatically turns off. The Push button functionality provides the possibility to trigger an event in CCU coming from HomeKit.

In the upcoming pop-up
Multichannel Push button

  • change the HomeKit Device name to be appeared in HomeKit,
  • select a Service HomeMaticSPMultiChannelPushButtonAccessory from the drop-down field,
  • select to the correct CCU device by choosing the Adress of the Key Channel from the drop-down menu and
  • map to the correct room in HomeKit by choosing the corresponding Instance.

Note: It is possible to assign a device to more than 1 room/ instance by using the Add to another instance-button

Multi Channel Virtual Key

As in HomeKit no button to trigger events is existing, HAP-HomeMatic provides as a workaround a switch, which automatically turns off. The Key functionality provides the possibility to trigger an event in HomeKit coming from the CCU.

In the upcoming pop-up
Multichannel Key

  • change the HomeKit Device name to be appeared in HomeKit,
  • select a Service HomeMaticSPMultiChannelKeyAccessory from the drop-down field,
  • select to the correct CCU device by choosing the Adress of the Key Channel from the drop-down menu and
  • map to the correct room in HomeKit by choosing the corresponding Instance.

Note: It is possible to assign a device to more than 1 room/ instance by using the Add to another instance-button.

Garage door

Refer/integrate to https://github.com/thkl/hap-homematic/wiki/Garagentor

HTTP Call

In the upcoming pop-up
HTTP GET CALL

  • change the HomeKit Device name to be appeared in HomeKit,
  • select a Service HomeMaticSPKeyAccessory from the drop-down field,
  • enter the correct URL for the HTTP request

Note: Currently, only the HTTP-GET method is supported. More to come.

  • map to the correct room in HomeKit by choosing the corresponding Instance.

Note: It is possible to assign a device to more than 1 room/ instance by using the Add to another instance-button.

Internals

Glossary

Services

HomeMaticWindowsAccessory - This service provides a window device in HomeKit based on a CCU contact.
HomeMaticPushTheButtonAccessory - This service provides a switch HomeKit which will press the assigned key at your CCU.
HomeMaticKeyAccessory - This service provides a programmable switch in HomeKit based on a CCU KEY.
HomematicDoorAccessory - This service provides a door based on a CCU contact in HomeKit.
HomematicContactSensorAccessory - This service provides a contact in HomeKit.
HomematicFloorHeatingActuatorAccessory - tbc

Subytypes of devices

  • Lightbulb
  • Fan
  • Switch
  • Outlet
  • ...

A full list of by HomeKit supported Accessories is maintained on the iOS Home Accessories website

Table of Contents

HAP-HomeMatic - WIKI

Table of contents

Clone this wiki locally