Commissioning Thread Devices in ioBroker (Matter over Thread using the new CZC Firmware)#
This guide shows how to add Matter-over-Thread devices (e.g. plugs, sensors) to ioBroker using the CZC as the Thread Border Router.
At the end, the device is part of the CZC's Thread network and can be controlled from ioBroker.
There are two ways:
| Method | When? |
|---|---|
| A – BLE directly in ioBroker (recommended) | The ioBroker host has Bluetooth (e.g. Raspberry Pi) |
| B – chip-tool + handover to ioBroker | The ioBroker host has no Bluetooth (e.g. VM, Docker, server) |
Tested with ioBroker.matter 1.3.1 on Debian 13 / Raspberry Pi OS.
1. What happens during commissioning#
ioBroker ──── LAN (IPv6) ──── CZC ~~~~ Thread radio ~~~~ Device
│ ▲
└──────────── Bluetooth (only while commissioning) ────┘
- During commissioning, ioBroker connects to the device via Bluetooth.
- Over that link, the device receives the "key" to the CZC's Thread network (the dataset).
- The device joins the Thread network over the radio. The CZC bridges it into your LAN.
- From then on, ioBroker talks to the device over the LAN (IPv6); Bluetooth is no longer needed.
Three terms used in this guide:
- Thread dataset: All credentials of the Thread network in one hex string (name, channel, network key …).
- Border Router: Connects the Thread radio network to your LAN. That's the CZC.
- Fabric: A device's "membership" with a Matter controller. A device can belong to several controllers at once.
2. Why commissioning via phone apps often fails#
Smartphone ecosystems use their own preferred Thread network when commissioning, not the CZC's.
- Apple (iPhone/iPad): iOS handles Bluetooth and Thread provisioning itself and gives the device the credentials of the Apple Thread network (HomePod, Apple TV). The dataset configured in the ioBroker adapter is not used. This also applies when commissioning through the ioBroker VISU app on iOS.
- Android / Google Home: Similar behavior with their own Thread credentials; results vary a lot between phones.
As a result, the device ends up in the wrong Thread network, doesn't show up on the CZC, or can't be reached by ioBroker.
Recommendation: Do not commission Thread devices for the CZC via a phone app. Use method A or method B instead.
3. Common prerequisites (for methods A and B)#
3.1 Connect the CZC via Ethernet#
The CZC must be connected with a LAN cable. Border routing over Wi-Fi is currently not supported.
Restart the CZC after plugging in the cable so that Ethernet is used as its LAN connection.
3.2 Same network segment#
The ioBroker host and the CZC must be in the same LAN / VLAN, with no router in between. The CZC announces its routes and services via link-local multicast (router advertisements, mDNS), which only reaches devices in the same segment. IPv4 connectivity alone is not enough.
3.3 IPv6 on the ioBroker host#
IPv6 must not be disabled on the host, and the host must accept router advertisements. On Debian / Raspberry Pi OS with NetworkManager this is the default (ipv6.method auto).
3.4 Note on Docker and VMs#
- Docker: Run the container with
network_mode: host, otherwise mDNS and router advertisements won't reach it. - VM (e.g. Proxmox): Attach the network as a bridge to the LAN, not via NAT.
- Bluetooth is usually not available in VMs and containers. Use method B, or pass through a USB Bluetooth dongle.
3.5 Set up the Thread network on the CZC#
If there is no Thread network yet: open "Form Thread Network" in the CZC web UI.
The form is pre-filled with default values. Replace them with your own random values:
Choose your own network name as well and form the network. Afterwards the CZC must show the role leader.
3.6 Export the dataset#
The dataset is not shown in the web UI, but you can retrieve it via REST:
The output is a long hex string starting with 0e08…. You'll need it, together with the network name, in the adapter later.
🔐 The dataset contains the network key. Treat it like a password.
3.7 Check the network: do the CZC's IPv6 announcements arrive?#
Run these checks on the ioBroker host (for method B, also on the machine running chip-tool). Replace eth0 with the name of your network interface if needed (ip link).
a) Request a router advertisement from the CZC
Expect a response from the CZC's MAC address containing:
Prefix : fdxx:xxxx:xxxx:xxxx::/64 ← only if no other router provides a prefix
Route : fdyy:yyyy:yyyy:yyyy::/64 ← the network of the Thread devices (OMR prefix)
from fe80::… ← the CZC's link-local address
Router lifetime: 0 is correct. The CZC is not a default gateway; it only routes into the Thread network.
b) Check the route into the Thread network, the most important check:
c) The host's IPv6 address
There should be at least one address with scope global.
d) CZC visible via mDNS
| Result | Meaning |
|---|---|
rdisc6 gets no response |
The CZC isn't sending RAs: is it connected via Ethernet and restarted after cabling? Is the Thread network formed? Is the host in the same segment? |
RA arrives, but no route in ip -6 route |
The host doesn't install the route; check the host's IPv6 configuration |
| Route present | ✅ Continue with method A or B |
❗ Do not continue without the route from b). Commissioning will otherwise fail at the latest when ioBroker tries to reach the device over IP after it has joined.
4. Method A: Commissioning via Bluetooth directly in ioBroker (recommended)#
4.1 Bluetooth on the ioBroker host#
sudo rfkill unblock bluetooth
bluetoothctl power on
bluetoothctl show | grep Powered # expected: Powered: yes
Enable Bluetooth permanently so it stays on after a reboot:
sudo sed -i 's/^#\?AutoEnable=.*/AutoEnable=true/' /etc/bluetooth/main.conf
grep AutoEnable /etc/bluetooth/main.conf # expected: AutoEnable=true
4.2 Install the Matter adapter#
In the ioBroker admin UI, go to Adapters, search for "Matter" and install it (version ≥ 1.3.1). The adapter is installed from the ioBroker repository, not from GitHub.
4.3 Configure the controller#
- Open instance
matter.0→ Controller tab → switch to On. - Open BLE COMMISSIONING SETTINGS and enter:
- Enable Bluetooth, HCI index
0 - Thread Network Name: the network name from 3.5
- Thread Operational Dataset: the hex string from 3.6 (complete, no spaces)
- Leave the Wi-Fi fields empty
- Save. The instance restarts.
4.4 Check that the controller is running#
- ✅
Node controller is online - ❌
BLE is not enabled on this platform→ check Bluetooth (4.1), then restart the instance - ❌
Failed to start the controller→ see the troubleshooting table (section 7)
4.5 Prepare the device#
- Factory reset the device (see the manufacturer's instructions).
- Place the device close to the ioBroker host (a few meters).
4.6 Commission the device#
- In the Controller tab, click DISCOVER AND PAIR DEVICES.
- Wait until the device shows up in the list (found via Bluetooth, shown with a MAC address as identifier).
- Select the device and enter the pairing code printed on the device (11-digit numeric code or the QR text
MT:…).
ℹ️ The dialog shows a red warning: "Please DO NOT use the QR code / pairing code that is printed on the Matter device." This warning does not apply here. It refers to devices already commissioned in another system. After a factory reset, the printed code is the correct one.
ℹ️ The Bluetooth address shown changes with every reset of the device. Don't rely on it to identify the device.
ℹ️ No QR scan needed. You can simply type in the numeric code.
4.7 "Unknown error": wait first#
Commissioning takes about 1–2 minutes. The UI often reports "Cannot pair device: Unknown error" before that, even though commissioning continues successfully in the background.
- Close the dialog.
- Wait 1–2 minutes.
- Reload the device list in the Controller tab.
Only if the device still doesn't appear, check the log for the cause (section 7).
4.8 Verify#
- The device appears in the Controller tab under Commissioned Devices.
- The CZC topology (web UI) shows a new child.
- Switching: Objects →
matter.0→ device → endpoint (e.g.OnOffPlugInUnit) → set the switch state totrue/false.
Optionally on the host:
avahi-browse -rt _matter._tcp # device with an address from the OMR prefix (fdyy:…)
ping -6 -c 3 <address from avahi-browse>
These log warnings are normal and not errors:
Attestation finding accepted for backward compatibility …Thread network scan returned no results for "…" – attempting connection anywayUsing development values for some BasicInformation attributes …
5. Method B: Commissioning with chip-tool and handover to ioBroker#
5.0 When to use this method#
When the ioBroker host has no Bluetooth (VM, Docker, server).
The device is first commissioned with chip-tool, the command-line controller from the official Matter SDK, on a Linux machine with Bluetooth. chip-tool then opens a commissioning window, and ioBroker takes over the device without Bluetooth, over the LAN only.
Linux machine (chip-tool) ── Bluetooth ──► device joins the Thread network
chip-tool opens a window ──► ioBroker takes over via LAN (pairing code)
5.1 Prerequisites#
- Everything from section 3 – run the checks from 3.7 on both the chip-tool machine and the ioBroker host.
- The chip-tool machine is in the same network segment as the CZC and has Bluetooth.
- Allow mDNS (UDP 5353) in the chip-tool machine's firewall, e.g.:
# firewalld (Fedora etc.)
sudo firewall-cmd --add-service=mdns
# ufw (Ubuntu etc.)
sudo ufw allow 5353/udp
- Matter adapter installed in ioBroker, controller switched On (4.2–4.4). Bluetooth is not needed there.
5.2 Get chip-tool#
- Snap (easiest, available for many distributions):
- Build it yourself: see the instructions in the official repository https://github.com/project-chip/connectedhomeip.
5.3 Provide production certificates (PAA)#
By default, chip-tool only trusts test certificates. Real devices need the production root certificates, otherwise commissioning aborts with Failed Device Attestation.
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
Path for the following commands: ~/chip-paa/credentials/production/paa-root-certs
5.4 Commission the device#
Factory reset the device and place it close to the chip-tool machine. Then:
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 you assign to the device (any number)<DATASET>: hex string from 3.6<PAIRING-CODE>: the printed 11-digit code
Successful if the output ends with:
ℹ️ Use the same
--storage-directoryfor all following chip-tool commands. chip-tool stores its credentials there; without it, chip-tool won't know the device anymore.
5.5 Test switching#
chip-tool onoff toggle 1 1 --storage-directory ~/chip-storage
chip-tool onoff read on-off 1 1 --storage-directory ~/chip-storage
The pattern is <node ID> <endpoint>. For plugs, the switched output is usually on endpoint 1.
5.6 Open a commissioning window for ioBroker#
chip-tool pairing open-commissioning-window 1 1 900 1000 3840 \
--storage-directory ~/chip-storage 2>&1 | grep "Manual pairing code"
| Value | Meaning |
|---|---|
1 |
Node ID of the device |
1 |
Method: new, random pairing code |
900 |
The window stays open for 900 s (15 min) |
1000 |
Security parameter for deriving the code (default value) |
3840 |
Identifier the device is discovered by on the network |
chip-tool prints a new manual pairing code. Only this code is valid for the handover; the printed code does not work here.
5.7 Add the device to ioBroker#
- In the Controller tab, click ADD DEVICE BY PAIRING CODE OR QR CODE.
- Enter the new code from 5.6 and click ADD.
- As in 4.7: on "Unknown error", wait 1–2 minutes and reload the list.
If the window has expired, simply open a new one (5.6). Each window has its own code.
5.8 Verify#
You should see two fabrics: chip-tool and ioBroker matter.0. Then switch the device both via chip-tool and in ioBroker.
5.9 Clean up: remove chip-tool#
If chip-tool was only used for commissioning, remove its fabric from the device. ioBroker's fabric is not affected.
Then check in ioBroker that the device still switches.
ℹ️ A device commissioned via method B is equivalent for ioBroker to one commissioned via Bluetooth.
6. Re-forming the Thread network#
If the Thread network on the CZC is re-formed, the dataset changes. Devices that were already commissioned don't know the new credentials.
- Export the new dataset (3.6).
- Enter the new dataset (and the new name, if changed) in the adapter under BLE COMMISSIONING SETTINGS.
- Factory reset all Thread devices and commission them again (method A or B).
7. Troubleshooting#
How to view the adapter log:
| Symptom / log message | Cause | Fix |
|---|---|---|
BLE is not enabled on this platform |
Bluetooth off or not available | Run 4.1, restart the instance; in VM/Docker: USB passthrough or method B |
| Device doesn't appear in DISCOVER AND PAIR DEVICES | Device not in pairing mode, too far away, Bluetooth off | Factory reset, move closer to the host, check Bluetooth |
Invalid checksum |
Pairing code mistyped | Re-enter the code carefully |
| "Unknown error", but the device appears shortly after | The UI doesn't wait long enough | Not an error, see 4.7 |
| "Unknown error", device still missing after 2 minutes | The real cause is in the log | Check the log, match the lines to this table |
| No new child in the CZC topology | Wrong or outdated dataset in the adapter | Re-export the dataset (3.6) and enter it again |
| Child present on the CZC, but ioBroker can't reach the device | No route into the Thread network or mDNS blocked | Repeat the checks from 3.7; same segment? Docker network_mode: host? |
Controller instance not yet started |
Controller off or failed to start | Switch the controller On, restart the instance, check the log for Failed to start the controller |
| Device commissioned via iPhone/Android app, doesn't show up on the CZC | The phone used its preferred Thread network | See section 2: factory reset, then method A or B |
Failed Device Attestation (chip-tool) |
Production certificates missing | Pass --paa-trust-store-path (5.3) |
| ioBroker doesn't find the device in method B | Commissioning window expired or old code used | Open a new window (5.6), use the new code |
8. Appendix#
Quick reference#
# Check the network
rdisc6 eth0
ip -6 route | grep "via fe80"
avahi-browse -art | grep -i meshcop
avahi-browse -rt _matter._tcp
# Export the dataset
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
Glossary#
| Term | Meaning |
|---|---|
| OMR prefix | IPv6 network in which Thread devices are reachable from outside the radio network |
| Router advertisement (RA) | IPv6 message a router uses to announce prefixes and routes on the LAN |
| SLAAC | A device builds its own IPv6 address from an announced prefix |
| mDNS | Name and service discovery on the local network without a central server |
| Fabric | A device's membership with a Matter controller |
| Commissioning window | Time span in which a device can be commissioned by an (additional) controller |