Support reporting usb interface

[mlsvrts]

USB composite devices have an interface identifier that can
be useful when attempting to distinguish between multiple
ports owned by the same USB device.

This feature adds support for an optional 'interface'
member of UsbInfo that will be populated for USB composite
devices. Errors detecting this interface information are
currently conservatively converted into None.

Closes #9

Signed-off-by: mlsvrts [email protected]

[mlsvrts]

Tested against some composite USB hardware:

• Windows 11
• Ubuntu 20.04 (arm)
• MacOs

Note: I don't have the hardware to test this change against MacOs.

[maeln]

This would be very useful for me. Is there anything I can do to help this PR be merged ? I do own a mac and an USB2serial adapter.

[mlsvrts]

This would be very useful for me. Is there anything I can do to help this PR be merged ? I do own a mac and an USB2serial adapter.

@maeln Thanks for the bump! Lints are passing now, and I've added some tests to make the Windows regex a little less frightening, so I think linux/windows are in a good place now.

If you want to run cargo run --example list_ports on your system and capture the output, that can at least show that this patch doesn't completely break port enumeration on MacOs. If that works, I can see if I can test against my composite hardware in a virtual machine.

[maeln]

@mlsvrts Tested and this is what I got :) :

➜  serialport-rs git:(support-reporting-usb-interface) cargo run --example list_ports
    Updating crates.io index
   Compiling libc v0.2.126
   Compiling CoreFoundation-sys v0.1.4
   Compiling autocfg v1.1.0
   Compiling IOKit-sys v0.1.5
   Compiling bitflags v1.3.2
   Compiling cfg-if v1.0.0
   Compiling hashbrown v0.11.2
   Compiling os_str_bytes v6.1.0
   Compiling textwrap v0.15.0
   Compiling termcolor v1.1.3
   Compiling strsim v0.10.0
   Compiling clap_lex v0.2.2
   Compiling indexmap v1.8.2
   Compiling mach v0.1.2
   Compiling mach v0.3.2
   Compiling nix v0.24.1
   Compiling atty v0.2.14
   Compiling clap v3.2.2
   Compiling serialport v4.1.1-alpha.0 (/Users/maeln/Work/serialport-rs)
    Finished dev [unoptimized + debuginfo] target(s) in 11.15s
     Running `target/debug/examples/list_ports`
Found 2 ports:
  /dev/tty.BLTH
    Type: PCI
  /dev/tty.Bluetooth-Incoming-Port
    Type: PCI
➜  serialport-rs git:(support-reporting-usb-interface)

Seems to work fine :)

[jessebraham]

I think this looks pretty good, thank you for the contribution!

I did try to test this out on my MacBook (x86_64, Big Sur) with an ESP-Prog connected, which has an FT2232HL onboard. I frankly know nothing about composite devices so I'm not sure if this counts as one, but it enumerates two different serial ports so I figured it was worth a shot. While the list_ports example ran successfully the Interface field is always empty. If this is expected behaviour please let me know. I'm not sure if I have any other devices that would work for testing.

λ cargo run --example=list_ports
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/examples/list_ports`
Found 6 ports:
  /dev/cu.Bluetooth-Incoming-Port
    Type: Bluetooth
  /dev/tty.Bluetooth-Incoming-Port
    Type: Bluetooth
  /dev/cu.usbserial-14400
    Type: USB
    VID:0403 PID:6010
     Serial Number: 
      Manufacturer: FTDI
           Product: Dual RS232-HS
         Interface: 
  /dev/tty.usbserial-14400
    Type: USB
    VID:0403 PID:6010
     Serial Number: 
      Manufacturer: FTDI
           Product: Dual RS232-HS
         Interface: 
  /dev/cu.usbserial-14401
    Type: USB
    VID:0403 PID:6010
     Serial Number: 
      Manufacturer: FTDI
           Product: Dual RS232-HS
         Interface: 
  /dev/tty.usbserial-14401
    Type: USB
    VID:0403 PID:6010
     Serial Number: 
      Manufacturer: FTDI
           Product: Dual RS232-HS
         Interface: 

[mlsvrts]

@jessebraham The interface will be 'None' if the device is not a compound device, or if the interface just can't be detected for some reason. If the FTDI driver masks that this a composite USB device, then the output is correct -- but I have no idea if that is the case:

Maybe we can compare with python -m serial.tools.list_ports -v to see if they provide any LOCATION or otherwise detect an interface for this device?

[jessebraham]

Location is printed and is the same for both devices when using PySerial:

λ python -m serial.tools.list_ports -v
/dev/cu.Bluetooth-Incoming-Port
    desc: n/a
    hwid: n/a
/dev/cu.usbserial-14400
    desc: Dual RS232-HS - Dual RS232-HS
    hwid: USB VID:PID=0403:6010 LOCATION=20-4
/dev/cu.usbserial-14401
    desc: Dual RS232-HS - Dual RS232-HS
    hwid: USB VID:PID=0403:6010 LOCATION=20-4
4 ports found

[mlsvrts]

It looks like those ports are correctly enumerating without interface information, and serialport-rs is doing the correct thing by reporting None. For comparison, here is what I can report with pyserial for a composite USB device in Windows:

COM15
    desc: USB Serial Device (COM15)
    hwid: USB VID:PID=1FC9:A101 SER=500100D20F3861D2 LOCATION=1-11:x.2
COM16
    desc: USB Serial Device (COM16)
    hwid: USB VID:PID=1FC9:A101 SER=500100D20F3861D2 LOCATION=1-11:x.0

Note the additional x.0 and x.2 strings -- those mark the interface indices. Unfortunately I don't think this is postive proof that the Mac implementation works, but it might be the best we can do until someone comes along with this use-case on Mac.

[jessebraham]

Okay thank you for checking into that. I am just going to merge this, while as you stated this is not a hard confirmation that it's working on macOS it also doesn't seem to be causing any issues. Before the next release I will find a composite device and verify that it is working as expected, and apply any fixes if needed.