Skip to main content

🔌 Z-Wave JS UI als externer Z-Wave Server für ioBroker

Stand: 2026-Februar

📡 Was ist Z-Wave?

Z-Wave ist ein drahtloser Funkstandard für Smart-Home-Anwendungen und arbeitet in Europa im lizenzfreien SRD-Band bei 868,4 MHz. Der Standard wurde speziell für die Hausautomation entwickelt und ist auf geringe Leistungsaufnahme sowie hohe Zuverlässigkeit ausgelegt.

Durch die niedrigere Frequenz im Vergleich zu z.B. Zigbee (2,4 GHz) eignet sich Z-Wave besonders gut für den Einsatz in Wohnungen und Häusern, da Wände und Decken in der Regel besser durchdrungen werden.

Die Geräte bilden ein vermaschtes (Mesh-)Netzwerk. Netzbetriebene Teilnehmer fungieren als Repeater und leiten Funktelegramme weiter. Dadurch erhöht sich die Reichweite und Stabilität des Gesamtnetzes.

Z-Wave ist ein zertifizierter Standard. Jedes Gerät muss eine offizielle Zertifizierung durchlaufen. Dadurch ist die herstellerübergreifende Interoperabilität in der Praxis meist zuverlässiger als bei z.B. Zigbee-Geräten.

Typische Einsatzbereiche

  • Licht
  • Heizung
  • Rollläden
  • Sensoren
  • Sicherheitsgeräte

👍 Z-Wave – Pro

  • Sehr geringer Energieverbrauch
  • Betrieb im SRD-Band (EU: 868,4 MHz) mit guter Durchdringung in Wohnungen
  • Geroutetes Mesh-Netzwerk für netzbetriebene Geräte
  • Gut geeignet für batteriebetriebene Geräte
  • Große Geräteauswahl durch viele Hersteller
  • Verschlüsselte Kommunikation bei sicherheitsrelevanten Geräten (S0 / S2)

👎 Z-Wave – Contra

  • Inclusion und vollständiges Interview können – besonders bei batteriebetriebenen Geräten – Zeit benötigen
  • Gerätepreise häufig höher als bei anderen Funkstandards
  • Nachträgliches Inkludieren/Exkludieren fest verbauter Geräte ist aufwendig
  • Netzwerkinformationen werden im Z-Wave Controller gespeichert und sind nicht Bestandteil eines ioBroker Backups
  • Bei Defekt oder Austausch des Controllers ist ein vorher erstelltes NVM-Backup zwingend erforderlich (z.B. über Z-Way oder zwave-js-ui)

🔁 Hinweis zu ioBroker Adaptern

Der Adapter ioBroker.zwave2 wird seit längerer Zeit nicht mehr weiterentwickelt (Release 3.1.0 on Sept. 2023).

Diese Anleitung dient als Vorbereitung für den Einsatz des Adapters ioBroker.zwavews

Hinweis: Der Adapter ioBroker.zwavews befindet sich zum Zeitpunkt dieser Anleitung noch im Beta-Status.

Hier wird ausschließlich die Installation und Konfiguration von Z-Wave JS UI beschrieben, welche Voraussetzung für ioBroker.zwavews ist.

Die Umstellung vom bisherigen ioBroker.zwave2 Adapter mit bestehenden Skripten und Visualisierungen kann Zeit in Anspruch nehmen. Dies betrifft insbesondere angepasste Datenpunkte und individuelle Logiken.

Im Zuge der Umstellung empfiehlt es sich, die Datenpunkte neu zu strukturieren und konsequent Aliase zu verwenden. Dadurch wird die Wartung vereinfacht und zukünftige Änderungen oder Updates lassen sich sauberer umsetzen.

⚠️ Achtung – Backup

Im ioBroker Backup sind keine Z-Wave Geräte enthalten.

ioBroker sichert ausschließlich:

  • eigene Objekte
  • Adapter-Einstellungen
  • Datenbanken

Die Z-Wave Netzwerkinformationen (Node-IDs, Security Keys, Routing, Inclusion-Status usw.) befinden sich immer im Z-Wave Controller bzw. im verwendeten Z-Wave Server.

Bei Verwendung von Z-Way

Mit Z-Way for Raspberry Pi Z-Way Repository kann ein NVM-Backup des Gateways mit allen inkludierten Z-Wave Geräten erstellt werden.

