Prerequisites
- Home Assistant Core (venv, Python 3.14)
- Ubuntu Linux (NUC or similar)
- nRF52840 USB dongle (Nordic Semiconductor)
- Android or iPhone with HA Companion App
1. Flash the nRF52840 as OpenThread RCP
Download firmware:
- Firmware:
ot-rcp-USB.hex - Source: GitHub - ArthFink/nrf52840-OpenThread · GitHub (Releases)
Download flashing tool:
- nRF Connect for Desktop:
nrfconnect-5.2.1-x86_64.AppImage - https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-Desktop
Flashing:
- Hold the reset button while inserting the dongle → LED blinks red
- Launch nRF Connect for Desktop → open Programmer
- Select device → load
ot-rcp-USB.hex→ Write
Verify success:
dmesg | grep -i nordic
# Expected output: "ASA Thread Co-Processor"
2. Install OpenThread Border Router (OTBR)
sudo snap install openthread-border-router --beta
Set permissions:
sudo snap connect openthread-border-router:raw-usb
sudo snap connect openthread-border-router:network-control
sudo snap connect openthread-border-router:firewall-control
sudo snap connect openthread-border-router:avahi-control avahi:avahi-control
Find LAN interface:
ip link show
# e.g. enp2s0, eth0, eno1
Configure:
sudo snap set openthread-border-router radio-url="spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800"
sudo snap set openthread-border-router infra-if="enp2s0" # adjust to your LAN interface
sudo snap set openthread-border-router webgui-port=82
sudo snap set openthread-border-router autostart=true
Start:
sudo snap start openthread-border-router
Form a Thread network:
sudo openthread-border-router.ot-ctl dataset init new
sudo openthread-border-router.ot-ctl dataset commit active
sudo openthread-border-router.ot-ctl ifconfig up
sudo openthread-border-router.ot-ctl thread start
Check status:
sudo openthread-border-router.ot-ctl state
# Expected output: leader
Reference: How to set up OpenThread Border Router on Ubuntu - Matter on Ubuntu documentation
3. Install python-matter-server
(Note: in the future, you can install also the new matter-js server)
source ~/homeassistant3.14/bin/activate
pip install "python-matter-server[server]"
Create systemd service:
sudo nano /etc/systemd/system/matter-server.service
Content:
[Unit]
Description=Matter Server
After=network.target
[Service]
User=nuc
ExecStart=/home/nuc/homeassistant3.14/bin/matter-server \
--storage-path /home/nuc/.matter-server \
--port 5580 \
--enable-test-net-dcl \
--paa-root-cert-dir /home/nuc/.matter-server/credentials
Restart=on-failure
[Install]
WantedBy=multi-user.target
Create directory and start service:
mkdir -p /home/nuc/.matter-server
mkdir -p /home/nuc/.matter-server/credentials
sudo systemctl daemon-reload
sudo systemctl enable matter-server
sudo systemctl start matter-server
Check status:
sudo systemctl status matter-server
4. Install HA Integrations
Matter Integration
- Settings → Integrations → + Integration → Matter
- Enter the Matter Server URL:
ws://localhost:5580/ws
OpenThread Border Router Integration
- Settings → Integrations → + Integration → OpenThread Border Router
- Enter the OTBR URL:
http://localhost:8081
5. Sync Thread credentials to phone
Thread credentials must be transferred to the phone before new Matter devices can be commissioned.
Android:
- Open HA Companion App
- Settings → Companion App → Troubleshooting
- Select Sync Thread credentials
iPhone:
- Open HA Companion App
- Settings → Devices & Services → Thread Integration
- Configure → Send credentials to phone
6. Add a new Matter device
- Power up the device → it automatically enters pairing mode
- A pop-up appears on your phone prompting you to scan the QR code
- If no pop-up: Settings → Matter → Add device → Add Matter device
- Select “No, it’s new”
- Scan the QR code on the Matter device
Architecture overview
Matter device (e.g. IKEA sensor)
↕ Thread (802.15.4 radio)
nRF52840 dongle (RCP – radio only)
↕ USB / Spinel protocol
OTBR Snap (Thread stack + IPv6 routing)
↕ LAN / IPv6
python-matter-server (port 5580)
↕ WebSocket
HA Matter Integration
↕
HA entities
Channel recommendations (avoiding interference)
Zigbee, Thread and WiFi all use 2.4 GHz and can interfere with each other.
| Protocol | Recommended channel |
|---|---|
| WiFi | 1 or 6 |
| Zigbee | 15 |
| Thread | 25 or 26 |
Change Thread channel:
sudo openthread-border-router.ot-ctl channel 26
sudo openthread-border-router.ot-ctl dataset commit active
Known issues
No module named 'chip.exceptions'
pip install "python-matter-server[server]"
# instead of just: pip install python-matter-server
OTBR not responding (no response from RCP)
- Check that the correct port is used:
dmesg | grep tty - Add the
uart-init-deassertparameter:
sudo snap set openthread-border-router radio-url="spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800&uart-init-deassert"
sudo snap restart openthread-border-router
Matter device cannot be re-commissioned
- Perform a factory reset on the device (device-specific procedure)
- Then commission again via HA