Confusion about ZBT-2 setup with HomeAssistant Container | Home Assistant | Page 1

hasty light Feb 3, 2026, 6:34 PM

#

So I am in the process of setting up my new ZBT-2 with HomeAssistant Container.
Step 3. on the Nabucasa support page mentions mapping the device into the home assistant container.
In this post the device is mapped only into the otbr container, but that seems to work fine for everyone in the thread.
So I was wondering, if both are valid options, or if the support page is wrong, or where that discrepency is coming from..

Best regards!

Home Assistant Community

Connect ZBT-2 Thread to Home Assistant Container

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

daring kayak Feb 3, 2026, 6:35 PM

#

If you use the official docs you don't need to map anything as privileged makes devices superfluous.

hasty light Feb 3, 2026, 6:38 PM

#

You mean the official docs on the initial homeassistant container setup?
yeah, I have that setup using ⁨⁨privileged⁩⁩, but the ZBT-2 is not auto detected in homeassistant, if that should be the case

daring kayak Feb 3, 2026, 6:40 PM

#

Yeah these: https://www.home-assistant.io/installation/linux#docker-compose
What's lsusb and lsusb -vt look like?

hasty light Feb 3, 2026, 6:41 PM

#

⁨```
➜ Docker git:(master) docker exec -it homeassistant bash
Pi5:/config# lsusb
Bus 003 Device 001: ID 1d6b:0002 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 001 Device 001: ID 1d6b:0002 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 003 Device 004: ID 303a:1001 Espressif USB JTAG/serial debug unit
Bus 004 Device 001: ID 1d6b:0003 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 002 Device 001: ID 1d6b:0003 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 001 Device 002: ID 303a:831a Nabu Casa ZBT-2
Pi5:/config#

#

same for -vt

#

⁨```
Pi5:/config# lsusb -vt
Bus 003 Device 001: ID 1d6b:0002 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 001 Device 001: ID 1d6b:0002 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 003 Device 004: ID 303a:1001 Espressif USB JTAG/serial debug unit
Bus 004 Device 001: ID 1d6b:0003 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 002 Device 001: ID 1d6b:0003 Linux 6.12.62+rpt-rpi-2712 xhci-hcd xHCI Host Controller
Bus 001 Device 002: ID 303a:831a Nabu Casa ZBT-2
Pi5:/config#

#

I have already flashed the ZBT-2 with the thread firmware

daring kayak Feb 3, 2026, 7:13 PM

#

Anything here?

ls -l /dev/serial/by-id

#

journalctl -fk before plugging it in might also be helpful.

#

It's also possible the thread firmware does not expose it as a serial device. I haven't used it yet.

#

By the way the commands were supposed to be ran on the host. Alpine's lsusb is neutered.

hasty light Feb 3, 2026, 8:29 PM

#

daring kayak By the way the commands were supposed to be ran on the host. Alpine's `lsusb` is...

⁨```
➜ ~ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 303a:831a Nabu Casa ZBT-2
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 003 Device 004: ID 303a:1001 Espressif USB JTAG/serial debug unit
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub

⁨```
➜  ~ lsusb -vt
/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci-hcd/2p, 480M
    ID 1d6b:0002 Linux Foundation 2.0 root hub
    |__ Port 002: Dev 002, If 0, Class=Communications, Driver=cdc_acm, 12M
        ID 303a:831a
    |__ Port 002: Dev 002, If 1, Class=CDC Data, Driver=cdc_acm, 12M
        ID 303a:831a
/:  Bus 002.Port 001: Dev 001, Class=root_hub, Driver=xhci-hcd/1p, 5000M
    ID 1d6b:0003 Linux Foundation 3.0 root hub
/:  Bus 003.Port 001: Dev 001, Class=root_hub, Driver=xhci-hcd/2p, 480M
    ID 1d6b:0002 Linux Foundation 2.0 root hub
    |__ Port 002: Dev 004, If 0, Class=Communications, Driver=cdc_acm, 12M
        ID 303a:1001
    |__ Port 002: Dev 004, If 1, Class=CDC Data, Driver=cdc_acm, 12M
        ID 303a:1001
    |__ Port 002: Dev 004, If 2, Class=Vendor Specific Class, Driver=[none], 12M
        ID 303a:1001
/:  Bus 004.Port 001: Dev 001, Class=root_hub, Driver=xhci-hcd/1p, 5000M
    ID 1d6b:0003 Linux Foundation 3.0 root hub
```⁩

hasty light Feb 3, 2026, 8:29 PM

#

daring kayak Anything here? ```bash ls -l /dev/serial/by-id ```

⁨```
➜ ~ ls -l /dev/serial/by-id
total 0
lrwxrwxrwx 1 root root 13 Feb 3 19:14 usb-Espressif_USB_JTAG_serial_debug_unit_10:20:BA:D7:2B:58-if00 -> ../../ttyACM0
lrwxrwxrwx 1 root root 13 Feb 3 19:14 usb-Nabu_Casa_ZBT-2_DCB4D90E9C04-if00 -> ../../ttyACM1

daring kayak Feb 3, 2026, 8:32 PM

#

Ah. So it's there. Nice. You should be able to see the same path inside the container.

hasty light Feb 3, 2026, 8:33 PM

#

in the container, the ⁨serial⁩ folder doesn't even exist

