Thread & Matter in Home Assistant mit Docker einrichten

Smart-Home-Fans aufgepasst! Wenn du deine Geräte zukunftssicher vernetzen willst, führt kein Weg an Thread und Matter vorbei. In diesem Artikel zeige ich dir Schritt für Schritt, wie du beides direkt in Home Assistant in Docker einrichtest. Am Ende steuerst du deine smarten Geräte zuverlässig und plattformübergreifend.

Die Einrichtung eines Thread Netzwerks in einem komplett dockerisierten Smart Home Setup ist furchtbar komplex und hast Monate gedauert bis ich es selbst hinbekommen habe und möchte euch nun hiermit eine Anleitung bieten, damit ihr es sofort hinbekommt!

Für eine detaillierte Anleitung und Erklärung aller Konfigurationsmöglichkeiten empfehle ich das unten verlinkte YouTube-Video. In diesem Video wird ausführlich auf jede einzelne Einstellung eingegangen, sodass du eine umfassende Anleitung zur genauen Einrichtung erhältst. Eventuellen Code aus dem Video findest du in diesem Beitrag, so dass du ihn direkt nutzen kannst ohne abtippen zu müssen.

Viele Smart-Home-Nutzer verwechseln oft Thread und Matter oder denken, es handle sich um dasselbe. Tatsächlich handelt es sich um zwei unterschiedliche, aber eng zusammenarbeitende Technologien.

Was ist Thread?

Thread ist ein modernes Mesh-Netzwerkprotokoll, das speziell für Smart-Home-Geräte entwickelt wurde. Anders als klassisches WLAN oder Bluetooth Low Energy, hat Thread einige entscheidende Vorteile:

1. Mesh-Netzwerk: Alle Geräte (Nodes) verbinden sich untereinander. Fällt ein Gerät aus, finden die Daten trotzdem einen anderen Weg.
2. Energieeffizienz: Ideal für batteriebetriebene Sensoren, da Thread sehr wenig Strom verbraucht.
3. Schnell & zuverlässig: Geräte kommunizieren direkt miteinander, ohne einen zentralen Hub zu überlasten.
4. Sicher: Thread nutzt moderne Verschlüsselung und authentifizierte Geräteverbindungen.

Thread selbst definiert nur, wie Geräte miteinander sprechen. Es sagt nicht, was die Geräte tun oder wie man sie steuert – dafür braucht es ein Protokoll wie Matter.

Praxisbeispiel:
Du hast mehrere Lampen und Sensoren im Haus verteilt. Mit Thread kann ein Bewegungssensor im Keller ein Licht im Erdgeschoss steuern, auch wenn das zentrale Gateway kurz offline ist. Das Netzwerk findet automatisch die schnellste Route.

Was ist Matter?

Matter ist ein offener Standard, der Geräte verschiedener Hersteller kompatibel macht. Ziel ist es, dass ein Smart-Home-Gerät „out-of-the-box“ in jedes kompatible System integriert werden kann.

Wichtige Punkte zu Matter:

• Herstellerübergreifend: Philips Hue, Ikea Tradfri, Nanoleaf und andere können gemeinsam gesteuert werden.
• Plattformunabhängig: Apple HomeKit, Google Home und Amazon Alexa unterstützen Matter.
• Sicher: Matter nutzt Thread, Wi-Fi oder Ethernet mit starker Verschlüsselung.
• Einfache Einrichtung: Pairing über QR-Code oder NFC.

Matter definiert also die Sprache, in der Geräte sprechen, während Thread das Transportmittel ist, über das diese Sprache zuverlässig übertragen wird.

Praxisbeispiel:
Du kaufst eine neue smarte Steckdose von einem anderen Hersteller. Mit Matter musst du sie nur scannen und kannst sie sofort in Automationen einbinden, ohne eine separate App.

Zusammenspiel von Thread und Matter

Man kann sich Thread und Matter wie folgt vorstellen:

• Thread = Straße
• Matter = Auto

Matter ist das Protokoll, das die „Befehle“ an Geräte gibt – z. B. „Schalte das Licht ein“. Thread ist das Netzwerk, über das diese Befehle transportiert werden.

Dank Thread können Matter-Nachrichten besonders schnell, stabil und energieeffizient zwischen Geräten weitergeleitet werden. Das Zusammenspiel hat drei entscheidende Vorteile:

1. Zuverlässigkeit: Auch bei vielen Geräten im Haus funktionieren Automationen problemlos, weil Thread ein selbstheilendes Mesh-Netzwerk bildet.
2. Energieeffizienz: Batteriebetriebene Geräte wie Sensoren halten deutlich länger durch.
3. Herstellerübergreifende Steuerung: Matter sorgt dafür, dass du Geräte verschiedener Hersteller zentral über Home Assistant oder andere Plattformen steuerst.

Merkmal	Thread	Matter
Typ	Netzwerkprotokoll	Anwendungsprotokoll / Geräte-Standard
Aufgabe	Daten transportieren	Geräte steuern & standardisieren
Betrieb	Mesh, energieeffizient	Über Thread, Wi-Fi oder Ethernet
Gerätekontrolle	Keine (nur Transport)	Ja (Steuerung, Automationen, Szenen)
Beispiel	Bewegungssensor sendet Signal	Matter schaltet Licht basierend auf Signal

Thread und Matter sind keine Konkurrenten, sondern ergänzen sich perfekt. Thread sorgt für stabile, schnelle und energieeffiziente Kommunikation zwischen Geräten, während Matter sicherstellt, dass alle Geräte unabhängig vom Hersteller kompatibel zusammenarbeiten. In Kombination bilden sie die Grundlage für ein Smart Home, das robust, flexibel und zukunftssicher ist.

Unterschiede: Thread vs Zigbee vs Matter over Wi-Fi

