Zum Inhalt

Thread-Geräte in ioBroker anlernen (Matter over Thread mit der neuen CZC Firmware)#

Dieser Guide zeigt, wie du Matter-over-Thread-Geräte (z. B. Steckdosen, Sensoren) über den CZC als Thread Border Router in ioBroker einbindest.

Am Ende ist das Gerät im Thread-Netz des CZC und lässt sich in ioBroker steuern.

Es gibt zwei Wege:

Weg Wann?
A – BLE direkt in ioBroker (empfohlen) Der ioBroker-Host hat Bluetooth (z. B. Raspberry Pi)
B – chip-tool + Übergabe an ioBroker Der ioBroker-Host hat kein Bluetooth (z. B. VM, Docker, Server)

Getestet mit ioBroker.matter 1.3.1 auf Debian 13 / Raspberry Pi OS.


1. Was beim Anlernen passiert#

 ioBroker ──── LAN (IPv6) ──── CZC ~~~~ Thread-Funk ~~~~ Gerät
     │                                                     ▲
     └──────────── Bluetooth (nur beim Anlernen) ──────────┘
  1. ioBroker verbindet sich beim Anlernen per Bluetooth direkt mit dem Gerät.
  2. Darüber bekommt das Gerät den „Schlüssel“ zum Thread-Netz des CZC (das Dataset).
  3. Das Gerät tritt per Funk dem Thread-Netz bei. Der CZC ist die Brücke ins LAN.
  4. Ab jetzt spricht ioBroker über das LAN (IPv6) mit dem Gerät, Bluetooth wird nicht mehr gebraucht.

Drei Begriffe, die im Guide vorkommen:

  • Thread-Dataset: Alle Zugangsdaten des Thread-Netzes in einem Hex-String (Name, Kanal, Netzwerkschlüssel …).
  • Border Router: Verbindet das Thread-Funknetz mit deinem LAN. Das ist der CZC.
  • Fabric: Die „Mitgliedschaft“ eines Geräts bei einem Matter-Controller. Ein Gerät kann mehreren Controllern gleichzeitig gehören.

2. Warum das Anlernen per Handy-App oft scheitert#

Smartphone-Ökosysteme verwenden beim Anlernen ihr eigenes, bevorzugtes Thread-Netz und nicht das des CZC.

  • Apple (iPhone/iPad): iOS übernimmt Bluetooth und Thread-Provisioning selbst und übergibt dem Gerät die Zugangsdaten des Apple-Thread-Netzes (HomePod, Apple TV). Das Dataset im ioBroker-Adapter wird dabei nicht benutzt. Das gilt auch beim Anlernen über die ioBroker-VISU-App auf iOS.
  • Android / Google Home: Ähnliches Verhalten mit eigenen Thread-Zugangsdaten; die Ergebnisse hängen stark vom Handy ab.

Die Folge: Das Gerät landet im falschen Thread-Netz, taucht nicht im CZC auf oder ist für ioBroker nicht erreichbar.

Empfehlung: Thread-Geräte für den CZC nicht per Handy-App anlernen, sondern über Weg A oder Weg B.


3. Gemeinsame Voraussetzungen (für Weg A und B)#

3.1 CZC per Ethernet anschließen#

Der CZC muss per LAN-Kabel angeschlossen sein. Border Routing über WLAN wird derzeit nicht unterstützt.

Starte den CZC nach dem Einstecken des Kabels neu, damit Ethernet als Verbindung ins LAN verwendet wird.

3.2 Gleiches Netzwerksegment#

Der ioBroker-Host und der CZC müssen im selben LAN bzw. VLAN hängen, ohne Router dazwischen. Der CZC verteilt seine Routen und Dienste per Link-Local-Multicast (Router Advertisements, mDNS). Diese erreichen nur Geräte im selben Segment. Eine reine IPv4-Verbindung reicht nicht.

3.3 IPv6 am ioBroker-Host#

IPv6 darf auf dem Host nicht deaktiviert sein, und der Host muss Router Advertisements annehmen. Bei Debian/Raspberry Pi OS mit NetworkManager ist das der Standard (ipv6.method auto).

