HomeKit YAHKA | ioBroker

Installation und Nutzung

Einzelheiten zur Installation und Konfiguration dieses Adapters finden Sie im Wiki

Voraussetzungen

Bevor Sie den Adapter installieren können, müssen Sie einige Pakete (für Linux) herunterladen: sudo apt-get install libavahi-compat-libdnssd-dev

Installieren Sie die neueste Version

Klicken Sie einfach im ioBroker-Admin-Panel auf der Seite „Adapter“ auf die Schaltfläche „+“ hinter „Homekit Yahka-Adapter“.

Installieren Sie die neueste Beta

Wenn Sie auf dem neuesten Stand sein und die neueste Beta testen möchten, können Sie den Adapter über das Beta-Repository von ioBroker installieren.

(Manchmal ist ein zusätzlicher Upload (z.B. iobroker upload yahka) und Adapterneustart notwendig)

Sichern und Wiederherstellen

Achtung: Um ioBroker.yahka auf einem anderen System wiederherstellen zu können, muss neben den üblichen iobroker backup und iobroker restore auch der Ordner yahka.X.hapdata unter /opt/iobroker/iobroker-data gesichert und ggf. wiederhergestellt werden. Wiki / Problem

Eine weitere Möglichkeit zur Sicherung und Wiederherstellung ist der Adapter Backup. Dieser sichert automatisch den Ordner yahka.X.hapdata. Eine Wiederherstellung ist auch über die BackItUp-GUI möglich.

Eine ausführliche Beschreibung finden Sie unter Hier.

Fehlerbehebung

Die Bridge funktioniert nicht oder ein Gerät reagiert nicht

Versuchen Sie, den MAC/Benutzernamen der Brücke zu ändern oder den Ciao-Werbetreibenden zu aktivieren

Nicht alle neuen Funktionen sind verfügbar:

Sollten nach einem Yahka-Update nicht alle neuen Features verfügbar sein, versuchen Sie einen Upload (z.B. iob upload yahka) und starten Sie den Adapter neu.

Fehlender Avahi-Daemon (Linux)

Wenn im Protokoll der folgende Fehler angezeigt wird:

Error:	2016-07-26 18:57:17.989	error	at Error (native)
Error:	2016-07-26 18:57:17.989	error	dns service error: unknown
uncaught	2016-07-26 18:57:17.985	error	exception: dns service error: unknown

Sie müssen einige zusätzliche Schritte ausführen:

Avahi-Daemon installieren:

sudo apt-get install avahi-daemon -y

Bearbeiten Sie avahi-daemon.conf

sudo nano avahi-daemon.conf

Ändern Sie die folgenden Variablen:

host-name=\<put in your hostname\>
domain-name=local
use-ipv4=yes
use-ipv6=yes
enable-dbus=yes

Fehlendes pam-devel-Paket (Linux)

Wenn im Protokoll der folgende Fehler angezeigt wird:

../authenticate_pam.cc:30:31: fatal error: security/pam_appl.h: Datei oder Verzeichnis nicht gefunden
#include <security/pam_appl.h>

Sie müssen das Paket pam-devel installieren:

Avahi-Daemon installieren:

sudo apt-get install pam-devel -y

Bonjour (Windows) fehlt

– Download: https://www.samuelattard.com/files/bonjourcore2.msi

Ausführen: msiexec /i bonjourcore2.msi /qn
entfernen: „del bonjourcore2.msi“.
Download: https://www.samuelattard.com/files/bonjoursdksetup.exe
Ausführen: bonjoursdksetup.exe /quiet
Entfernen: „del bonjoursdksetup.exe“.
Setzen Sie: set BONJOUR_SDK_HOME=C:\Programme\Bonjour SDK

Und installieren Sie anschließend den Yahka-Adapter.

Einige Worte zu HomeKit

Die Architektur von HomeKit ist wie folgt:

Es gibt Geräte als logische Einheiten. Jedes Gerät kann mehrere Dienste haben und jeder Dienst hat mehrere Eigenschaften.

Am Ende ist ein Merkmal ein Endpunkt, von dem Werte gelesen oder in den Werte geschrieben werden können.