Eigenschaft	Thread	Zigbee	Matter over Wi-Fi
Netzwerktyp	Mesh	Mesh	Client-Server (Wi-Fi)
Energieverbrauch	Sehr gering	Gering	Hoch (Wi-Fi)
Reichweite	Mittel (durch Mesh erweiterbar)	Mittel (Mesh)	Abhängig von WLAN
Kompatibilität	Matter, nur kompatible Geräte	Herstellerabhängig	Matter, nur kompatible Geräte
Stabilität & Latenz	Hoch, selbstheilend	Mittel	Mittel, abhängig vom WLAN
Vorteil	Effizient, selbstheilend	Viele Geräte verfügbar	Einfach zu installieren

Kurz gesagt:

• Thread ist ideal für batteriebetriebene, energieeffiziente Mesh-Geräte und auch die Zukunft.
• Zigbee ist weit verbreitet, aber herstellerabhängig und weniger standardisiert, aber aktuell noch der Standard.
• Matter over Wi-Fi ist einfach, verbraucht aber mehr Energie und ist abhängig von der WLAN-Qualität.

Was ist Home Assistant?

Home Assistant ist eine Open-Source-Plattform für die Heimautomatisierung, die darauf abzielt, alle Geräte im Haus miteinander zu verbinden und zentral zu steuern. Sie wurde entwickelt, um eine einheitliche Benutzeroberfläche und eine einfache, flexible Steuerung für eine Vielzahl von Smart-Home-Geräten aus unterschiedlichen Ökosystemen zu bieten. Hier sind einige Punkte, die für Home Assistant spechen:

1. Kompatibilität: Home Assistant unterstützt Tausende von Geräten und Diensten von verschiedenen Herstellern, einschließlich Beleuchtung, Klimaanlagen, Heizungen, Kameras, Wettersensoren, Sprachassistenten und mehr.
2. Lokale Steuerung: Im Gegensatz zu vielen kommerziellen Smart-Home-Plattformen, die auf Cloud-Dienste angewiesen sind, läuft Home Assistant lokal in deinem Netzwerk. Dies bedeutet erhöhte Privatsphäre und Zuverlässigkeit, da deine Smart-Home-Geräte auch ohne aktive Internetverbindung funktionieren.
3. Automatisierung und Szenen: Eines der Hauptmerkmale von Home Assistant ist die Möglichkeit, komplexe Automatisierungen und Szenarien zu erstellen. Du kannst beispielsweise Lichter automatisch einschalten lassen, wenn es dunkel wird oder die Heizung einschalten, wenn die Temperatur unter einen bestimmten Wert fällt.
4. Einfache Benutzeroberfläche: Home Assistant bietet eine nutzerfreundliche Oberfläche, die es einfach macht, Geräte zu überwachen und zu steuern. Diese Oberfläche ist vollständig anpassbar.
5. Integration mit Sprachassistenten: Home Assistant kann mit Sprachassistenten wie Amazon Alexa oder Google Assistant integriert werden, um eine sprachgesteuerte Steuerung deiner Smart-Home-Geräte zu ermöglichen.
6. Open-Source und Community-Getrieben: Da Home Assistant Open-Source ist, wird es von einer aktiven Community unterstützt, die ständig neue Integrationen entwickelt und bestehende verbessert.
7. Datenschutz und Sicherheit: Als lokal laufende Plattform hat Home Assistant den Vorteil, dass die Daten im eigenen Netzwerk bleiben. Dies schützt die Privatsphäre und erhöht die Sicherheit im Vergleich zu Cloud-basierten Lösungen.

Zusammenfassend ist Home Assistant eine leistungsstarke und flexible Lösung für diejenigen, die ihr Smart Home selbst gestalten und ihre Geräte unabhängig vom Hersteller oder Ökosystem zentral steuern möchten.

Unser Setup: Home Assistant, Docker & Matter mit Thread

Für dieses Setup nutzen wir Home Assistant auf einem Server in einem Docker-Container. Dadurch läuft Home Assistant nicht als Supervised-Version, was bedeutet:

• Wir haben keine integrierten Addons wie das offizielle Matter-Addon.
• Alles, was wir brauchen, müssen wir selbst in eigenen Docker-Containern bereitstellen.

Daher benötigen wir in unserem Setup:

1. Einen Matter Server Container
   Dieser Container stellt die Matter-Funktionalität bereit, die es Home Assistant ermöglicht, Matter-Geräte zu steuern.
2. Einen OpenThread Border Router Container
   Dieser Container verbindet das Thread-Mesh-Netzwerk mit Home Assistant und sorgt dafür, dass Matter über Thread laufen kann.
3. Einen Thread-kompatiblen USB-Stick
   Der USB-Stick fungiert als Schnittstelle zwischen den Thread-Geräten im Mesh und dem OpenThread Border Router Container.

Welchen USB-Stick verwenden wir?

Für unser Beispiel verwenden wir den Home Assistant ZBT-1 (ehemals bekannt als SkyConnect).

• Dieser Stick ist Thread-kompatibel und funktioniert zuverlässig in Docker.
• Hinweis: Ein Stick kann immer nur für ein Funkprotokoll genutzt werden.
  • Das heißt: Wenn du Thread über Matter betreibst, kannst du denselben Stick nicht gleichzeitig für Zigbee nutzen.
  • Möchtest du Zigbee parallel einsetzen, benötigst du einen zweiten Stick, z. B. einen Zigbee USB-Dongle.

Übersicht: So läuft alles zusammen

1. Home Assistant Container
   • Läuft auf deinem Server
   • Enthält keine Addons
   • Steuert Automationen und Geräte über die Matter-API
2. Matter Server Container
   • Übersetzt die Matter-Kommandos in Thread-kompatible Nachrichten
   • Bindet Home Assistant an das Thread-Mesh an