daring kayak Feb 3, 2026, 8:34 PM

#

Weird. Can you share your compose file?

hasty light Feb 3, 2026, 8:35 PM

#

⁨```yml
services:
homeassistant:
container_name: homeassistant
image: "ghcr.io/home-assistant/home-assistant:stable"
volumes:
- ~/Docker/HomeAssistant/config:/config
- /etc/localtime:/etc/localtime:ro
- /run/dbus:/run/dbus:ro
- type: bind
source: /mnt/Docker_Backups/HomeAssistant
target: /config/backups
environment:
DISABLE_JEMALLOC: true
restart: unless-stopped
privileged: true
network_mode: host
depends_on:
matter-server:
condition: service_healthy
restart: true
healthcheck:
test: curl -f localhost:8123 || exit 1
interval: 10s
retries: 5

#

I shouldn't need to restart the container for it register the usb device right?

daring kayak Feb 3, 2026, 8:37 PM

#

Maybe. You can try to add something like

- devices:
    - /dev/serial/by-id/usb-Nabu_Casa_ZBT-2_DCB4D90E9C04-if00

but as far as I know this is not needed with privileged.

hasty light Feb 3, 2026, 8:38 PM

#

do I not need the ⁨:/dev/serial/...⁩ if it's the same, or did you just leave it out?

daring kayak Feb 3, 2026, 8:38 PM

#

I left that out because we can use the same path. It should be equivalent to

/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_DCB4D90E9C04-if00:/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_DCB4D90E9C04-if00

hasty light Feb 3, 2026, 8:39 PM

#

I mean, does Docker work like that?

daring kayak Feb 3, 2026, 8:39 PM

#

Try it 🙂

hasty light Feb 3, 2026, 8:44 PM

#

now it's there :)

#

do I still need the otbr docker container like this?

#

nvm, I do

#

daring kayak Feb 3, 2026, 8:45 PM

#

Like I said I can't tell you any specifics about thread/matter.

hasty light Feb 3, 2026, 8:46 PM

#

that's probably why it was done the other way in the blog post

azure light Feb 3, 2026, 9:00 PM

#

yeah, there's no officially supported by home assistant containers for the otbr, but there's some community ones available. You could try https://github.com/ownbee/hass-otbr-docker for example.

#

or use the upstream openthread provided docker container, which is what the link in your first post uses.

hasty light Feb 3, 2026, 9:02 PM

#

how important / what is ⁨OT_INFRA_IF⁩ used for?
Cause my device is in 2 networks at the same time

azure light Feb 3, 2026, 9:04 PM

#

i'd recommend connecting all your thread and matter stuff only to a single network to avoid problems relating to link-local multicast.

hasty light Feb 3, 2026, 9:05 PM

#

makes sense.. though am I missunderstanding something here?
thread doesn't use IP and stuff so I thought the only interface here is the ZBT-2 it self, no?

azure light Feb 3, 2026, 9:06 PM

#

thread uses IP

hasty light Feb 3, 2026, 9:06 PM

#

ohhh

azure light Feb 3, 2026, 9:06 PM

#

in fact, a thread border router is just an ipv6 router between two subnets

#

uses ipv6 router announcements and everything.

hasty light Feb 3, 2026, 9:06 PM

#

huh

#

so basically OT_INFRA_IF is the interface I want to connect the thread subnet with?

azure light Feb 3, 2026, 9:07 PM

#

I'm not sure what the specific meaning of that config param is, but sounds right to me...?

hasty light Feb 3, 2026, 9:33 PM

#

not 100% sure why, but to get the container to not crash in a loop, I needed
⁨```
devices:
- /dev/net/tun

as well

azure light Feb 3, 2026, 9:36 PM

#

otbr needs the tun device to be able to create the pan0 network interface which is the actual thread network interface that gets exposed to the system

#

then routing between pan0 and your lan is actually performed by the linux kernel.

hasty light Feb 3, 2026, 9:37 PM

#

so I guess I needed that because I used add_cap NET_Admin instead of priveleged true

azure light Feb 3, 2026, 9:40 PM

#

I'd recommend just using privileged mode, tbh, the otbr has to do a bunch of system level stuff and i'm not sure NET_ADMIN covers everything.

hasty light Feb 3, 2026, 9:49 PM

#

sooo

#

I got it up and running

#

otbr integration in HA runs, the otbr docker container runs, and I managed to pair the first MoT device

azure light Feb 3, 2026, 9:50 PM

#

congrats :)

hasty light Feb 3, 2026, 9:51 PM

#

using NET_ADMIN.. we'll see if I face any issues later on

azure light Feb 3, 2026, 9:51 PM

#

that means that you don't have any problems with mdns or router announcements, so it should be good

hasty light Feb 3, 2026, 9:52 PM

#

do you happen to know, if there is a place where I can check out the release notes for the firmware updates of ikea products?

azure light Feb 3, 2026, 9:53 PM

#

I only know for ikea zigbee devices, not matter devices. https://ww8.ikea.com/ikeahomesmart/releasenotes/releasenotes.html

hasty light Feb 3, 2026, 9:53 PM

#

hmm sad

#

thanks!

azure light Feb 3, 2026, 9:54 PM

#

technically that's the release notes for the older tradfri gateway, i think, but it also includes info about the zigbee device firmware.

#Confusion about ZBT-2 setup with HomeAssistant Container