Accessing USB Devices from Docker Containers

One of the common problems people have when they use Home Assistant Container is getting Home Assistant to recognise USB devices that you have plugged into the host computer, usually things like Zigbee or Z-Wave USB dongles.

You go to add the Zigbee Home Automation integration, and find that it can't detect your USB stick.

To make this work you need to map the USB stick from the Host Computer to the Docker Container. This is easily done via the docker-compose.yaml file.

Firstly, plug the USB stick into your host computer and then SSH into it. You then need to run this command, which will list all the USB serial devices connected to your host.

ls -l /dev/serial/by-id

You can see the output here on mine.  The part you are interested in is the bit at the end, in my case /ttyUSB0.  

You then need to update your docker-compose.yaml file to include a Devices key, as indicated in this Home Assistant article.  

devices:# your usb device forwarding to the docker image- /dev/<tty port name>:/dev/<tty port name>

Be sure to replace the <tty port name> in the example above with the port that you see in the output of the command you ran in the SSH session. Most of the time it will be ttyUSB0, but I've also seen ones like ttyACM0 or similar, so it's best to check.

This part maps the USB serial port of the Zigbee stick from your local host to your Container. You can see the full configuration from my docker-compose.yaml file below, with the devices part highlighted.

Once you've got that bit in your docker-compose.yaml file you will need to run the docker-compose up -d command from the SSH session, in the folder where the docker-compose.yaml file lives, to recreate the container with the new USB mapping.

ZHA should now find your USB stick and you can start pairing Zigbee devices!