How are USB ports mapped?

Tags: #<Tag:0x00007f780343fad0>

I have a test system running Home Assistant 0.110.0 on an RPI3. When I connect a serial-to-USB converter cable to one of its USB ports, here is how it appears in Supervisor > System > Hardware:

Screenshot from 2020-05-23 19-21-19

In theory, it means the converter cable is accessible via either:
/dev/ttyUSB0
or
/dev/serial/by-id/usb-Prolific_Technology_Inc._USB-Serial_Controller_D-if00-port0

I have the SSH & Web Terminal Add-On installed so I can connect to HassOS and open a console. When I list the contents of /dev there is no serial sub-directory nor a /dev/ttyUSB0 listed:

Screenshot from 2020-05-23 19-20-29

I also have the Portainer Add-On installed so I can connect to the Home Assistant docker container and open a console. When I list the contents of /dev, once again there is no serial sub-directory nor a /dev/ttyUSB0.

Screenshot from 2020-05-23 19-24-25

So how are the (connected) USB ports displayed in the Hardware view when there appears to be no evidence of them elsewhere?

The reason for this exploration is because I installed the UPB integration and, in order to communicate via the converter cable, you must specify the connected port. However, the integration is unable to find a port called /dev/ttyUSB0 (nor the other one, ‘/dev/serial/by-id/usb…etc’). That seems consistent with my inability to find evidence of them … except in the Hardware view.

The SSH add-on is a different container than Home Assistant.

The docker container runs in privileged mode and maps all USB devices through.

Thanks for your help. I have a few more novice questions:

So the SSH Add-On isn’t actually showing me /dev at the operating system level?

Shouldn’t I see /dev/ttyUSB0 in the console of Home Assistant Core’s container?

Ultimately, I’m trying to understand why the UPB integration claims it cannot find /dev/ttyUSB0. I thought I’d see it in Home Assistant Core’s docker container but it’s not present.

Nope. It’s showing you /dev/ in the container that it’s running.

Yes. If you are in the HA Core container.

I just re-read that you were using Portainer to connect to the console of HA Core and not seeing the devices. Perhaps this is some more f$%kery that supervisor is doing. Can you see it in the supervisor container?

That’s the thing, I don’t see a Supervisor container. It’s Home Assistant installed as a disk-image on an RPI3 (my test system) and it’s different from Home Assistant Supervised on Ubuntu (my production system).

Production System

  • Home Assistant Supervised on Ubuntu
  • Portainer is installed but not as an Add-On (i.e. installed as a standard-issue docker container).
  • In Portainer, I can see every docker container: Home Assistant Core, Supervisor, Add-Ons, etc.

Screenshot from 2020-05-23 21-41-42

Everything you’d expect to see is visible.

Test System

  • Home Assistant on RPI3 (disk-image)
  • Portainer is installed as an Add-On (no other choice).
  • In Portainer, I initially see it reports 10 containers but then only two are listed: Home Assistant Core and Multicast (not Supervisor nor any of the four Add-Ons installed).

Screenshot from 2020-05-23 21-37-52
Notice how the following screen now indicates only 2 containers (unclear to me why the previous one indicates 10 then only 2):


Here they are, just Core and the multicast container:

Where are the others that are visible in the Supervised edition? Beats me.

There appears to be no other plausible answer other than: Yes.

If I recall, there was a setting you had to do for your portainer add-on to see the HA stuff properly. I don’t use any form of supervised though, so I don’t remember what the setting is.

I’m unfamiliar with that setting. The Portainer Add-On has a configuration section but, according to its documentation, it only has two options, one to set the log_level and the other is something called agent_secret whose purpose is unclear (even after reading its brief description).

The only other thing is on the Portainer Add-On main page which is a switch to turn off Protection Mode. I have that set to off (the Add-On fails to work if you leave it on).

Go into Portainer -> Settings -> Hidden containers:
Delete the listed hidden labels (io.hass.type labels).

Cool! Thanks! I had no idea it was possible to hide containers like that.

OK, I checked /dev in the Supervisor container and it doesn’t list ttyUSB0.

I came across this interesting post:

It reports an inability to communicate with a USB device. What caught my eye is it shows a listing of /dev which contains the serial sub-directory and a ttyUSBx port (i.e. what I’m searching for). What’s unclear is the flavor of Home Assistant being used.

