Home Assistant Connect ZBT-2 with Docker on Raspberry Pi

Home Assistant Connect ZBT-2

Instead of using a hub like the IKEA DIRIGERA to communicate with matter/thread supported home-automation devices, I went with the open-source route. Purchanced a Home Assistant Connect ZBT-2 since I am already using Home Assistant.

Firmare Installation

1. Plug your ZBT-2 to your laptop (Mac for me).
2. Go to https://toolbox.openhomefoundation.org/home-assistant-connect-zbt-2/install/ with Chrome.
3. Click INSTALL FIRMWARE.
4. Select the ZBT-2 device and Connect.
5. Click CHANGE FIRMWARE and select the OpenThread (RCP) firmware and click INSTALL`.

Connect to Raspberry Pi

Once the firmware has been installed, plug it into the raspberry pi and confirm the device is showing up. We will be using the /dev/serial/by-id/ path for the docker-compose yaml file setting.

$ ls -lh /dev/serial/by-id/*
lrwxrwxrwx 1 root root 13 Jan  1 16:35 /dev/serial/by-id/usb-Nabu_Casa_ZBT-2_DCB4D90C2590-if00 -> ../../ttyACM0

Docker Compose

Because I have all my services in a single docker-compose.yml file, they will look like the following.

Notice! My otbr environment variable for OT_INFRA_IF is set to br0 because I have bridge setup on my Pi, yours is likely just eth0.

services:

  home-assistant:
    container_name: home-assistant
    image: ghcr.io/home-assistant/home-assistant:stable
    network_mode: host
    privileged: true
    restart: unless-stopped
    volumes:
      - './home-assistant/config:/config'

  matter-server:
    image: ghcr.io/matter-js/python-matter-server:stable
    container_name: matter-server
    depends_on:
      - otbr
    network_mode: host
    restart: unless-stopped
    security_opt:
      - apparmor:unconfined
    volumes:
      - './matter-server/data:/data'

  otbr:
    container_name: otbr
    image: openthread/border-router:latest
    devices:
      - /dev/serial/by-id/usb-Nabu_Casa_ZBT-2_DCB4D90C2590-if00:/dev/ttyACM0
    environment:
      OT_RCP_DEVICE: spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800
      OT_INFRA_IF: br0
      OT_THREAD_IF: wpan0
      OT_REST_PORT: 8981
      OT_REST_LISTEN_PORT: 8981
    network_mode: host
    privileged: true
    restart: unless-stopped

Start up the services.

$ docker compose up --remove-orphans -d
[+] Running 12/12
 ✔ Container home-assistant  Started
 ✔ Container otbr            Started
 ✔ Container matter-server   Started

Confirm the container status.

$ docker compose ps --format "table{{.Name}}\t{{.Image}}\t{{.Service}}\t{{.RunningFor}}\t{{.State}}\t{{.Status}}"
NAME             IMAGE                                           SERVICE          CREATED          STATE     STATUS
home-assistant   ghcr.io/home-assistant/home-assistant:stable    home-assistant   49 seconds ago   running   Up 48 seconds
matter-server    ghcr.io/matter-js/python-matter-server:stable   matter-server    49 seconds ago   running   Up 47 seconds
otbr             openthread/border-router:latest                 otbr             49 seconds ago   running   Up 48 seconds

Add Home Assistant Integrations

Log into your Home Assistant admin portal and add the following Matter/Thread integrations.

1. Thread
2. Open Thread Border Router: This will prompt you to enter the URL for REST API (http://127.0.0.1:8981).
3. Matter

To be safe, restart all the docker services.

$ docker compose restart home-assistant
[+] Restarting 1/1
 ✔ Container home-assistant  Started

$ docker compose restart otbr
[+] Restarting 1/1
 ✔ Container otbr  Started

$ docker compose restart matter-server
[+] Restarting 1/1
 ✔ Container matter-server  Started

Add Matter Devices via Home Assistant App

1. Go to the Thread integration in the phone app, click Send credentials to Home Assistant.
2. We can now add Matter devices.

Once the devices have been added, you can confirm under Matter in Integration.

References

• Connect ZBT-2 Thread to Home Assistant Container