Z-Wave

ZWave
Zweck / Funktion
Ansteuerung Z-Wave-Geräte über ZWDongle
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	ZWave
Modulname	10_ZWave.pm
Ersteller	Rudolf König (Forum)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

ZWDongle
Zweck / Funktion
Einbindung Z-Wave-Gateways
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	ZWave
Modulname	00_ZWDongle.pm
Ersteller	Rudolf König (Forum)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Z-Wave ist ein drahtloser Kommunikations-Standard im 868 Mhz-Band (Europa), der von der Firma Sigma Designs und der Z-Wave Alliance, einen Zusammenschluss von mehreren Hundert Herstellern, für die Heimautomatisierung entwickelt wurde. Es existieren mehr als 1000 zertifizierte Produkte verschiedenster Hersteller, die innerhalb eines gemeinsamen Z-Wave-Netzes einsetzbar sind. (Quelle: Wikipedia)

Auf dieser Seite wird das Einrichten eines Z-Wave Systems in Fhem beschrieben.

Z-Wave

Nodes - Controller und Slaves

Ein Z-Wave-Netz besteht aus mindestens 2 Geräten, den sogenannten Nodes (Knoten). Es setzt sich zusammen aus dem steuernden Controller (Zentrale) und min. 1 bis max. 231 gesteuerten Slaves (Geräten).

Home-Id und Node-ID

Innerhalb eines Z-Wave-Netzes gibt es zu 2 Identifikationsnummern zur Kennzeichnung der Netzstruktur:

1. Home-ID: Gemeinsame Identifikationsnummer aller Nodes in einem Netz zur Abgrenzung gegenüber anderen Netzen. Nur Nodes mit der gleichen Home-ID können miteinander kommunizieren.
2. Node-ID: Identifikationsnummer zur eindeutigen Kennzeichnung von jedem Node im Netz.

Die Home-ID ist im Controller (fest) hinterlegt und seine Node-ID ist typischerweise 1. Die Slaves haben zunächst keine Home-ID und Node-ID. Bei der Inklusion (Aufnahme) der Slaves in das Z-Wave-Netz überträgt der Controller seine Home-ID auf die Slaves und weist den Slaves eine eindeutige Node-ID im Netz zu, mit der Sie direkt angesprochen werden.

Besondere Node-ID ist die 255. Eine Nachricht an die Node-ID 255 kann von allen Z-Wave-Nodes ausgewertet werden (Broadcast)

Primär- und Sekundärcontroller

Der Controller, der durch Zuteilung seiner Home-ID auf die Slaves, das Netz aufbaut, ist der Primärcontroller. Grundsätzlich können in einem Netz mehrere Controller existieren, aber immer nur ein Primärcontroller. Weitere in das Netz eingebundene Controller werden zum Sekundärcontroller. Nur der Primärcontroller kann die Inklusion (Einbindung) der Nodes in das Netz durchführen. Hingegen können sowohl Primär- als auch Sekundärcontroller die Exklusion (Ausschluss) eines Nodes aus dem Netz vornehmen.

Acknowledge

Im Z-Wave-Netz werden Nachrichten vom Empänger-Node an den Sender-Node rückbestätigt (Acknowledge). Bei ausbleibendem Acknowledge wiederholt der Sender-Node die Nachricht bis zu 2 mal. Hierdurch wird eine höhere Betriebssicherheit des Z-Wave-Netzes erreicht. Bei Broadcast-Nachrichten an die Node-ID 255 findet keine Rückbestätigung statt.

Vermaschtes Netzwerk mit Routing

Z-Wave nutzt als Netzwerktopologie ein mesh network (vermaschtes Netzwerk), d. h. jeder Node ist mit einem oder mehreren anderen Nodes verbunden. Das hat den Vorteil, dass eine Nachricht zwischen zwei Nodes übermittelt werden kann, selbst wenn diese nicht direkt miteinander kommunizieren können, z. B. weil sie zu weit voneinander entfernt sind. In diesem Fall wird die Funk-Nachricht über einen oder mehrere „Zwischen-Nodes“ übertragen; dieser Vorgang wird Routing genannt. (Quelle: Wikipedia)

