OpenThread Border Router (OTBR)

Overview

The OpenThread Border Router (OTBR) provides connectivity between the Thread network and the infrastructure network (Ethernet/Wi-Fi). It allows Matter-over-Thread devices to communicate with Home Assistant and the internet.

In this homelab, we use the native NixOS service for OTBR. It manages a SONOFF Dongle Max (Dongle-M) connected via USB.

Hardware Configuration

• Controller: SONOFF Dongle Max (Dongle-M)
• Mode: Thread RCP (Radio Co-Processor)
• Connection: USB (Serial)
• Device Path: /dev/serial/by-id/usb-SONOFF_SONOFF_Dongle_Max_MG24_...

[!WARNING] If the dongle is in Thread RCP mode, it cannot be used for Zigbee at the same time. Ensure Zigbee2MQTT uses a different radio.

Architecture

The OTBR service consists of two main components:

1. otbr-agent: The core service that manages the Thread radio and the wpan0 virtual interface.
2. otbr-web: A web-based dashboard for managing the Thread network (Join, Form, Status).

Network Integration

The OTBR is connected to the Eero network (via the host’s enp1s0 interface). This allows it to participate in a larger Thread mesh with Alexa and Eero devices.

Ports & Access

Service	Port	Access
Web UI	8091	http://nixos.local:8091 or https://otbr-home.javiersc.com
REST API	8081	Internal use

NixOS Configuration

The service is defined in modules/nixos/services/open-thread-border-router.nix.

services.openthread-border-router = {
  enable = true;
  backboneInterfaces = [ "enp1s0" ];
  radio = {
    device = "/dev/serial/by-id/usb-SONOFF_SONOFF_Dongle_Max_MG24_...";
    baudRate = 115200;
  };
};

Troubleshooting

Failed to secure wpan0 / File exists

This error occurs if systemd-networkd tries to manage the wpan0 interface before the OTBR agent. Fix: Ensure systemd.network.networks."99-wpan0".linkConfig.Unmanaged = true; is set in modules/nixos/system/network.nix.

Web UI is inaccessible

If the web UI is not responding:

1. Verify the service is running: systemctl status openthread-border-router.
2. Check the firewall: The service automatically opens the necessary ports (8091, 8081) for the local network.
3. Ensure you are on the Eero network.

Checking Logs

sudo journalctl -u otbr-agent -f

Backup

The Thread network state (keys, dataset) is stored in /var/lib/otbr-agent and is included in the daily Restic backups.