Feature: Enumerate interfaces

[dpkristensen]

The API allows for connecting to a device by index, but does not present a way to see what all of the interfaces are.

Nordic Semiconductor recently started shipping all of their development kits with an nRF5340 chip as the debug chip, even for older DK's like the nRF52832 and nRF52840. This presents TWO serial ports; the first one is the debug interface, and the second is the UART passthrough to the MCU.

It would be nice to have some more details about these interfaces programmatically. Some other libraries which are focused on more generic USB functionality provide more granular API to select the communication path which is available from Android:

• UsbDevice.getConfiguration() to access one or more
• UsbConfiguration.getInterface() to access one or more
• UsbInterface.getEndpoint() to access one or more
• UsbEndpoint

[dpkristensen]

Also here is the USB enumeration of an nRF52840 DK, for reference:

Information for device J-Link (VID=0x1366 PID=0x1051):

------------------------------
Connection Information:
------------------------------
Device current bus speed: FullSpeed
Device supports USB 1.1 specification
Device supports USB 2.0 specification
Device address: 0x000C
Current configuration value: 0x01
Number of open pipes: 10


------------------------------
Device Descriptor:
------------------------------
0x12	bLength
0x01	bDescriptorType
0x0200	bcdUSB
0xEF	bDeviceClass      (Miscellaneous device)
0x02	bDeviceSubClass   
0x01	bDeviceProtocol   
0x40	bMaxPacketSize0   (64 bytes)
0x1366	idVendor
0x1051	idProduct
0x0100	bcdDevice
0x01	iManufacturer   "SEGGER"
0x02	iProduct        "J-Link"
0x03	iSerialNumber   "001050221072"
0x01	bNumConfigurations


-------------------------
Configuration Descriptor:
-------------------------
0x09	bLength
0x02	bDescriptorType
0x00BB	wTotalLength   (187 bytes)
0x06	bNumInterfaces
0x01	bConfigurationValue
0x04	iConfiguration   "Configuration"
0x80	bmAttributes   (Bus-powered Device)
0x32	bMaxPower      (100 mA)

Interface Association Descriptor:
------------------------------
0x08	bLength
0x0B	bDescriptorType
0x00	bFirstInterface
0x02	bInterfaceCount
0x02	bFunctionClass      (Communication Device Class)
0x02	bFunctionSubClass   (Abstract Control Model - ACM)
0x00	bFunctionProtocol   
0x05	iFunction   "CDC"

Interface Descriptor:
------------------------------
0x09	bLength
0x04	bDescriptorType
0x00	bInterfaceNumber
0x00	bAlternateSetting
0x01	bNumEndPoints
0x02	bInterfaceClass      (Communication Device Class)
0x02	bInterfaceSubClass   (Abstract Control Model - ACM)
0x01	bInterfaceProtocol   (ITU-T V.250)
0x05	iInterface   "CDC"

CDC Header Functional Descriptor:
------------------------------
0x05	bFunctionalLength
0x24	bDescriptorType
0x00	bDescriptorSubtype
0x0110	bcdCDC

CDC Call Management Functional Descriptor:
------------------------------
0x05	bFunctionalLength
0x24	bDescriptorType
0x01	bDescriptorSubtype
0x03	bmCapabilities
0x01	bDataInterface

CDC Abstract Control Management Functional Descriptor:
------------------------------
0x04	bFunctionalLength
0x24	bDescriptorType
0x02	bDescriptorSubtype
0x06	bmCapabilities