Informationen über das optimale Routing werden bei der Inklusion der Nodes in einer Routing-Tabelle des Primärcontrollers gespeichert. Dies geschieht durch Abfrage des Nodes, welche weiteren Nodes er erreichen kann. Durch örtliche Änderung oder Defekte von Nodes können die in der Routing-Tabelle gespeicherten Informationen fehlerhaft bzw. suboptimal werden. Dies kann sich in Funkkommunikationsproblemen im Netzwerk äußern. Hier kann ein per Software angefordert Neuaufbau der Routingtabelle gegebenenfalls Abhilfe schaffen.

Command Classes

Die Steuerung und Kommunikation der Nodes erfolgt über Command Classes (Kommandoklassen). Die Command Classes sind nach Gerätefunktionen unterteilt.

Alle Z-Wave-Geräte haben als gemeinsame kleinste Übereinstimmung die Class Basic.

Z-Wave-Geräte haben im Originalzustand eine bestimmte arbeitsfähige Grund-Konfiguration. Anpassbar an individuelle Bedürfnisse ist die Konfiguration über die Class Configuration.

Durch eine Assoziation wird definiert, welche Geräte miteinander direkt -ohne Umweg über den Controller- kommunizieren können. Auch bei Ausfall des Controllers können diese Geräte ihre gemeinsame Funkton ausüben. Zudem dienen Assoziationen der Geschwindigkeitssteigerung und Funklastreduzierung innerhalb des Netzes. Angelegt werden Assoziationen über die Class Association.

Dies sind nur die allerwichtigsten Command Classes. Weitere Command Classes sind den Handbüchern zu entnehmen.

Z-Wave in Fhem

Allgemein

Fhem wird fortwährend weiterentwickelt und verbessert. Daher ist es zwingend notwendig, dass Fhem auf dem aktuellsten Stand ist. Dazu nach der Fhem-Installation den Befehl update ausführen und anschließend shutdown restart durchführen. Genauso auch vor Anfragen im Forum die Aktualität von Fhem überprüfen.

Die Nutzung von Z-Wave in Fhem ist für den Anfänger nur mit der standardmäßig eingeschalteten autocreate-Funktion einfach umsetzbar. Die Kenntnis der Fhem-Grundlagen und Durcharbeitung der Anfänger-Lektüren wird im Folgenden vorausgesetzt. Insbesondere ist Heimautomatisierung mit Fhem zu empfehlen, auch wenn es nicht speziell Z-Wave behandelt, so werden doch wesentliche Punkte für ein Verständnis von Fhem vermittelt.

Im Folgendem und auf den Wiki-Seiten der Einzelgeräte werden immer wieder Auszüge aus der fhem.cfg dargestellt. Diese dienen zur Erläuterung und Veranschaulichung. Die Bearbeitung der fhem.cfg sollte -zur Verhinderung von Anfängerfehlern- nach Möglichkeit immer über das "Befehl-Eingabefeld" und die "Objektdetails" erfolgen.

Vorbereitung

Die Bedienungsanleitungen (Handbücher) und technischen Informationen nahezu aller Z-Wave-Geräte sind -trotz verschiedener Hersteller- regelmäßig zentral bei den Internetadressen unter Links in Deutsch abrufbar. Der Aufbau aller dort veröffentlichten Handbücher ist gleichartig, so dass man einen schnellen Einstieg in die Produkte und deren technischen Eigenschaften von verschiedenen Herstellern findet. Manche Hersteller (z.B. Fibaro) bieten zusätzlich auf Ihren Internetseiten noch separate, eigene Handbücher an. Das Handbuch ist zwingende Voraussetzung zur Einbindung und Konfiguration (Parametisierung) von Z-Wave-Geräten in Fhem.

Definition des Gateways / Controllers

