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

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.

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.run OTBR(hass-otbr-docker) on the pi using docker

 

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

 

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

Connect Home Assistant to an Existing OpenThread Border Router.

Add an OpenThread Border Router to Home assistant.

 

 

 

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.

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

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.

 

 

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 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