3.4 Hinweis zu Docker und VMs#

  • Docker: Den Container mit network_mode: host betreiben, sonst kommen mDNS und Router Advertisements nicht an.
  • VM (z. B. Proxmox): Netzwerk als Bridge in das LAN, nicht per NAT.
  • Bluetooth ist in VMs und Containern meist nicht verfügbar. Dann Weg B nutzen oder einen USB-Bluetooth-Stick durchreichen.

3.5 Thread-Netz auf dem CZC einrichten#

Falls noch kein Thread-Netz besteht: Im Web-GUI des CZC „Form Thread Network“ öffnen.

Das Formular ist mit Standardwerten vorbelegt. Ersetze sie durch eigene, zufällige Werte:

openssl rand -hex 16   # Network Key
openssl rand -hex 8    # Extended PAN ID

Vergib außerdem einen eigenen Netzwerknamen und forme das Netz. Danach muss der CZC die Rolle leader anzeigen.

3.6 Dataset exportieren#

Das Dataset wird im Web-GUI nicht angezeigt, lässt sich aber per REST abrufen:

curl -H "Accept: text/plain" http://<CZC-IP>/node/dataset/active

Die Ausgabe ist ein langer Hex-String, beginnend mit 0e08…. Du brauchst ihn zusammen mit dem Netzwerknamen später im Adapter.

🔐 Das Dataset enthält den Netzwerkschlüssel. Behandle es wie ein Passwort.

3.7 Netz prüfen: Kommen die IPv6-Ankündigungen des CZC an?#

Diese Prüfungen laufen auf dem ioBroker-Host (bzw. bei Weg B auf dem Rechner mit chip-tool). Ersetze eth0 ggf. durch den Namen deiner Netzwerkschnittstelle (ip link).

sudo apt install ndisc6 avahi-utils

a) Router Advertisement des CZC abfragen

rdisc6 eth0

Erwartet wird eine Antwort mit der MAC des CZC und darin:

 Prefix                   : fdxx:xxxx:xxxx:xxxx::/64     ← ggf., wenn kein anderer Router ein Präfix verteilt
 Route                    : fdyy:yyyy:yyyy:yyyy::/64     ← das Netz der Thread-Geräte (OMR-Präfix)
 from fe80::…                                            ← Link-Local-Adresse des CZC

Router lifetime: 0 ist korrekt. Der CZC ist kein Standard-Gateway, er routet nur ins Thread-Netz.

b) Route ins Thread-Netz prüfen, das ist die wichtigste Prüfung:

ip -6 route | grep "via fe80"
fdyy:yyyy:yyyy:yyyy::/64 via fe80::… dev eth0 proto ra metric 100 pref medium

c) IPv6-Adresse des Hosts

ip -6 addr show eth0

Es sollte mindestens eine Adresse mit scope global vorhanden sein.

d) CZC per mDNS sichtbar

avahi-browse -art | grep -i meshcop
Ergebnis Bedeutung
rdisc6 antwortet nicht Der CZC sendet keine RAs: Ist er per Ethernet angeschlossen und nach dem Verkabeln neu gestartet? Ist das Thread-Netz geformt? Liegt der Host im selben Segment?
RA kommt an, aber keine Route in ip -6 route Der Host übernimmt die Route nicht, IPv6-Konfiguration des Hosts prüfen
Route vorhanden ✅ Weiter mit Weg A oder B

❗ Ohne die Route aus b) nicht weitermachen. Das Anlernen scheitert sonst spätestens, wenn ioBroker das Gerät nach dem Beitritt über IP erreichen will.


4. Weg A: Anlernen per Bluetooth direkt in ioBroker (empfohlen)#

4.1 Bluetooth am ioBroker-Host#

sudo rfkill unblock bluetooth
bluetoothctl power on
bluetoothctl show | grep Powered      # erwartet: Powered: yes

Bluetooth dauerhaft einschalten, damit es auch nach einem Neustart aktiv ist:

sudo sed -i 's/^#\?AutoEnable=.*/AutoEnable=true/' /etc/bluetooth/main.conf
grep AutoEnable /etc/bluetooth/main.conf   # erwartet: AutoEnable=true

4.2 Matter-Adapter installieren#

In der ioBroker-Admin-Oberfläche unter Adapter nach „Matter“ suchen und installieren (Version ≥ 1.3.1). Der Adapter wird über das ioBroker-Repository installiert, nicht von GitHub.