3. OpenThread Border Router Container
   • Kommuniziert direkt mit dem Thread USB-Stick
   • Baut das Thread-Mesh auf und leitet Nachrichten zwischen Matter Server und Thread-Geräten weiter
4. Thread-kompatibler USB-Stick (ZBT-1 / SkyConnect)
   • Wird ausschließlich für Thread verwendet
   • Stellt die Verbindung zwischen physischen Geräten und dem OpenThread Router Container her

Voraussetzungen

Damit du unser Setup erfolgreich einrichten kannst, solltest du folgende Voraussetzungen erfüllen:

1. Docker & Home Assistant in Docker

• Docker: Docker muss auf deinem Server installiert sein, da sowohl Home Assistant als auch die benötigten Zusatzcontainer (Matter Server, OpenThread Border Router) darin laufen.
• Home Assistant in Docker:
  • Wir nutzen Home Assistant als Container-Lösung.
  • Vorteil: einfache Updates, Backups und Portabilität.
  • Hinweis: Wenn du eine nicht Docker-Version von Home Assistant nutzt, funktioniert das Setup grundsätzlich auch, die Integration der Zusatzdienste läuft dann aber leicht anders

2. Thread-kompatibler USB-Stick

• Ein Thread USB-Stick wird benötigt, um das Thread-Mesh-Netzwerk mit Home Assistant zu verbinden.
• Beispiel: Home Assistant ZBT-1 (ehemals SkyConnect).
• Wichtig: Ein Stick kann immer nur ein Funkprotokoll bedienen. Möchtest du gleichzeitig Zigbee nutzen, brauchst du einen zweiten USB-Stick.

3. Matter-fähiges Gerät

• Du brauchst mindestens ein Gerät, das Matter über Thread unterstützt, um die Integration testen zu können.
• Beispiele: Philips Hue Lampen (neueste Generation), Nanoleaf Shapes, Eve Energy Steckdosen.
• Diese Geräte bilden die Basis für Automationen, Szenen und Smart-Home-Steuerung über Home Assistant.

4. Zugriff auf deinen Router

• Für die korrekte Einrichtung von Thread & Matter ist Zugriff auf deinen Router notwendig.
• Gründe:
  • Prüfen der Netzwerkverbindung und Aktivierung von IPv6
  • Sicherstellen, dass Docker-Container auf das Netzwerk zugreifen können (z. B. Host-Netzwerkmodus oder Portfreigaben)
  • Erforderliche Kommunikation zwischen Matter-Geräten, Border Router und Home Assistant

Schritt-für-Schritt Anleitung

Schritt 1: Thread USB-Stick vorbereiten (Home Assistant ZBT-1)

Bevor du Matter über Thread nutzen kannst, muss dein Thread-kompatibler USB-Stick vorbereitet und mit der richtigen Firmware geflasht werden. Dieser Schritt ist entscheidend, damit der Stick als OpenThread Border Router funktioniert.

Hinweise zur Firmware

• Das Firmware-Update über den Web-Flasher ist nur für Home Assistant SkyConnect und Home Assistant ZBT-1 Geräte verfügbar.
• Unterstützt werden nur Geräte, die nach dem 20. Oktober 2024 gekauft wurden.

Wichtig: Ohne die richtige Firmware kann der Stick kein Thread-Mesh aufbauen und Matter-Geräte nicht korrekt ansprechen.

USB-Stick bereitstellen:

• Verwende den Home Assistant ZBT-1 Stick (ehemals SkyConnect).
• Schließe den Stick an einen PC oder Laptop an, der über USB erreichbar ist.

Firmware auswählen:

• Öffne die Seite: https://home-assistant-skyconnect.netlify.app/firmware-update/
• Wähle die aktuelle Firmware-Version für den ZBT-1 aus.

Web Flasher nutzen:

• Die Firmware wird über den Silicon Labs Web Flasher direkt im Browser auf den Stick geschrieben.
• Dazu muss der Stick an den Computer angeschlossen sein.
• Wähle die gewünschte Firmware aus und starte den Flash-Vorgang.

Schritt 2: USB-Stick in den Server einstecken und Pfad ermitteln

Nachdem der Home Assistant ZBT-1 Stick mit der Thread-Firmware vorbereitet wurde, steckst du ihn in den Server, auf dem auch Home Assistant läuft. Damit die Container später auf den Stick zugreifen können, musst du den genauen Gerätenamen/Pfad herausfinden.

So findest du den USB-Stick auf Linux

In das entsprechende Verzeichnis wechseln:

cd /dev/serial/by-id

Inhalt anzeigen lassen:

ls -l

Du siehst dann alle angeschlossenen seriellen Geräte. Bei uns sieht es beispielsweise so aus:

usb-Nabu_Casa_Home_Assistant_Connect_ZBT-1_fe6994e0f338ef119e76e3d154516304-if00-port0 -> ../../ttyUSB0

• usb-Nabu_Casa_Home_Assistant_Connect_ZBT-1_fe6994e0f338ef119e76e3d154516304-if00-port0 ist der Name des Geräts.
• ../../ttyUSB0 zeigt auf das eigentliche Linux-Gerät.

Diesen Pfad solltest du dir für die spätere Docker-Konfiguration notieren, da der OpenThread Border Router Container genau diesen USB-Port benötigt, um mit dem Stick zu kommunizieren.

Wenn du mehrere USB-Sticks hast, prüfe sorgfältig, welcher Stick für Thread verwendet werden soll.

Schritt 3: IPv6 auf dem Linux-Server aktivieren

Damit Thread und Matter korrekt funktionieren, ist IPv6-Unterstützung auf deinem Server erforderlich. Thread basiert intern auf IPv6, genauer gesagt auf 6LoWPAN over IEEE 802.15.4. Matter nutzt diese IPv6-Adressen, um Geräte zuverlässig zu adressieren und Datenpakete im Mesh zu routen.

