Hallo zusammen,
ich möchte hier mein FHEM-Modul
70_HomeConnectLocal.pm
vorstellen.
Das Modul ermöglicht die direkte lokale Kommunikation mit Home-Connect-fähigen
Hausgeräten von Bosch/Siemens/BSH über das eigene Netzwerk.
Im Gegensatz zur Home-Connect-Cloud-API erfolgt die Kommunikation nach der
einmaligen Beschaffung des Geräteprofils direkt zwischen FHEM und dem Hausgerät
im lokalen Netzwerk.
Eine dauerhafte Verbindung zur Home-Connect-Cloud ist für die eigentliche
Kommunikation mit dem Gerät nicht erforderlich.
Aktuell von mir getestet:
- Geschirrspüler
- Kochfeld
- Waschtrockner
Unterstützung für weitere Home-Connect-Geräte ist grundsätzlich möglich, da
Programme, Optionen, Einstellungen, Enumerationen und viele weitere
Geräteeigenschaften nicht fest im Modul hinterlegt, sondern dynamisch aus den
originalen Home-Connect-Geräteprofilen gelesen werden.
FUNKTIONSWEISE
==============
HomeConnectLocal verbindet sich direkt mit dem Hausgerät über dessen lokale
Home-Connect-Schnittstelle.
Abhängig vom Gerät erfolgt die verschlüsselte Kommunikation über:
- TLS-PSK
- AES
Darüber läuft die eigentliche Home-Connect-Kommunikation per WebSocket.
Das Modul verarbeitet unter anderem:
- Gerätestatus
- Betriebszustand
- Programme
- ausgewähltes Programm
- aktives Programm
- Restlaufzeit
- Programmfortschritt
- Geräteeinstellungen
- Programmoptionen
- Temperaturen
- Schleuderdrehzahlen
- Trocknungsziele
- Türstatus
- Remote-Control-Status
- Kochzonen beim Kochfeld
- weitere geräteabhängige Werte
Welche Funktionen tatsächlich vorhanden sind, wird weitgehend dynamisch aus
dem jeweiligen Geräteprofil ermittelt.
Dadurch muss nicht für jedes einzelne Bosch-/Siemens-Gerätemodell eine eigene
Liste mit Programmen und Funktionen in das Modul eingebaut werden.
HOME CONNECT PROFILE DOWNLOADER
===============================
Für die lokale Kommunikation werden die individuellen Daten des jeweiligen
Home-Connect-Gerätes benötigt.
Dazu gehören insbesondere:
- Verschlüsselungsschlüssel
- Verbindungstyp
- ggf. AES-IV
- DeviceDescription
- FeatureMapping
Diese Daten werden einmalig mit dem "Home Connect Profile Downloader" aus dem
Home-Connect-Konto geladen.
Der Home Connect Profile Downloader ist ein eigenständiges Projekt und nicht
Bestandteil von HomeConnectLocal.
Projektseite:
https://github.com/bruestel/homeconnect-profile-downloader
Aktuelle Version / Download:
https://github.com/bruestel/homeconnect-profile-downloader/releases/latest
HOME CONNECT PROFILE DOWNLOADER VERWENDEN
=========================================
Zunächst muss das betreffende Hausgerät ganz normal in der offiziellen
Home-Connect-App eingerichtet und dem eigenen Home-Connect-/SingleKey-ID-Konto
zugeordnet sein.
Danach:
1. Auf der Releases-Seite des Home Connect Profile Downloaders die aktuelle
Version für das eigene Betriebssystem herunterladen.
2. Archiv entpacken bzw. Anwendung installieren/starten.
3. Home Connect Profile Downloader starten.
4. Die passende Region auswählen.
5. Den Abruf der Appliance-Profile starten.
6. Es öffnet sich die Home-Connect-/SingleKey-ID-Anmeldung.
7. Mit dem Konto anmelden, in dem die betreffenden Hausgeräte registriert sind.
8. Nach erfolgreicher Anmeldung zeigt der Profile Downloader die verfügbaren
Geräteprofile an.
Für jedes registrierte reale Hausgerät kann ein Profil heruntergeladen werden.
Das Geräteprofil enthält unter anderem drei für HomeConnectLocal wichtige
Dateien:
<Seriennummer>.json
<Seriennummer>_DeviceDescription.xml
<Seriennummer>_FeatureMapping.xml
Die JSON-Datei enthält die Verbindungsinformationen und den individuellen
Verschlüsselungsschlüssel.
"connectionType" gibt an, ob das Gerät TLS oder AES verwendet.
Bei AES-Geräten wird zusätzlich ein IV benötigt, dieser steht auch in der *.json Datei.
Die beiden XML-Dateien beschreiben die Funktionen des Gerätes.
DEVICEDESCRIPTION UND FEATUREMAPPING
====================================
DeviceDescription.xml
---------------------
Die DeviceDescription enthält unter anderem Informationen über:
- verfügbare Funktionen
- Programme
- Programmoptionen
- Settings
- Commands
- Zugriffsrechte
- Wertebereiche
- EnumerationTypes
- Parent-/Programmzuordnungen
FeatureMapping.xml
------------------
Das FeatureMapping ordnet die numerischen Home-Connect-UIDs den verständlichen
Funktionsnamen zu.
Außerdem enthält es unter anderem:
- Enum-Werte
- Klartextbezeichnungen
- Fehlerzuordnungen
- Feature-Namen
Aus beiden Dateien baut HomeConnectLocal zur Laufzeit das jeweilige
Gerätemodell auf.
Zusätzlich werden die statischen Informationen mit den vom Gerät gelieferten
Runtime-Informationen abgeglichen.
Dadurch werden beispielsweise Programmoptionen abhängig vom ausgewählten
Programm und dem aktuellen Gerätezustand angeboten.
VORAUSSETZUNGEN
===============
HomeConnectLocal verwendet überwiegend Perl-Core-Module, die bei einer normalen
FHEM-/Perl-Installation bereits vorhanden sind.
Vom Modul werden folgende Perl-Module verwendet:
- JSON::PP
- IO::Socket::INET
- MIME::Base64
- Digest::SHA
- Encode
- Crypt::Mode::CBC
JSON::PP, IO::Socket::INET, MIME::Base64, Digest::SHA und Encode gehören bei
einer üblichen aktuellen Perl-Installation bereits zur Standardausstattung.
Zusätzlich benötigt wird:
Crypt::Mode::CBC
Unter Ubuntu/Debian/Raspberry Pi OS wird dieses Modul über das Paket
"libcryptx-perl" bereitgestellt.
Für die TLS-PSK-Kommunikation werden zusätzlich OpenSSL und socat verwendet.
Am einfachsten werden alle zusätzlichen Abhängigkeiten gemeinsam installiert.
Im Ubuntu-/Debian-Terminal:
sudo apt update
sudo apt install libcryptx-perl openssl socat
Damit sind die für HomeConnectLocal zusätzlich benötigten Pakete installiert.
INSTALLATION DES FHEM-MODULS
============================
Zur Installation gehören:
70_HomeConnectLocal.pm
HomeConnectLocal_Translation.pm
HomeConnectLocal.js
1. Perl-Dateien
---------------
Die beiden Perl-Dateien müssen in das FHEM-Modulverzeichnis:
/opt/fhem/FHEM/
kopiert werden.
2. JavaScript-Datei
-------------------
Die Datei
HomeConnectLocal.js
kommt nach:
/opt/fhem/www/pgm2/
Die JavaScript-Datei wird für die erweiterte FHEMWEB-Oberfläche und
insbesondere für den Dialog "Programm vorbereiten" verwendet.
GERÄTEPROFILE INSTALLIEREN
==========================
Standardmäßig erwartet HomeConnectLocal die Mappingdateien unter:
/opt/fhem/FHEM/FHEM_HomeConnectLocal/
Das Verzeichnis kann im Ubuntu-Terminal angelegt werden:
sudo mkdir -p /opt/fhem/FHEM/FHEM_HomeConnectLocal
sudo chown fhem:dialout /opt/fhem/FHEM/FHEM_HomeConnectLocal
Die beiden XML-Dateien aus dem heruntergeladenen Geräteprofil werden
anschließend in dieses Verzeichnis kopiert.
Beispiel:
/opt/fhem/FHEM/FHEM_HomeConnectLocal/*_DeviceDescription.xml
/opt/fhem/FHEM/FHEM_HomeConnectLocal/*_FeatureMapping.xml
Wichtig ist, dass beide Dateien dasselbe Präfix besitzen.
In diesem Beispiel lautet das Präfix:
*
Bei mehreren Home-Connect-Geräten können die XML-Dateien gemeinsam in diesem
Verzeichnis liegen.
Das Modul kann das passende Dateipaar anhand des Gerätetyps bzw. über das
Attribut "mappingPrefix" auswählen.
VERBINDUNGSDATEN AUS DEM GERÄTEPROFIL
=====================================
Nun die Datei
<Seriennummer>.json
aus dem vom Profile Downloader erzeugten Profil öffnen.
Benötigt werden insbesondere:
- connectionType
- Verschlüsselungsschlüssel/PSK
- bei AES zusätzlich der IV
WICHTIG:
Diese Daten sind vertraulich und sollten nicht im Forum oder in Logs
veröffentlicht werden.
Insbesondere der Verschlüsselungsschlüssel sollte niemals zusammen mit einem
vollständigen Geräteprofil öffentlich hochgeladen werden.
GERÄT IN FHEM DEFINIEREN
========================
Das Hausgerät sollte eine feste bzw. bekannte IP-Adresse im lokalen Netzwerk
besitzen.
Beispiel für einen Geschirrspüler:
define Geschirrspueler_Lokal HomeConnectLocal 192.168.1.55
Danach den Gerätetyp setzen:
attr Geschirrspueler_Lokal deviceType dishwasher
Mögliche Gerätetypen sind derzeit:
dishwasher
hob
washer
washerdryer
VERSCHLÜSSELUNG KONFIGURIEREN
=============================
TLS-Gerät
---------
Bei einem TLS-PSK-Gerät:
attr Geschirrspueler_Lokal connectionType TLS
attr Geschirrspueler_Lokal encryptionKey <SCHLÜSSEL_AUS_DEM_PROFIL>
AES-Gerät
---------
Bei einem AES-Gerät:
attr Kochfeld_Lokal connectionType AES
attr Kochfeld_Lokal encryptionKey <SCHLÜSSEL_AUS_DEM_PROFIL>
attr Kochfeld_Lokal iv <IV_AUS_DEM_PROFIL>
Schlüssel und IV müssen exakt aus dem Geräteprofil übernommen werden.
MAPPING AUSWÄHLEN
=================
Normalerweise werden die XML-Dateien aus dem Standardverzeichnis geladen:
/opt/fhem/FHEM/FHEM_HomeConnectLocal/
Falls ein anderes Verzeichnis verwendet werden soll:
attr <name> mappingDir /mein/pfad
Bei mehreren Profilen kann ein bestimmtes Mapping explizit ausgewählt werden:
attr Geschirrspueler_Lokal mappingPrefix 013080530166000676
Anschließend das Mapping neu laden:
set Geschirrspueler_Lokal reloadMapping
Mit:
get Geschirrspueler_Lokal mapping
kann geprüft werden, welche Mappingdateien verwendet werden.
VERBINDUNG HERSTELLEN
=====================
Danach:
set Geschirrspueler_Lokal connect
Bei erfolgreicher Initialisierung baut HomeConnectLocal die lokale
WebSocket-Verbindung auf, liest die Geräteinformationen ein und erzeugt
dynamisch die verfügbaren Readings und SET-Befehle.
Die Modulversion wird direkt unter den FHEM-Internals angezeigt.
Beispiel:
MODULE_VERSION 1.37
ÜBERSETZUNG
===========
Die Darstellung kann über das Attribut "translation" gesteuert werden.
Deutsch:
attr Geschirrspueler_Lokal translation DE
Englisch:
attr Geschirrspueler_Lokal translation EN
Keine Übersetzung:
attr Geschirrspueler_Lokal translation off
Die Übersetzung verändert nur die Darstellung in FHEM.
Die eigentlichen Home-Connect-Protokollwerte bleiben unverändert.
PROGRAMME UND OPTIONEN
======================
Die Programmliste wird dynamisch aus dem Geräteprofil erzeugt.
Beispielsweise können bei einem Geschirrspüler – abhängig vom tatsächlichen
Gerät – Programme wie folgende auftauchen:
Intensiv70
Auto2
Eco50
Quick45
PreRinse
NightWash
Kurz60
MachineCare
Favorite.001
Die tatsächlich angebotenen Programme stammen immer aus dem jeweiligen
Geräteprofil.
Programm auswählen:
set Geschirrspueler_Lokal program Eco50
Programm starten:
set Geschirrspueler_Lokal start
Programm stoppen:
set Geschirrspueler_Lokal stop
Auch Optionen wie beispielsweise ExtraDry, HygienePlus oder IntensivZone
werden – sofern vom jeweiligen Gerät und Programm unterstützt – dynamisch
angeboten.
Bei Waschmaschinen/Waschtrocknern gilt dasselbe beispielsweise für:
- Temperatur
- Schleuderdrehzahl
- ProgramMode
- DryingTarget
- SpeedPerfect
- WaterPlus
- Prewash
- RinsePlus
- SilentMode
- LessIroning
- weitere geräte- und programmabhängige Optionen
Entscheidend ist dabei nicht nur das statische XML-Profil.
HomeConnectLocal wertet zusätzlich die aktuellen Runtime-Metadaten des
Hausgerätes aus.
Dadurch kann sich die verfügbare SET-Liste abhängig vom gewählten Programm
und Gerätezustand dynamisch verändern.
PROGRAMM VORBEREITEN
====================
Für FHEMWEB gibt es zusätzlich einen komfortableren Programmdialog.
Aktivieren mit:
attr <name> programPopup on
In der Detailansicht erscheint anschließend der Button:
"Programm vorbereiten"
Dort können – abhängig vom Gerät und Programm – beispielsweise gewählt werden:
- Programm
- Program mode
- Temperature
- Spin speed
- Drying target
- weitere Optionen
Die Auswahl im Dialog wird zunächst nur lokal zusammengestellt.
Das bloße Öffnen des Dialogs sendet noch keine Änderungen an das Hausgerät.
Erst mit "An das Gerät senden" werden das ausgewählte Programm und die
gewählten Optionen an das Hausgerät übertragen.
Das Programm wird dadurch bewusst noch NICHT gestartet.
Der Start erfolgt anschließend separat in FHEM:
set <name> start
Dadurch kann ein Programm vollständig vorbereitet werden, ohne dass es
unbeabsichtigt sofort startet.
READINGS REDUZIEREN
===================
Home-Connect-Geräte können sehr viele Werte liefern.
Nicht benötigte Readings können deshalb über "excludeReadings" ausgeblendet
werden.
Beispiel:
attr <name> excludeReadings <Muster>
Wildcards "*" und "?" werden unterstützt.
Damit können auch komplette Reading-Gruppen ausgeblendet werden.
Das Reading "state" wird dabei geschützt.
SET-BEFEHLE REDUZIEREN
======================
Analog dazu können nicht benötigte SET-Befehle aus der FHEMWEB-Auswahlliste
entfernt werden:
attr <name> excludeSets <Muster>
Auch hier sind Wildcards "*" und "?" möglich.
Die zugrunde liegende Gerätefunktion wird dadurch nicht aus dem Mapping
entfernt. Der Befehl wird lediglich aus der normalen SET-Liste ausgeblendet.
RAW-READINGS
============
Die großen Rohdaten des Home-Connect-Protokolls werden standardmäßig nicht als
Readings angezeigt.
Standard:
attr <name> showRawReadings 0
Für die Fehlersuche können sie vorübergehend aktiviert werden:
attr <name> showRawReadings 1
Dann können unter anderem Rohdaten wie
authentication
ci_info
descriptionChanges
iz_info
mandatoryValues
ni_info
registeredDevices
services
values
sichtbar werden.
Diese Einstellung sollte nur zur Diagnose verwendet werden, da solche Daten
Geräte-, Netzwerk- und andere interne Informationen enthalten können.
LOGGING / VERBOSE
=================
Das Logging des Moduls ist bewusst aufgeteilt.
verbose 2:
Wichtige Verbindungs- und Lebenszyklusmeldungen.
Für den normalen Betrieb:
attr <name> verbose 2
verbose 3:
Fehler.
verbose 5:
Ausführliche Diagnose- und Protokollinformationen.
Bei Problemen kann deshalb vorübergehend gesetzt werden:
attr <name> verbose 5
Anschließend kann beispielsweise die Verbindung neu aufgebaut werden:
set <name> disconnect
set <name> connect
Vor dem Veröffentlichen eines Debug-Logs bitte unbedingt auf persönliche Daten,
Seriennummern, Netzwerkdaten und insbesondere Verschlüsselungsschlüssel achten.
SICHERHEIT
==========
Die lokale Home-Connect-Kommunikation ist verschlüsselt.
HomeConnectLocal unterstützt dabei die von den Geräten verwendeten
TLS-PSK- bzw. AES-Verbindungen.
Kryptografische Session-Keys, IV-Zustände, HMAC-Zustände usw. werden intern
verwaltet und nicht als normale FHEM-Internals angezeigt.
Der konfigurierte encryptionKey selbst ist allerdings zwangsläufig Bestandteil
der FHEM-Konfiguration und muss daher vertraulich behandelt werden.
Ein komplettes vom Profile Downloader erzeugtes Geräteprofil sollte ebenfalls
NICHT öffentlich im Forum hochgeladen werden, da es die für die lokale
Gerätekommunikation erforderlichen Zugangsdaten enthalten kann.
Auch die XML-Dateien können gerätespezifische Informationen enthalten und
sollten vor einer Veröffentlichung geprüft werden.
KOMPLETTES BEISPIEL – GESCHIRRSPÜLER
====================================
Eine minimale Konfiguration könnte beispielsweise so aussehen:
define Geschirrspueler_Lokal HomeConnectLocal 192.168.1.55
attr Geschirrspueler_Lokal deviceType dishwasher
attr Geschirrspueler_Lokal connectionType TLS
attr Geschirrspueler_Lokal encryptionKey <MEIN_KEY>
attr Geschirrspueler_Lokal translation DE
attr Geschirrspueler_Lokal programPopup on
attr Geschirrspueler_Lokal verbose 2
Falls mehrere Mappingdateien vorhanden sind:
attr Geschirrspueler_Lokal mappingPrefix 013080530166000676
Danach:
set Geschirrspueler_Lokal reloadMapping
set Geschirrspueler_Lokal connect
KOMPLETTES BEISPIEL – AES-GERÄT / KOCHFELD
==========================================
define Kochfeld_Lokal HomeConnectLocal 192.168.1.55
attr Kochfeld_Lokal deviceType hob
attr Kochfeld_Lokal connectionType AES
attr Kochfeld_Lokal encryptionKey <MEIN_KEY>
attr Kochfeld_Lokal iv <MEIN_IV>
attr Kochfeld_Lokal translation DE
attr Kochfeld_Lokal verbose 2
Danach:
set Kochfeld_Lokal reloadMapping
set Kochfeld_Lokal connect
AKTUELLER ENTWICKLUNGSSTAND
===========================
Das Modul ist aktuell mit folgenden Geräteklassen getestet:
- Geschirrspüler
- Kochfeld
- Waschtrockner
Da Home Connect je nach Modell, Gerätegeneration und Firmware unterschiedliche
Features und Runtime-Metadaten liefert, ist das erklärte Ziel das HomeConnect-Modul von Adimarantis mit diesem zu verschmelzen. Dazu benötige ich aber noch etwas Zeit und vor allem mehr Tests.
Bei Problemen wären folgende Informationen hilfreich:
- Gerätetyp
- HomeConnectLocal-Version
- connectionType
- relevante Readings
- Log mit verbose 5
Bitte KEINE Verschlüsselungsschlüssel oder kompletten Profil-JSON-Dateien
öffentlich posten.
FEHLERSUCHE
===========
Wenn ein Gerät keine Verbindung aufbaut, zunächst verbose 5 aktivieren:
attr <name> verbose 5
Verbindung neu aufbauen:
set <name> disconnect
set <name> connect
Falls das Mapping nicht korrekt erkannt wurde:
set <name> reloadMapping
und anschließend:
get <name> mapping
prüfen.
Fehlt Crypt::Mode::CBC, kann unter Ubuntu/Debian/Raspberry Pi OS nochmals
folgendes ausgeführt werden:
sudo apt update
sudo apt install libcryptx-perl
Für TLS-Geräte sollten außerdem OpenSSL und socat vorhanden sein:
sudo apt install openssl socat
HINTERGRUND
===========
Das Modul basiert auf der lokalen Home-Connect-Kommunikation und den
Gerätebeschreibungen, die Home Connect für die jeweiligen Hausgeräte
bereitstellt.
Hilfreich für das Verständnis des lokalen Protokolls waren insbesondere die
Arbeiten rund um hcpy und verschiedene Home-Connect-Local-Projekte.
Ein großes Dankeschön geht daher an die Entwickler und die
Reverse-Engineering-Arbeit dieser Projekte sowie an den Entwickler des
Home Connect Profile Downloaders.
Ziel von HomeConnectLocal ist es, diese lokale Schnittstelle möglichst
FHEM-typisch nutzbar zu machen:
- ein FHEM-Modul
- direkte lokale Kommunikation
- dynamische Readings
- dynamische SET-Befehle
- dynamische Programme und Programmoptionen
- möglichst wenig gerätespezifischer Hardcode
- keine dauerhaft benötigte Cloud-Verbindung
Feedback, Logs von weiteren Gerätetypen und Tests sind willkommen.
Jetzt steht erst einmal die Sanierung von 2 Zimmern im Haus an.
Die Dateien sind HIER (https://github.com/Shadow3561/FHEM-HomeConnectLocal) auf Github zu finden