Welche Eigenschaften ein Dienst haben kann, wird von Apple/HomeKit vorgegeben und durch den Diensttyp bestimmt. Die Diensttypen werden ebenfalls von Apple/HomeKit vorgegeben.

Beispiel:

Ein Garagentoröffner ist ein Gerät, das zwei Funktionen erfüllen kann:

Garagentoröffner
Licht

Der Garagentoröffnerdienst selbst kann verschiedene Eigenschaften haben, wie: CurrentDoorState, TargetDoorState und viele mehr.

Außerdem könnte der Lichtdienst verschiedene Eigenschaften haben, wie: Ein (und viele andere zum Ändern der Lichtfarbe usw.)

Was Yahka macht

Mit Yahka ist es möglich, einen ioBroker-Datenpunkt einer HomeKit-Eigenschaft zuzuordnen.

Da manchmal Zuordnungen notwendig sind (z. B. unterscheiden sich die "State"-Werte eines Garagentors zwischen HomeKit und anderen Systemen), besteht auch die Möglichkeit, Funktionen zur Konvertierung der Werte anzugeben. Dies wird weiter unten beschrieben.

Um unnötigen Verwaltungsaufwand zu vermeiden, befinden sich alle in Yahka angelegten Geräte hinter einer sogenannten „Bridge“. Mit dieser Bridge müssen Sie die Bridge lediglich mit Ihrem iOS-Gerät koppeln, um Zugriff auf alle Geräte zu erhalten. Andernfalls müssten Sie jedes Yahka-Gerät mit Homekit koppeln.

Richten Sie die Bridge ein und erstellen Sie Geräte und Dienste

Jedes Gerät, das mit Homekit gekoppelt werden soll, benötigt einen Benutzernamen in Form einer MAC-Adresse. Yahka generiert automatisch einen zufälligen Benutzernamen für jede Yahka-Instanz.

Wichtig: Wenn du den Benutzernamen änderst, nachdem du Yahka mit HomeKit gekoppelt hast, musst du alle Geräte in iOS neu konfigurieren (Raumzuordnung, Position usw.). Die Änderung des Benutzernamens bedeutet für iOS, dass es sich um ein komplett neues Gerät handelt!

Neben dem Benutzernamen benötigen Sie einen PIN-Code, der auf dem iOS-Gerät eingegeben werden muss.

Dies kann durch einen Klick auf „:yahka.0“ im Yahka-Adminbereich erfolgen. (Klappen Sie den Bereich nach dem Klick auf den Listeneintrag rechts auf.) Der Name der Bridge kann dort ebenfalls geändert werden.

Nachdem Sie die Bridge eingerichtet haben, können Sie die gewünschten Geräte über die Schaltfläche „Gerät hinzufügen“ oben hinzufügen. Sobald ein Gerät hinzugefügt/ausgewählt ist, können Sie diesem Gerät Dienste hinzufügen.

Es ist notwendig, einen Dienstnamen und einen Diensttyp anzugeben.

Je nach Diensttyp ändert sich die Liste der verfügbaren Merkmale.

Einrichten von Merkmalen

Wenn Sie eine Eigenschaft unterstützen möchten, aktivieren Sie das Kontrollkästchen „Aktiviert“ links neben der Eigenschaft. Für jede Eigenschaft können Sie die folgenden Eigenschaften festlegen:

InOutFunction: Sie können eine vordefinierte Funktion angeben, die für die Übergabe der Werte von HomeKit an ioBroker und umgekehrt verantwortlich ist
InOutParameter: Hier können Sie Parameter für die ausgewählte InOutFunction angeben. Die verfügbaren/erwarteten Parameter hängen von der ausgewählten Funktion ab. Eine kurze Übersicht über die Funktionen und Parameter finden Sie unten.
ConversionFunction: Zusätzlich zur InOutFunction können Sie auch eine Funktion angeben, die einen von HomeKit kommenden Wert in ioBroker konvertiert (und umgekehrt).
ConversionParameter: dasselbe wie InOutParameter – die verfügbaren/erwarteten Parameter hängen von der ausgewählten Funktion ab.

Übersicht der InOut-Funktionen

