Cannot set up additional ZBT-2 as Thread router, gets claimed by the ZHA integration

Configuration Matter/Thread
,
1

Hej,

I already have one ZBT-2 set up as a Zigbee router with ZHA, working nicely.

So I bought another ZBT-2 to set up a Thread network. I plugged it in and mapped it into HA’s container. It shows up in the “Home Assistant Connect ZBT-2” integration next to the first ZBT-2. When I click the gear icon to set it up and select Thread, I get this message:

This Home Assistant Connect ZBT-2 is in use by the Zigbee Home Automation integration. Please migrate your Zigbee network to another adapter or delete the integration and try again.

Well. The other ZBT-2 is certainly in use. But this one? I beg to differ. And I’m pretty sure I’m not confusing the two devices since it says the same thing for both. The new ZBT-2 is still pulsing blueish “I am uninitialized” light while the existing one is dark as ever.

(What makes this trickier than necessary is that HA identifies the ZBT-2’s by a serial number that is nowhere to be found on the case. It only shows up in /dev/serial/by-id.)

So… how would I convince HA that the second ZBT-2 can in fact be set up for Thread?

  • HA 2026.3.1 container in podman
2

Hi,
I managed to use HA for the conversion, but that was on bare metal HAOS, so no mapping of interfaces needed.

The simplest method to convert a ZBT-2 to Thread is…

If this helps, :heart: this post!

1 Like
3

Make sure you are using the serial by-id URL for the sticks ans not the ttyxxxx url…
The TTY ports can sometimes change internally, so it is suggested to use the /serial/by-id/ URL that always talks to your dongle by serial number so it is always right.
You can find out what that is by using:

and looking for it under all hardware, something like this:

Once you have the long URL use that instead of the ttyxxx one.

If you are using a Container installation, this is how to see the /serial/by-id/ URL:
ls -l /dev/serial/by-id

4

Thanks, that sounded very promising! :sweat_smile:

I flashed the ZBT-2 to OpenThread 2.7.2.0 through the web flasher and it shows the correct firmware afterwards. However.

Going into HA again, it still thinks this ZBT-2 is running Zigbee firmware (“EmberZNet Zigbee 7.5.1.0”). I deleted the device from HA (Three Dots → Delete). Unplugged it. Replugged it. Restarted HA. Restarted the whole machine. Still supposedly Zigbee.

It seems like HA persisted that information about the device somewhere and so far it didn’t re-interview it, maybe?

5

I’m afraid both ZBT’s are already mapped unambiguously into the container:

devices:
  - /dev/serial/by-id/usb-Nabu_Casa_ZBT-2_1CDBD45F5730-if00:/dev/ttyACM1
  - /dev/serial/by-id/usb-Nabu_Casa_ZBT-2_9C139EAC1A6C-if00:/dev/ttyACMthread
1 Like
6

If you only restarted HA , the USB device state might not have fully refreshed. Did you try a full system reboot to re-enumerate the USB devices?

7

I did, but I hadn’t completely removed power from the RPi so far. So I did it again now:

  • Deleted the ZBT-2 from the “Home Assistant Connect ZBT-2” integration in HA
  • Unplugged it from the Pi
  • Shut the Pi down and removed the power supply completely
  • (Intermezzo: Plugged the ZBT-2 into my desktop machine and verified that it still runs the OpenThread firmware.)
  • Booted the Pi up again, verified there is only the ZBT-2 for Zigbee listed
  • Plugged the second ZBT-2 in again
  • Restarted HA only (not the Pi)
  • The second ZBT-2 shows up again, but still HA says it runs EmberZNet and is in use by the ZHA integration. The ZHA integration only shows one ZBT-2, the coordinator.
8

I was massively frustrated today because I bought the ZBT-2 expecting that setting up Thread will just work with HA. Which it didn’t. At all. The whole documentation is written for HAOS and only HAOS. (Bear with me, I’m trying to make this a helpful rant.)

Last time I checked simply running HA in a container is a supported method, too. HA in a container requires many more steps to set up Thread that need to be picked from random forum threads. Not to mention that OpenThread Border Router is more of a device developer’s thing than documented for Thread admins.

I think I figured it out though.

First I checked the HA source code. I needed to figure out how this weird check works that erroneously claims that the ZHA integration owns the secondary ZBT-2. I still don’t understand that, but it got me onto the tracks of OTBR - OpenThread Border Router. Which becomes important later on.

Second I spent a long evening in front of the HA Pi, trying to get “Home Assistant Connect ZBT-2” to show the two ZBT-2’s correctly. It didn’t and it still doesn’t in the end. Even when I started HA only with the ZBT-2 for Thread it showed only the Zigbee-ZBT-2 as connected. (Yes, I checked the serial number.) However, at that point the ZHA integration consequently failed to start and couldn’t block the ZBT-2. This gave me another error message when trying to configure the ZBT-2 for Thread: This time HA told me that outside of HAOS, it cannot set up OTBR automatically. Hooray! Now I finally have something to work with. (Where are the docs on this?)

Setting up OTBR looked simple at first. Get the Docker image from Google, start up, figure out the baud rate of the ZBT-2 (wtf?), and the container was running. (I’ll spare you the fun I had trying to get it to run in Podman instead of Docker.) Well, gotcha! This one does not work. Searching for error messages led me to this HA forums thread where it turns out that Google’s OTBR image does not work with HA. Apparently there is a dedicated OTBR build for HA with tweaks and the REST API enabled. And someone made a Docker image from it. (How that’s going to be regularly updated? I have no clue.)

That thread also revealed that OTBR isn’t enough, I also need a Matter server. Another container, another Python project I don’t understand (yet). But this one doesn’t need special privileges so it was easy to set up in rootless Podman.

From here on things were easier to find: HA must have the OTBR integration installed which eventually talks to OTBR’s REST API port. Then the Thread and Matter integrations need to be installed and do their things.

After I manually added the border router to one of the two (?!) Thread networks that showed up in HA by now things look fine-ish. Now I’ll need an actual Thread device to see whether pairing does anything sensible.

So… bottom line?

  • The ZBT-2 documentation looks nice and easy. Reality is massively more messy.
  • Thread + Matter appear to be much more complex than the Zigbee and Z-Wave I was used to. Will need to read things.
  • Thread networks apparently cannot be renamed and the autogenerated names are… unrevealing.

Thanks for reading. I hope somebody will eventually find this entertaining.