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) ──────────┘
- ioBroker verbindet sich beim Anlernen per Bluetooth direkt mit dem Gerät.
- Darüber bekommt das Gerät den „Schlüssel“ zum Thread-Netz des CZC (das Dataset).
- Das Gerät tritt per Funk dem Thread-Netz bei. Der CZC ist die Brücke ins LAN.
- 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: hostbetreiben, 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:
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:
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).
a) Router Advertisement des CZC abfragen
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:
c) IPv6-Adresse des Hosts
Es sollte mindestens eine Adresse mit scope global vorhanden sein.
d) CZC per mDNS sichtbar
| 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#
- Instanz
matter.0öffnen → Tab Controller → Schalter auf On. - BLE COMMISSIONING SETTINGS öffnen und eintragen:
- Bluetooth aktivieren, HCI-Index
0 - Thread Network Name: Name des Netzes aus 3.5
- Thread Operational Dataset: Hex-String aus 3.6 (komplett, ohne Leerzeichen)
- WLAN-Felder leer lassen
- Speichern. Die Instanz startet neu.
4.4 Prüfen, ob der Controller läuft#
- ✅
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#
- Gerät auf Werkseinstellungen zurücksetzen (siehe Herstelleranleitung).
- Gerät in die Nähe des ioBroker-Hosts legen (wenige Meter).
4.6 Gerät anlernen#
- Im Controller-Tab auf DISCOVER AND PAIR DEVICES klicken.
- Warten, bis das Gerät in der Liste erscheint (per Bluetooth gefunden, als Kennung wird eine MAC-Adresse angezeigt).
- 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.
- Dialog schließen.
- 1–2 Minuten warten.
- 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 auftrue/falsesetzen.
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 anywayUsing 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):
- Selbst bauen: Siehe die Anleitung im offiziellen Repository https://github.com/project-chip/connectedhomeip.
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:
ℹ️ 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#
- Im Controller-Tab auf ADD DEVICE BY PAIRING CODE OR QR CODE klicken.
- Den neuen Code aus 5.6 eingeben und auf ADD klicken.
- 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#
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.
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.
- Neues Dataset exportieren (3.6).
- Im Adapter unter BLE COMMISSIONING SETTINGS das neue Dataset (und ggf. den neuen Namen) eintragen.
- Alle Thread-Geräte auf Werkseinstellungen zurücksetzen und neu anlernen (Weg A oder B).
7. Fehlertabelle#
So siehst du das Log des Adapters:
| 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 |