Warum IPv6 nötig ist:

• Jedes Thread-Gerät benötigt eine eindeutige 64-Bit-Adresse, die über IPv6 bereitgestellt wird.
• Matter-Kommunikation über Thread erfolgt über IPv6 Multicast für Geräte-Discovery und automatische Konfiguration.
• Ohne IPv6 kann der OpenThread Border Router keine Geräte erkennen, und Matter kann keine Befehle korrekt zustellen.

sysctl: Was ist das?

sysctl ist ein Linux-Werkzeug, mit dem du Kernel-Parameter zur Laufzeit ändern kannst.

• Beispiel: Du kannst Forwarding aktivieren, also das Weiterleiten von Paketen zwischen Netzwerken.
• Du kannst IPv6 ein- oder ausschalten, Router Advertisements akzeptieren oder maximale Präfix-Längen festlegen.
• Änderungen mit sysctl gelten sofort, können aber bei einem Neustart verloren gehen, daher nutzen viele Nutzer ein Startskript.

Skript für IPv6 & Docker

In meinem Fall habe ich ein Skript erstellt, das beim Start meines Unraid Servers ausgeführt wird. Es aktiviert IPv6 und konfiguriert die Netzwerkschnittstellen korrekt für Docker, Thread und Matter. Es gibt auch nochmal die Konfiguration aus, um zu prüfen, ob es übernommen wurde.

#!/bin/bash
#description=This script applies sysctl settings to allow Docker to use IPv6.
#arrayStarted=true
#name=Docker Enable IPv6

# Delay before starting
sleep 10

apply_sysctl_settings() {
echo "Applying sysctl settings..."
sysctl -w net.ipv4.conf.all.forwarding=1
sysctl -w net.ipv6.conf.all.disable_ipv6=0
sysctl -w net.ipv6.conf.all.forwarding=1 # IPv6 Forwarding aktivieren
sysctl -w net.ipv6.conf.br0.accept_ra=2 # br0 akzeptiert Router Advertisements 
sysctl -w net.ipv6.conf.br0.accept_ra_rt_info_max_plen=64 # Routen-Infos aus den RAs können verarbeitet werden

#Check user script log for info
echo "Verifying sysctl settings..."
sysctl net.ipv4.conf.all.forwarding
sysctl net.ipv6.conf.all.disable_ipv6
sysctl net.ipv6.conf.all.forwarding
sysctl net.ipv6.conf.br0.accept_ra
sysctl net.ipv6.conf.br0.accept_ra_rt_info_max_plen
}

#Execute script after delay...
apply_sysctl_settings

Erklärung der wichtigsten Parameter

Parameter	Funktion
net.ipv4.conf.all.forwarding=1	Aktiviert IPv4-Forwarding zwischen Interfaces
net.ipv6.conf.all.disable_ipv6=0	IPv6 einschalten
net.ipv6.conf.all.forwarding=1	IPv6-Paketweiterleitung aktivieren
net.ipv6.conf.br0.accept_ra=2	Das Interface br0 akzeptiert Router Advertisements (RA) für automatische Konfiguration
net.ipv6.conf.br0.accept_ra_rt_info_max_plen=64	Maximale Präfixlänge für Routeninfos aus RA

• Setze das Skript so, dass es beim Serverstart automatisch ausgeführt wird, z. B. über /boot/config/go bei Unraid oder systemd-Unit bei anderen Linux-Servern.
• Ohne korrektes IPv6 funktioniert Matter über Thread nicht, Geräte erscheinen nicht und Automationen schlagen fehl.

Erklärung: Was ist br0 und warum benötigen wir es?

• br0 ist ein Bridge-Interface unter Linux.
• Es verbindet mehrere Netzwerk-Interfaces miteinander und wird oft von Docker genutzt, um Container ins Netzwerk einzubinden.
• Im Kontext von Thread & Matter dient br0 als Schnittstelle, über die der OpenThread Border Router Container und der Matter Server Container mit deinem lokalen Netzwerk kommunizieren.
• IPv6 muss auf br0 aktiviert werden, damit der Container IPv6-Pakete empfangen und senden kann, die für Thread- und Matter-Kommunikation notwendig sind.

Kurz gesagt:
br0 fungiert als Brücke zwischen deinem Server (Docker-Host), den Containern und dem restlichen Heimnetzwerk. Ohne korrektes IPv6 auf br0 könnten Thread-Geräte nicht über den Border Router erkannt werden.

IPv6 im Router aktivieren

Damit Thread über IPv6 funktioniert, muss IPv6 auch in deinem Heimnetzwerk aktiviert sein. Ansonsten können die Border Router Container keine IPv6-Adressen nutzen und Matter-Geräte nicht gefunden werden.

Beispiel: FRITZ!Box 6690 Cable

1. FRITZ!Box Oberfläche öffnen:
   • Browser öffnen, 192.168.178.1 eingeben und einloggen.
2. IPv6 aktivieren:
   • Gehe zu Internet → Zugangsdaten → IPv6.
   • Setze den Haken bei „IPv6-Unterstützung aktivieren“.
3. Präfixzuweisung prüfen:
   • Stelle sicher, dass die FRITZ!Box ein IPv6-Präfix verteilt.
   • Optional: Prüfe unter Heimnetz → Netzwerk → Netzwerkeinstellungen, dass dein Server eine IPv6-Adresse vom Router erhält.
4. Router Advertisements (RA) aktivieren:
   • Thread benötigt Router Advertisements, um Netzwerkinformationen automatisch zu bekommen.
   • In der FRITZ!Box werden RAs automatisch mit aktiviertem IPv6 verteilt.
