[solved] Pass Zigbee device to Docker Container

Installation
, ,
1

I’m trying to migrate my install from core (installed in a virtual environment) to a docker container.

I’m using a conbee II and the zha integration successfully in my current core install. I ran a backup of my current install and imported it when I first ran the container. Everything else seems fine, but zha is not working in the container.

This is my compose.yml:

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /serverfiles/homeassistant-container/data:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      TZ: America/New_York
    devices:
      - /dev/serial/by-id/usb-0658_0200-if00:/dev/serial/by-id/usb-0658_0200-if00
      - /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2123939-if00:/dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2123939-if00

this is the error I’m getting in the frontend when I run the container:

zigbee_err
zigbee_err1222×383 27 KB

this is my configuration.yml:

homeassistant:
default_config:
group: !include groups.yaml
automation: !include automations.yaml
script: !include scripts.yaml
zha:
  database_path: /config/zigbee.db
  zigpy_config:
    network:
      channel: 15
      channels: [15, 20, 25]
    ota:
      otau_directory: /config/otaus
logger:
  default: info
  logs:
    homeassitant.components.zha: debug
    bellows.zigbee.application: debug
    bellows.ezsp: debug
    zigpy: debug
    zigpy_cc: debug
    zigpy_deconz.zigbee.application: debug
    zigpy_deconz.api: debug
    zigpy_xbee.zigbee.application: debug
    zigpy_xbee.api: debug
    zigpy_zigate: debug
    zigpy_znp: debug
    zhaquirks: debug
frontend:
energy:
system_health:
mobile_app:
sensor:
  - platform: time_date
    display_options:
      - 'time'
      - 'date'
      - 'date_time'
zeroconf:

What do I need to change to make it recognize my device?

2

Use docker exec to enter the container and see if the mapped drive (/dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2123939-if00) is showing up inside your container.

If it is there then I’m afraid I can’t help why it isn’t working :frowning_face:.

If it is not there then there may be a problem mapping it to the “/dev/serial/by-id” subdirectory. Try mapping to a simpler name directly in /dev - something live /dev/zigbee should work - and then update your configs to use “/dev/zigbee” for the coordinator device.

3

what environment is your docker running in? Ubuntu, proxmox, Nas,…?

4

when I tried this there was no /dev/serial at all (no clue how zwave was working with this being the case). And strangely when the container was running,

/dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2123939-if00

disappeared from the host machine as well (and came back as soon as I stopped the container).

When I tried mapping the devices directly:

      - /dev/ttyACM0:/dev/ttyACM0
      - /dev/ttyACM1:/dev/ttyACM1

zha would prompt me to migrate my adapter, but then I’d end up with this error:

The adapter you are restoring to does not properly support backup restoration. Please upgrade the firmware.

Error: Please upgrade your adapter firmware. Firmware version 0x264a0700 does not support writing the network key frame counter, which is required for migration to succeed.

docker host is gnu/linux: Linux 6.17.8-arch1-1 #1 SMP PREEMPT_DYNAMIC Fri, 14 Nov 2025 06:54:20 +0000 x86_64 GNU/Linux

5

I suspected that the problem was udev related but wasn’t sure. Based on what you see I’m fairly certain that it is.

The reason “/dev/serial” doesn’t exist at all is because it isn’t actually part of the baseline /dev structure. It is created by udev when a serial device is plugged it to create meaningful names for the devices.

Unfortunately, docker containers don’t (normally) support udev. So there is nothing there to recognize that a device has been plugged in and no udev trigger to create the symlinks with the more rational names. That’s why you need to map the actual device (/dev/ACMx) to a device directly in /dev.

Now - second question - ZHA thinks you need to do a migraton. That is because the USB device name changed. I don’t use ZHA (Z2M works so much better for me :slight_smile:). But google suggests that the path for the co-ordinator can be found in your Home Assistant configuration in
“/config/.storage/core.config_entries”. If you edit that file and change it to the name you end up mapping in /dev it should solve your problem. Maybe…

1 Like
6

Thanks for walking me through that, it makes complete sense now.

After updating the config_entries file with the direct path to the device, all my zha integration is again functional.

Thank you!

1 Like