HM-CFG-USB USB Konfigurations-Adapter

HM-CFG-USB USB Konfigurations-Adapter
HomeMatic USB Konfigurationsadapter (Version 2)
Allgemein
Protokoll	HomeMatic
Typ	Interface/Gateway
Kategorie	HomeMatic
Technische Details
Kommunikation	868,3 MHz
Kanäle
Betriebsspannung	5 V
Leistungsaufnahme
Versorgung	USB-Bus
Abmessungen	V1: 40 x 90 x 25 mm V2: 28 x 84 x 11,5 mm
Sonstiges
Modulname	CUL_HM
Hersteller	eQ-3

Der HomeMatic USB Konfigurations-Adapter ist ein USB-Stick, der außer zur Konfiguration von HomeMatic-Komponenten auch als Interface zwischen FHEM und HomeMatic-Geräten benutzt werden kann. Er existiert in zwei Versionen: der älteren HM-CFG-USB und der neueren HM-CFG-USB2. Die folgenden Beschreibungen gelten für beide Versionen, es sei denn, es ist ausdrücklich eine spezifische Version genannt.

Einbindung in FHEM

Im FHEM-Forum wird die Einbindung als Interface in diesem Thema beschrieben und diskutiert. Im Eröffnungsbeitrag wird eine gut funktionierende HMLAN-Emulationssoftware hmland von ihrem Entwickler vorgestellt, um den HM-CFG-USB in FHEM zu integrieren. Die HMLAN-Emulationssoftware muss zunächst kompiliert und installiert werden. Anschließend wird der HM-CFG-USB (üblicherweise auf localhost) genau wie HMLAN in FHEM eingebunden.

Einrichtung unter Linux

Die Schritte zur Kompilierung und Installation hat der hmland-Entwickler sowohl auf der hmland-Internetseite in Englisch (kurz) als auch im oben genannten Eröffnungsbeitrag in Deutsch (ausführlich) dargestellt. Die dort gemachten Angaben werden auch bei Bedarf aktualisiert und sind deshalb der beste Anlaufpunkt für Kompilierung und Installation.

Skript zur Kompletteinrichtung unter Linux Dieser Bericht im Forum stellt ein Script vor, das hmland herunterlädt, übersetzt (kompiliert), installiert sowie ein init-Script anlegt, so dass fast keine manuellen Eingriffe mehr notwendig sind.

Die nachfolgenden Angaben in diesem Abschnitt sind rein zu Informationszwecken (noch) enthalten:

Zunächst muss die HMLAN-Emulationssoftware kompiliert werden. Analog zu dieser Beschreibung ist die Vorgehensweise die folgende (in Debian/Ubuntu/Raspbian):

 cd /opt/
 apt-get install build-essential libusb-1.0-0-dev make gcc git
 git clone git://git.zerfleddert.de/hmcfgusb
 cd hmcfgusb
 make

Danach kann der Dienst (zu Testzwecken sind Debugging-Ausgaben mit -D aktiviert) gestartet werden:

/opt/hmcfgusb/hmland -p 1234 -D

Start als Daemon

Um hmland automatisch als Daemon bei init.d Systemen zu starten, kann ein init-Script genutzt werden. Die Quellen von hmland enthalten ein solches Script im debian/ Unterverzeichnis:

cp /opt/hmcfgusb/debian/hmland.init /etc/init.d/hmland
cp /opt/hmcfgusb/debian/hmland.default /etc/default/hmland

Einstellungen, beispielsweise der Port, auf dem hmland hört, können (und sollten) in der Datei /etc/default/hmland vorgenommen werden. Wichtig: Wenn diese Anleitung befolgt wurde, muss in der Datei /etc/init.d/hmland die folgende Zeile wie folgt angepasst werden (/hm aus dem Pfad entfernen), damit der automatische Start des Daemon klappt:

DAEMON=/opt/hmcfgusb/$NAME # Introduce the server's location here

Die kopierte Datei mit chmod 755 /etc/init.d/hmland ausführbar machen, anschließend kann hmland mit folgendem Befehl gestartet werden:

/etc/init.d/hmland start

Bei Distributionen, die systemd einsetzen (z.B. Debian Stretch) kann folgende Konfigurationsdatei verwendet werden:

[Unit]
Description=Homematic LAN Adapter service
After=network.target

[Service]
ExecStart=/usr/local/bin/hmland -p 1234

[Install]
WantedBy=multi-user.target

Dabei muss dann natürlich der Port (1234) an die eigene Konfiguration angepasst werden und auch der Pfad wo sich der hmland befindet, wenn man sich an oben stehendem Beispiel orientiert wäre das dann /opt/hmcfgusb/