Funktion	Erwarteter Parameter	Beschreibung
const	Wert	Die const-Funktion übergibt den in "InOutParameter" angegebenen Wert immer dann an die Konvertierungsfunktion, wenn HomeKit den Wert liest. Möchte HomeKit den Wert schreiben, wird diese Aktion verweigert
ioBroker.State	Name eines ioBroker-Datenpunkts	Mit dieser Funktion verwendet der Adapter den angegebenen ioBroker-Datenpunkt für Lese- und Schreibvorgänge. Alle Vorgänge werden sofort und ohne Pufferung oder Filterung ausgeführt (die Werte werden an die angegebenen Konvertierungsfunktionen übergeben).
ioBroker.State.Deferred	Name eines ioBroker-Datenpunkts	Mit dieser Funktion verwendet der Adapter den angegebenen ioBroker-Datenpunkt für Lese- und Schreibvorgänge. Schreibvorgänge von HomeKit werden direkt an die Konvertierungsfunktion übergeben. Änderungen von ioBroker werden 150 ms lang entprellt, d. h. der Wert wird nur dann an HomeKit übertragen, wenn innerhalb von 150 ms keine weitere Änderung erfolgt.
ioBroker.State.OnlyACK	Name eines ioBroker-Datenpunkts	Mit dieser Funktion verwendet der Adapter den angegebenen ioBroker-Datenpunkt für Lese- und Schreibvorgänge. Schreibvorgänge von HomeKit werden direkt an die Konvertierungsfunktion übergeben. Änderungen von ioBroker werden nur an HomeKit weitergeleitet, wenn das "Acknowledged"-Flag des Wertes gesetzt ist. Andernfalls wird der zuletzt bestätigte Wert an HomeKit übertragen.
ioBroker.homematic. WindowCovering.Zielposition	Id des HomeMatic-Level-Datenpunkts oder String-Array mit der ID des Level-Datenpunkts und der ID des Working-Datenpunkts	Diese Funktion dient insbesondere zur Steuerung der HomeMatic Fensterabdeckung. Sie verzögert die Übertragung von Werten an HomeKit, während sich die Fensterabdeckung bewegt. Dies ist notwendig, um ein Flackern des Schiebereglers der Fensterabdeckung unter iOS zu vermeiden.

Übersicht der Konvertierungsfunktionen

Funktion	Erwarteter Parameter	Beschreibung
Passthrough	<keine>	Der Wert von ioBroker wird ohne Konvertierung an HomeKit übergeben (und umgekehrt)
HomematicDirectionTo HomekitPositionState	<none>	Diese Funktion bildet die Richtungsaufzählung der Homematic-Fensterabdeckung auf die PositionState-Aufzählung von HomeKit ab (und umgekehrt)
HomematicControlModeTo HomekitHeizungKühlungStatus	<none>	Diese Funktion bildet die ControlMode-Aufzählung von Homematic auf die HeatingCoolingState-Aufzählung von HomeKit ab (und zurück)
Stufe 255	<none>	Diese Funktion skaliert einen ioBroker-Wert mit einem Wertebereich von 0 bis 255 auf einen HomeKit-Wert mit einem Wertebereich von 0 bis 100 (und zurück). Beispiel: 255 in ioBroker wird für HomeKit in 100 umgewandelt.
scaleInt scaleFloat	`{ "homekit.min": <number>, "homekit.max": <number>, "iobroker.min": <number>, "iobroker.max": <number> }`	Diese Funktion ähnelt "level255", ist aber allgemeiner. Sie transformiert einen ioBroker-Wert mit einem Wertebereich von "iobroker.min" (0, falls weggelassen) bis "iobroker.max" in einen HomeKit-Wert mit einem Wertebereich von "homekit.min" (0, falls weggelassen) bis "homekit.max" (und zurück). Beispiel: Wenn das Parameterfeld lautet: `{ "homekit.max": 500, "iobroker.max": 250}` Der Wert von ioBroker wird tatsächlich mit 2 multipliziert, bevor er an HomeKit gesendet wird. Die Min-Parameter sind erst ab Version 0.8.0 verfügbar
Farbton	<keine>	Diese Funktion ist eine spezialisierte Version von scaleInt mit den Parametern `iobroker.max=65535` und `homekit.max=360`.
Farbton	<keine>	Diese Funktion ist eine spezialisierte Version von scaleInt mit den Parametern „iobroker.max=65535“ und „homekit.max=360“.