Using Portainer, I opened a console in the homeassistant container and checked dmesg. It shows the converter cable was detected (each time I had plugged it) and assigned it to ttyUSB0.

bash-5.0# dmesg | grep -i usb
[227725.011438] usb 1-1.4: new full-speed USB device number 4 using dwc_otg
[227725.143792] usb 1-1.4: New USB device found, idVendor=0557, idProduct=2008, bcdDevice= 3.00
[227725.149981] usb 1-1.4: New USB device strings: Mfr=1, Product=2, SerialNumber=0
[227725.156251] usb 1-1.4: Product: USB-Serial Controller D
[227725.159440] usb 1-1.4: Manufacturer: Prolific Technology Inc.
[227725.226218] usbcore: registered new interface driver pl2303
[227725.228585] usbserial: USB Serial support registered for pl2303
[227725.240810] usb 1-1.4: pl2303 converter now attached to ttyUSB0
[228939.439616] usb 1-1.4: USB disconnect, device number 4
[228939.443497] pl2303 ttyUSB0: pl2303 converter now disconnected from ttyUSB0
[229085.649906] usb 1-1.4: new full-speed USB device number 5 using dwc_otg
[229085.782166] usb 1-1.4: New USB device found, idVendor=0557, idProduct=2008, bcdDevice= 3.00
[229085.788235] usb 1-1.4: New USB device strings: Mfr=1, Product=2, SerialNumber=0
[229085.794384] usb 1-1.4: Product: USB-Serial Controller D
[229085.797471] usb 1-1.4: Manufacturer: Prolific Technology Inc.
[229085.811877] usb 1-1.4: pl2303 converter now attached to ttyUSB0
[230076.079572] usb 1-1.4: USB disconnect, device number 5
[230076.083527] pl2303 ttyUSB0: pl2303 converter now disconnected from ttyUSB0
[230679.769963] usb 1-1.4: new full-speed USB device number 6 using dwc_otg
[230679.902304] usb 1-1.4: New USB device found, idVendor=0557, idProduct=2008, bcdDevice= 3.00
[230679.908398] usb 1-1.4: New USB device strings: Mfr=1, Product=2, SerialNumber=0
[230679.914576] usb 1-1.4: Product: USB-Serial Controller D
[230679.917703] usb 1-1.4: Manufacturer: Prolific Technology Inc.
[230679.931096] usb 1-1.4: pl2303 converter now attached to ttyUSB0
bash-5.0#

However, there’s no evidence of ttyUSB0 in /dev

bash-5.0# ls /dev/ttyUSB*
ls: /dev/ttyUSB*: No such file or directory
bash-5.0#

It’s unclear to me how an integration within the homeassistant container can communicate with ttyUSB0 when there does not appear to be a path to it within the container.

In an associated thread, gwww suggested I use mknod to create the missing ttyUSB0. I did that in the homeassistant container and it created /dev/ttyUSB0. Afterwards, the UPB integration was able to find, open, and read/write data through it. This patch was done as an experiment and doesn’t represent a permanent solution.

Without the presence of /dev/ttyUSB0 within the homeassistant container, I don’t understand how an integration can access it. Why isn’t /dev/ttyUSB0 automatically created within the container when the converter cable is first detected and assigned to ttyUSB0? Is this a bug?

I’ve have now tested these two installation methods:

  • Home Assistant 0.110.2 as disk-image on Raspberry PI3
  • Home Assistant Supervised 0.110.2 in Ubuntu

Neither of them exposed the connected device as /dev/ttyUSB0 in the homeassistant container.

This omission prevents integrations from accessing the connected device (notably the UPB integration).

Given that people who use USB Zigbee and Zwave devices are not reporting connection failures, I’m puzzled why they are not affected by it.

I found the answer. It’s so simple, it elicited a “Oh, FFS!”

After plugging in the converter cable to the USB port, restart Home Assistant.

That’s it, that’s all.


It came about as a result of this thought: after you plug in the converter, HassOS or Ubuntu detect it immediately, but when is Home Assistant informed of it? The simple answer is: not immediately. It detects it on startup.

That was a rather long journey, only to arrive at such an inauspicious destination.

3 Likes