Bei Verwendung von Z-Wave JS / zwave-js-ui

  • Das Z-Wave Netzwerk läuft im Z-Wave JS Server, nicht in ioBroker
  • ioBroker greift ausschließlich über eine WebSocket-Verbindung (ws://IP:Port) auf die Daten zu
  • Das Controller-Backup muss in zwave-js-ui erstellt werden

Das NVM (Non-Volatile Memory) Backup sichert:

  • inkludierte Geräte (Nodes)
  • Node-IDs
  • Security Keys (S0 / S2)
  • Netzwerktopologie (Routing-Informationen)
  • Home-ID und Controller-Rolle

Das Backup befindet sich in zwave-js-ui unter:

Settings → Backup → Controller (NVM) Backup

Backup-Schalter aktivieren. Nach dem Aktivieren erscheint darunter die Möglichkeit, ein Backup zu erzeugen bzw. herunterzuladen.

  • STORE → Backup (optional, betrifft nur UI-Daten)
  • Controller (NVM) Backup
  • Restore erscheint erst, wenn mindestens ein NVM-Backup vorhanden ist

Ohne ein solches Controller-Backup können inkludierte Geräte bei einem Hardwaredefekt oder einem Stick-Tausch nicht wiederhergestellt werden.

Fazit

Ein ioBroker Backup ersetzt niemals ein Z-Wave Controller-Backup – unabhängig davon, ob Z-Way oder Z-Wave JS verwendet wird.

🔄 MQTT oder Websocket (ioBroker.zwavews)

MQTT

  • Überträgt Status- und Set-Werte
  • Plattformunabhängig nutzbar
  • Geeignet für gemischte Umgebungen
  • Keine Controller-Verwaltung

Websocket (ioBroker.zwavews)

  • Direkte Anbindung an die Z-Wave JS API
  • Vollständige Integration in ioBroker
  • Ermöglicht Controller-Funktionen
  • Weniger Konfigurationsaufwand im reinen ioBroker-Setup

⚠️ Wichtig

Inkludieren (Inclusion/Exclusion) geht nicht über MQTT.

Das geht nur über:

  • Z-Way (z-wave.me)
  • ioBroker.zwave2
  • Webinterface von zwave-js-ui
  • Websocket-API (also über ioBroker.zwavews)

🟢 Z-Wave JS UI nativ auf EndeavourOS ARM headless mit ioBroker

Z-Wave JS UI als Vorbereitung für ioBroker.zwavews

Voraussetzungen für ioBroker

  • Eine laufende zwave-js-ui Umgebung
  • Aktivierte WS (Websocket) Kommunikation
  • Installation und Konfiguration des Adapters ioBroker.zwavews

ℹ️ Hinweis

  • Das Webinterface läuft standardmäßig auf Port 8091
  • Der Websocket-Server für ioBroker.zwavews läuft standardmäßig auf Port 3000

📋 Voraussetzungen

System

  • Raspberry Pi 4 oder 5
  • EndeavourOS ARM (headless)
  • ioBroker nativ installiert unter /opt/iobroker
  • NodeJS LTS 22 (nodejs-lts-jod) wie von ioBroker empfohlen
  • Funktionierender Z-Wave Controller
    • USB-Stick (z.B. /dev/ttyACM0 oder /dev/ttyUSB0)
    • oder RaZberry 7 (z.B. /dev/ttyAMA0)
  • SSH-Zugriff

⚙️ Wichtige Systemkonfiguration bei RaZberry 7

Die Konfiguration erfolgte bereits bei: "ioBroker auf Pi 4 mit EndeavourOS → Schritt 7: Vorbereitung für ioBroker"

Dort muss folgendes gesetzt sein:

/boot/config.txt
enable_uart=1
dtoverlay=disable-bt
/boot/cmdline.txt

Falls vorhanden, entfernen:

console=serial0,115200

🔎 System prüfen

node -v
npm -v

Bei USB-Stick:

ls -l /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

Bei RaZberry 7 (GPIO):

ls -l /dev/serial* /dev/ttyAMA* 2>/dev/null

meine Ausgabe:

crw-rw---- 1 root uucp 204, 64 10. Feb 18:42  /dev/ttyAMA0

Gerät gehört Gruppe uucp und nur root und Mitglieder der Gruppe uucp dürfen zugreifen.

In zwave-js-ui verwendest du später:

/dev/ttyAMA0

🚀 Installation

Z-Wave JS UI lokal in eigenes Verzeichnis installieren

Für eine bessere Übersicht nutze ich den Ordner /opt, da sich dort auch iobroker und pihole befinden.

sudo mkdir -p /opt/zwave-js-ui
cd /opt/zwave-js-ui
npm init -y
npm install zwave-js-ui

Ohne Versionsangabe wird die aktuell als latest markierte Version installiert.

Service-User mit eigenem Home-Verzeichnis anlegen und Rechte setzen

sudo useradd -r -m -d /opt/zwave-js-ui -s /usr/bin/nologin zwave
sudo usermod -aG uucp zwave
sudo chown -R zwave:zwave /opt/zwave-js-ui

Prüfen mit:

id zwave

Meine Ausgabe:

uid=963(zwave) gid=962(zwave) Gruppen=962(zwave),986(uucp)

systemd Service anlegen

sudo nano /etc/systemd/system/zwave-js-ui.service

Inhalt:

[Unit]
Description=Z-Wave JS UI
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/zwave-js-ui
ExecStart=/usr/bin/node --preserve-symlinks /opt/zwave-js-ui/node_modules/zwave-js-ui/server/bin/www.js
Restart=on-failure
User=zwave
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Store-Verzeichnis im richtigen Pfad anlegen (damit kein mkdir im falschen Kontext scheitert):

sudo mkdir -p /opt/zwave-js-ui/node_modules/zwave-js-ui/store

Rechte anpassen, Service laden, aktivieren, starten:

sudo chown -R zwave:zwave /opt/zwave-js-ui
sudo systemctl daemon-reload
sudo systemctl enable zwave-js-ui
sudo systemctl start zwave-js-ui

Status prüfen und Ports:

systemctl status zwave-js-ui
sudo ss -tulpn | grep -E '8091|3000'

Port 3000 ist noch nicht offen, weil der Websocket-Server noch nicht aktiviert ist (kommt später im Webinterface).

🌐 Webinterface öffnen

http://<IP-deines-Pi>:8091

bei mir ist das:

http://192.168.0.164:8091

🔌 Serielles Device konfigurieren

Im Webinterface:

Settings → MQTT Gateway

Das MQTT Gateway wird für ioBroker.zwavews nicht benötigt und kann deaktiviert bleiben. Die Kommunikation mit ioBroker erfolgt ausschließlich über Websocket.

Settings → Z-Wave → Serial Port

In meinem Beispiel:

/dev/ttyAMA0

Zusätzlich konfigurieren:

  • Bei einer Neuinstallation die Security Keys generieren lassen
  • Bei einem Upgrade von ioBroker.zwave2 die dort verwendeten Security Keys übernehmen
  • Bei meinem Upgrade mussten die „Security Keys (Long Range)“ neu generiert werden, da ioBroker.zwave2 diese nicht unterstützt
  • Default Radio Configuration: Europe

Websocket für ioBroker.zwavews aktivieren

Im Webinterface:

Settings → Home Assistant

  • Websocket Server aktivieren
  • Server Host leer lassen (bindet auf allen Interfaces)
  • Standard-Port 3000 verwenden
  • DNS Discovery deaktivieren (bei fester IP und manueller URL im Adapter nicht erforderlich)

Speichern.

Du wirst gefragt, ob der Z-Wave JS driver neu starten soll: YES

Alternativ:

sudo systemctl restart zwave-js-ui

Wichtig

Ein Z-Wave Controller ist ein serielles Gerät. Der Port kann in der Regel nur von einem Prozess exklusiv geöffnet werden (Lock). Während du zwave-js-ui einrichtest, muss zwave2 deaktiviert bleiben. Später ersetzt zwave-js-ui den zwave2 Adapter vollständig.

Diese URL im ioBroker.zwavews Adapter eintragen:

ws://<IP-deines-Pi>:3000

Nach dem Speichern prüfen:

sudo ss -tulpn | grep 3000

💡 Tipp:
Die Einstellungen der zwave-js-ui Oberfläche können über Import / Export gesichert und wiederhergestellt werden.

🔄 Update von Z-Wave JS UI

Update installieren und kontrollieren:

sudo -u zwave npm update --prefix /opt/zwave-js-ui

Dienst neu starten:

sudo systemctl restart zwave-js-ui

Version prüfen (optional):

cd /opt/zwave-js-ui
sudo -u zwave npm list zwave-js-ui

Ergebnis:

zwave-js-ui@1.0.0 /opt/zwave-js-ui
└── zwave-js-ui@11.11.0

🗑 Z-Wave JS UI sauber deinstallieren

Service stoppen und deaktivieren

sudo systemctl stop zwave-js-ui
sudo systemctl disable zwave-js-ui

Status prüfen:

systemctl status zwave-js-ui

systemd Service-Datei löschen

sudo rm /etc/systemd/system/zwave-js-ui.service
sudo systemctl daemon-reload

Lokale npm-Installation entfernen

Da die Installation unter /opt/zwave-js-ui erfolgt ist, gibt es keine globale npm-Installation.

sudo rm -rf /opt/zwave-js-ui

Service-User entfernen

sudo userdel zwave

Optional prüfen:

id zwave

Prüfen, ob noch Ports belegt sind (optional)

sudo ss -tulpn | grep -E '8091|3000'

Es darf kein Listener mehr angezeigt werden.

Ergebnis

Entfernt sind:

  • systemd-Service
  • Installationsverzeichnis /opt/zwave-js-ui (inkl. node_modules und Daten)
  • Service-User zwave
Back to top