4.3 Controller einrichten#

  1. Instanz matter.0 öffnen → Tab Controller → Schalter auf On.
  2. BLE COMMISSIONING SETTINGS öffnen und eintragen:
  3. Bluetooth aktivieren, HCI-Index 0
  4. Thread Network Name: Name des Netzes aus 3.5
  5. Thread Operational Dataset: Hex-String aus 3.6 (komplett, ohne Leerzeichen)
  6. WLAN-Felder leer lassen
  7. Speichern. Die Instanz startet neu.

4.4 Prüfen, ob der Controller läuft#

grep "matter.0" /opt/iobroker/log/iobroker.current.log | tail -20
  • ✅ Node controller is online
  • ❌ BLE is not enabled on this platform → Bluetooth prüfen (4.1), dann Instanz neu starten
  • ❌ Failed to start the controller → siehe Fehlertabelle (Abschnitt 7)

4.5 Gerät vorbereiten#

  1. Gerät auf Werkseinstellungen zurücksetzen (siehe Herstelleranleitung).
  2. Gerät in die Nähe des ioBroker-Hosts legen (wenige Meter).

4.6 Gerät anlernen#

  1. Im Controller-Tab auf DISCOVER AND PAIR DEVICES klicken.
  2. Warten, bis das Gerät in der Liste erscheint (per Bluetooth gefunden, als Kennung wird eine MAC-Adresse angezeigt).
  3. Gerät auswählen und den auf dem Gerät aufgedruckten Pairing-Code eingeben (11-stelliger Zahlencode oder QR-Text MT:…).

ℹ️ Der Dialog zeigt eine rote Warnung: „Please DO NOT use the QR code / pairing code that is printed on the Matter device.“ Diese Warnung gilt hier nicht. Sie betrifft Geräte, die bereits in einem anderen System angelernt sind. Nach einem Werksreset ist der aufgedruckte Code der richtige.

ℹ️ Die angezeigte Bluetooth-Adresse ändert sich bei jedem Reset des Geräts. Sie eignet sich nicht zur Wiedererkennung.

ℹ️ Ein QR-Scan ist nicht nötig. Den Zahlencode kannst du einfach abtippen.

4.7 „Unknown error“: erst einmal warten#

Das Anlernen dauert ca. 1 bis 2 Minuten. Die Oberfläche meldet oft schon vorher „Cannot pair device: Unknown error“, obwohl das Anlernen im Hintergrund erfolgreich weiterläuft.

  1. Dialog schließen.
  2. 1–2 Minuten warten.
  3. Geräteliste im Controller-Tab neu laden.

Erst wenn das Gerät dann nicht erscheint, im Log nach der Ursache suchen (Abschnitt 7).

4.8 Erfolg prüfen#

  • Das Gerät erscheint im Controller-Tab unter Commissioned Devices.
  • In der CZC-Topologie (Web-GUI) ist ein neues Child zu sehen.
  • Schalten: Objekte → matter.0 → Gerät → Endpoint (z. B. OnOffPlugInUnit) → Schalt-Datenpunkt auf true/false setzen.

Optional auf dem Host:

avahi-browse -rt _matter._tcp          # Gerät mit Adresse aus dem OMR-Präfix (fdyy:…)
ping -6 -c 3 <Adresse aus avahi-browse>

Diese Warnungen im Log sind normal und kein Fehler:

  • Attestation finding accepted for backward compatibility …
  • Thread network scan returned no results for "…" – attempting connection anyway
  • Using development values for some BasicInformation attributes …

5. Weg B: Anlernen mit chip-tool und Übergabe an ioBroker#

5.0 Wann dieser Weg?#

Wenn der ioBroker-Host kein Bluetooth hat (VM, Docker, Server).

Das Gerät wird zunächst mit chip-tool angelernt, dem Kommandozeilen-Controller aus dem offiziellen Matter-SDK, auf einem Linux-Rechner mit Bluetooth. Anschließend öffnet chip-tool ein Commissioning-Fenster, und ioBroker übernimmt das Gerät ohne Bluetooth, nur über das LAN.

 Linux-Rechner (chip-tool) ── Bluetooth ──► Gerät tritt Thread-Netz bei
 chip-tool öffnet Fenster  ──► ioBroker übernimmt per LAN (Pairing-Code)

