Wie kann die Konfiguration angepasst werden?

Nur notwendig wenn das HConnect VPN AddOn NICHT verwendet wird

Die Konfiguration des HConnect-Gateways besteht nur aus 2 Dateien. Diese liegen direkt im Anwendungsverzeichnis mit den folgenden Namen:

• hosting.json
• appsettings.json

Die Dateien sind mit sinnvollen Standardwerten versehen und ausführlich dokumentiert. Nachdem die Konfigurationsdateien den eigenen Wünschen angepasst sind kann die Anwendung gestartet werden. Sollte nach dem Start auffallen, dass die ein oder andere Option noch nicht richtig eingestellt wurde, so kann die Konfigurationsdatei einfach während der Laufzeit des Gateways verändert werden. Die Applikation merkt eigenständig wenn die Konfigurationsdatei gespeichert wird. In diesem Fall wird die Konfiguration neu eingelesen und aktiviert. Ebenfalls werden die Geräte aus der HomeMatic Zentrale neu geladen, da sich ggfs. die Namen der Geräte in der Alexa App dadurch ändern müssen. Dies funktioniert mit allen Optionen, ausser den Optionen die in der Datei hosting.json angegeben sind.

hosting.json

Nur notwendig wenn das HConnect VPN AddOn NICHT verwendet wird

Das Gateway muss auf einer IP-Adresse und einem Port auf Ihrem Rechner ausgeführt werden. Welche IP-Adresse und welcher Port dies ist kann in der Datei hosting.json auf verschiedene Arten festgelegt werden.

Auf allen lokalen Adressen auf einem Port

"server.urls": "http://*:5100"

Auf Adressen des lokalen Rechnernamens auf einem Port

"server.urls": "http://mein-rechner-name:5100"

Das gleiche, nur hier noch mit Domänenname des Rechners

"server.urls": "http://mein-rechner-name.domain.local.com:5100"

Oder einfach nur mit IP-Adresse und Port

"server.urls": "http://192.168.1.90:5100"

appsettings.json

Nur notwendig wenn das HConnect VPN AddOn NICHT verwendet wird

In diesem Abschnitt werden die verschiedenen Konfigurationsoptionen beschrieben, welche für die Verbindungen von und zu dem HConnect-Gateway zuständig sind.

Wie ist die Adresse der HomeMatic-Zentrale

Dazu geben Sie bitte entweder die IP-Adresse oder den auflösbaren Hostnamen der Zentrale an

"HomematicHostname": "192.168.1.90",

Welche Adresse hat der HConnect-Web Cloud-Dienst

Das Gateway muss sich mit dem Cloud-Dienst verbinden und sich dort authentifizieren, damit der Cloud-Dienst den Client verifizieren kann. Erst nach erfolgreicher Verifizierung und Verbindungsprüfung wird der Cloud-Dienst später Befehle vom Alexa Skill an das Gateway weitergeben.

"ServiceProviderUrl": "https://hconnect.deike.cc",

Wie ist das Gateway aus dem Internet erreichbar

Bei der Verbindung zum Cloud-Dienst gibt der Client bekannt unter welcher Adresse er aus dem Internet erreichbar ist. Ohne diese Angabe kann der Cloud-Dienst nicht in Verbindung mit dem Gateway treten. Hier gibt es verschiedene Möglichkeiten dies zu konfigurieren.

Es kann ein DNS-Name angegeben werden:

"ClientAddress": "http://mein-gateway.dyndns.com:8080",

Dem Cloud-Dienst die IP-Adresse des Gateways erkennen lassen:

"ClientAddress": "http://0.0.0.0:8080",

Der Port kann auch jeweils weg gelassen werden. Der Cloud-Dienst nutzt dann den Standard-Port 80. Bei dem Start des Gateways verbindet sich dieses zum Cloud-Dienst und übergibt seine Adresse. Der Cloud-Dienst überprüft daraufhin sofort ob er das Gateway erreichen kann und sendet das Ergebnis zurück.

Achtung: Die meisten werden einen DSL Router im Einsatz haben. Die hier angegebene Adresse muss den Port natürlich in das lokale Netzwerk zum Gateway weiterreichen (Port Forwarding). Dies muss im Router konfiguriert werden. Der hier angegebene Port muss also aus diesem Grund nicht mit dem Port übereinstimmen auf den das Gateway eingestellt ist (siehe hosting.json)