Diese Datei muss dann als hmland.service unter

/etc/systemd/system

abgelegt werden.

Nun muss einmalig der Befehl

systemctl daemon-reload

ausgeführt werden damit die neuen Dateien eingelesen werden. Mit dem Befehl

systemctl enable hmland

wird dafür gesorgt, dass bei einem Systemstart hmland automatisch gestartet wird Mit

systemctl status hmland

kann dann noch geprüft werden ob der Service läuft

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgende Konfigurationsdatei verwendet werden:

# HMLAND

description     "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

chdir /opt/hmcfgusb
exec /opt/hmcfgusb/hmland -d -l 127.0.0.1 -p 1234

Die Datei sollte als /etc/init/hmland.conf angelegt werden. Mit dem Befehl

initctl reload-configuration

wird Upstart angewiesen, seine Konfiguration erneut einzulesen. Danach kann der Dienst hmland mit

service hmland start

gestartet werden. hmland wird jetzt immer vor FHEM gestartet und nach FHEM beendet.

Start über FHEM Startskript

Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

Zunächst hmland kompilieren wie oben beschrieben, bis zum make. Das muss erfolgreich durchgelaufen sein.

Dann geht es weiter:

sudo cp hmcfgusb.rules /etc/udev/rules.d/

Jetzt das FHEM Startskript anpassen (in den Blöcken 'start' und 'stop' muss quasi nur jeweils 1 Zeile eingefügt werden:

Damit editiert man das FHEM Startskript:

sudo nano /etc/init.d/fhem

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)

 'start')
        echo "Starting fhem..."
        /opt/hmcfgusb/hmland -d -p 1234
        perl fhem.pl fhem.cfg
        RETVAL=$?
        ;;

 'stop')
        echo "Stopping fhem..."
        perl fhem.pl $port "shutdown"
        RETVAL=$?
        pkill hmland

So wird hmland vor FHEM gestartet und nach FHEM beendet. Letztlich erspart es Probleme mit den diversen Startskripten und ihren Rechten.

Es dauert nach dem Start von FHEM noch einige Sekunden, bis hmland fertig geladen ist. In dieser Zeit kann es zu fehlerhaften Einträgen im Logfile kommen.

Einrichtung auf Synology DiskStations

Packages für DSM5.2 finden sich hier: https://github.com/mkunzmann/spksrc/releases/tag/0.101-3

Welches Package für welche DS kann man hier sehen: https://github.com/SynoCommunity/spksrc/wiki/Architecture-per-Synology-model

Einfach das passende Package installieren und dann kann man den hmland über den Synology Package-Manager starten und stoppen. Während der Installation kann man den Port für hmland festlegen. Bitte einen Port > 1024 wählen, da der hmland nicht als root läuft. Außerdem kann ein Logfile angegeben werden. Hier am besten eine Datei auf einem USB Stick angeben die für jedermann schreibbar sein muss. Damit sollten die Platten nach wie vor in den Standby gehen.

Einrichtung unter Mac OS X

Wie unter Linux braucht man die HMLAN-Emulationssoftware hmland, die man aus Quelltexten erstellen muss. Dazu muss man die Bibliothek libusb installieren, entweder mit einem der Paketmanager wie Fink, MacPorts oder Homebrew oder direkt aus den Quellentexten (Beispiel: "fink install libusb1-shlibs libusb1"). Hat man wie bei Linux das Quelltextarchiv für hmland heruntergeladen und ausgepackt, müssen die Dateien Makefile und hmcfgusb.c angepasst werden.

Im Makefile muss man den Pfad zur libusb anpassen. Hat man libusb mit fink installiert, muss man, "/opt/local/" durch "/sw/" bei den CFLAGS und den LDFLAGS ersetzen und das "-lrt" aus den LDLIBS entfernen. Die Library librt gibt es bei Mac OS X nicht und wird anscheinend auch nicht gebraucht. (Stimmt das eigentlich?)

In der Datei hmcfgusb.c muss man die Zeilen 130-134 mit dem Aufruf libusb_detach_kernel_driver auskommentieren oder löschen. Der geht nicht auf Mac OS X.

Nach den Änderungen in den zwei Dateien, kann man wie bei Linux den Dämon hmland mit dem Kommando "make" erzeugen und mit "./hmland" ausführen. Automatisches Starten beim Booten mit launchd ist noch nicht probiert.

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:

Datum Zeit: Client 127.0.0.1 connected!
Can't claim interface: Access denied (insufficient permissions)
Can't find/open hmcfgusb!
Datum Zeit: Connection to 127.0.0.1 closed!