5.1 Voraussetzungen#

  • Alle Punkte aus Abschnitt 3 – die Prüfungen aus 3.7 auf dem chip-tool-Rechner und dem ioBroker-Host.
  • Der chip-tool-Rechner liegt im selben Netzwerksegment wie der CZC und hat Bluetooth.
  • mDNS (UDP 5353) in der Firewall des chip-tool-Rechners erlauben, z. B.:
# firewalld (Fedora u. a.)
sudo firewall-cmd --add-service=mdns
# ufw (Ubuntu u. a.)
sudo ufw allow 5353/udp
  • Matter-Adapter in ioBroker installiert, Controller auf On (4.2–4.4). Bluetooth wird dort nicht benötigt.

5.2 chip-tool beschaffen#

  • Snap (am einfachsten, für viele Distributionen verfügbar):
sudo snap install chip-tool

5.3 Produktionszertifikate (PAA) bereitstellen#

chip-tool vertraut standardmäßig nur Test-Zertifikaten. Für echte Geräte brauchst du die Produktions-Wurzelzertifikate, sonst bricht das Anlernen mit Failed Device Attestation ab.

git clone --depth 1 --filter=blob:none --sparse https://github.com/project-chip/connectedhomeip ~/chip-paa
cd ~/chip-paa
git sparse-checkout set credentials/production/paa-root-certs

Pfad für die folgenden Befehle: ~/chip-paa/credentials/production/paa-root-certs

5.4 Gerät anlernen#

Gerät auf Werkseinstellungen zurücksetzen und in die Nähe des chip-tool-Rechners legen. Dann:

mkdir -p ~/chip-storage

chip-tool pairing code-thread 1 hex:<DATASET> <PAIRING-CODE> \
  --paa-trust-store-path ~/chip-paa/credentials/production/paa-root-certs \
  --storage-directory ~/chip-storage
  • 1: Node-ID, die du dem Gerät gibst (frei wählbar)
  • <DATASET>: Hex-String aus 3.6
  • <PAIRING-CODE>: aufgedruckter 11-stelliger Code

Erfolgreich, wenn am Ende steht:

Device commissioning completed with success

ℹ️ Verwende bei allen weiteren chip-tool-Befehlen dasselbe --storage-directory. Dort speichert chip-tool seine Zugangsdaten. Ohne die Option kennt chip-tool das Gerät nicht mehr.

5.5 Testschalten#

chip-tool onoff toggle 1 1 --storage-directory ~/chip-storage
chip-tool onoff read on-off 1 1 --storage-directory ~/chip-storage

Das Muster ist <Node-ID> <Endpoint>. Bei Steckdosen liegt der Schaltausgang meist auf Endpoint 1.

5.6 Commissioning-Fenster für ioBroker öffnen#

chip-tool pairing open-commissioning-window 1 1 900 1000 3840 \
  --storage-directory ~/chip-storage 2>&1 | grep "Manual pairing code"
Wert Bedeutung
1 Node-ID des Geräts
1 Methode: neuer, zufälliger Pairing-Code
900 Fenster bleibt 900 s (15 min) offen
1000 Sicherheitsparameter für die Code-Ableitung (Standardwert)
3840 Kennung, unter der das Gerät im Netz gefunden wird

chip-tool gibt einen neuen Manual Pairing Code aus. Nur dieser gilt für die Übergabe, der aufgedruckte Code funktioniert hier nicht.

5.7 Gerät in ioBroker übernehmen#

  1. Im Controller-Tab auf ADD DEVICE BY PAIRING CODE OR QR CODE klicken.
  2. Den neuen Code aus 5.6 eingeben und auf ADD klicken.
  3. Wie in 4.7: Bei „Unknown error“ 1–2 Minuten warten und die Liste neu laden.

Ist das Fenster abgelaufen, öffne einfach ein neues (5.6). Jedes Fenster hat einen eigenen Code.

5.8 Prüfen#

chip-tool operationalcredentials read fabrics 1 0 --storage-directory ~/chip-storage

Es sollten zwei Fabrics zu sehen sein: chip-tool und ioBroker matter.0. Schalte das Gerät danach sowohl per chip-tool als auch in ioBroker.

5.9 Aufräumen: chip-tool entfernen#