Beispiel: Das lokale HConnect-Gateway ist konfiguriert für die Adresse: 192.168.1.90 und Port 5100 (192.168.1.90:5100)

Als ClientAddress wird angegeben: http://mein-gateway.dyndns.com:8080

Dann muss im Router also der TCP-Port 8080 auf die Adresse 192.168.1.90 Port 5100 weitergeleitet werden. Es empfiehlt sich aber die Ports gleich zu wählen

Nutzung von HTTPS

Man benötigt dann ein SSL Zertifikat von einer ofiziellen trusted CA (Self signed wird nicht funktionieren). Aber: Kann man machen, muss man aber nicht, denn technisch läuft die Kommunikation folgendermaßen ab:

Das Gateway meldet sich beim Cloud-Dienst stets über https an und meldet sich mit den Account-Daten dort an (https ==> Verschlüsselt). Das Hosting des Cloud-Dienstes findet mit abgesichertem Zertifikat in der Microsoft-Cloud statt. Bei der Anmeldung des Client beim Cloud-Dienst erzeugen beide Seiten (lokales Gateway und Cloud-Dienst) jeweils ein Private/Public Key Pärchen und geben der anderen Partei dabei jeweils den Public Key. Jede weitere Kommunikation die ab nun stattfindet, findet stark verschlüsselt statt.

Beispiel

• Alexa, schalte das Licht im Arbeitszimmer ein!

• Versteht das Gerät und sendet einen Befehl an den HConnect Skill

• Kommuniziert über HTTPS verschlüsselt mit dem HConnect-Cloud Dienst und sendet Befehl und Benutzer (als Token)

• Ist über den Benutzer mit dem Amazon Account verknüpft und kennt über das Token euren Cloud-Benutzer
• Verschlüsselt die Nachricht zum Benutzer per AES (2048 Bits)
• Verschlüsselt den gerade neu erzeugten AES Schlüssel mit dem Public Key des HConnect Gateways
• (Diesen hat das Gateway bei der Anmeldung dem Server verschlüsselt übertragen)
• Sendet dann die Verschlüsselte Nachricht plus den verschlüsselten AES Key zum HConnect Gateway

• Nur das Gateway kennt seinen eigenen Privaten Schlüssel und kann somit den AES Key entschlüsseln
• Mit dem AES Key kann es nun auch die Nachricht entschlüsseln
• Und den Befehl umsetzen und die Homematic Zentrale dazu bewegen das Licht im Arbeitszimmer einzuschalten
• Hierzu nutzt das Gateway die XML-API

Zugangsdaten

Benutzername (Email-Adresse)

Für den Cloud-Dienst benötigt man einen Account. Der Account kann bei der Aktivierung des Skills in der Alexa App erstellt werden, da die Alexa App bei der Aktivierung auf den Cloud-Dienst weiterleitet. Die Test-Benutzer haben bereits fertig eingerichtete und frei geschaltete Accounts und müssen die zugeordnete Email-Adresse hier eintragen

"ServiceProviderAccount": "meine-emailadresse@anbieter.de",

Kennwort

Hier bitte das Kennwort für den Cloud-Dienst eintragen der bei der Registrierung angegeben wurde

"AlexaHomematicGateway": "MeinKennwort",

appsettings.json

Nur notwendig wenn das HConnect VPN AddOn NICHT verwendet wird

In diesem Abschnitt werden die verschiedenen Konfigurationsoptionen beschrieben, welche für die Benennung von Geräten in der Alexa App zuständig sind.

Geräteaktualisierung / Geräte durch Alexa erkennen lassen