Auch ein Start von hmland mit Superuser-Rechten ändert daran nichts. Damit das claim interface klappt, muss man eine codeless kext in den Ordner /Library/Extensions legen. Ich habe dieses (http://mspdebug.sourceforge.net/misc/ex430rf2500-kext.zip) herunter geladen. Damit es funktioniert, muss man aber in der Datei Info.plist des Bundle die Properties idProduct und idVendor ändern, entweder mit dem Property List Editor oder einem anderen Texteditor. Die beiden Properties sind etwas versteckt bei Information Property List → IOKitPersonalities → ComIntf. Bei DebugIntf und DeviceDriver scheint man es nicht ändern zu müssen, aber schaden kann es nicht.

idProduct: 49167
idVendor: 6943

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:

  chmod -R 755 ex430rf2500.kext
  chown -R root:wheel ex430rf2500.kext

Danach die Datei ex430rf2500.kext in den Ordner /Library/Extensions legen und hmland sollte dann funktionieren.

Es kann sein, dass ab Mac OS X 10.9 der Trick mit dem codeless kext nicht mehr funktioniert, aber noch ist das nicht getestet oder bestätigt. Langfristig kann man vielleicht auch eine kext mit einem Treiber für den HM-CFG-USB USB erstellen

Einrichtung unter Windows

Bei der Einrichtung und vermutlich auch dem Betrieb unter Windows 8.1 sind wegen der erweiterten Energieverwaltungsfunktionen die von eQ-3 zusammengestellten Tipps zu befolgen.

Definition(en) in der FHEM-Konfiguration

In der FHEM Konfiguration muss noch, sofern/sobald der hmland läuft, das Device eingerichtet werden mit den folgenden Anweisungen:

define hmusb HMLAN 127.0.0.1:1234

wobei hmusb der frei wählbare Devicename ist. Anschließend sollte bzw. muss noch mit

attr hmusb hmId <hmId>

eine hmId zugeordnet werden (dabei bitte auch die Hinweise und Regeln beachten, die im Zusammenhang mit der VCCU beschrieben sind!

Firmware Update

Der Firmware Update (unter Linux) ist ebenfalls auf der hmland-Internetseite beschrieben. Auch die letzte bekannte Firmware-Version (0.967) steht dort zur Verfügung.

Bekannte Probleme

Verbindung zu neueren hmland-Versionen nicht stabil

Seit Version 0.100 meldet sich die HMLAN-Emulationssoftware als USB-Interface bei FHEM. Ältere FHEM-Versionen (vor dem 19.6.2015) brechen deshalb die Verbindung ab, da sie nur ein LAN-Interface erwarten.

Lösung: Kommandozeilenparameter -I dem hmland-Aufruf hinzufügen, dann meldet sich dieser wieder als LAN-Interface.

Stick nicht (mehr) ansprechbar

Zitat aus dem FHEM-Forum:

... befürchte ich, dass dein Stick das Zeitliche gesegnet hat. Machen die Dinger leider sehr gerne... Ganz besonders beim Modus-Wechsel vom 10k- in den 100k-Modus, wenn man bei irgendeinem Device ein Firmwareupdate durchführt.
Die gute Nachricht ist, dass der Fehler bei sämtlichen Händlern bekannt ist und anstandslos getauscht wird.

Raspberry Pi

Der USB-Stack am Raspberry Pi ist für viele Probleme verantwortlich. Daher sieht man öfter Fehlermeldungen:

usb-transfer took more than 100ms (1039ms), this may lead to timing problems!

Da das Timing bei HomeMatic wichtig ist führt das zu vielen Retransmits und zu unzuverlässigen Aktoren. Als Workaround kann man den USB-Stack auf die deutlich langsamere Version 1.1 stellen. Dazu fügt man folgenden Text am Anfang der Datei /boot/cmdline.txt ein:

dwc_otg.speed=1

Weitergehende Informationen

Es sind zwei Versionen des HM-CFG-USB im Umlauf:

Stand März 2016 ist allem Anschein nach kein HM-CFG-USB mehr im ELV Programm enthalten!

• HM-CFG-USB-2: die aktuelle Version; Kennzeichen dieser Version:
  • Größe: 28 x 84 x 11,5 mm
  • Gewicht: 18 g
  • Antenne innenliegend
• HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation (Völkner); Kennzeichen:
  • Anschluss per separatem USB-Kabel
  • abstehende Stabantenne
  • Größe: 40 x 90 x 25 mm
  • Gewicht: 45 g

Links

• Bedienungsanleitung HM-CFG-USB-2, PDF
• FHEM-Forums Thema: HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in FHEM nutzen
• ELV Shopseite zum HM-CFG-USB
• eQ-3 Produktseite zum "HomeMatic Funk-Konfigurationsadapter USB"; Downloads, technische Daten, etc.