|
9 | 9 |
|
10 | 10 | For details on how to install and configure this adapter, please see the [Wiki](https://github.com/jensweigele/ioBroker.yahka/wiki) |
11 | 11 |
|
| 12 | +## Prerequisites |
| 13 | +Before you can install the Adapter, you have to some packages (for Linux): |
| 14 | +```sudo apt-get install libavahi-compat-libdnssd-dev``` |
| 15 | + |
| 16 | +## Install the latest **Release** |
| 17 | +Just hit the "+" button behind "Homekit yahka adapter" in the ioBroker Admin Panel on the "Adapter" page |
| 18 | + |
| 19 | +## Install the latest **Beta** |
| 20 | +If you want to be on the edge and test the latest beta, you could install the adapter via a github url.<br> |
| 21 | +(Sometimes an additional upload [f.e. iobroker upload yahka] and adapter restart is needed) |
| 22 | +<br> |
| 23 | + |
| 24 | +## Troubleshooting |
| 25 | + |
| 26 | +### Not all new features are available: |
| 27 | +If not all new feature are available after a yahka update, try a upload (f.e. iobrober yahka upload) and restart the adapter. |
| 28 | + |
| 29 | + |
| 30 | +### Missing Avahi daemon (linux) |
| 31 | +If you are having the following error in the log:<br> |
| 32 | +``` |
| 33 | +Error: 2016-07-26 18:57:17.989 error at Error (native) |
| 34 | +Error: 2016-07-26 18:57:17.989 error dns service error: unknown |
| 35 | +uncaught 2016-07-26 18:57:17.985 error exception: dns service error: unknown |
| 36 | +``` |
| 37 | + |
| 38 | +You have to do some additional steps: |
| 39 | +* install avahi daemon: |
| 40 | +```sudo apt-get install avahi-daemon -y``` |
| 41 | +* Edit avahi-daemon.conf |
| 42 | +```sudo nano avahi-daemon.conf ```<br> |
| 43 | +change the following variables: |
| 44 | +```host-name=\<put in your hostname\> |
| 45 | +domain-name=local |
| 46 | +use-ipv4=yes |
| 47 | +use-ipv6=yes |
| 48 | +enable-dbus=yes |
| 49 | +``` |
| 50 | + |
| 51 | +### Missing pam-devel Package (linux) |
| 52 | +If you are having the following error in the log:<br> |
| 53 | +``` |
| 54 | +../authenticate_pam.cc:30:31: fatal error: security/pam_appl.h: Datei oder Verzeichnis nicht gefunden |
| 55 | +#include <security/pam_appl.h> |
| 56 | +``` |
| 57 | +You have to install the pam-devel package: |
| 58 | +* install avahi daemon: |
| 59 | +```sudo apt-get install pam-devel -y``` |
| 60 | + |
| 61 | +### Missing bonjour (windows) |
| 62 | +- Download: ```https://www.samuelattard.com/files/bonjourcore2.msi``` |
| 63 | +- Execute: ```msiexec /i bonjourcore2.msi /qn``` |
| 64 | +- remove: ```del bonjourcore2.msi``` |
| 65 | +- Download: ```https://www.samuelattard.com/files/bonjoursdksetup.exe``` |
| 66 | +- Execute: ```bonjoursdksetup.exe /quiet``` |
| 67 | +- Remove: ```del bonjoursdksetup.exe``` |
| 68 | +- Set: ```set BONJOUR_SDK_HOME=C:\Program Files\Bonjour SDK``` |
| 69 | + |
| 70 | +And after that install yahka adapter. |
| 71 | + |
| 72 | +## Some words about HomeKit |
| 73 | +The architecture of HomeKit is as follows:<br> |
| 74 | +There are **devices** as logical entities. Each device can have multiple **services** and each service has multiple **characteristics**.<br> |
| 75 | +At the end, a characteristic is an endpoint where values could be read from or write to.<br> |
| 76 | +Which characteristics a service could have, is defined by Apple/HomeKit and determined by the service type. The service types are also defined by Apple/HomeKit. |
| 77 | + |
| 78 | +Example:<br> |
| 79 | +A Garage Door opener is a device which could have two services: <br> |
| 80 | +1. Garage Door Opener |
| 81 | +2. Light |
| 82 | + |
| 83 | +The Garage Door Opener Service itself could have different characteristic like: CurrentDoorState, TargetDoorState and many more. <br> |
| 84 | +Also the Light Service could have different characteristics, like: On (and many others for chaning the light color etc.) |
| 85 | + |
| 86 | +## What Yahka does |
| 87 | +With Yahka it is possible to map an ioBroker Datapoint to an HomeKit Characteristic. <br> |
| 88 | +Since sometimes mappings are necessary (e.g. the "State" values of a garage door is different between HomeKit and other systems), there is also the possibility to specify Functions to convert the values. This is described below.<br> |
| 89 | +To avoid too much administration work, all Devices you create in Yahka are behind a so called "Bridge". With this bridge, you only need to pair the Bridge with your iOS device to get access to all devices. Otherwise you would need to pair every Yahka device with Homekit. |
| 90 | + |
| 91 | +## Setup the Bridge and create devices and services |
| 92 | +Each device which needs to be paired with Homekit needs a "username" which has the form of a mac-address. Yahka automatically generates a random username for each yahka instance. <br> |
| 93 | +**Important: if you change the username after pairing Yahka with HomeKit, you need to reconfigure all devices in iOS (room assignment, position etc.). Changing the username means to iOS, that it is a complety new device!**<br> |
| 94 | +Beside the username, you need to specify a PIN code which needs to be entered on the iOS device. |
| 95 | +This could all be specified by clicking on ":yahka.0" in the admin panel of Yahka. (Expand the Panel on the right side after clicking on the list entry). The name of the bridge could also be changed there. |
| 96 | + |
| 97 | +After setting up the bridge, you could add the devices you like with the "Add Device" Button on the top. |
| 98 | +Once a device is added/selected, you could add services to this device.<br> |
| 99 | +It is necessary to specify a service name and a service type.<br> |
| 100 | +Depending on the service type, the list of available characteristic changes<br> |
| 101 | + |
| 102 | +## Setting up Characteristics |
| 103 | +If you want to support a characteristic, you have to tick the "enabled" checkbox on the left side of the characteristic. |
| 104 | +For each characteristic you could specify the following properties: |
| 105 | +- InOutFunction: you could specify a predefined function which is responsible for passing the values from HomeKit to ioBroker and vice versa |
| 106 | +- InOutParameter: here you could specify parameters for the selected InOutFunction. The available/expected Parameters depends on the selected Function. A brief overview of the Functions and Parameters are stated below. |
| 107 | +- ConversionFunction: additionally to the InOutFunction, you could also specify a function which converts a value coming from HomeKit to ioBroker (and vice versa) |
| 108 | +- ConversionParameter: same as InOutParameter - the available/expected params depend on the selected function. |
| 109 | + |
| 110 | +## Overview of InOut-Functions |
| 111 | + |
| 112 | +|Function|Expected Parameter|Description| |
| 113 | +|---|---|---| |
| 114 | +|const|Value|The const function always passes the value specified in "InOutParameter" to Conversion Function if HomeKit reads the value. If HomeKit wants to write the value, this action is denied |
| 115 | +|ioBroker.State|name of a ioBroker datapoint|With this function, the adapter uses the specified ioBroker datapoint for read and write operations. All operations are done immediatelly without buffering or filtering (values are passed to the specified Conversion functions)| |
| 116 | +|ioBroker.State.Defered|name of a ioBroker datapoint|With this function, the adapter uses the specified ioBroker datapoint for read and write operations. Write operations from HomeKit are directly passed to the conversion function. Changes from ioBroker are debounced for 150ms - which means that the value is only transmitted to HomeKit if no other change occured within 150ms.| |
| 117 | +|ioBroker.State.OnlyACK|name of a ioBroker datapoint|With this function, the adapter uses the specified ioBroker datapoint for read and write operations. Write operations from HomeKit are directly passed to the conversion function. Changes from ioBroker are only forwarded to HomeKit if the "Acknowledged"-Flag of the value is set. Otherwise, the last acknowledged value is getting transmitted to HomeKit| |
| 118 | +|ioBroker.homematic.<br>WindowCovering.TargetPosition|Id of the HomeMatic Level Datapoint <br> or <br> String-Array with the Id of the Level Datapoint and the Id of the Working Datapoint|This function is especially for controlling the HomeMatic Window Covering. This function defferes the transmission of values to HomeKit while the Window Covering is moving. This is necessary to avoid flickering of the window covering slider in iOS| |
| 119 | + |
| 120 | +## Overview of Conversion-Functions |
| 121 | + |
| 122 | +|Function|Expected Parameter|Description| |
| 123 | +|---|---|---| |
| 124 | +|passthrough|\<none\>|The value from ioBroker is passed to HomeKit without conversion (and vice versa) |
| 125 | +|HomematicDirectionTo<br>HomekitPositionState|\<none\>|This function maps the direction enum of Homematic window covering to the PositionState enum of HomeKit (and back)| |
| 126 | +|HomematicControlModeTo<br>HomekitHeathingCoolingState|\<none\>|This function maps the ControlMode enum of Homematic to the HeathingCoolingState enum of HomeKit (and back) | |
| 127 | +|level255|\<none\>|This function scales an ioBroker value with a value range from 0 to 255 to a HomeKit value with a value range from 0 to 100 (and back). <br>**Example:** 255 in ioBroker is transformed to 100 for HomeKit.| |
| 128 | +|scaleInt<br>scaleFloat|```{ "homekit.min": <number>, "homekit.max": <number>, "iobroker.min": <number>, "iobroker.max": <number> }```|This function is similiar to "level255" but it's more generic. It transforms an ioBroker value with an range from "iobroker.min" (0 if omitted) to "iobroker.max" to a HomeKit value with a value range from "homekit.min" (0 if omitted) to "homekit.max" (and back).<br> **Example:** If the parameter field is: ```{ "homekit.max": 500, "iobroker.max": 250}``` <br> the value of ioBroker is in fact multiplied by 2 before sending it to HomeKit.<br>**The min-Parameters are only available in version 0.8.0 and higher**| |
| 129 | +|inverse|number|This function is used to "inverse" a value from ioBroker. The parameter specified the maximum of the value in ioBroker. The formula is: ```Parameter - value```<br>**Example:** If the parameter field is ```100```, the value 100 from ioBroker is send as 0 to HomeKit, the value 80 is send as 20 to HomeKit etc.| |
| 130 | +|hue|\<none\>|This function is specialized version of scaleInt with the parameters ```iobroker.max=65535``` and ```homekit.max=360```.| |
| 131 | + |
| 132 | +## Homematic Blind Actuator \ Window Covering |
| 133 | +To integrate the Homematic Blind Actuators (like HM-LC-Bl1PBU-FM), the following settings are needed: |
| 134 | + |
| 135 | +* Add a service to a device |
| 136 | +* Set Service Name to some name and service type to "WindowCovering". Service subtype could be left blank |
| 137 | +* Enable and fill in the following characteristics: |
| 138 | + |
| 139 | +|Characteristic Name|1: InOut Function <br> 2: Conversion Function|1: InOut Parameters <br> 2: Conversion Parameters| |
| 140 | +|---|---|---| |
| 141 | +|CurrentPosition| 1: ioBroker.State.OnlyACK<br>2: passthrough| 1: _\<path to homematic object\>_.1.LEVEL<br> 2: \<empty\>| |
| 142 | +|PositionState | 1: ioBroker.State.OnlyACK<br>2: HomematicDirectionToHomekitPositionState| 1: _\<path to homematic object\>_.1.DIRECTION<br> 2: \<empty\>| |
| 143 | +|TargetPosition | 1: ioBroker.homematic.WindowCovering.TargetPosition<br>2: passthrough| 1: _\<path to homematic object\>_.1.LEVEL<br> 2: \<empty\>| |
| 144 | + |
| 145 | +The value _\<path to homematic object\>_ needs to be replaced with the actual path to the device (e.g. hm-rpc.0.NEQ0012345) |
| 146 | + |
| 147 | +For general Information about the Configuration Mask, see: TODO<br> |
| 148 | +For more information about the Configuration, the InOut Functions and Conversion Functions, see: [Wiki](https://github.com/jensweigele/ioBroker.yahka/wiki/Configuration,-InOut-Functions-and-Conversion-Functions) |
| 149 | + |
12 | 150 | ## Changelog |
13 | 151 | ### 0.10.0 (2020-02-19) |
14 | 152 | (apollon77) updated dependencies, nodejs 12 support<br> |
|
0 commit comments