Mit dem Befehl "Alexa, schalte 'Geräte erkennen' ein" möchte ich erreichen, dass das HConnect-Gateway seine Konfiguration neu einliest und sofort eine vollständige Aktualisierung der Geräte mit der neuen Konfiguration startet. Der Befehl kann mit dem Parameter DeviceDiscoveryUtterance (Aussprache) konfiguriert werden. Daraufhin wird die Konfiguration neu eingelesen und die XML-API der Homematic bemüht die Geräte neu zu ermitteln. Dieser Weg wurde gewählt, da Alexa von sich aus in regelmäßigen Abständen selbstständig die Geräteerkennung auslöst. Dies ist zwar toll, aber jedes mal die XML-API zu bemühen ist für die Homematic Zentrale nicht so gut (da bei vielen Geräten die Homematic schon etwas ausgelastet ist). Da Alexa dies wirklich regelmäßig tut (im Abstand von ca. 15 Minuten) liefert das HConnect Gateway dann nur die Ergebnisse aus dem internen Cache (die Homematic wird also nicht belastet). Mit dem hier konfigurierten Befehl kann man aber die "richtige" Geräteerkennung auf Wunsch starten (ich weiss schließlich selbst am besten, wann sich an meiner Gerätekonfiguration etwas verändert hat). Dann wartet man einfach mal eine halbe Minute (dann dürfte die XML Api durch sein) und sagt dann:

Alexa, erkenne meine Geräte.

Et voila. Alexa triggert seine Geräteerkennung und bekommt vom HConnect-Gateway natürlich eine aktualisierte Geräteliste.

"DeviceDiscoveryUtterance": "Ger$ate erkennen",
"DeviceDiscoveryDescription": "Befehl startet die Ger$ateerkennung",

Gerätebenennung, Duplizierung, Ersetzung und Gruppierung

Wenn in der Homematic ein Schaltkanal eingerichtet ist mit dem Namen "Deckenlampe Wohnzimmer", dann ist es immer besser, dass in der Alexa App das Gerät "Deckenlampe im Wohnzimmer" heisst. Denn die meisten werden zu Alexa sagen wollen

"Alexa, schalte die Deckenlampe im Wohnzimmer ein!"

Damit man dies nicht in der Homematic machen muss, kann man hier die entsprechenden prefixes angeben, die vor den Raum gesetzt werden sollen. Da die prefixes pro Raum immer anders sein können, z.B. "in der Küche", aber "im Wohnzimmer" kann dies hier konfiguriert werden. Ein Standardsatz ist hier gepflegt, kann aber beliebig verändert werden.

"Wheres": {
    "im": "Arbeitszimmer,Wohnzimmer,Esszimmer,Flur,Badezimmer",
    "in der": "Küche,Wohnung,Wohnung unten,Wohnung oben",
    "auf dem": "Balkon",
    "auf der": "Terasse"
},

Problemworte

Eins vorab: Alexa hat Problem beim Erkennen von bestimmten Wörtern. Teilweise ist die einfache Schreibweise schon ausschlaggebend. Heisst das Gerät z.B. "Deckenlampe im Wohnzimmer" kommt bei dem Befehl "Alexa, schalte die Deckenlampe im Wohnzimmer ein", schon mal gerne die Antwort von Alexa: "Ich habe mehrere Geräte mit diesem Namen erkannt, welches möchtest du", oder "Entschuldigung, aber ich habe kein Gerät mit diesem Namen in XXXX Account gefunden. Gibt man Alexa aber das Gerät als "Decken lampe im Wohnzimmer" bekannt, funktioniert alles bestens. Amazon scheint hieran aber auf Rückfrage noch zu arbeiten. Bis dahin kann man hier sogenannte Replacements konfigurieren. Aus den Wörtern links (welche in den Namen der Homematic zu finden sind wird dann für Alexa der rechte Teil. Der hier gepflegte Standardsatz funktioniert bei mir wunderbar, aber vielleicht liegt es auch an meiner Aussprache der Wörter. Bitte testet hier. Leider ist hier noch ein Bug im parsing dieser Datei im .NET Framework: Umlaute wie ö können nicht direkt verwendet werden. Verwendet dafür bitte $o ==> ö

"ProblemWordsReplacements": {
    "Deckenlampe": "Decken lampe",
    "Deckenspots": "Decken spots",
    "Tischlampe": "Tisch lampe",
    "Wandlampe": "Wand lampe",
    "Deckenfluter": "Decken fluter",
    "Heizk$orperthermostat": "Heizk$orper thermostat"
},

Geräteduplizierung und/oder Umbenennung