Autocreate des Gateways

Fhem kann mit einem Funkgateway Z-Wave-Funk empfangen und senden. Z-Wave-Gateways existieren von verschiedenen Hersteller.

Das Z-Wave-Gateway wird nach dem Anschluss an den Fhem-Rechner beim Fhem-Start zumeist automatisch erkannt und grundlegend durch entsprechende Einträge in der fhem.cfg definiert. Ein manuelles Anlegen des ZWDongle-Moduls oder Eingriff in die fhem.cfg ist normalerweise nicht notwendig und auch nicht ratsam. Das Fhem-Gateway-Device ist in Fhem im Raum "Everything" zu finden.

Beispiele der automatisch erzeugten define-Zeile in der fhem.cfg:

Aeon Labs Z-Stick an der Fritzbox:

define ZWDongle_1 ZWDongle /dev/ttyUSB0@115200

Vision Z-Wave USB Stick ZU 1401 EU am Raspberry Pi:

define ZWDongle_1 ZWDongle /dev/ttyACM0@115200

Folgende Gateways wurden bereits erfolgreich mit Fhem eingesetzt:

• Goodway WD6001
• Vision Z-Wave USB Stick ZU 1401 EU (VIS_ZU1401)
• Razberry in Verbindung mit Raspberry Pi (Notwendige Vorarbeiten: Beitrag)
• Aeon Labs Z-Stick
• Z-Wave.Me Z-StickC (Beitrag)
• Z-Wave USB Stick (ZME_UZB1) (Thema)

Folgende Gateways sind nicht mit Fhem einsetzbar:

• Merten Funk-USB-Datenschnittstelle CONNECT

Sollte das eigene Gateway hier nicht aufgeführt sein, ist aufgrund der Standardisierung dennoch die Chance für eine erfolgreiche Einbindung des Gateways in Fhem vorhanden. Bitte dies hier oder im Forum entsprechend vermerken.

homeId und nodeList des Gateways

Zur manuellen Definition von Z-Wave Aktoren und Sensoren ist die homeId notwendig. Bei der hier bevorzugten Definition der Geräte durch autocreate ist die Kenntnis der homeId nicht zwingend. Jedoch kann durch Abfrage der homeId direkt nach Einbindung des Zwave-Gateways dessen Funktionsfähigkeit getestet werden.

Die homeId und CtrlNodeId des Gateways wird mit folgendem Befehl ausgelesen (ZWDongle_1 ist im folgenden durch den eigenen Gatewaynamen zu ersetzen):

get ZWDongle_1 homeId

ergibt beispielsweise:

ZWDongle_1 homeId => HomeId:e345c456 CtrlNodeId:01 

Die aktuelle Liste der Z-Wave Knoten, die bereits am Gateway registriert/inkludiert sind, wird mit dem folgendem Befehl ausgelesen:

get ZWDongle_1 nodeList

ergibt beispielsweise:

ZWDongle_1 nodeList => 1,2,3,4,5 

Definition von Geräten / Slaves

Hinzufügen eines neuen Z-Wave Geräts / Inklusion

Zuerst wird das Z-Wave Gateway in den Modus zur Inklusion (zum Aufnehmen) neuer Geräte gesetzt:

set ZWDongle_1 addNode on

Danach muss das Gerät in den Inklusionsmodus (Aufnahmemodus) versetzt werden. Wie dies zu erfolgen hat, ist im Handbuch des Geräte nachzulesen. Typisch sind ein- oder dreimaliges Drücken einer Taste am Gerät oder beim Anlegen der Versorgungsspannung. Durch die Inklusion werden Home-ID und Node-ID im Gerät gespeichert. Zudem teilt das Gerät über ein spezielle Funknachricht (Node Information Frame) dem Controller seinen Gerätetyp und seine Geräteeigenschaften mit. Hierbei werden dem Controller auch die vom Gerät unterstützten Command Classes mitgeteilt. Aus diesen Informationen erzeugt Fhem automatisch durch autocreate das Fhem-Geräte-Device. Die vom Geräte unterstützen Command Classes werden automatisch im Attribut classes des Fhem-Geräte-Device gespeichert. Das Gerät ist damit grundlegend in Fhem definiert.