5. Testen:
   • Nach Aktivierung kannst du auf deinem Server prüfen:
     • ip -6 addr show br0
   • Du solltest eine IPv6-Adresse sehen, z. B. fdxx:xxxx:xxxx::xxxx.

Die IPv6-Adresse siehst du aber auch nur dann, wenn dein Server ebenfalls IPv6 aktiviert hat! Bei Unraid müssen wir das ebenfalls noch manuell machen

Hinweis: Für detaillierte visuelle Schritte gibt es auch Video-Tutorials, in denen die IPv6-Aktivierung auf der FRITZ!Box gezeigt wird. Das ist besonders hilfreich, wenn man sich unsicher ist, welche Einstellungen genau nötig sind.

Schritt 4: IPv6 auf dem (Unraid-)Server aktivieren

Damit Thread & Matter über IPv6 korrekt arbeiten, muss IPv6 auch direkt auf deinem Unraid-Server aktiviert sein. Wir gehen das Schritt für Schritt durch.

1. Vorbereitung: Docker und VM-Service stoppen

• In Unraid müssen Änderungen am Netzwerkprotokoll erfolgen, daher müssen Docker und VM-Service gestoppt werden.
• Gehe zu Einstellungen → Docker → Docker-Dienst stoppen und ebenso VM-Service stoppen.

Wichtig: Solange diese Dienste laufen, können Netzwerkänderungen nicht korrekt übernommen werden.

2. Netzwerkschnittstelle anpassen

• Meistens ist die Hauptschnittstelle deines Servers eth0.
• Gehe zu Einstellungen → Netzwerk → eth0.
• Stelle bei Network protocol um auf IPv4 + IPv6.

3. Optional: Statische IPv6-DNS-Server hinterlegen

• Du kannst statische IPv6-DNS-Server eintragen, z. B. 2001:4860:4860::8888 (Google DNS).
• Das ist optional, aber sinnvoll, falls IPv6-Verbindungen zuverlässig sein sollen.

4. Docker und VM-Service wieder starten

• Nach der Änderung musst du Docker und VM-Service wieder aktivieren.
• Gehe zurück zu Einstellungen → Docker und klicke auf Start.
• Ebenso bei VM-Service starten.

5. Prüfen, ob IPv6 aktiv ist

• Pro-Tipp: Auf der Seite, auf der Docker aktiviert/deaktiviert wird, kannst du die IP-Adressen für br0 sehen.
• Dort sollte sowohl die IPv4- als auch die IPv6-Adresse angezeigt werden.
• Wenn eine IPv6-Adresse vorhanden ist, wurde die Konfiguration erfolgreich übernommen.

Damit ist der Unraid-Server korrekt für IPv6 konfiguriert und bereit, den OpenThread Border Router Container und den Matter Server Container zu betreiben.

Schritt 5: Matter Server Docker Container installieren

Nachdem der USB-Stick vorbereitet und IPv6 auf dem Server aktiviert ist, können wir nun den Matter Server in Docker installieren. Dazu nutzen wir docker-compose für eine einfache Verwaltung.

docker-compose.yml für den Matter Server

services:
  matter-server:
    container_name: matter-server
    image: ghcr.io/home-assistant-libs/python-matter-server:stable
    restart: unless-stopped
    network_mode: host
    security_opt:
      - apparmor:unconfined
    volumes:
      - /mnt/cache/appdata/smart-home/matter-server:/data
      - /run/dbus:/run/dbus:ro

Wichtige Hinweise

1. network_mode: host

• Warum entscheidend:
  • Matter und Thread benötigen direkten Zugriff auf das Netzwerk des Hosts, insbesondere auf IPv6 Multicast und lokale Ports, um Geräte im Thread-Mesh zu entdecken und zu steuern.
  • Wenn der Container im Standard-Bridge-Modus läuft, können Pakete nicht korrekt zwischen Host und Thread-Geräten ausgetauscht werden.
  • Daher gilt: alle relevanten Container (Home Assistant, Matter Server, OpenThread Border Router) müssen im host-Modus laufen.
• Vorteile von host für unser Setup:
  1. Volle Netzwerkzugriffe wie der Host selbst
  2. IPv6 Multicast funktioniert zuverlässig
  3. Geräte im LAN/Thread-Mesh werden korrekt erkannt

2. Volumes

• /mnt/cache/appdata/smart-home/matter-server:/data
  • Persistente Daten wie Geräte-Pairings, Zertifikate und Konfigurationen werden hier gespeichert.
• /run/dbus:/run/dbus:ro
  • Zugriff auf D-Bus des Hosts, notwendig für bestimmte Systeminteraktionen und Bluetooth.

3. Sicherheit

• apparmor:unconfined erlaubt dem Container, alle nötigen Netzwerkoperationen auszuführen, die ansonsten durch AppArmor eingeschränkt wären.

Zusammenfassung

1. Erstelle die Datei docker-compose.yml an einem Ort deiner Wahl, z. B. /mnt/cache/appdata/smart-home/matter-server/.
2. Füge den obigen Inhalt ein.
3. Starte den Container mit:

docker-compose up -d

• Danach sollte der Matter Server laufen und auf dein Netzwerk zugreifen können.
• Durch den Host-Netzwerkmodus kann er alle IPv6- und Multicast-Kommunikationen korrekt durchführen, die für Matter über Thread erforderlich sind.

Offizielle Dokumentation

Für alle Details, zusätzlichen Konfigurationsoptionen und Updates gibt es die offizielle Dokumentation des Python Matter Servers auf GitHub:
Python Matter Server Docker Setup

Warum network_mode: host so wichtig ist – mDNS

Neben dem allgemeinen Netzwerkzugriff ist host mode besonders für mDNS (Multicast DNS) entscheidend.