Mein Schaltkanal für die Deckenlampe im Wohnzimmer heisst in meiner Homematic: Wohnzimmer Deckenlampe. Ich möchte daraus 2 Geräte machen, da ich die folgenden Befehle geben möchte:
Alexa, schalte im Wohnzimmer die Deckenlampe ein!
Alexa, schalte die Deckenlampe im Wohnzimmer ein!
Dazu kann man hier sogenannte NameReversal Gruppen einrichten. In der Konfigurationsdatei ist dieses Beispiel noch einmal detaillierter dokumentiert.

"NameReversals": {
    "Lampen in Räumen": {
        "Names": "Deckenlampe,Deckenspots,Spiegellampe,Tischlampe,Wandlampe,Salzkristall",
        "Pattern": "[room] {name}",
        "Reversal": "{name} [room]",
        "Variant": "both"
    },
    "Lampen in Räumen (Beide Varianten behalten, mit optionalem im, in...)": {
        "Names": "Keinelampe",
        "Pattern": "[room] {name}",
        "Reversal": "{name} [where] [room]",
        "Variant": "reversal only"
    }
},

Automatisches Erzeugen von Gruppen

Ich möchte, dass ich mit dem Befehl "Alexa, mach das Licht im Wohnzimmer aus", dass alle Lampen im Wohnzimmer ausgeschaltet werden. Die Homematic hat dafür natürlich kein einzelnes Gerät welches an Alexa gesendet werden kann. Dazu kann man sogenannte SpecialRoom Devices erzeugen lassen. Dies geht zunächst nur für 2 Gewerke (Trades). Licht (Lights) und Heizungssteuerungen (Heater). Das Gateway erzeugt dann ein Gerät, z.B. Licht Wohnzimmer und weiss ja, welche Schaltaktoren es im Wohnzimmer gibt, die einen Schaltkanal haben dem das Gewerk Licht zugeordnet ist. Da das Gewerk nicht unbedingt bei jedem LICHT heisst ist dies konfigurierbar. Ebenso ist konfigurierbar wie die Beschreibung des Gerätes in der Alexa App auftauchen soll. Auch dieser Konfigurationsabschnitt ist in der Konfigurationsdatei noch einmal detaillierter dokumentiert.

"SpecialRoomDevices": {
    "Lights": {
        "Trade": "Licht",
        "DescriptionPattern": "Schaltet das {0} im Raum {1}",
        "SpecialRoomsOnlyPattern": ""
    },
    "Heater": {
    "Trade": "Heizung",
    "DescriptionPattern": "Schaltet die {0} im Raum {1}",
    "SpecialRoomsOnlyPattern": " SR"
    }
},

Steuerung des Temperaturmodus der Heizungsstuerung

Mit dem Konfigurationsparameter ChangeTemperatureMode kann eingestellt werden, in welchen Modus eine Heizungssteuerungskomponente der Homematic versetzt werden soll, wenn die Temperatur geändert wird, z.B. durch den Befehl "Alexa, stelle die Heizung im Arbeitszimmer auf 25 Grad". Der Standard ist: "DontChange" ==> Modus nicht ändern, es wird also lediglich die Temperatur im Arbeitszimmer auf 25 Grad gestellt. Weitere Optionen:

• "AutoMode" ==> Der Modus wird auf AUTOMATIK gestellt und dann die Temperatur auf 25 Grad gestellt
• "ManuMode" ==> Der Modus wird auf MANUELL gestellt und dann die Temperatur auf 25 Grad gestellt

"ChangeTemperatureMode": "DontChange",

Boosting Modus der Heizungssteuerung nutzen

Die Heizkörperthermostate der HomeMatic unterstützen den sogenannten "Boosting" Modus. Wir dieser aktiviert, so wird über einen gewissen Zeitraum (konfigurierbar in der HomeMatic) das Ventil des Heizkörperthermostates stark geöffnet (ebenfalls konfigurierbar). Damit man diesen Modus auch über die Alexa Sprachsteuerung aktivieren kann muss man eine "Ansprache" (engl. Utterance) konfigurieren. Mit diesem konfigurierten Befehl kann man dann den Modus aktivieren, welcher sich nach der konfigurierten Zeit wirde selbstständig deaktiviert und in den vorherigen Modus zurückschaltet.