Abschließend wird der Inklusionsmodus am Z-Wave Gateway wieder ausgeschaltet:

set ZWDongle_1 addNode off

Nächster Schritt ist die Assoziation des Gerätes mit dem Gateway.

Erneutes Hinzufügen eines bereits registrierten Z-Wave Geräts

Die an einem Z-Wave-Gateway bereits registrierten/inkludierten Geräte sind im Gateway selbst abgespeichert und können durch Fhem jederzeit wieder abgerufen werden. Dies kann man in folgenden Fällen sinnvoll nutzen:

• Inklusion mit einem batteriegespeisten ZWave-Gateway (bspw. Aeon Labs Z-Stick) ohne Fhem-Server-Anschluss während der Inklusion
• Umstieg eines ZWave-Netzwerkes von Fremdsoftware auf Fhem
• Vollständiger oder teilweiser Verlust der fhem.cfg

Eine Node-Liste aller inkludierten Geräte des Gateways wird abgerufen durch:

get ZWDongle_1 nodeList

Es werden die verschiedenen IDs der inkludierten Geräte zurückgeliefert, wobei 1 der Z-Wave Stick selbst ist.

Mit dem folgenden Befehl wird beispielsweise das bereits im Gateway inkludierte Gerät mit der ID 2 in Fhem durch autocreate definiert:

set ZWDongle_1 createNode 2

Assoziation

Devices die die Association unterstützen sind in der Lage, direkt mit anderen Devices zu kommunizieren. Dies können zum einen direkte Befehle sein, als auch Meldungen über den Status und Zustand der Devices.

Zum Beispiel kann damit ein Bewegungsmelder bei entdeckter Bewegung direkt eine Lampe ein oder ausschalten oder die aktuelle Temperatur an den Controller senden.

Devices können mehrere Association Groups haben, die für vom Hersteller vorgesehene unterschiedliche Aktionen definiert sind. Welche das sind, geht aus der jeweiligen Beschreibung hervor.

Damit FHEM auf Statusmeldungen von Sensoren/Aktoren reagieren (und auch Anzeigen) kann, muss der Controller (ZWDongle_1, CtrlNodeId = 1) mit dem jeweiligen Device <name> assoziiert werden.

set <name> associationAdd <associationGroup> <CtrlNodeId>

Nahezu alle in Europa erhältlichen Devices unterstützen die Rückmeldung des Status via Association. Daher ist diese Konfiguration in der Regel Pflicht, um ein Device sinnvoll mit FHEM nutzen zu können.

Ausnahmen gibt es in Nordamerika, wo aufgrund von Patentansprüchen einige Hersteller auf die Statusrückmeldungen verzichten. Diese Geräte unterstützen in der Regel die Command Class ASSOCIATION nicht.

Nächster Schritt ist die Konfiguration des Gerätes.

Konfiguration

Die Standard-Konfiguration eines Gerätes entspricht oftmals nicht den eigenen Wünschen und Anforderungen (Einheiten usw.). Mit der Class Configuration lässt sich die Konfiguration beispielsweise bei Parametergröße 1 mit diesem Befehl anpassen:

set <name> configByte <Parameternummer> <Parameterwert>

Die Angaben zu den Parameternummern, -größen und -werten sind im jeweiligen Geräte-Handbuch enthalten.

Zudem bietet Fhem seit 10/2014 basierend auf XML-Dateien von http://www.openzwave.com/ die Möglichkeit die speziellen Parameternummern, -größen und -werten des Gerätes mit Hilfsinformationen einzubinden Beitrag. Ein manuelles Suchen im Geräte-Handbuch ist dadurch entbehrlich. Dazu muss das Gerät von Fhem einmalig durch folgenden Befehl identifiziert werden:

get <name> model

Die Readings model, modelID und modelConfig werden dadurch erzeugt. In model sollte der Klartextname des Gerätes stehen. Zudem sind dann spezielle set/get-Kommandos configXYZ für das Geräte im Auswahldialog der Detailansicht mit Hilfsinformationen verfügbar.

Der Aufruf von get <name> model ist auch für die Nutzung der Class MANUFACTURER_PROPRIETARY zwingende Einsatzvoraussetzung.

Entfernen eines Z-Wave-Geräts / Exklusion

Zuerst wird der Z-Wave Stick in den Modus zur Exklusion (Ausschluss) von Geräten gesetzt:

set ZWDongle_1 removeNode on

Danach muss das Gerät in den Exklusionsmodus (Ausschlussmodus) versetzt werden. Wie dies zu erfolgen hat, ist im Handbuch des Geräte nachzulesen. Durch die Exklusion wird die Home-ID und Node-ID aus dem Gerät gelöscht.

Abschließend wird der Exklusionsmodus am Z-Wave Gateway wieder ausgeschaltet:

set ZWDongle_1 removeNode off

Das Fhem-Device muss nach der Exklusion manuell durch delete <name> gelöscht werden.

Geräte-Besonderheiten

Batterie betriebene Geräte

Um die Batterielaufzeit zu erhöhen, legen sich batteriebetriebene Geräte „schlafen“ und wachen in konfigurierbaren Intervallen auf um einen "wakeup notification" zu senden. Daraufhin senden andere Devices und Fhem ihre bis dahin gesammelten Befehle, die dann verarbeitet bzw. beantwortet werden.

Dies wird wie folgt konfiguriert.

set <name> wakeupInterval  <CtrlNodeId>

ist die Zeit in Sekunden zwischen den Intervallen und <nodeID> der gewünschte Empfänger des "wakeup notification". In der Regel ist dies wieder der Controller (NodeId=1). Viele Geräte kommen im Auslieferungszustand mit der NodeID 255 (die "wakeup notification" wird als Broadcast an alle erreichbaren Devices gesendet). Hier empfiehlt es sich die Konfiguration auf nodeID 1 zu ändern, da dies robuster ist und zusätzlich noch Batterielaufzeit spart.

Bei Konfigurationsänderungen an batteriebetriebenen Geräten mit set <name> config... sollte die korrekte Verarbeitung der Befehle immer mit dem entsprechenden get <name> config... überprüft werden, um eventuelle Funk-Telegrammverluste sofort festzustellen.

Fibaro

Bei den bisher erschienenen Devices wird die Association Group 3 für die Übermittlung von Sensor Werten verwendet.

set <name> associationAdd 3 <CtrlNodeId>

FGSS-001 Rauchmelder

Dieser Rauchmelder scheint einen falschen Batterie-Level (0%) zu senden, wenn er außerhalb des wakeup intervals abgefragt wird.

Workaround: Den Batterie-Level nicht direkt via get anfordern, sondern per notify auf den wakeup Report reagieren.

FGRM-222 Roller shutter 2

siehe FGRM-222-Rollladenaktor

FGK-101 Tür/Fensterkontakt

Der Tür/Fensterkontakt sendet Zustandsänderungen nur als basicReport (ff oder 00). Der Status (open / closed) wird nur nach explizitem get gemeldet.

Philio

PHI_PSM02 Z-Wave 4 in 1 Sensor (Tür, Bewegung, Helligkeit, Temperatur)

siehe PSM02-Tür-, Bewegungs-, Helligkeits-, Temperatursensor

PHI_PAN04 Relais Unterputzeinsatz 2 Schalter a 1.5kW mit Messfunktion

siehe Thema

GE

GE (Model t.b.d)

Dieser Schalter unterstützt keine Statusrückmeldungen.

DüWI/Popp

