It took me the better part of a day to figure out how to get this shiny new ZBT-2 to work as a Thread device for Home Assistant, installed in a container.
Below is what I did to get it to work, hopefully saves this you a few headaches.
My environment
My environment consists of a Ubuntu 22.04 server on a NUC, with Home Assistant running in a Docker container.
The Home Assistant container uses docker host networking.
IP V6 was already enabled on my Ubuntu system (but it turned out there was more to it).
Flashing the ZBT-2
The ZBT-2 comes without firmware, so you have to flash it first.
I connected the ZBT-2 to my Macbook, and visited this site and install the Openthread firmware.
Installing Openthread
I connected the ZBT-2 to my NUC, and a new device appeared, you can find it in /dev/serial/by-id.
Next step is to run the Openthread Border Router. Start it as a docker container with the following command:
docker run \
--name otbr \
--network host \
--restart unless-stopped \
-d \
-v /<your thread path>:/data \
--device=/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_<your device>-if00:/dev/ttyACM5 \
-e TZ=Europe/Amsterdam \
--privileged \
--env-file=/<your thread path>/otbr-env.list \
--device=/dev/net/tun \
openthread/border-router:latest
Make sure to use host networking and add the privileged option.
In my case, the otbr container already showed some ttyACMx devices. Number 5 was not in use, that is why I chose ttyACM5.
Content of the file otbr-env.list:
OT_RCP_DEVICE=spinel+hdlc+uart:///dev/ttyACM5?uart-baudrate=460800
OT_INFRA_IF=eno1
OT_THREAD_IF=wpan0
OT_LOG_LEVEL=7
OT_REST_PORT=8981
OT_REST_LISTEN_PORT=8981
Note 1: the /dev/ttyACM5, it must match what is in the docker run command.
Note 2: the OT_INFRA_IF - in my case the interface for my local network is eno1, yours may be different.
Note 3: By default the port for the REST interface is 8081. That is in use on my Ubuntu system, so I chose another port.
After starting this container, look at the logs:
docker logs otbr
It should give a lot of information.
Installing Matter
Next step: install the Matter container:
docker run -d \
--name matter-server \
--restart=unless-stopped \
--security-opt apparmor=unconfined \
-v /<your matter path>:/data \
--network=host \
ghcr.io/matter-js/python-matter-server:stable
Check the logs:
docker logs matter-server
there might be an error message:
CHIP_ERROR [chip.native.DIS] Failed to advertise records: src/inet/UDPEndPointImplSockets.cpp:417: OS Error 0x02000065: Network is unreachable
It is save to ignore if you have another network interface in your environment (like I have).
Allow IPv6 forwarding
On my Linux system IPv6 is by default enabled, but forwarding is not.
As per this link, download this script. There is an interface in that script (wlan0), I had to change that to eno1 - the primary interface on my NUC.
Run the script, it should complete without errors.
Configure Home Assistant
First, add the Thread integration.
Second, add the Open Thread Border Router integration.
When asked for an URL, enter
http://127.0.0.1:<your port number>
The port number is by default 8081, I changed it to 8981 in my OTBR configuration.
Third, add the Matter integration. Accept the proposed Websocket url.
Fourth, go to settings → integrations → Thread → settings and make your newly installed border router the preferred border router.
Configure your mobile device with Home Assistant
On your mobile go to settings → integrations → Thread → settings and send credentials to phone.
Add Matter devices
My first device I added was a light bulb.
On your mobile, go to settings ->integrations → devices → add device → matter device → it is new → scan qr code on the Matter device.
I sat back and after some time a new device appeared in Home Assitant and it works!
I hope this helps you getting started as well if you don’t use HA-OS.
Sietse