IKEA Matter Thread-Geräte auf RaspberryPi (docker) commissionen via chip-tool (ohne Smartphone)

Anleitungen / Projekte
,
1

Das Problem

Wer Home Assistant nicht als HAOS betreibt sondern als Container/Core auf einem Raspberry Pi (z.B. DietPi), kennt das Problem: Matter-over-Thread Geräte lassen sich kaum einbinden.

  • python-matter-server (Docker) hat kein BLE → kann Thread-Geräte nicht selbst commissionen

  • Android Companion App findet den Thread Border Router nicht (bekanntes Problem, fehlende Thread-Credentials)

  • iPhone Companion App funktioniert zwar, aber nicht jeder hat ein iPhone

Die Lösung: chip-tool direkt auf dem Raspberry Pi. Das ist das offizielle Matter-Referenz-Tool und kann über das eingebaute Bluetooth des RPi das BLE-Pairing übernehmen.

Getestet mit: IKEA ALPSTUGA Air Quality Monitor auf Raspberry Pi 5 + DietPi + SONOFF Dongle-M (OTBR)

Wie funktioniert Matter Commissioning eigentlich?

Viele stolpern hier, weil Matter Commissioning aus mehreren Phasen besteht:

Schritt 1: BLE-Pairing
   Dein RPi verbindet sich per Bluetooth Low Energy mit dem neuen Gerät.
   → Das ist der Grund warum ein Smartphone/BLE nötig ist.

Schritt 2: Thread-Credentials übergeben
   Der RPi schickt dem Gerät die Thread-Netzwerk-Daten (Network Key, Channel, PAN ID).
   → Das Gerät weiß jetzt wie es ins Thread-Netz kommt.

Schritt 3: Gerät tritt Thread-Netzwerk bei
   Das Gerät verbindet sich mit deinem Thread Border Router.
   → Ab jetzt ist es über IPv6 erreichbar, BLE wird nicht mehr gebraucht.

Schritt 4: Multi-Admin (Fabric-Übergabe)
   chip-tool öffnet ein Commissioning-Fenster auf dem Gerät.
   → Home Assistant kann das Gerät jetzt als zweite "Fabric" übernehmen.

Schritt 5: In HA hinzufügen
   HA's Matter-Server kommuniziert über IPv6/Thread mit dem Gerät.
   → Kein BLE mehr nötig, alles geht über Thread.

Voraussetzungen

Hardware

  • Raspberry Pi mit Bluetooth (RPi 3/4/5 haben alle BLE)

  • Thread Border Router (z.B. SONOFF Dongle-M, SkyConnect, oder SLZB-06 mit OTBR)

  • Funktionierendes Thread-Netzwerk (OTBR muss als “leader” oder “router” laufen)

Software

  • bluez — Bluetooth-Stack (normalerweise vorinstalliert)

  • avahi-daemon — mDNS/DNS-SD Discovery

  • snapd — Snap Package Manager (für chip-tool)

  • OTBR Docker Container mit REST API

  • python-matter-server Docker Container

  • Home Assistant mit Matter-Integration

:warning: KRITISCH: IPv6 Forwarding

Docker resettet net.ipv6.conf.all.forwarding beim Start auf 0. Ohne IPv6 Forwarding kann der OTBR keine Thread-Pakete ins lokale Netz routen → kein Matter-Gerät ist erreichbar.

Prüfen:

sysctl net.ipv6.conf.all.forwarding    # MUSS 1 sein!
sysctl net.ipv6.conf.eth0.accept_ra    # MUSS 2 sein!

Dauerhaft fixen — eigener systemd-Service der NACH Docker läuft:

cat > /etc/systemd/system/ipv6-forwarding.service << 'EOF'
[Unit]
Description=Enable IPv6 Forwarding (after Docker)
After=docker.service
Wants=docker.service

[Service]
Type=oneshot
ExecStart=/sbin/sysctl -w net.ipv6.conf.all.forwarding=1
ExecStart=/sbin/sysctl -w net.ipv6.conf.eth0.accept_ra=2
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now ipv6-forwarding.service

Hinweis: sysctl.conf allein reicht NICHT, weil Docker nach systemd-sysctl startet und den Wert wieder auf 0 setzt.

Installation

chip-tool via Snap installieren

# Snap installieren (falls noch nicht vorhanden)
apt update && apt install -y snapd
reboot

# Nach dem Reboot: chip-tool installieren
snap install chip-tool

# BLE-Interface verbinden
snap connect chip-tool:bluez
snap connect chip-tool:process-control

# PATH ergänzen (damit chip-tool ohne /snap/bin/ Prefix funktioniert)
echo 'export PATH=$PATH:/snap/bin' >> ~/.bashrc
source ~/.bashrc

Prüfen ob alles funktioniert

# Bluetooth muss UP RUNNING sein
hciconfig hci0

# chip-tool muss antworten
chip-tool pairing

# OTBR muss "leader" sein
curl -s http://localhost:8081/node/state

