This comprehensive guide walks you through setting up a self-hosted OpenThread Border Router (OTBR) alongside a Matter server using Docker on a Linux/Home Assistant host. It covers host IPv6 configuration, hardware identification, container deployment, Home Assistant integration, and thread credential syncing for mobile devices.

Hardware Used

  • Coordinator / Radio: SONOFF ZBDongle-E (EFR32MG21-based USB Dongle, flashed with OpenThread RCP firmware). Note that even though it appears in /dev/serial/by-id/ with a Plus_V2 identifier string, it is the ZBDongle-E model in my case.

Step 1: Configure Host IPv6 Support (Mandatory)

Thread and Matter rely entirely on IPv6 mesh networking. Your host system must have IPv6 forwarding and Router Advertisement (RA) acceptance enabled.

1. Apply Settings Immediately

Run these commands in your host terminal:

sudo sysctl -w net.ipv6.conf.all.disable_ipv6=0
sudo sysctl -w net.ipv6.conf.all.forwarding=1
sudo sysctl -w net.ipv6.conf.default.forwarding=1
sudo sysctl -w net.ipv6.conf.all.accept_ra=2
sudo sysctl -w net.ipv6.conf.all.accept_ra_rt_info_max_plen=64

2. Make Settings Permanent (Survive Reboots)

Create a sysctl configuration file:

sudo tee /etc/sysctl.d/99-otbr-ipv6.conf <<EOF
net.ipv6.conf.all.disable_ipv6=0
net.ipv6.conf.all.forwarding=1
net.ipv6.conf.default.forwarding=1
net.ipv6.conf.all.accept_ra=2
net.ipv6.conf.all.accept_ra_rt_info_max_plen=64
EOF

Reload the configuration:

sudo sysctl --system

3. Verify IPv6

  • Check forwarding (should return 1):

    sysctl net.ipv6.conf.all.forwarding
    
  • Check interface addresses (replace enp1s0 with your network interface name):

    ip -6 addr show dev enp1s0
    

Step 2: Identify Your Environment Settings

Before writing your configuration files, find your specific system paths and interface names:

  1. Find Your Network Interface (OT_INFRA_IF): Run ip link or ip route show default and note your active primary network interface name (e.g., enp1s0, eth0, eno1).

  2. Find Your USB Dongle Serial Path: Plug in your Sonoff dongle and run:

    ls -l /dev/serial/by-id/
    

    Copy the persistent symlink pointing to your adapter (e.g., usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_...-if00-port0).

Step 3: Create Configuration Files

1. Create otbr-env.list

Define your infrastructure interface and RCP device string:

OT_RCP_DEVICE=spinel+hdlc+uart:///dev/radio?uart-baudrate=460800
OT_INFRA_IF=enp1s0

2. Create docker-compose.yml

Set up the Docker compose stack for both the OpenThread Border Router and the Matter server:

YAML

services:
  otbr:
    image: openthread/border-router:latest
    container_name: otbr
    restart: unless-stopped
    network_mode: host
    privileged: true
    cap_add:
      - NET_ADMIN
      - NET_RAW
    environment:
      - OT_WEB_LISTEN_PORT=8050
      - OT_WEB_LISTEN_ADDR=0.0.0.0
    env_file:
      - otbr-env.list
    volumes:
      - /dev/net/tun:/dev/net/tun
      - ./otbr-data:/data
    devices:
      - /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_38875f584b91f01196d2b97629b3d7e9-if00-port0:/dev/radio

  matterjs-server:
    container_name: matterjs-server
    image: ghcr.io/matter-js/matterjs-server:latest
    read_only: true
    environment:
      - LISTEN_ADDRESS=127.0.0.1
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./matterjs-data:/data

Step 4: Deploy and Verify Containers

  1. Start the stack in detached mode:

    docker compose up -d
    
  2. Access the OTBR Web Management UI in your browser at port 8050:http://<your-host-ip>:8050

Step 5: Home Assistant Integration & Credential Syncing

1.Discover OTBR in Home Assistant:

Because the container runs in host network mode with mDNS advertising, Home Assistant will automatically detect the Border Router. Go to Settings > Devices & Services and click Configure on the discovered Thread / OTBR integration banner.

2.Sync Thread Credentials to Mobile Devices:

To allow your phone, Home Assistant Companion App, or other border routers (like Apple TV or Nest Hub) to commission Matter devices, they must share the identical Thread operational dataset:

  • Open the Home Assistant Companion App on your iOS or Android device.

  • Go to Settings > Companion App > Troubleshooting (or Thread settings) and choose Sync Thread credentials to pull/push the dataset to your mobile ecosystem keyring (Apple Keychain / Google Play Services).

  • Verify that the active dataset hash in Home Assistant matches the network details visible in your OTBR Web UI (http://<your-host-ip>:8050).

3.Commission Matter-over-Thread Devices:

With credentials synchronized across your network and mobile devices, put your Matter-over-Thread hardware into pairing mode and add it directly via Home Assistant (Settings > Devices & Services > Add Integration > Matter).

Neuen Kommentar hinzufügen

Klartext

  • Keine HTML-Tags erlaubt.
  • Zeilenumbrüche und Absätze werden automatisch erzeugt.
  • Website- und E-Mail-Adressen werden automatisch in Links umgewandelt.
CAPTCHA
This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.