CDC Union Functional Descriptor:
------------------------------
0x05	bFunctionalLength
0x24	bDescriptorType
0x06	bDescriptorSubtype
0x00	bControlInterface
0x01	bSubordinateInterface(0)

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x82	bEndpointAddress  (IN endpoint 2)
0x03	bmAttributes      (Transfer: Interrupt / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (1 x 64 bytes)
0x01	bInterval         (1 frames)

Interface Descriptor:
------------------------------
0x09	bLength
0x04	bDescriptorType
0x01	bInterfaceNumber
0x00	bAlternateSetting
0x02	bNumEndPoints
0x0A	bInterfaceClass      (CDC Data)
0x00	bInterfaceSubClass   
0x00	bInterfaceProtocol   
0x06	iInterface   "CDC DATA interface"

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x81	bEndpointAddress  (IN endpoint 1)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x01	bEndpointAddress  (OUT endpoint 1)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Interface Association Descriptor:
------------------------------
0x08	bLength
0x0B	bDescriptorType
0x02	bFirstInterface
0x02	bInterfaceCount
0x02	bFunctionClass      (Communication Device Class)
0x02	bFunctionSubClass   (Abstract Control Model - ACM)
0x00	bFunctionProtocol   
0x07	iFunction   "CDC"

Interface Descriptor:
------------------------------
0x09	bLength
0x04	bDescriptorType
0x02	bInterfaceNumber
0x00	bAlternateSetting
0x01	bNumEndPoints
0x02	bInterfaceClass      (Communication Device Class)
0x02	bInterfaceSubClass   (Abstract Control Model - ACM)
0x01	bInterfaceProtocol   (ITU-T V.250)
0x07	iInterface   "CDC"

CDC Header Functional Descriptor:
------------------------------
0x05	bFunctionalLength
0x24	bDescriptorType
0x00	bDescriptorSubtype
0x0110	bcdCDC

CDC Call Management Functional Descriptor:
------------------------------
0x05	bFunctionalLength
0x24	bDescriptorType
0x01	bDescriptorSubtype
0x03	bmCapabilities
0x03	bDataInterface

CDC Abstract Control Management Functional Descriptor:
------------------------------
0x04	bFunctionalLength
0x24	bDescriptorType
0x02	bDescriptorSubtype
0x06	bmCapabilities

CDC Union Functional Descriptor:
------------------------------
0x05	bFunctionalLength
0x24	bDescriptorType
0x06	bDescriptorSubtype
0x02	bControlInterface
0x03	bSubordinateInterface(0)

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x84	bEndpointAddress  (IN endpoint 4)
0x03	bmAttributes      (Transfer: Interrupt / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (1 x 64 bytes)
0x01	bInterval         (1 frames)

Interface Descriptor:
------------------------------
0x09	bLength
0x04	bDescriptorType
0x03	bInterfaceNumber
0x00	bAlternateSetting
0x02	bNumEndPoints
0x0A	bInterfaceClass      (CDC Data)
0x00	bInterfaceSubClass   
0x00	bInterfaceProtocol   
0x08	iInterface   "CDC DATA interface"

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x83	bEndpointAddress  (IN endpoint 3)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x02	bEndpointAddress  (OUT endpoint 2)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Interface Descriptor:
------------------------------
0x09	bLength
0x04	bDescriptorType
0x04	bInterfaceNumber
0x00	bAlternateSetting
0x02	bNumEndPoints
0xFF	bInterfaceClass      (Vendor specific)
0xFF	bInterfaceSubClass   
0xFF	bInterfaceProtocol   
0x09	iInterface   "BULK interface"

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x85	bEndpointAddress  (IN endpoint 5)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x03	bEndpointAddress  (OUT endpoint 3)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Interface Descriptor:
------------------------------
0x09	bLength
0x04	bDescriptorType
0x05	bInterfaceNumber
0x00	bAlternateSetting
0x02	bNumEndPoints
0x08	bInterfaceClass      (Mass Storage Device Class)
0x06	bInterfaceSubClass   (Transparent SCSI subclass)
0x50	bInterfaceProtocol   (Bulk only transport)
0x0A	iInterface   "MSD interface"

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x86	bEndpointAddress  (IN endpoint 6)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Endpoint Descriptor:
------------------------------
0x07	bLength
0x05	bDescriptorType
0x04	bEndpointAddress  (OUT endpoint 4)
0x02	bmAttributes      (Transfer: Bulk / Synch: None / Usage: Data)
0x0040	wMaxPacketSize    (64 bytes)
0x01	bInterval         

Microsoft OS Descriptor is not available. Error code: 0x0000001F


--------------------------------
String Descriptor Table
--------------------------------
Index  LANGID  String
0x00   0x0000  0x0409 
0x01   0x0409  "SEGGER"
0x02   0x0409  "J-Link"
0x03   0x0409  "001050221072"
0x04   0x0409  "Configuration"
0x05   0x0409  "CDC"
0x06   0x0409  "CDC DATA interface"
0x07   0x0409  "CDC"
0x08   0x0409  "CDC DATA interface"
0x09   0x0409  "BULK interface"
0x0A   0x0409  "MSD interface"

------------------------------

Connection path for device: 
USB xHCI Compliant Host Controller
Root Hub
Generic USB Hub
Generic USB Hub
J-Link (VID=0x1366 PID=0x1051) Port: 1

Running on: Windows 10 or greater (Build Version 22621)

Brought to you by TDD v2.17.0, Feb 23 2021, 14:04:02

[altera2015]

If the UsbSerial Java library supports this it would be doable to add it. However I do not have this hardware and won't be able to implement this. Also I need to make sure to not break backward compat.

[dpkristensen]

The connection API already supports taking an index, so if there was a separate API to list out what those indexable items are then the existing one wouldn't have to break. But as a new API it would have to have support in all of the various plugins in such a way that the list it returns correlates to the index number passed in.

As for testing, many USB devices have multiple interfaces (including other phones); but at least you should be able to return a list of at least one entry in all cases. I could try to help with testing on Android at least.