# Thread-Dataset muss abrufbar sein
curl -s -H 'Accept: text/plain' http://localhost:8081/node/dataset/active

Schritt-für-Schritt: Neues Thread-Gerät einbinden

Schritt 1: Gerät in Pairing-Modus bringen

Je nach Hersteller:

  • IKEA: Reset-Knopf 5–10 Sekunden drücken (LED blinkt)

  • Xiaomi: In der Hersteller-App “Matter” aktivieren

  • Allgemein: Handbuch checken, meist gibt es einen Reset-Button

:warning: Das Gerät muss in BLE-Reichweite des RPi sein. Für das erste Pairing am besten < 3 Meter. Der Pairing-Modus läuft nach 2–5 Minuten ab!

Schritt 2: Pairing-Code bereithalten

Steht auf dem Gerät oder der Verpackung als Matter-Code.

Manueller Pairing-Code (11 Ziffern, Format: XXXX-XXX-XXXX):

Beispiel: 2019-184-0351

QR-Code String (fängt mit MT: an):

Beispiel: MT:Y3.13OTB00KA0648G00

Optional kannst du den Code parsen um PIN und Discriminator zu sehen:

chip-tool payload parse-setup-payload 20191840351
# → Short discriminator: 8
# → Passcode:            66111358

Schritt 3: Thread-Dataset vom OTBR holen