// Wird AddBoostingForHeaters auf true gesetzt, so werden der Heizungsgruppen der Räume (SpecialRoomDevices Heater) 
// und sonstigen Heizungsgeräten auch sogenannte Boosting-Geräte hinzugefügt. Heizungsregler von Homematic können
// in einen Boostingzustand versetzt werden.
"AddBoostingForHeaters": true,

// Hier kann konfiguriert werden wie man dieses Boosting ansprechen möchte. Hier im Beispiel kann man dann sagen:
// Alexa, schalte Boosting Heizung Küche ein, wenn das Gerät oder die Gruppe Heizung Küche heisst
"BoostingUtterance": "aufheizen",

// Ein Pattern muss konfiguriert werden wie man Alexa ansprechen möchte
// Beispiel: Gerät in Alexa heisst "Heizung Wohnzimmer", BoostingUtterance: "Boosting"
//
// Alexa, schalte Boosting Heizung Wohnzimmer ein! oder
// Alexa, starte Boosting Heizung Wohnzimmer
// BoostingUtterancePattern = "{boostingUtterance} {deviceName}"
//
// Beispiel: Gerät in Alexa heisst "Heizung Wohnzimmer", BoostingUtterance: "aufheizen"
//
// Alexa, schalte Wohnzimmer aufheizen ein! oder
// Alexa, starte Wohnzimmer aufheizen
// BoostingUtterancePattern = "{deviceName} {boostingUtterance}"
"BoostingUtterancePattern": "{deviceName} {boostingUtterance}",

// Und wie oben eine Gerätebeschreibung
"BoostingDescriptionPattern": "Schaltet Aufheizen für {0} ein",

Ausblenden von Schaltkanälen

Einige Geräte, bzw. Schaltkanäle möchte man einfach nicht in seiner Alexa App haben um diese zu steuern. Es empfiehlt sich auch nur die Geräte in die Alexa App mit aufzunehmen die man auch wirklich benötigt. Denn je mehr Geräte Alexa kennt, desto länger dauert es auch bis Alexa einen Sprachbefehl versteht.

Ich habe bei mir einmal einen Test mit 125 Geräten in der Alexa App gefahren. Es ist zwar erträglich, doch muss man schon mal bis zu 5 Sekunden warten bis Alexa OK sagt. Aus diesem Grund können hier Zeichenfolgen oder Wörter hinterlegt werden. Werden diese Zeichenfolgen in einem Schaltkanal erkannt, so ignoriert das Gateway diesen Kanal und meldet dazu kein Gerät an Alexa.

Die einfache Schreibweise schaut einfach nur nach, ob der angegebene Text im Kanalnamen des Gerätes vorkommt. Es können aber auch so genannte Regular Expressions verwendet werden (ein Pattern), mit denen es möglich ist komplexe Ausdrücke für das Erkennen von Zeichenketten zu verwenden. Ein Beispiel ist hier mit angegeben. Möchte man eine regular expression "designen" geht man am besten auf http://regexr.com/ Dort gibt es auch ein super Tutorial.

Es ist zu beachten, dass reguläre Ausdrücke hier immer mit / beginnen müssen um als solche erkannt zu werden.

"IgnoreChannels": {
    // Alles ignorieren wo der Text (no_alexa) vorkommt
    "HomeMatic Kanäle die ich mit (no_alexa) im Namen gekennzeichnet habe": "(no_alexa)",
    // Alle Lampen im Esszimmer ignorieren (z.B: Deckenlampe im Vorratsraum)
    "Regular Expression 1": "/(.*)(lampe)(.*)(Vorratsraum)/gi"
},

Sonstiges

In der Alexa-App werden die gefundenen Geräte als Geräte von folgendem Hersteller angegeben. Der Name kann frei gewählt werden

"AlexaDeviceManufacturerName": "INTEX Datensysteme",

In der Alexa-App werden die gefundenen Geräte mit der folgenden Geräteversion angegeben. Die Version kann frei gewählt werden

"AlexaDeviceVersion": "1.0"

appsettings.json

Nur notwendig wenn das HConnect VPN AddOn NICHT verwendet wird

"Scopes" sind ein Feature, mit welchem es möglich ist mit mehreren echo's oder echo dot's die zu verschiedenen Benutzern gehören die Geräte einer HomeMatic Installation in Bereiche zu unterteilen. Damit können mit nur einer HConnect-Gateway Installation und einer HomeMatic Zentrale z.B. mehrere voneinander unabhängige Wohnbereiche gesteuert werden ohne dass der eine Wohnbereich auf die Geräte des anderen Wohnbereiches zugreifen kann.

