Configuration, InOut Functions and Conversion Functions - jensweigele/ioBroker.yahka GitHub Wiki

The architecture of HomeKit is as follows:
There are devices as logical entities. Each device can have multiple services and each service has multiple characteristics.
At the end, a characteristic is an endpoint where values could be read from or write to.
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.

Example:
A Garage Door opener is a device which could have two services:

1. Garage Door Opener
2. Light

The Garage Door Opener Service itself could have different characteristic like: CurrentDoorState, TargetDoorState and many more.
Also the Light Service could have different characteristics, like: On (and many others for chaning the light color etc.)

With Yahka it is possible to map an ioBroker Datapoint to an HomeKit Characteristic.
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.
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.

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.
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!
Beside the username, you need to specify a PIN code which needs to be entered on the iOS device. 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.

After setting up the bridge, you could add the devices you like with the "Add Device" Button on the top. Once a device is added/selected, you could add services to this device.
It is necessary to specify a service name and a service type.
Depending on the service type, the list of available characteristic changes

If you want to support a characteristic, you have to tick the "enabled" checkbox on the left side of the characteristic. For each characteristic you could specify the following properties:

• InOutFunction: you could specify a predefined function which is responsible for passing the values from HomeKit to ioBroker and vice versa
• 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.
• ConversionFunction: additionally to the InOutFunction, you could also specify a function which converts a value coming from HomeKit to ioBroker (and vice versa)
• ConversionParameter: same as InOutParameter - the available/expected params depend on the selected function.

Function	Expected Parameter	Description
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
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)
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.
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
ioBroker.homematic. WindowCovering.TargetPosition	Id of the HomeMatic Level Datapoint or 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

Function	Expected Parameter	Description
passthrough	<none>	The value from ioBroker is passed to HomeKit without conversion (and vice versa)
HomematicDirectionTo HomekitPositionState	<none>	This function maps the direction enum of Homematic window covering to the PositionState enum of HomeKit (and back)
HomematicControlModeTo HomekitHeathingCoolingState	<none>	This function maps the ControlMode enum of Homematic to the HeathingCoolingState enum of HomeKit (and back)
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). Example: 255 in ioBroker is transformed to 100 for HomeKit.
scaleInt 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). Example: If the parameter field is: { "homekit.max": 500, "iobroker.max": 250} the value of ioBroker is in fact multiplied by 2 before sending it to HomeKit. The min-Parameters are only available in version 0.8.0 and higher
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 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.
hue	<none>	This function is specialized version of scaleInt with the parameters iobroker.max=65535 and homekit.max=360.