• Was ist mDNS?
  • mDNS ist ein Protokoll, mit dem Geräte im lokalen Netzwerk ihre Dienste automatisch ankündigen und entdecken können.
  • Geräte brauchen mDNS, um sich gegenseitig zu finden, ohne dass man IP-Adressen manuell eingeben muss.
  • Es funktioniert über Multicast auf IPv4 und IPv6, damit alle Geräte im LAN die Informationen empfangen.
• Warum es für Matter/Thread nötig ist:
  • Matter-Geräte nutzen mDNS, um sich im Netzwerk zu registrieren und vom Matter Server erkannt zu werden.
  • Ohne direkten Zugriff auf das Host-Netzwerk könnten mDNS-Pakete den Container nicht erreichen.
  • Mit network_mode: host kann der Container Multicast-Pakete empfangen und senden, sodass Geräte automatisch gefunden werden.

Zusammengefasst: network_mode: host ist entscheidend für IPv6, Multicast und mDNS, damit der Matter Server alle Geräte im Thread-Mesh korrekt entdecken und steuern kann.

Schritt 6: Open Thread Border Router Docker Container installieren

Damit Home Assistant und der Matter Server überhaupt mit Thread-Geräten kommunizieren können, brauchen wir einen OpenThread Border Router (OTBR). Dieser übernimmt die Rolle eines Gateways zwischen deinem lokalen IP-Netzwerk (IPv6) und dem Thread-Mesh.

Dafür erstellen wir eine weitere docker-compose.yml:

services:
    openthread:
        image: openthread/border-router:latest
        container_name: openthread
        network_mode: host
        privileged: true
        environment:
            - TZ=Europe/Berlin
            - OT_RCP_DEVICE=spinel+hdlc+uart:///dev/ttyUSB0?uart-baudrate=460800
            - OT_LOG_LEVEL=7
            - OT_THREAD_IF=wpan0
            - OT_INFRA_IF=br0
            - OT_REST_LISTEN_ADDR=0.0.0.0
            - OT_REST_LISTEN_PORT=9212
        volumes:
            - /mnt/cache/appdata/smart-home/openthread:/data:rw
        devices:
            - /dev/serial/by-id/usb-Nabu_Casa_Home_Assistant_Connect_ZBT-1_fe6994e0f338ef119e76e3d154516304-if00-port0:/dev/ttyUSB0
            - /dev/net/tun:/dev/net/tun
        cap_add:
            - NET_ADMIN
        restart: always

Erklärung der wichtigsten Parameter

Variable / Einstellung	Bedeutung
network_mode: host	Wie beim Matter Server zwingend notwendig für Multicast, IPv6 und mDNS. Nur so kann der OTBR korrekt im Netzwerk sichtbar sein.
privileged: true	Erlaubt direkten Zugriff auf Netzwerkfunktionen und Kernel-Interfaces, z. B. zur Erstellung des wpan0 Interfaces.
/dev/serial/by-id/...:/dev/ttyUSB0	Bindet den USB-Stick als RCP (Radio Co-Processor) ein. Der Pfad muss exakt zu deinem Stick passen.
/dev/net/tun	Notwendig für das Erstellen des virtuellen Netzwerkinterfaces für das Thread-Mesh.
cap_add: NET_ADMIN	Gibt dem Container zusätzliche Netzwerkrechte, etwa zum Erstellen von wpan0 oder Routenmanagement.

Erklärung der wichtigen Environment-Variablen

Variable	Funktion
OT_RCP_DEVICE=spinel+hdlc+uart:///dev/ttyUSB0?uart-baudrate=460800	Definiert das Thread-Funkmodul (RCP). Hier wird über UART + Spinel-Protokoll die Verbindung zum USB-Stick aufgebaut. 460800 Baud sind Standard für den Home Assistant ZBT-1 Stick. Und eigentlich auch für alle anderen Sticks.
OT_LOG_LEVEL=7	Setzt den Log-Level auf Debug. Sehr hilfreich in der Einrichtung, später kann man ihn auf 3 oder 4 reduzieren.
OT_THREAD_IF=wpan0	Name des Interfaces, das der Container als Thread-Mesh Interface erstellt.
OT_INFRA_IF=br0	Gibt an, welches Interface der OTBR nutzt, um ins lokale Netzwerk (LAN) zu kommunizieren – hier unsere Linux Bridge br0 mit IPv6-Unterstützung.
OT_REST_LISTEN_ADDR=0.0.0.0	Der REST-API-Endpunkt wird für alle Geräte im Netzwerk erreichbar.
OT_REST_LISTEN_PORT=9212	Port für REST-API. Wird später für Diagnosen oder Integration mit Tools genutzt.

Offizielle Referenz

Weitere mögliche Variablen, erweiterte Optionen und Debug-Tools findest du in der offiziellen Dokumentation:
👉 https://openthread.io/guides/border-router/build-docker

Schritt 7: Thread-Netzwerk aufbauen (Form Thread Network)

Damit dein OpenThread Border Router ein neues Thread-Netzwerk erstellt, führst du über die ot-ctl-Schnittstelle (OpenThread CLI) folgende Befehle aus:

In die ot-ctl-Konsole einsteigen

• Wenn dein Border Router Container bereits läuft, kannst du mit docker exec eine ot-ctl-Session öffnen:

docker exec -it openthread ot-ctl

• Wenn du OpenThread nativ (nicht in Docker) betreibst, kannst du direkt:

sudo ot-ctl

In der ot-ctl-Konsole erhältst du eine Kommando-Eingabeaufforderung > .

Neues Thread-Netzwerk konfigurieren

1. Neues Dataset initialisieren

Das Dataset enthält alle Netzwerkparameter (Kanal, Netzname, Schlüssel etc.):

dataset init new
Done

Damit wird ein „leeres“ neues Dataset angelegt.