Wenn chip-tool nur zum Anlernen diente, entferne dessen Fabric vom Gerät. Die Fabric von ioBroker bleibt davon unberührt.

chip-tool pairing unpair 1 --storage-directory ~/chip-storage

Anschließend in ioBroker prüfen, dass das Gerät weiterhin schaltet.

ℹ️ Ein über Weg B angelerntes Gerät ist für ioBroker gleichwertig zu einem per Bluetooth angelernten Gerät.


6. Thread-Netz neu formen#

Wird das Thread-Netz auf dem CZC neu geformt, ändert sich das Dataset. Bereits angelernte Geräte kennen dann die neuen Zugangsdaten nicht.

  1. Neues Dataset exportieren (3.6).
  2. Im Adapter unter BLE COMMISSIONING SETTINGS das neue Dataset (und ggf. den neuen Namen) eintragen.
  3. Alle Thread-Geräte auf Werkseinstellungen zurücksetzen und neu anlernen (Weg A oder B).

7. Fehlertabelle#

So siehst du das Log des Adapters:

grep "matter.0" /opt/iobroker/log/iobroker.current.log | tail -50
Symptom / Logmeldung Ursache Lösung
BLE is not enabled on this platform Bluetooth aus oder nicht vorhanden 4.1 ausführen, Instanz neu starten; in VM/Docker: USB-Passthrough oder Weg B
Gerät erscheint nicht bei DISCOVER AND PAIR DEVICES Gerät nicht im Pairing-Modus, zu weit entfernt, Bluetooth aus Werksreset, näher an den Host legen, Bluetooth prüfen
Invalid checksum Pairing-Code falsch abgetippt Code erneut sorgfältig eingeben
„Unknown error“, Gerät erscheint nach kurzer Zeit doch Oberfläche wartet nicht lange genug Kein Fehler, siehe 4.7
„Unknown error“, Gerät erscheint auch nach 2 Minuten nicht Echte Ursache steht im Log Log prüfen, Zeilen dieser Tabelle zuordnen
Kein neues Child in der CZC-Topologie Falsches oder veraltetes Dataset im Adapter Dataset neu exportieren (3.6) und eintragen
Child im CZC vorhanden, aber ioBroker erreicht das Gerät nicht Keine Route ins Thread-Netz oder mDNS blockiert Prüfungen aus 3.7 wiederholen; gleiches Segment? Docker network_mode: host?
Controller instance not yet started Controller aus oder beim Start gescheitert Controller-Schalter auf On, Instanz neu starten, Log auf Failed to start the controller prüfen
Gerät per iPhone/Android-App angelernt, taucht nicht im CZC auf Handy hat sein bevorzugtes Thread-Netz verwendet Siehe Abschnitt 2: Werksreset, dann Weg A oder B
Failed Device Attestation (chip-tool) Produktionszertifikate fehlen --paa-trust-store-path angeben (5.3)
ioBroker findet das Gerät bei Weg B nicht Commissioning-Fenster abgelaufen oder alter Code Neues Fenster öffnen (5.6), neuen Code verwenden

8. Anhang#

Kurzreferenz#

# Netz prüfen
rdisc6 eth0
ip -6 route | grep "via fe80"
avahi-browse -art | grep -i meshcop
avahi-browse -rt _matter._tcp

# Dataset exportieren
curl -H "Accept: text/plain" http://<CZC-IP>/node/dataset/active

# Bluetooth
bluetoothctl show | grep Powered

# ioBroker-Log
grep "matter.0" /opt/iobroker/log/iobroker.current.log | tail -50

Glossar#

Begriff Bedeutung
OMR-Präfix IPv6-Netz, in dem die Thread-Geräte von außerhalb des Funknetzes erreichbar sind
Router Advertisement (RA) IPv6-Nachricht, mit der ein Router Präfixe und Routen im LAN ankündigt
SLAAC Ein Gerät bildet sich seine IPv6-Adresse selbst aus einem angekündigten Präfix
mDNS Namens- und Dienstsuche im lokalen Netz ohne zentralen Server
Fabric Die Mitgliedschaft eines Geräts bei einem Matter-Controller
Commissioning-Fenster Zeitraum, in dem ein Gerät von einem (weiteren) Controller angelernt werden kann