HM-CFG-USB USB Konfigurations-Adapter

HM-CFG-USB USB Konfigurations-Adapter
todo
Allgemein
Protokoll	HomeMatic
Typ	Interface/Gateway
Kategorie	HomeMatic
Technische Details
Kommunikation	868,3MHz
Kanäle
Betriebsspannung
Leistungsaufnahme
Versorgung	USB-Bus
Abmessungen
Sonstiges
Modulname	CUL_HM
Hersteller	HomeMatic

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.

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-core
git clone git://git.zerfleddert.de/hmcfgusb
cd hmcfgusb
make

(Unter Debian ist "build-essentials" nicht als Paket vorhanden, dieser Schritt kann entfallen.)

Danach kann der Dienst zu Testzwecken gestartet werden (in /opt/hmcfgusb):

./hmland -p 1234 -D

Start als Daemon

Um den hmland als Daemon mit dem Betriebsystem automatisiert zu starten, kann ein init-script genutzt werden. In diesem Beitrag ist ein Skript zur automatischen Einrichtung von hmland als Daemon über init mit Installationsanweisung enthalten. Dieses Skript enthält zudem auch die Befehle zum Download, Kompilierung und Installation von hmland, so dass fast keine manuellen Eingriffe notwendig sind.

Alternativ ist auch der (umständlichere) manuelle Weg möglich:

#!/bin/sh
### BEGIN INIT INFO
# Provides: hmland
# Required-Start: $localfs $syslog $remote_fs
# Required-Stop:
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: hmland daemon
# Description: hmland daemon, Homematic USB Adapter on port 1234
### END INIT INFO

 # simple init for hmland
 
 pidfile=/var/run/hmland.pid
 port=1234
 
 case "$1" in
  start|"")
 	chrt 50 /opt/hmcfgusb/hmland -d -P -l 127.0.0.1 -p $port 2>&1 | perl -ne '$|=1; print localtime . ": [hmland] $_"' >> /var/log/hmland.log &
 	;;
  restart|reload|force-reload)
 	echo "Error: argument '$1' not supported" >&2
 	exit 3
 	;;
  stop)
 	killall hmland
 	;;
  status)
 	if [ ! -e $pidfile ]; then
 		echo "No pid"
 		exit 1
 	fi
 	pid=`cat $pidfile`
 	if kill -0 $pid &>1 > /dev/null; then
 		echo "Running"
 		exit 0
 	else
 		rm $pidfile
 		echo "Not running"
 		exit 1
 	fi
 
 	;;
  *)
 	echo "Usage: hmland [start|stop|status]" >&2
 	exit 3
 	;;
 esac

Bei Distributionen, die Upstart einsetzen (z.B. xbian) kann folgendes Konfigurationsfile 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 neue Dienst 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 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.

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

Windows

Die erweiterte Energieverwaltung unter Windows 8.1 kann dazu führen, dass der Adapter unerwünschterweise in den Stand-by Modus versetzt wird (siehe Einrichtung unter Windows).

Weitergehende Informationen

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

• HM-CFG-USB-2: die aktuelle Version; Dokumentation derzeit (12/2013) nicht über die ELV-Artikelseite verfügbar, alternativ jedoch bei Völkner; 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

• 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.