Homematic Jalousieaktor \ Fensterabdeckung

Zur Einbindung der Homematic Jalousieaktoren (z.B. HM-LC-Bl1PBU-FM) sind folgende Einstellungen notwendig:

Fügen Sie einem Gerät einen Dienst hinzu
Geben Sie den Dienstnamen und den Diensttyp „Fensterabdeckung“ ein. Der Dienstuntertyp kann leer bleiben.
Aktivieren und füllen Sie die folgenden Merkmale aus:

Merkmalsname	1: InOut-Funktion 2: Konvertierungsfunktion	1: InOut-Parameter 2: Konvertierungsparameter
Aktuelle Position	1: ioBroker.State.OnlyACK 2: Durchgang	1: _<path to homematic object> _.1.EBENE 2: <empty>
PositionState	1: ioBroker.State.OnlyACK 2: HomematicDirectionToHomekitPositionState	1: _<path to homematic object> _.1.RICHTUNG 2: <empty>
Zielposition	1: ioBroker.homematic.WindowCovering.Zielposition 2: Durchgang	1: _<path to homematic object> _.1.EBENE 2: <empty>

Der Wert <Pfad zum Homematic-Objekt> muss durch den tatsächlichen Pfad zum Gerät ersetzt werden (z. B. hm-rpc.0.NEQ0012345).

Allgemeine Informationen zur Konfigurationsmaske finden Sie unter: TODO

Weitere Informationen zur Konfiguration, den InOut-Funktionen und Konvertierungsfunktionen finden Sie unter: Wiki

Hinweise für Entwickler

Dieses Repo enthält ein Untermodul. Bevor Sie es erstellen, müssen Sie dieses auch schließen/initialisieren, z. B. indem Sie git submodule update --init --recursive verwenden, um seinen Inhalt zu aktualisieren und abzurufen.

Changelog

1.1.0 (2025-04-16)

(tarikweiss) Updated GitHub build file. Try testing a build-process with GitHub.
Updated design to be more responsive
Restructured code a bit
(@GermanBluefox) Updated packages

1.0.9 (2024-09-08)

Corrected Admin GUI

1.0.6 (2024-08-30)

(tarikweiss) Fixes errors with non-existing service types

1.0.5 (2024-08-29)

(tarikweiss) Fixes errors with non-existing service types
(bluefox) Revert renaming of states back: HomematicControlModeToHomekitHeatingCoolingState => HomematicControlModeToHomekitHeathingCoolingState, Deferred => Defered

1.0.4 (2024-08-12)

(Apollon77) Important: js-controller 5.0 is required at least
(tarikweiss) Rewrote community types from submodule (js) to TypeScript
(tarikweiss) Added the ability to set an ioBroker state for the availability indication in HomeKit

1.0.3 (2023-03-29)

(TA2K) Corrected empty device list with rebuild

1.0.1 (2023-03-24)

(foxriver76) we ensured controller 5 compatibility
(bluefox) Formatting

0.17.0 (2022-10-17)

Added AVAHI advertiser as default and updated HomeKit Library to improve performance and stability
Update release and test scripts

0.14.0 (unreleased)

(jw) added support to group devices in Admin Interface
(jw) added support to mark services as "primary" and as "hidden"
(jw) added ioFunctions "round" and "invert"
(jw) updated dependencies
(jw) Updated to HAP-Node.js 0.9.2
(jw) Fixed crashes due to changes in used HomeKit Library
(nh) improved changelog in readme

0.13.1 (2021-01-14)

(jw) switched to HAP-Node.js 0.9.0-beta.113 and added useLegacyAdvertiser option
(jw) fixed bug which prevented cameras from deletion and duplication

0.13.0 (2021-01-08)

(jw) updated dependencies
(jw) improved state selector (scrolling and refresh on open)

0.12.0 (2020-12-23)