DATASET=$(curl -s -H 'Accept: text/plain' http://localhost:8081/node/dataset/active)
echo $DATASET

Das Dataset enthält alle Credentials deines Thread-Netzwerks. Du brauchst es für den nächsten Schritt.

Schritt 4: Commissioning starten

chip-tool pairing code-thread <NODE_ID> hex:$DATASET <PAIRING_CODE> \
  --bypass-attestation-verifier true \
  --timeout 120

Konkretes Beispiel:

chip-tool pairing code-thread 100 \
  hex:$(curl -s -H 'Accept: text/plain' http://localhost:8081/node/dataset/active) \
  20191840351 \
  --bypass-attestation-verifier true \
  --timeout 120

<NODE_ID> = beliebige Nummer die du dem Gerät in chip-tool zuweist (z.B. 100, 101, 102…).

Wichtige Flags:

Flag Warum
code-thread Statt ble-thread! Handhabt Short/Long Discriminator automatisch
--bypass-attestation-verifier true Nötig für IKEA und die meisten Consumer-Geräte
--timeout 120 Gibt dem Gerät genug Zeit für den Thread-Join

Erfolg:

[TOO] Pairing Success
[CTL] Successfully finished commissioning step 'ReadCommissioningInfo'
[CTL] Successfully finished commissioning step 'ArmFailSafe'
[CTL] Successfully finished commissioning step 'ConfigRegulatory'
[CTL] Successfully finished commissioning step 'SendTrustedRootCert'
[CTL] Successfully finished commissioning step 'SendNOC'
[CTL] Successfully finished commissioning step 'ThreadNetworkEnable'
[CTL] Commissioning complete

Schritt 5: Gerät verifizieren (optional)

chip-tool basicinformation read product-name <NODE_ID> 0
# → ProductName: ALPSTUGA air quality monitor

Schritt 6: Commissioning-Fenster für HA öffnen

chip-tool hat das Gerät jetzt auf seiner eigenen Fabric. HA braucht ein offenes Commissioning-Fenster um es als zweite Fabric zu übernehmen (Multi-Admin):

chip-tool administratorcommissioning open-basic-commissioning-window 600 \
  <NODE_ID> 0 \
  --timedInteractionTimeoutMs 5000

600 = Fenster bleibt 10 Minuten offen. --timedInteractionTimeoutMs 5000 ist Pflicht!

Schritt 7: In Home Assistant hinzufügen

  1. HA → Settings → Devices & Services → Matter

  2. “Add Device” klicken

  3. “Already in use” wählen (Gerät ist schon auf chip-tool’s Fabric)

  4. Pairing-Code eingeben (z.B. 2019-184-0351)

  5. Warten — HA findet das Gerät über IPv6/Thread (kein BLE mehr nötig!)

  6. Fertig! Gerät erscheint mit allen Sensoren und Controls

Fehlerbehebung

“BLE Scan findet kein Gerät” / Timeout

Scan complete. No matching device found.

  • Gerät wirklich im Pairing-Modus? LED muss blinken

  • Näher an den RPi bringen (< 1 Meter zum Testen)

  • Pairing-Modus abgelaufen → Reset-Knopf nochmal drücken

  • Bluetooth prüfen: hciconfig hci0 → muss “UP RUNNING” zeigen

  • Scan testen: bluetoothctl scan on → Gerät sollte auftauchen

“Failed Device Attestation”

CHIP Error 0x00000020: Failed Device Attestation

Lösung: --bypass-attestation-verifier true hinzufügen. Ist normal für Consumer-Geräte — deren Zertifikate sind nicht in chip-tool’s Trust-Store.

“Device discriminator does not match”

Skip connection: Device discriminator does not match: 2233 != 8

Lösung: code-thread statt ble-thread verwenden! ble-thread erwartet den langen Discriminator (12 Bit), der manuelle Pairing-Code enthält aber nur den kurzen (4 Bit). code-thread rechnet automatisch um.

“NEEDS_TIMED_INTERACTION”

IM Error 0x000005C6: General error: 0xc6 (NEEDS_TIMED_INTERACTION)

Lösung: --timedInteractionTimeoutMs 5000 zum Befehl hinzufügen.

“HA findet das Gerät nicht bei Add Device”

  • Commissioning-Fenster noch offen? Läuft nach 10 Min ab → nochmal Schritt 6

  • IPv6 Forwarding prüfen! sysctl net.ipv6.conf.all.forwarding → muss 1 sein!

  • OTBR läuft? docker ps | grep otbr

  • Matter Server läuft? docker ps | grep matter

“IPv6 Forwarding ist 0 nach Reboot”

Docker resettet es. Siehe oben den ipv6-forwarding.service Fix.

Das war bei mir DER Fehler. Alles sah richtig aus, OTBR war “leader”, Thread-Netzwerk existierte — aber ohne IPv6 Forwarding kann der Border Router die Pakete nicht routen. Geräte wurden per BLE gepairt, traten dem Thread-Netz bei, waren aber nicht erreichbar. Hat mich Wochen gekostet.

Nützliche Befehle

# Thread-Netzwerk Status
docker exec otbr ot-ctl state              # → "leader"
docker exec otbr ot-ctl router table       # → Liste der Router
docker exec otbr ot-ctl child table        # → Liste der Sleepy End Devices

# Thread-Dataset
curl -s -H 'Accept: text/plain' http://localhost:8081/node/dataset/active

# Gerät nach Commissioning abfragen
chip-tool basicinformation read product-name <NODE_ID> 0
chip-tool basicinformation read vendor-name <NODE_ID> 0

# chip-tool komplett zurücksetzen (bei Problemen)
rm -rf /root/snap/chip-tool/common/chip_tool_kvs /tmp/chip_*.ini

Mein Setup

Komponente Details
Raspberry Pi RPi 5, 8 GB RAM, DietPi v9.17 (Debian Trixie)
Thread Border Router SONOFF Dongle-M (EFR32MG24, Thread RCP), OTBR Docker (bnutzer/otbr-tcp)
Matter Server ghcr.io/home-assistant-libs/python-matter-server:stable (Docker)
Home Assistant 2025.10.1 (venv, systemd Service)
Bluetooth BCM4345C0 (onboard RPi 5), BlueZ 5.82
chip-tool v1.5.0.1 (Snap)
Thread-Netzwerk OpenThread, Channel 24
Erstes Gerät IKEA ALPSTUGA Air Quality Monitor (CO2, PM2.5, Temp, Humidity)

Fazit

Mit chip-tool auf dem RPi kann man Matter-Thread-Geräte komplett ohne Smartphone einbinden. Die Installation dauert 5 Minuten (Snap), das Commissioning selbst ca. 2 Minuten pro Gerät.

Die größte Falle ist IPv6 Forwarding — Docker killt es bei jedem Boot. Der systemd-Service-Fix oben löst das dauerhaft.

Hoffe das hilft jemandem, der genauso lange daran verzweifelt ist wie ich!

image
image1020×864 76.4 KB

1 „Gefällt mir“
2

Update: Ich habe mir mit Claude Code eine kleine Integration gebaut, mit der man IKEA Matter-Geräte in wenigen Sekunden commissionen kann — komplett ohne Smartphone (oder mit smartphone HA web, companion app)

So geht’s:

  1. Gerät in Pairing-Modus versetzen

  2. Neben den Raspberry Pi legen

  3. Im HA-Dashboard den Code vom Gerät eingeben

  4. Button drücken — fertig!

Das Ganze läuft über chip-tool (Snap) auf dem RPi, der das BLE-Pairing übernimmt und das Gerät automatisch ins Thread-Netz bringt und in HA einbindet. Kein iPhone, kein Android nötig.

Getestet mit IKEA ALPSTUGA (Luftqualität) und MYGGBETT (Tür/Fenster).

Bonus-Erkenntnis: Bei mir war wochenlang IPv6 Forwarding kaputt (Docker resettet es bei jedem Boot) — das war der eigentliche Grund warum nichts funktioniert hat. Falls bei euch auch Thread-Geräte nicht erreichbar sind: sysctl net.ipv6.conf.all.forwarding prüfen!

Das Ganze geht natürlich auch bequem über die HA Companion App auf dem Handy — Code eingeben, Button drücken, vom Sofa aus commissionen. Das Gerät muss nur neben dem RPi liegen.

Wer mehr wissen will oder die Dateien haben möchte — gerne per PM!

image
image1536×2048 187 KB

image
image1440×754 53.4 KB

image
image1152×2048 104 KB

1 „Gefällt mir“