Home

-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
  1. Issues and not supported devices
• Installation
  1. CCU-firewall
• Getting started
  1. HTTPS and CCU-User-Management
• Room concept
  1. Creating HAP instances for each room
  2. Adding HAP instance in HomeKit as a bridge
• Devices
  1. Publishing settings
  2. Mapping devices to instances
• Variables
• Programs
• Special devices
• Internals
• HomeKit Services Glossary

---

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.
• 

---

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:

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

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:

• Please enter under 5. the PIN given from your HomeKit-Instances list.

---

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.

Mapping devices to instances

...

---

...More to come...under construction...

Variables

Programs

Special devices

Internals

HomeKit Services Glossary

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