Special Devices - thkl/hap-homematic GitHub Wiki

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:

In the upcoming pop-up

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

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

In the upcoming pop-up

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

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:

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

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

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

The Key functionality provides the possibility to trigger an event in HomeKit coming from a Button connected to your CCU.

In the upcoming pop-up

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

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

In the upcoming pop-up

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

✔️ The HTTP-request methods GET, POST, PUT and DELETE are supported.

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

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

For more complex calls it might be better to define a script within a CCU program that is executed by pressing a key of a virtual device. See Issue #549

In the upcoming pop-up

• change the HomeKit Device name to be appeared in HomeKit,
• select the Service HomeMaticKeyMaticAccessory from the drop-down field,
• enter the correct Unlock Modus for your expected behavior of the KeyMatic

ℹ️ You can choose to either unlock or open the door.

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

// This device is available from version 0.55 onwards.

The garage door service retrieves information from multiple CCU devices. Thus, a garage door is created as "Special device".

⚠️ Before you move forward, please backup your HAP-HomeMatic configuration. A wrong configuration can cause loosing the total configuration, please find also in Issue #121. Issue solved from version 0.55 onwards.

ℹ️ If applicable, please create a new HomeKit Instance for your garage door and publish to HomeKit to find the garage door later in the Apple Home or Eve App.

A table of existing parameters Parameterliste helps for the configuration.

• The correct addressed of the devices are linked by the "Select" button. This is important, as e.g. the actor is using true/false, but the sensor 1/0 values.

Mandatory values are:

• The address of the sensor for the closed garage door, e.g. HmIP-RF.0000DA00000000:1.STATE
• The value of the sensor for the closed garage door , e.g. 0
• The address of the actor which opens the garage door, e.g. BidCos-RF.OEQ0000000:1.STATE

ℹ️ In this example the CCU has an internal program for closing the actor within 1s after opening.

Additional configuration:

• The message (JSON) for open actor: {"on": true, "off": false}
• If the actor only requires an impulse, an onTime can be added to the message: {"on":true,"onTime":1} (In this example, the actor will be closed after 1s)
• Sensor requery time (sec): 5

Important: 👀

• Please remove all grey sample values, as otherwise the configuration may get corrupt.
• All values without " "
• Finally select the HAP Instance - z.B. "Homematic Garage" and "Finish" the configuration.

ℹ️ Especially when the garage door disappears from your list of devices or from the HAP-Homematic page, please check the config.json, because default values such as the "Delay" are written into the json with every "Edit".
The file can be found at 📁 /usr/local/etc/config/addons/hap-homematic. Potentially SSH should be activated in the CCU (Control Panel - Security) to access.

Below a config.json of this example:

   "name": "Garagentor",
   "Service": "HomeMaticSPGarageDoorAccessory",
   "instance": "fb347482-bcaf-4a85-a6b8-0c1c5e426ace",
   "settings": {
    "state_sensor_close": "0",
    "state_sensor_open": "",
    "delay_actor_open": null,
    "delay_actor_close": null,
    "message_actor_open": "{\"on\": true, \"off\": false}",
    "message_actor_close": "",
    "sensor_requery_time": 5,
    "address_actor_open": "BidCos-RF.OEQ0000000:1.STATE",
    "address_sensor_close": "HmIP-RF.0000DA00000000:1.STATE"
   }

ℹ️ Remember to restart the HAP Service after any change ("Internals / Restart HAP Service")

The following example shows a photo documentation of working garage door opener solution for the acceleration sensor HMIP-SAM in combination with the garage door controller HmIP-WGC from the user @Icke-NOH:

More to come ...🚧