Geräte von DÜWI liefern bei örtlicher Betätigung kein automatisches Funk-Signal über die Statusänderung. Das liese sich nur durch eine regelmäßige Statusabfrage durch Fhem (at) beheben. Dies ist bei Produkten von Z-wave.me, die zum Teil auf DÜWI-Geräten basieren, durch eine erweiterte Firmware behoben. Die erweiterte Firmware behebt auch andere Firmware-Schwächen der Original-Produkte von DÜWI.

Links

• Grundlageninformation "Z-Wave-Haupt-Anleitung": Wie errichte und betreibe ich ein Z-Wave basiertes Funknetz
• herstellerübergreifende Datenbank mit Bedienungsanleitungen zu Z-Wave-Geräten: Z-Wave Handbücher
• herstellerübergreifende Datenbank mit technischen Informationen zu Z-Wave-Geräten: Z-Wave Device Library
• informative Webseiten zu Z-Wave:
  • http://www.z-wavealliance.org/, englisch
  • http://www.zwaveeurope.com/, englisch
  • http://www.zwave.de/, deutsch
  • Infos zu CommandClasses (ausführlich), RaZBerry und Z-Wave allgemein, englisch

FAQ

Welche Schritte sind für die Einbindung von ZWave-Geräten in Fhem mindestens durchzuführen?

Voraussetzung: ZWave-Gateway ist erfolgreich eingebunden!

1. Inklusion des Gerätes
2. Assoziation des Gerätes mit dem Gateway
3. Konfiguration des Gerätes
   1. immer: get <device> model
   2. Konfiguration dann gegebenenfalls nach eigenen Bedürfnissen anpassen

Wie können bei mehrkanaligen Aktoren die zusätzlichen Kanäle (>1) angesprochen werden?

• Bei der Inklusion des Gerätes wird nur der 1. Kanal angelegt
• zusätzliche Kanäle werden mit Hilfe der Befehle get <device> mcEndpoints und get <device> mcCapability <chid> aus der Class MULTI_CHANNEL ermittelt/angelegt (Details und Beispiel siehe commandref)

Wie wird ein fehlendes Kernelmodul (Fritzbox) eingebunden?

Auf der Fritzbox (und evtl. auch anderen Systemen) muss sichergestellt werden, dass das Kernelmodul für das Gateway geladen wird. Ansonsten scheitert die Einbindung des Gateways in Fhem.

Für den Aeon Labs Z-Stick muss beispielsweise auf der Fritzbox das Kernelmodul cp2101.ko geladen werden. Diese Datei ist bei einer FHEM und FritzBox 7390 Installation über das Image von fhem.de bereits enthalten. Um den Aeon Labs Z-Stick zu verwenden, muss dieses Kernelmodul vor oder beim Starten des Fhem-Servers geladen sein. Dies erreicht man durch einen Eintrag in der Datei startfhem.

Die entsprechende Zeile kann direkt unterhalb der modprobe Anweisungen eingefügt werden.

insmod $home/lib/cp2101.ko

Nach einem Fhem-Neustart sollte das Gateway (der USB Stick) nun erkannt werden.

Welche Infos sollten Anfragen im ZWave-Forum enthalten?

• Anfragen bitte nur zur aktuellsten Fhem-Version: Befehl update ergibt Ausgabe "nothing to do..."
• detaillierte Beschreibung des Problems
• beteiligte Komponenten (genaue Bezeichnung und evtl. Link auf Hersteller-Dokumentation)
• list des jeweiligen devices (list <device>) oder zumindest Config-Auszug (fhem.cfg)
• logs mit verbose 5 (attr <device> verbose 5)

Wie kann ich zur Fortentwicklung der ZWave-Module beitragen?

• Erfolgreichen Einsatz von neuen/bisher nicht gemeldeten ZWave-Geräten im Forum mitteilen
• Codeschnipsel und Ideen im Forum posten
• Fehler und Probleme im Forum melden
• Wiki: Korrekturen vornehmen; neue Geräte ins Wiki aufnehmen; Codeschnipsel und Beispiele einpflegen