Homeassistant and Zigbee2MQTT on a QNAP NAS

I’ve been recently playing with getting Zigbee2MQTT working on my QNAP network attached storage device, and I ran into an interesting problem.

In my case, I am running an QNAP TS-451+ with QTS 5.0.1.2194 (though it’s due for an update).

For reasons, I am running my HA instance using Docker, rather than as LXC containers in the built-in ContainerStation application. Mostly due to the fact that I want to use docker compose to manage a stack of services all configured together.

So, on this NAS, I’ve got a Z-Wave USB dongle that’s been working swell. It maps to /dev/ttyACM0, which is pretty standard. I map that device into a zwave-js container, and all is well.

But then I got a Sonoff Zigbee 3.0 USB Plus-P dongle to add zigbee devices to my rig. I flashed the firmware with the right coordinator, and I plugged it in, and tried to get zigbee2mqtt working.

Well, I couldn’t for the life of me figure out how to map the zigbee usb dongle into the zigbee2mqtt container. Most of the instructions you’ll find online tell you to map the device using /dev/serial/by-id/WhateverYourDeviceIs

Problem with that is QTS 5 doesn’t provide you with any such directory. I had some serial devices available and I tried mapping to them, but no dice. I tried troubleshooting with lsusb, dmesg, all kinds of stuff. But I made no progress. I was stuck looking at this:

crw------- 1 admin administrators 166, 0 2022-12-08 20:46 ttyACM0 crw--w---- 1 admin administrators 4, 64 2022-12-08 20:21 ttyS0 crw------- 1 admin administrators 4, 65 2022-12-08 20:17 ttyS1 crw------- 1 admin administrators 4, 66 2022-12-08 13:10 ttyS2 crw------- 1 admin administrators 4, 67 2022-12-08 13:10 ttyS3

Turns out, the secret sauce is that QTS doesn’t include USB serial drivers for tons of common stuff. You have to install additional kernel drivers to make it work. I found this package: https://www.qnapclub.eu/en/qpkg/803 which installed in the standard way for QTS, and wouldn’t you know it? My zigbee dongle showed up right away as a new ttyUSB device.

I mapped that ttyUSB0 device into my zigbee2mqtt container, and it was off to the races.

Surely I’m not the only person to have this problem, so hopefully I’ve stuffed this post with enough keywords that anyone in the same position who is googling around for an answer will stumble upon it and not spend pointless hours trying to figure out how serial devices are mapped in QNAP like I did.

Good luck!