(jw) updated dependencies
(jw) added support for linking services to support Television Services
(jw) added possibility to publish devices without the bridge (necessary for TV service)
(jw) added support for audio stream in camera
(jw) added support for custom characteristics on the services (e.g., to add Wattage characteristic to plugs)
(jw) added support for additional services to camera (to enable usage of doorbell service)> (many20) fixed scaleInt conversion - results are now rounded

0.11.0 (2020-02-19)

Intermediate release

0.10.0 (2020-02-19)

(apollon77) updated dependencies, Node.js 12 support

0.10.0

(jw) updated dependencies
(apollon77) removed support for Node.js 4 - Node.js 6 is now the minimum required Node.js version (merged #109)
(yaming116) fixed scale conversion to support min values others than 0

0.9.2 (2019-03-12)

(jw) fixed a bug where the adapter didn't start anymore
(jw) removed the reference to the git repository of the hap community types

0.9.1 (2019-01-29)

(jw) fixed a bug where the adapter crashes if a state does not exist
(jw) added io functions for HomeMatic dimmers (#30 and #75)
(jw) fixed a bug where adapter didn't start anymore when using the conversion function "inverse" (#98)
(jw) updated to a latest HAP-Node.js library to support TV services and characteristics (available since iOS 12.2 beta 1)
Note: that's still in development, not all services are working correctly. For more information see: (#89)

0.9.0 (2019-01-24)

(jw) added more services and characteristics (from https://github.com/homespun/hap-Node.js-community-types)
(jw) improved admin interface to support individual editors for IO/Conversion functions
(jw) added new conversion function "script" which adds the ability to run JavaScript functions as conversion functions
(jw) fixed a bug in the scaleInt and scaleFloat methods (thanks to balzreber)
(jw) added ioFunction "MultiState" to get multiple states and/or separate between read and write states
(jw) added conversion function "map" to customize mappings between ioBroker and HomeKit
(jw) added possibility to specify IP for Bonjour broadcasting (for bridge configuration and camera configuration)(#86)
(jw) switched to webpack and refactored admin interface and io/conversion functions
(jw) fixed a problem where numeric values where transmitted to homekit as strings (#87)
(jw) added possibility to specify "firmware" version for bridge and devices (#90)
(jw) added Internet Explorer / MS Edge detection to print error message in admin panel (#83)
(jw) added support for new compact mode (#95)
(jw) added support for specifying device information via data points (#91)
(SchumyHao) added Chinese support

0.8.2 (2018-12-09)

(jw) Removed a bug which flooded logging when starting/stopping the adapter which led to excessive memory consumption

0.8.1 (2018-12-04)

(jw) updated dependencies
(jw) change default name of new instances
(foxriver76) remove excessive logging
(mdietz666) scaleInt and scaleFloat now supports min-values (this allows mapping from e.g. -90 to 90 to 0 to 180)
(arichter83) added "Duplicate Device" functionality

0.7.1 (2018-02-14)

(jw) fixed a bug where state selection with admin 2.0.9 did not work anymore
(jw) restructured repository to support install via url

0.7.0 (2018-02-01)

(bluefox) Fixed the ID select dialog in Admin3
(jw) updated hap-Node.js to support the following new services: Faucet, IrrigationSystem and Valve
(jw) added ip-package to dependencies to avoid errors on some installations

0.6.1 (2018-01-25)

(jw) fixed startup crash

0.6.0 (2018-01-24)

(jw) add support for IP-Cameras
(jw) included iOS 11 device definitions
(jw) allowed negative temperatures for temperature sensors
(jw) fixed crashes due to duplicate device names
(oliverschulze) added conversion functions "hue" and "level255"
(jw) added conversion functions scaleInt, scaleFloat and inverse
(jw) devices are now sorted by name in the admin panel

0.5.5 (2017-05-08)

(bluefox) allow select ID in configuration dialog

0.5.4 (2017-02-08)

(jw) improve log output
(jw) added HomematicControlModeToHomekitHeathingCoolingState mapping

0.5.3 (2017-02-08)

(jw) internal release

0.5.2 (2016-12-23)

(jw) fixed issues with empty characteristic values
(jw) fixed issue with empty adapter.systemConfig.system object

0.5.1 (2016-10-05)

(jw) fixed issue with wrongly displayed logo

0.5.0 (2016-10-05)

(jw) initial release

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.