2. Dataset anzeigen

Nachdem das neue Dataset erzeugt wurde, kannst du es ansehen:

dataset
Active Timestamp: 1
Channel: 15
Wake-up Channel: 16
Channel Mask: 0x07fff800
Ext PAN ID: 39758ec8144b07fb
Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64
Network Key: f366cec7a446bab978d90d27abe38f23
Network Name: OpenThread-5938
PAN ID: 0x5938
PSKc: 3ca67c969efb0d0c74a4d8ee923b576c
Security Policy: 672 onrc 0
Done

Damit bekommst du alle wichtigen Einstellungen auf einen Blick und weißt, wie dein Netzwerk später aussehen wird.

Wir sind weiterhin in der ot-ctl CLI des Containers (docker exec -it openthread ot-ctl)

3. Dataset aktiv übernehmen

Nun müssen wir das Thread-Netzwerk aktivieren und starten.

Nachdem dataset init new ausgeführt wurde, muss dieses Dataset aktiv gesetzt werden:

dataset commit active
Done

Damit speichert der Border Router die Netzwerkkonfiguration dauerhaft (persistiert im Container-Volume).

4. Interface aktivieren

Jetzt wird das Netzwerkinterface eingeschaltet:

ifconfig up
Done

Hinweis: Das erstellt das Thread-Interface wpan0 logisch und bringt es in den aktiven Zustand.

5. Thread-Netzwerk starten

thread start
Done

Das dauert ein paar Sekunden. Anschließend kannst du den Status prüfen:

state

Sobald alles korrekt läuft, solltest du eine der folgenden Rollen sehen:

Rolle	Bedeutung
leader	Dein Border Router ist das zentrale Steuergerät des Mesh-Netzwerks (erwartet bei frischem Netzwerk)
router	Agiert als Weiterleitungs-Knoten / Routen-Manager
child	Untergeordneter Knoten (bei weiteren Nodes üblich)

Wichtig: Wenn „detached“ erscheint → IPv6 oder Dataset stimmt nicht. Dann prüfen, ob br0 IPv6 aktiv hat und der USB-Stick korrekt eingebunden ist.

6. Thread-Interface (wpan0) auf dem Host-System prüfen

Dieser Schritt wird nicht im ot-ctl Terminal, sondern direkt auf dem Linux-Host ausgeführt, also in Unraid SSH oder Terminal. Gib Folgendes ein:

ifconfig wpan0

Wenn alles korrekt eingerichtet wurde, siehst du eine Ausgabe ähnlich wie:

wpan0: flags=4305  mtu 1280
        inet6 fe80::3c98:89e8:ddec:bda7  prefixlen 64  scopeid 0x20
        inet6 fd4d:b3e5:9738:3193:0:ff:fe00:fc00  prefixlen 64  scopeid 0x0
        inet6 fd4d:b3e5:9738:3193:0:ff:fe00:f800  prefixlen 64  scopeid 0x0
        inet6 fd4d:b3e5:9738:3193:39c4:ee02:ca9e:2b1d  prefixlen 64  scopeid 0x0
        unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  txqueuelen 500  (UNSPEC)
        RX packets 16  bytes 1947 (1.9 KiB)
        RX errors 0  dropped 3  overruns 0  frame 0
        TX packets 7  bytes 1152 (1.1 KiB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

Was bedeutet das?

✅ wpan0 ist sichtbar → OpenThread Border Router hat erfolgreich ein Netzwerkinterface erstellt
✅ Mehrere IPv6-Adressen sichtbar → Thread Mesh hat Prefixes und Local Addresses erhalten
✅ RX/TX-Daten → das Interface sendet und empfängt aktiv Pakete (z. B. Multicast für mDNS, Mesh-Kommunikation)
✅ Prefix fdxx: → das ist das Mesh-Local Prefix deines Thread-Netzwerks

Fehlercheck:

• Wird kein wpan0 Interface angezeigt → Container hat keine Rechte / privileged: true fehlt oder /dev/net/tun nicht gebunden
• Nur inet6 fe80::... (Link-Local) aber kein fdxx:: Prefix → Netzwerk nicht richtig gestartet → thread start oder dataset commit active prüfen

Damit ist dein Thread-Netzwerk auf Host-Ebene aktiv und IPv6-geroutet. Genau diese Sichtbarkeit ist später essenziell, damit Home Assistant das Netzwerk automatisch als „Border Router verfügbar“ erkennt.

Schritt 8: Integrationen in Home Assistant anbinden

Wenn alles davon erfüllt ist, erkennt Home Assistant die Dienste automatisch über mDNS & IPv6 Multicast. Du musst keine manuelle Konfiguration über Dateien machen – alles passiert über das UI.

Thread-Integration hinzufügen (ohne Eingaben)

1. Home Assistant → Einstellungen → Geräte & Dienste → Integration hinzufügen
2. Suche nach „Thread“
3. Wichtig: Hier nichts eintragen, einfach hinzufügen/bestätigen.
4. Danach erscheint im Home Assistant unter Einstellungen → Netzwerk → Thread der Eintrag, aber ohne aktiven Border Router, nur als generische Thread-Verwaltung.

➡ Dieser Schritt aktiviert nur die Thread-Infrastruktur innerhalb Home Assistant, aber noch keine Verbindung zum OTBR.

Open Thread Border Router Integration (mit URL-Eingabe)

1. Noch einmal Integration hinzufügen
2. Dieses Mal „Open Thread Border Router“ auswählen
3. Hier muss die REST-API Adresse manuell eingetragen werden:

http://<deine-Server-IP>:9212
http://192.168.178.29:9212

Bestätigen → Home Assistant verbindet sich und liest Dataset, Status & Rolle (Leader/Router) aus dem OTBR aus.

Danach erscheint im gleichen Thread-Menü unter Netzwerk → Thread ein aktiver Border Router-Eintrag mit Device-Details. Dann wird einem ein anderes Netzwerk angezeigt mit dem Namen OpenThread-xxxx. Dann muss man auf den Button Make preferred network klicken um das Netzwerk zu aktivieren.

Matter Integration (mit URL-Eingabe)

1. Noch einmal Integration hinzufügen
2. Dieses Mal „Matter“ auswählen
3. Hier muss die Adresse nicht geändert werden:

ws://localhost:5580/ws

Was passiert nach der Einrichtung?

• Unter Einstellungen → Geräte & Dienste → Matter Server siehst du, ob die Verbindung hergestellt wurde
• Du bekommst neue Optionen: „Matter Gerät hinzufügen“
• Sobald du ein neues Matter-fähiges Gerät (z. B. über Thread) in den Pairing-Modus versetzt, erscheint in Home Assistant die Option, einen Setup-Code zu scannen oder manuell einzugeben (z. B. XXX-XXX-XXX)
• Home Assistant nutzt erst Matter → dann automatisch Thread-Kommissionierung, wenn das Gerät Thread-basiert ist → es fragt dich, welches Thread-Netzwerk verwendet werden soll (aus dem OTBR-Dataset)

Schritt 9: 📱 Thread-Zugangsdaten mit Home Assistant App synchronisieren (iOS & Android)

Matter über Thread funktioniert nur dann vollständig, wenn dein Smartphone die Thread-Netzwerk-Credentials von Home Assistant erhält.
Denn: Das Smartphone übernimmt beim Pairing die Rolle des Commissioner und muss das Thread-Netzwerk kennen, um das Gerät hineinzubringen.

🔁 So aktivierst du die Synchronisation:

• Home Assistant App auf dem Smartphone öffnen (iOS oder Android)
• Profil / Einstellungen → Companion App-Einstellungen
• Unter „Problemlösungen / Entwicklertools“ findest du den Punkt:
  • 👉 „Thread-Zugangsdaten synchronisieren“ (englisch: „Sync Thread credentials“)
• Diesen Button aktivieren bzw. Synchronisation starten

Schritt 10: Matter Gerät über Thread koppeln

Beispiel Nanoleaf Essentials E27 (QR-Code / Setup-Code). Du musst dafür dein Smartphone mit der Home Assistant App nutzen.

1. Matter-Gerät in HA hinzufügen

• In Home Assistant → Einstellungen → Geräte & Dienste → Gerät hinzufügen
• Auswahl: „Matter-Gerät hinzufügen“
• Home Assistant öffnet einen Hinweis und zeigt die Optionen:
  • QR-Code scannen
  • Setup-Code manuell eingeben (XXX-XXX-XXX Format)

👉 Für die Nanoleaf Essentials findest du den Code auf der Lampenfassung oder beiliegender Karte. Alternativ kannst du den QR-Code direkt mit der HA Companion App scannen.

2. Mit Smartphone koppeln (Commissioning-Prozess)

• HA App öffnet Kamera / Eingabe-Feld
• Scanne den Matter QR-Code
• Bestätigen → Home Assistant startet die Matter-Kommissionierung

3. Gerät joint dem Thread-Netzwerk

• Die Nanoleaf-Lampe verbindet sich jetzt automatisch mit dem OTBR (über wpan0 / Border Router)
• Home Assistant zeigt den Fortschritt:
  • ✅ Matter-Verbindung hergestellt
  • ✅ Gerät dem Thread-Netzwerk hinzugefügt
  • ✅ Dienste initialisiert

👉 Nach erfolgreichem Join-vorgang erscheint die Lampe direkt in Home Assistant als neues Gerät mit Matter-Integration

Umsetzung im YouTube-Video

Fazit

Mit diesem Setup hast du dir nicht nur Matter- und Thread-Unterstützung in Home Assistant integriert, sondern gleichzeitig die Grundlage für ein stabiles, schnelles und zukunftssicheres Smart Home geschaffen – und das komplett ohne Supervisor und Add-ons, rein über Docker.

Du weißt jetzt:

• Was Matter und Thread wirklich bedeuten und worin sie sich von Zigbee oder WLAN unterscheiden
• Warum IPv6 und mDNS unverzichtbar für Matter sind und wie man sie sauber auf Server, Docker und Router-Ebene aktiviert
• Wie man einen Home Assistant ZBT-1 USB-Stick korrekt auf Thread flasht und per OTBR in das System einbindet
• Warum der Host-Netzwerkmodus essenziell ist – nicht optional
• Wie du über Matter-Server, OTBR und Thread-Integration alle Bausteine miteinander verknüpfst
• Wie Pairing wirklich abläuft – inklusive Smartphone-Thread-Sync, der oft vergessen wird
• Und schließlich: Wie ein echtes Matter-Gerät wie die Nanoleaf Essentials Lampe eingebunden wird

👉 Damit bist du nicht mehr auf Hersteller-Clouds angewiesen, deine Geräte funken lokal, energieeffizient und blitzschnell, und du hast die volle Kontrolle – genau so, wie es ein echtes Smart Home verdient.

🔗 Nützliche Links auf einen Blick

Thema	Link
Thread Firmware Flash für HA ZBT-1	https://home-assistant-skyconnect.netlify.app/firmware-update/
Matter Server Docker Docs	https://github.com/matter-js/python-matter-server/blob/main/docs/docker.md
OpenThread Border Router Guide	https://openthread.io/guides/border-router/build-docker
Netzwerkaufbau mit OTBR	https://openthread.io/guides/border-router/form-network

Interesse, aber Zeit oder Kenntnisse fehlen?

Kein Problem. Kontaktieren Sie mich und wir besprechen Ihre Anforderungen. Egal, ob geschäftlich oder privat.