Part 4 - Thread border router - Home Assistant Connect ZBT-1(image: "ghcr.io/d34dc3n73r/hass-otbr-docker")

In this guide, we will set up the OTBR docker container on Raspberry Pi 5 to form a thread network for Matter Server docker container. 

This guide will walk you through the steps to run a locally operated OpenThread Border Router (OTBR) using docker and integrate it with supported Matter platforms, including  Home Assistant.

I have a raspberry pi 5 with Raspberry Pi OS Lite.

I have home assistant running in a docker on Raspberry Pi 5.

I’m using a Connect ZBT-1 with OpenThread RCP firmware.

I have flashed my Connect ZBT-1 with an openthread firmware (thread only).  The dongle will act as a border router. 

I use this pi for my Home Assistant Connect ZBT-1 dongle - running ghcr.io/d34dc3n73r/hass-otbr-docker container.

 

Requirements

hardware

Home Assistant Connect ZBT-1

Raspberry Pi 5

docker

OTBR docker:ghcr.io/d34dc3n73r/hass-otbr-docker

ha docker:

 

 

 

First, plug the ZBT-1 into the extension cable and then into your Raspberry Pi. Debian OS should automatically detect a ZBT-1.

Then, install dedicated Thread Firmware on the ZBT-1.

Third,run OTBR on the pi using docker.

Finally, Configure the Open Thread Border Router Integration and configure the Thread integration to ensure the Home Assistant network is the preferred network and share the Thread credentials with your mobile app.

 

step 1. Install dedicated Thread Firmware on ZBT-1

detail:https://blog.matterxiaomi.com/blog/matter-gateway-part-2/#mcetoc_1inetvnqq1

 

step 2.Configure and run OTBR docker(hass-otbr-docker) on the pi using docker

Pull the image from ghcr.io

 

 

To run in Docker in its simplest form just run:

docker compose up

docker-compose.yml

services:
  otbr:
    container_name: otbr
    image: ghcr.io/d34dc3n73r/hass-otbr-docker
    restart: unless-stopped
    privileged: true # don't change this !
    network_mode: host # don't change this !
    cap_add:
      - SYS_ADMIN
      - NET_ADMIN
    environment:
      DEVICE: "/dev/ttyUSB0"
      BACKBONE_IF: eth0
      FLOW_CONTROL: 1
      FIREWALL: 1
      NAT64: 1
      BAUDRATE: 460800
      OTBR_REST_PORT: 8081
      OTBR_WEB_PORT: 8080
      AUTOFLASH_FIRMWARE: 0
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
      - /dev/net/tun:/dev/net/tun
    volumes:
      - ./otbr_data:/var/lib/thread

source code:https://github.com/mslycn/hass-otbr-docker/blob/main/docker-compose.yml

 

Let's dissect that command:

    docker compose up              - run this container, initially building locally if necessary

    container_name: otbr          - give this machine a friendly local name

    image: ghcr.io/d34dc3n73r/hass-otbr-docker      - the image to based on the Home Assistant OpenThread Border Router add-on.

    OTBR_REST_PORT: 8081            - connect local port 8081 to the exposed internal port 8081

    OTBR_WEB_PORT: 8080             - Set port 8080 for the Web UI

   ./otbr_data:/var/lib/thread  - mount the host otbr_data directory to the container /data directory so any changes made to flows are persisted

 

Note

1. if you run OTBR with “network_mode=host” you don’t need the sysctl and port settings, not to mention avoiding other IPv6 routing/mDNS issues if Matter server is running in a different container on the same host.

2.An implementation of a Thread Border Router (the bridge between Thread mesh devices and your normal Wi-Fi/Ethernet LAN) using the OpenThread open-source stack.

3.Converts between Thread mesh traffic and your LAN traffic.

4. You may need to pass through USB OTBR devices into the Docker container.

5.Replace /dev/ttyUSB0 with the device node name of the OpenThread radio co-processor.

 

other

cd /datadocker/hass-otbr-docker

docker compose down

docker compose rm -f

 

Web UI

http://192.168.2.125:8080/

You should be able to access the otbr web dashboard in your browser at http://hostnameorip:8080 — if your browser can’t reach it, HA likely won’t be able to make a web api connection.

Step 3.Add obtr integration - Connect Home Assistant to an Existing OpenThread Border Router.

Connect Home Assistant to an Existing OpenThread Border Router.

This enables HA to function as a border router on the combined Thread network.

Add an OpenThread Border Router to Home assistant.

 

http://192.168.2.125:8081

 

 

step 5.Add Thread integration - create an thread network

Thread integration be used to create thread network.

This will automatically create a new Thread network with the name ha-thread-xxxx. The last for digits are a network-specific identifier (PAN ID)

Network name: ha-thread-7b2a
Channel: 15
Dataset id: 01JTE4E6EDZF5Z7NMPZP8EJV5T
Pan id: 7b2a
Extended Pan id: 827a4c42394dc26f
OTBR URL: http://192.168.2.125:8081
Active dataset TLVs: 0e080000000000010000000300000f4a0

Note

1.ha-thread-xxxx,The last for digits are a network-specific identifier (PAN ID).

2.each vendor forms their own Thread network when you start using their products. This means you can end up having a Home Assistant, an Apple, and a Google Thread network in your home. The Thread configuration panel lists all Thread border routers and groups them by the Thread network

3.These are all separate networks using different credentials. This means devices can’t roam between the Thread networks.

3.The  icon indicates that Home Assistant has the credentials for that network. In this case, only the credentials of the home assistant network are known

 

 

Step 6.Make the Thread network preferred-Connect Home Assistant to an Existing Thread Network.

Connect Home Assistant to an Existing Thread Network.Make the Thread network preferred.

Once set, HA will use this network by default when commissioning new Thread devices.

Make the Thread network preferred.

 

In the Home Assistant Thread settings, select the imported network and mark it as the preferred network. 

Note

1.The intention of the Preferred network in Home Assistant is that it will be used as the default network when adding Thread⁻based devices.

 

 

 

 

 

Step 7.Add Thread Device

 

 

detail:https://blog.matterxiaomi.com/blog/matter-gateway-part-2/#mcetoc_1ioh0ffhm3

 

 

 

 

Useful links

https://github.com/mslycn/hass-otbr-docker

https://blog.matterxiaomi.com/boards/topic/44294/docker-pull-ghcrioownbeehass-otbr-docker#68641