Beispielszenario

• Eine HomeMatic Installation mit diversen Komponenten aus verschiedenen Wohnbereichen
• Mehrere Wohnungen, oder voneinander separierte Wohneinheiten mit eigener Alexa (eigenen Alexa’s)

Familie Müller und Meier wohnen in einem Zweifamilienhaus und teilen sich eine HomeMatic Zentrale. Beide haben ein paar Echos und Echo dots, welche auch die eigenen Komponenten der gemeinsamen HomeMatic Installation über ihre eigenen Alexen steuern möchten. Natürlich möchte Familie Müller in ihrer Alexa App nicht die Geräte von Familie Meier sehen und umgekehrt. Außerdem hat Familie Meier keine Ahnung von Technik. Deshalb wird die HomeMatic Installation von Familie Müller betrieben, die dann auch ein HConnect Gateway am Laufen hat. Dabei soll es auch bleiben. Keine weiteren Gateways.

Gelöst wird dies über Scopes folgendermaßen

• In der HomeMatic wird ein neuer Raum angelegt ==> Scope: Meier
• Den entsprechenden Geräten von Familie Meier werden neben den normalen Räumen auch der Scope Raum hinzugefügt
• Natürlich haben beide ein Wohnzimmer. Diese „normalen Räume“ werden Wohnzimmer (Meier) und Wohnzimmer (Müller) genannt (Hconnect filtert diese Addons in Klammern wieder für die Alexa App heraus)
• Das wars an HomeMatic Änderungen
• Herr Müller sendet nun aus seinem HConnect-Account auf der Webseite eine Einladung an Herrn Meier. Dazu hat Herr Meier den HConnect Skill aktiviert und sich mit einen Benutzeraccount auf der Webseite angelegt (während der Verknüpfung)
• Herr Müller muss dazu nur den Benutzernamen von Herrn Meier eingeben, einen Scope zuteilen (Den die Webseite vom Gateway erhalten hat). Zusätzlich sichert er das ganze über ein Kennwort ab
• Herr Meier bekommt eine Email mit einem "Akzeptieren" Link. Den klickt er an
• Er landet dann auf der HConnect-Webseite erhält einige Erklärungen und muss das vereinbarte Kennwort eingeben
• Fertig. Beide lassen einmal durch Alexa die Geräte erkennen und sehen auch nur noch Ihre zugewiesenen Geräte des eigenen Scopes
• Der Benutzer der das Gateway betreibt kann keinen Scope haben. Er kann immer nur Geräte steuern, die ohne Scope sind. Nur weitere eigenständige Benutzer benötigen einen Scope

Schaltkanäle die alle Benutzer des Systems nutzen sollen

Legen Sie hierfür einen weiteren Scope-Raum mit dem Namen Scope: All oder Scope: Alle an und weisen Sie den entsprechenden Schaltkanälen diesen Scope zu. Diese Geräte dürfen dann alle Benutzer des Systems bedienen.

Restriktionen

• Ein Benutzer kann immer nur 1 Scope Einladung annehmen
• Der Hauptbenutzer, welcher das Gateway betreibt benötigt kein (kann kein) Scope haben
• Der Hauptbenutzer kann nun Geräte ohne Scope sehen/steuern
• Die "Mitbenutzer" können nur Geräte ihres zugewiesenen Scopes sehen/steuern
• Einem Schaltkanal eines Gerätes kann immer nur 1 Scope zugewiesen werden. Weisen Sie mehr als 1 Scope dem Schaltkanal hinzu, so wird bei der Geräteerkennung die Funktionalität komplett abgeschaltet (Es erscheint im Log ebenfalls ein Fehler dazu). Dies wird dann wiederum dazu führen, dass nur noch der Hauptbenutzer des Systems die Geräte bedienen kann
• Wichtig zu wissen: Den Kanälen sind die Scopes zuzuordnen, nicht den Geräten, denn es gibt Geräte die mehrere Schaltpunkt haben (z.B. 4 fach Schaltaktoren), deren Schaltpunkte dadurch auch in unterschiedlichen Scopes liegen können