Merge pull request #39 from google/gbg/usb-descriptors

improve USB device detection logic

apps/usb_probe.py

@@ -28,6 +28,7 @@
 # -----------------------------------------------------------------------------
 import os
 import logging
+import sys
 import usb1
 from colors import color
 
@@ -35,6 +36,7 @@ from colors import color
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+USB_DEVICE_CLASS_DEVICE                          = 0x00
 USB_DEVICE_CLASS_WIRELESS_CONTROLLER             = 0xE0
 USB_DEVICE_SUBCLASS_RF_CONTROLLER                = 0x01
 USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER = 0x01
@@ -75,9 +77,79 @@ USB_DEVICE_CLASSES = {
     0xFF: 'Vendor Specific'
 }
 
+USB_ENDPOINT_IN    = 0x80
+USB_ENDPOINT_TYPES = ['CONTROL', 'ISOCHRONOUS', 'BULK', 'INTERRUPT']
+
+USB_BT_HCI_CLASS_TUPLE = (
+    USB_DEVICE_CLASS_WIRELESS_CONTROLLER,
+    USB_DEVICE_SUBCLASS_RF_CONTROLLER,
+    USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+)
+
 
 # -----------------------------------------------------------------------------
-def main():
+def show_device_details(device):
+    for configuration in device:
+        print(f'  Configuration {configuration.getConfigurationValue()}')
+        for interface in configuration:
+            for setting in interface:
+                alternateSetting = setting.getAlternateSetting()
+                suffix = f'/{alternateSetting}' if interface.getNumSettings() > 1 else ''
+                (class_string, subclass_string) = get_class_info(
+                    setting.getClass(),
+                    setting.getSubClass(),
+                    setting.getProtocol()
+                )
+                details = f'({class_string}, {subclass_string})'
+                print(f'      Interface: {setting.getNumber()}{suffix} {details}')
+                for endpoint in setting:
+                    endpoint_type = USB_ENDPOINT_TYPES[endpoint.getAttributes() & 3]
+                    endpoint_direction = 'OUT' if (endpoint.getAddress() & USB_ENDPOINT_IN == 0) else 'IN'
+                    print(f'        Endpoint 0x{endpoint.getAddress():02X}: {endpoint_type} {endpoint_direction}')
+
+
+# -----------------------------------------------------------------------------
+def get_class_info(cls, subclass, protocol):
+    class_info = USB_DEVICE_CLASSES.get(cls)
+    protocol_string = ''
+    if class_info is None:
+        class_string = f'0x{cls:02X}'
+    else:
+        if type(class_info) is tuple:
+            class_string = class_info[0]
+            subclass_info = class_info[1].get(subclass)
+            if subclass_info:
+                protocol_string = subclass_info.get(protocol)
+                if protocol_string is not None:
+                    protocol_string = f' [{protocol_string}]'
+
+        else:
+            class_string = class_info
+
+    subclass_string = f'{subclass}/{protocol}{protocol_string}'
+
+    return (class_string, subclass_string)
+
+
+# -----------------------------------------------------------------------------
+def is_bluetooth_hci(device):
+    # Check if the device class indicates a match
+    if (device.getDeviceClass(), device.getDeviceSubClass(), device.getDeviceProtocol()) == USB_BT_HCI_CLASS_TUPLE:
+        return True
+
+    # If the device class is 'Device', look for a matching interface
+    if device.getDeviceClass() == USB_DEVICE_CLASS_DEVICE:
+        for configuration in device:
+            for interface in configuration:
+                for setting in interface:
+                    if (setting.getClass(), setting.getSubClass(), setting.getProtocol()) == USB_BT_HCI_CLASS_TUPLE:
+                        return True
+
+    return False
+
+
+# -----------------------------------------------------------------------------
+def main(verbose):
     logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 
     with usb1.USBContext() as context:
@@ -91,23 +163,28 @@ def main():
 
             device_id = (device.getVendorID(), device.getProductID())
 
-            device_is_bluetooth_hci = (
-                device_class    == USB_DEVICE_CLASS_WIRELESS_CONTROLLER and
-                device_subclass == USB_DEVICE_SUBCLASS_RF_CONTROLLER and
-                device_protocol == USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+            (device_class_string, device_subclass_string) = get_class_info(
+                device_class,
+                device_subclass,
+                device_protocol
             )
 
-            device_class_details = ''
-            device_class_info    = USB_DEVICE_CLASSES.get(device_class)
-            if device_class_info is not None:
-                if type(device_class_info) is tuple:
-                    device_class = device_class_info[0]
-                    device_subclass_info = device_class_info[1].get(device_subclass)
-                    if device_subclass_info:
-                        device_class_details = f' [{device_subclass_info.get(device_protocol)}]'
-                else:
-                    device_class = device_class_info
+            try:
+                device_serial_number = device.getSerialNumber()
+            except usb1.USBError:
+                device_serial_number = None
 
+            try:
+                device_manufacturer = device.getManufacturer()
+            except usb1.USBError:
+                device_manufacturer = None
+
+            try:
+                device_product = device.getProduct()
+            except usb1.USBError:
+                device_product = None
+
+            device_is_bluetooth_hci = is_bluetooth_hci(device)
             if device_is_bluetooth_hci:
                 bluetooth_device_count += 1
                 fg_color = 'black'
@@ -123,35 +200,42 @@ def main():
             if device_is_bluetooth_hci:
                 bumble_transport_names.append(f'usb:{bluetooth_device_count - 1}')
 
-            serial_number_collision = False
-            if device_id in devices:
-                for device_serial in devices[device_id]:
-                    if device_serial == device.getSerialNumber():
-                        serial_number_collision = True
-
             if device_id not in devices:
                 bumble_transport_names.append(basic_transport_name)
             else:
                 bumble_transport_names.append(f'{basic_transport_name}#{len(devices[device_id])}')
 
-            if device.getSerialNumber() and not serial_number_collision:
-                bumble_transport_names.append(f'{basic_transport_name}/{device.getSerialNumber()}')
+            if device_serial_number is not None:
+                if device_id not in devices or device_serial_number not in devices[device_id]:
+                    bumble_transport_names.append(f'{basic_transport_name}/{device_serial_number}')
 
+            # Print the results
             print(color(f'ID {device.getVendorID():04X}:{device.getProductID():04X}', fg=fg_color, bg=bg_color))
             if bumble_transport_names:
                 print(color('  Bumble Transport Names:', 'blue'), ' or '.join(color(x, 'cyan' if device_is_bluetooth_hci else 'red') for x in bumble_transport_names))
             print(color('  Bus/Device:            ', 'green'), f'{device.getBusNumber():03}/{device.getDeviceAddress():03}')
-            if device.getSerialNumber():
-                print(color('  Serial:                ', 'green'), device.getSerialNumber())
-            print(color('  Class:                 ', 'green'), device_class)
-            print(color('  Subclass/Protocol:     ', 'green'), f'{device_subclass}/{device_protocol}{device_class_details}')
-            print(color('  Manufacturer:          ', 'green'), device.getManufacturer())
-            print(color('  Product:               ', 'green'), device.getProduct())
+            print(color('  Class:                 ', 'green'), device_class_string)
+            print(color('  Subclass/Protocol:     ', 'green'), device_subclass_string)
+            if device_serial_number is not None:
+                print(color('  Serial:                ', 'green'), device_serial_number)
+            if device_manufacturer is not None:
+                print(color('  Manufacturer:          ', 'green'), device_manufacturer)
+            if device_product is not None:
+                print(color('  Product:               ', 'green'), device_product)
+
+            if verbose:
+                show_device_details(device)
+
             print()
 
-            devices.setdefault(device_id, []).append(device.getSerialNumber())
+            devices.setdefault(device_id, []).append(device_serial_number)
 
 
 # -----------------------------------------------------------------------------
 if __name__ == '__main__':
-    main()
+    if len(sys.argv) == 2 and sys.argv[1] == '--verbose':
+        verbose = True
+    else:
+        verbose = False
+
+    main(verbose)

bumble/gatt_client.py

@@ -163,7 +163,6 @@ class ProfileServiceProxy:
 class Client:
     def __init__(self, connection):
         self.connection               = connection
-        self.mtu                      = ATT_DEFAULT_MTU
         self.mtu_exchange_done        = False
         self.request_semaphore        = asyncio.Semaphore(1)
         self.pending_request          = None
@@ -217,7 +216,7 @@ class Client:
 
         # We can only send one request per connection
         if self.mtu_exchange_done:
-            return
+            return self.connection.att_mtu
 
         # Send the request
         self.mtu_exchange_done = True
@@ -230,8 +229,10 @@ class Client:
                 response
             )
 
-        self.mtu = max(ATT_DEFAULT_MTU, response.server_rx_mtu)
-        return self.mtu
+        # Compute the final MTU
+        self.connection.att_mtu = min(mtu, response.server_rx_mtu)
+
+        return self.connection.att_mtu
 
     def get_services_by_uuid(self, uuid):
         return [service for service in self.services if service.uuid == uuid]
@@ -629,7 +630,7 @@ class Client:
         # If the value is the max size for the MTU, try to read more unless the caller
         # specifically asked not to do that
         attribute_value = response.attribute_value
-        if not no_long_read and len(attribute_value) == self.mtu - 1:
+        if not no_long_read and len(attribute_value) == self.connection.att_mtu - 1:
             logger.debug('using READ BLOB to get the rest of the value')
             offset = len(attribute_value)
             while True:
@@ -651,7 +652,7 @@ class Client:
                 part = response.part_attribute_value
                 attribute_value += part
 
-                if len(part) < self.mtu - 1:
+                if len(part) < self.connection.att_mtu - 1:
                     break
 
                 offset += len(part)

bumble/gatt_server.py

@@ -40,6 +40,12 @@ from .gatt import *
 logger = logging.getLogger(__name__)
 
 
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+GATT_SERVER_DEFAULT_MAX_MTU = 517
+
+
 # -----------------------------------------------------------------------------
 # GATT Server
 # -----------------------------------------------------------------------------
@@ -49,9 +55,8 @@ class Server(EventEmitter):
         self.device                = device
         self.attributes            = []  # Attributes, ordered by increasing handle values
         self.attributes_by_handle  = {}  # Map for fast attribute access by handle
-        self.max_mtu               = 23  # FIXME: 517  # The max MTU we're willing to negotiate
+        self.max_mtu               = GATT_SERVER_DEFAULT_MAX_MTU  # The max MTU we're willing to negotiate
         self.subscribers           = {}  # Map of subscriber states by connection handle and attribute handle
-        self.mtus                  = {}  # Map of ATT MTU values by connection handle
         self.indication_semaphores = defaultdict(lambda: asyncio.Semaphore(1))
         self.pending_confirmations = defaultdict(lambda: None)
 
@@ -188,9 +193,8 @@ class Server(EventEmitter):
         value = attribute.read_value(connection) if value is None else attribute.encode_value(value)
 
         # Truncate if needed
-        mtu = self.get_mtu(connection)
-        if len(value) > mtu - 3:
-            value = value[:mtu - 3]
+        if len(value) > connection.att_mtu - 3:
+            value = value[:connection.att_mtu - 3]
 
         # Notify
         notification = ATT_Handle_Value_Notification(
@@ -219,9 +223,8 @@ class Server(EventEmitter):
         value = attribute.read_value(connection) if value is None else attribute.encode_value(value)
 
         # Truncate if needed
-        mtu = self.get_mtu(connection)
-        if len(value) > mtu - 3:
-            value = value[:mtu - 3]
+        if len(value) > connection.att_mtu - 3:
+            value = value[:connection.att_mtu - 3]
 
         # Indicate
         indication = ATT_Handle_Value_Indication(
@@ -272,8 +275,6 @@ class Server(EventEmitter):
         return await self.notify_or_indicate_subscribers(True, attribute, value, force)
 
     def on_disconnection(self, connection):
-        if connection.handle in self.mtus:
-            del self.mtus[connection.handle]
         if connection.handle in self.subscribers:
             del self.subscribers[connection.handle]
         if connection.handle in self.indication_semaphores:
@@ -314,9 +315,6 @@ class Server(EventEmitter):
                 # Just ignore
                 logger.warning(f'{color("--- Ignoring GATT Request from [0x{connection.handle:04X}]:", "red")}  {att_pdu}')
 
-    def get_mtu(self, connection):
-        return self.mtus.get(connection.handle, ATT_DEFAULT_MTU)
-
     #######################################################
     # ATT handlers
     #######################################################
@@ -336,12 +334,16 @@ class Server(EventEmitter):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.2.1 Exchange MTU Request
         '''
-        mtu = max(ATT_DEFAULT_MTU, min(self.max_mtu, request.client_rx_mtu))
-        self.mtus[connection.handle] = mtu
-        self.send_response(connection, ATT_Exchange_MTU_Response(server_rx_mtu = mtu))
+        self.send_response(connection, ATT_Exchange_MTU_Response(server_rx_mtu = self.max_mtu))
 
-        # Notify the device
-        self.device.on_connection_att_mtu_update(connection.handle, mtu)
+        # Compute the final MTU
+        if request.client_rx_mtu >= ATT_DEFAULT_MTU:
+            mtu = min(self.max_mtu, request.client_rx_mtu)
+
+            # Notify the device
+            self.device.on_connection_att_mtu_update(connection.handle, mtu)
+        else:
+            logger.warning('invalid client_rx_mtu received, MTU not changed')
 
     def on_att_find_information_request(self, connection, request):
         '''
@@ -358,7 +360,7 @@ class Server(EventEmitter):
             return
 
         # Build list of returned attributes
-        pdu_space_available = self.get_mtu(connection) - 2
+        pdu_space_available = connection.att_mtu - 2
         attributes = []
         uuid_size = 0
         for attribute in (
@@ -409,7 +411,7 @@ class Server(EventEmitter):
         '''
 
         # Build list of returned attributes
-        pdu_space_available = self.get_mtu(connection) - 2
+        pdu_space_available = connection.att_mtu - 2
         attributes = []
         for attribute in (
             attribute for attribute in self.attributes if
@@ -457,8 +459,7 @@ class Server(EventEmitter):
         See Bluetooth spec Vol 3, Part F - 3.4.4.1 Read By Type Request
         '''
 
-        mtu = self.get_mtu(connection)
-        pdu_space_available = mtu - 2
+        pdu_space_available = connection.att_mtu - 2
         attributes = []
         for attribute in (
             attribute for attribute in self.attributes if
@@ -471,7 +472,7 @@ class Server(EventEmitter):
 
             # Check the attribute value size
             attribute_value = attribute.read_value(connection)
-            max_attribute_size = min(mtu - 4, 253)
+            max_attribute_size = min(connection.att_mtu - 4, 253)
             if len(attribute_value) > max_attribute_size:
                 # We need to truncate
                 attribute_value = attribute_value[:max_attribute_size]
@@ -511,7 +512,7 @@ class Server(EventEmitter):
         if attribute := self.get_attribute(request.attribute_handle):
             # TODO: check permissions
             value = attribute.read_value(connection)
-            value_size = min(self.get_mtu(connection) - 1, len(value))
+            value_size = min(connection.att_mtu - 1, len(value))
             response = ATT_Read_Response(
                 attribute_value = value[:value_size]
             )
@@ -530,7 +531,6 @@ class Server(EventEmitter):
 
         if attribute := self.get_attribute(request.attribute_handle):
             # TODO: check permissions
-            mtu = self.get_mtu(connection)
             value = attribute.read_value(connection)
             if request.value_offset > len(value):
                 response = ATT_Error_Response(
@@ -538,14 +538,14 @@ class Server(EventEmitter):
                     attribute_handle_in_error = request.attribute_handle,
                     error_code                = ATT_INVALID_OFFSET_ERROR
                 )
-            elif len(value) <= mtu - 1:
+            elif len(value) <= connection.att_mtu - 1:
                 response = ATT_Error_Response(
                     request_opcode_in_error   = request.op_code,
                     attribute_handle_in_error = request.attribute_handle,
                     error_code                = ATT_ATTRIBUTE_NOT_LONG_ERROR
                 )
             else:
-                part_size = min(mtu - 1, len(value) - request.value_offset)
+                part_size = min(connection.att_mtu - 1, len(value) - request.value_offset)
                 response = ATT_Read_Blob_Response(
                     part_attribute_value = value[request.value_offset:request.value_offset + part_size]
                 )
@@ -574,8 +574,7 @@ class Server(EventEmitter):
             self.send_response(connection, response)
             return
 
-        mtu = self.get_mtu(connection)
-        pdu_space_available = mtu - 2
+        pdu_space_available = connection.att_mtu - 2
         attributes = []
         for attribute in (
             attribute for attribute in self.attributes if
@@ -586,7 +585,7 @@ class Server(EventEmitter):
         ):
             # Check the attribute value size
             attribute_value = attribute.read_value(connection)
-            max_attribute_size = min(mtu - 6, 251)
+            max_attribute_size = min(connection.att_mtu - 6, 251)
             if len(attribute_value) > max_attribute_size:
                 # We need to truncate
                 attribute_value = attribute_value[:max_attribute_size]

bumble/transport/usb.py

@@ -36,7 +36,7 @@ logger = logging.getLogger(__name__)
 async def open_usb_transport(spec):
     '''
     Open a USB transport.
-    The parameter string has this syntax:
+    The moniker string has this syntax:
     either <index> or
     <vendor>:<product> or
     <vendor>:<product>/<serial-number>] or
@@ -47,27 +47,40 @@ async def open_usb_transport(spec):
     /<serial-number> suffix or #<index> suffix max be specified when more than one device with
     the same vendor and product identifiers are present.
 
+    In addition, if the moniker ends with the symbol "!", the device will be used in "forced" mode:
+    the first USB interface of the device will be used, regardless of the interface class/subclass.
+    This may be useful for some devices that use a custom class/subclass but may nonetheless work as-is.
+
     Examples:
     0 --> the first BT USB dongle
     04b4:f901 --> the BT USB dongle with vendor=04b4 and product=f901
     04b4:f901#2 --> the third USB device with vendor=04b4 and product=f901
     04b4:f901/00E04C239987 --> the BT USB dongle with vendor=04b4 and product=f901 and serial number 00E04C239987
+    usb:0B05:17CB! --> the BT USB dongle vendor=0B05 and product=17CB, in "forced" mode.
     '''
 
     USB_RECIPIENT_DEVICE                             = 0x00
     USB_REQUEST_TYPE_CLASS                           = 0x01 << 5
-    USB_ENDPOINT_EVENTS_IN                           = 0x81
-    USB_ENDPOINT_ACL_IN                              = 0x82
-    USB_ENDPOINT_ACL_OUT                             = 0x02
+    USB_DEVICE_CLASS_DEVICE                          = 0x00
     USB_DEVICE_CLASS_WIRELESS_CONTROLLER             = 0xE0
     USB_DEVICE_SUBCLASS_RF_CONTROLLER                = 0x01
     USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER = 0x01
+    USB_ENDPOINT_TRANSFER_TYPE_BULK                  = 0x02
+    USB_ENDPOINT_TRANSFER_TYPE_INTERRUPT             = 0x03
+    USB_ENDPOINT_IN                                  = 0x80
+
+    USB_BT_HCI_CLASS_TUPLE = (
+        USB_DEVICE_CLASS_WIRELESS_CONTROLLER,
+        USB_DEVICE_SUBCLASS_RF_CONTROLLER,
+        USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+    )
 
     READ_SIZE = 1024
 
     class UsbPacketSink:
-        def __init__(self, device):
+        def __init__(self, device, acl_out):
             self.device      = device
+            self.acl_out     = acl_out
             self.transfer    = device.getTransfer()
             self.packets     = collections.deque()  # Queue of packets waiting to be sent
             self.loop        = asyncio.get_running_loop()
@@ -116,7 +129,7 @@ async def open_usb_transport(spec):
             packet_type = packet[0]
             if packet_type == hci.HCI_ACL_DATA_PACKET:
                 self.transfer.setBulk(
-                    USB_ENDPOINT_ACL_OUT,
+                    self.acl_out,
                     packet[1:],
                     callback=self.on_packet_sent
                 )
@@ -152,10 +165,12 @@ async def open_usb_transport(spec):
                     logger.debug('OUT transfer likely already completed')
 
     class UsbPacketSource(asyncio.Protocol, ParserSource):
-        def __init__(self, context, device):
+        def __init__(self, context, device, acl_in, events_in):
             super().__init__()
             self.context         = context
             self.device          = device
+            self.acl_in          = acl_in
+            self.events_in       = events_in
             self.loop            = asyncio.get_running_loop()
             self.queue           = asyncio.Queue()
             self.closed          = False
@@ -172,7 +187,7 @@ async def open_usb_transport(spec):
             # Set up transfer objects for input
             self.events_in_transfer = device.getTransfer()
             self.events_in_transfer.setInterrupt(
-                USB_ENDPOINT_EVENTS_IN,
+                self.events_in,
                 READ_SIZE,
                 callback=self.on_packet_received,
                 user_data=hci.HCI_EVENT_PACKET
@@ -181,7 +196,7 @@ async def open_usb_transport(spec):
 
             self.acl_in_transfer = device.getTransfer()
             self.acl_in_transfer.setBulk(
-                USB_ENDPOINT_ACL_IN,
+                self.acl_in,
                 READ_SIZE,
                 callback=self.on_packet_received,
                 user_data=hci.HCI_ACL_DATA_PACKET
@@ -248,7 +263,7 @@ async def open_usb_transport(spec):
             await self.event_loop_done
 
     class UsbTransport(Transport):
-        def __init__(self, context, device, interface, source, sink):
+        def __init__(self, context, device, interface, setting, source, sink):
             super().__init__(source, sink)
             self.context   = context
             self.device    = device
@@ -257,6 +272,10 @@ async def open_usb_transport(spec):
             # Get exclusive access
             device.claimInterface(interface)
 
+            # Set the alternate setting if not the default
+            if setting != 0:
+                device.setInterfaceAltSetting(interface, setting)
+
             # The source and sink can now start
             source.start()
             sink.start()
@@ -273,6 +292,13 @@ async def open_usb_transport(spec):
     context.open()
     try:
         found = None
+
+        if spec.endswith('!'):
+            spec = spec[:-1]
+            forced_mode = True
+        else:
+            forced_mode = False
+
         if ':' in spec:
             vendor_id, product_id = spec.split(':')
             serial_number = None
@@ -284,10 +310,14 @@ async def open_usb_transport(spec):
                 device_index = int(device_index_str)
 
             for device in context.getDeviceIterator(skip_on_error=True):
+                try:
+                    device_serial_number = device.getSerialNumber()
+                except usb1.USBError:
+                    device_serial_number = None
                 if (
                     device.getVendorID() == int(vendor_id, 16) and
                     device.getProductID() == int(product_id, 16) and
-                    (serial_number is None or device.getSerialNumber() == serial_number)
+                    (serial_number is None or serial_number == device_serial_number)
                 ):
                     if device_index == 0:
                         found = device
@@ -295,13 +325,27 @@ async def open_usb_transport(spec):
                     device_index -= 1
                 device.close()
         else:
+            # Look for a compatible device by index
+            def device_is_bluetooth_hci(device):
+                # Check if the device class indicates a match
+                if (device.getDeviceClass(), device.getDeviceSubClass(), device.getDeviceProtocol()) == \
+                        USB_BT_HCI_CLASS_TUPLE:
+                    return True
+
+                # If the device class is 'Device', look for a matching interface
+                if device.getDeviceClass() == USB_DEVICE_CLASS_DEVICE:
+                    for configuration in device:
+                        for interface in configuration:
+                            for setting in interface:
+                                if (setting.getClass(), setting.getSubClass(), setting.getProtocol()) == \
+                                        USB_BT_HCI_CLASS_TUPLE:
+                                    return True
+
+                return False
+
             device_index = int(spec)
             for device in context.getDeviceIterator(skip_on_error=True):
-                if (
-                    device.getDeviceClass()    == USB_DEVICE_CLASS_WIRELESS_CONTROLLER and
-                    device.getDeviceSubClass() == USB_DEVICE_SUBCLASS_RF_CONTROLLER and
-                    device.getDeviceProtocol() == USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
-                ):
+                if device_is_bluetooth_hci(device):
                     if device_index == 0:
                         found = device
                         break
@@ -313,10 +357,62 @@ async def open_usb_transport(spec):
             raise ValueError('device not found')
 
         logger.debug(f'USB Device: {found}')
-        device = found.open()
 
-        # Use the first interface
-        interface = 0
+        # Look for the first interface with the right class and endpoints
+        def find_endpoints(device):
+            for (configuration_index, configuration) in enumerate(device):
+                interface = None
+                for interface in configuration:
+                    setting = None
+                    for setting in interface:
+                        if (
+                            not forced_mode and
+                            (setting.getClass(), setting.getSubClass(), setting.getProtocol()) != USB_BT_HCI_CLASS_TUPLE
+                        ):
+                            continue
+
+                        events_in = None
+                        acl_in    = None
+                        acl_out   = None
+                        for endpoint in setting:
+                            attributes = endpoint.getAttributes()
+                            address    = endpoint.getAddress()
+                            if attributes & 0x03 == USB_ENDPOINT_TRANSFER_TYPE_BULK:
+                                if address & USB_ENDPOINT_IN and acl_in is None:
+                                    acl_in = address
+                                elif acl_out is None:
+                                    acl_out = address
+                            elif attributes & 0x03 == USB_ENDPOINT_TRANSFER_TYPE_INTERRUPT:
+                                if address & USB_ENDPOINT_IN and events_in is None:
+                                    events_in = address
+
+                        # Return if we found all 3 endpoints
+                        if acl_in is not None and acl_out is not None and events_in is not None:
+                            return (
+                                configuration_index + 1,
+                                setting.getNumber(),
+                                setting.getAlternateSetting(),
+                                acl_in,
+                                acl_out,
+                                events_in
+                            )
+                        else:
+                            logger.debug(f'skipping configuration {configuration_index + 1} / interface {setting.getNumber()}')
+
+        endpoints = find_endpoints(found)
+        if endpoints is None:
+            raise ValueError('no compatible interface found for device')
+        (configuration, interface, setting, acl_in, acl_out, events_in) = endpoints
+        logger.debug(
+            f'selected endpoints: configuration={configuration}, '
+            f'interface={interface}, '
+            f'setting={setting}, '
+            f'acl_in=0x{acl_in:02X}, '
+            f'acl_out=0x{acl_out:02X}, '
+            f'events_in=0x{events_in:02X}, '
+        )
+
+        device = found.open()
 
         # Detach the kernel driver if supported and needed
         if usb1.hasCapability(usb1.CAP_SUPPORTS_DETACH_KERNEL_DRIVER):
@@ -329,21 +425,21 @@ async def open_usb_transport(spec):
 
         # Set the configuration if needed
         try:
-            configuration = device.getConfiguration()
-            logger.debug(f'current configuration = {configuration}')
+            current_configuration = device.getConfiguration()
+            logger.debug(f'current configuration = {current_configuration}')
         except usb1.USBError:
-            configuration = 0
+            current_configuration = 0
 
-        if configuration != 1:
+        if current_configuration != configuration:
             try:
-                logger.debug('setting configuration 1')
-                device.setConfiguration(1)
+                logger.debug(f'setting configuration {configuration}')
+                device.setConfiguration(configuration)
             except usb1.USBError:
-                logger.warning('failed to set configuration 1')
+                logger.warning('failed to set configuration')
 
-        source = UsbPacketSource(context, device)
-        sink   = UsbPacketSink(device)
-        return UsbTransport(context, device, interface, source, sink)
+        source = UsbPacketSource(context, device, acl_in, events_in)
+        sink   = UsbPacketSink(device, acl_out)
+        return UsbTransport(context, device, interface, setting, source, sink)
     except usb1.USBError as error:
         logger.warning(color(f'!!! failed to open USB device: {error}', 'red'))
         context.close()

docs/mkdocs/mkdocs.yml

@@ -45,6 +45,10 @@ nav:
     - HCI Bridge: apps_and_tools/hci_bridge.md
     - Golden Gate Bridge: apps_and_tools/gg_bridge.md
     - Show: apps_and_tools/show.md
+    - GATT Dump: apps_and_tools/gatt_dump.md
+    - Pair: apps_and_tools/pair.md
+    - Unbond: apps_and_tools/unbond.md
+    - USB Probe: apps_and_tools/usb_probe.md
   - Hardware:
     - Overview: hardware/index.md
   - Platforms:

docs/mkdocs/src/apps_and_tools/usb_probe.md

@@ -13,17 +13,29 @@ type of device (there's no way to tell).
 
 ## Usage
 
-This command line tool takes no arguments.
+This command line tool may be invoked with no arguments, or with `--verbose`
+for extra details.
 When installed from PyPI, run as
 ```
 $ bumble-usb-probe
 ```
 
+or, for extra details, with the `--verbose` argument
+```
+$ bumble-usb-probe --v
+```
+
 When running from the source distribution:
 ```
 $ python3 apps/usb-probe.py
 ```
 
+or 
+
+```
+$ python3 apps/usb-probe.py --verbose
+```
+
 !!! example
     ```
     $ python3 apps/usb_probe.py 

docs/mkdocs/src/transports/usb.md

@@ -5,6 +5,7 @@ The USB transport interfaces with a local Bluetooth USB dongle.
 
 ## Moniker
 The moniker for a USB transport is either:
+
   * `usb:<index>`
   * `usb:<vendor>:<product>`
   * `usb:<vendor>:<product>/<serial-number>`
@@ -16,6 +17,10 @@ In the `usb:<vendor>:<product>#<index>` form, matching devices are the ones with
 
 `<vendor>` and `<product>` are a vendor ID and product ID in hexadecimal.
 
+In addition, if the moniker ends with the symbol "!", the device will be used in "forced" mode:
+the first USB interface of the device will be used, regardless of the interface class/subclass.
+This may be useful for some devices that use a custom class/subclass but may nonetheless work as-is.
+
 !!! examples
     `usb:04b4:f901`  
     The USB dongle with `<vendor>` equal to `04b4` and `<product>` equal to `f901`
@@ -29,6 +34,10 @@ In the `usb:<vendor>:<product>#<index>` form, matching devices are the ones with
     `usb:04b4:f901/#1`
     The second USB dongle with `<vendor>` equal to `04b4` and `<product>` equal to `f901`
 
+    `usb:0B05:17CB!`
+    The BT USB dongle vendor=0B05 and product=17CB, in "forced" mode.
+
+
 ## Alternative
 The library includes two different implementations of the USB transport, implemented using different python bindings for `libusb`.
 Using the transport prefix `pyusb:` instead of `usb:` selects the implementation based on  [PyUSB](https://pypi.org/project/pyusb/), using the synchronous API of `libusb`, whereas the default implementation is based on [libusb1](https://pypi.org/project/libusb1/), using the asynchronous API of `libusb`. In order to use the alternative PyUSB-based implementation, you need to ensure that you have installed that python module, as it isn't installed by default as a dependency of Bumble.

tests/gatt_test.py

@@ -131,7 +131,7 @@ async def test_characteristic_encoding():
         def decode_value(self, value_bytes):
             return value_bytes[0]
 
-    [client, server] = TwoDevices().devices
+    [client, server] = LinkedDevices().devices[:2]
 
     characteristic = Characteristic(
         'FDB159DB-036C-49E3-B3DB-6325AC750806',
@@ -306,14 +306,15 @@ def test_CharacteristicValue():
 
 
 # -----------------------------------------------------------------------------
-class TwoDevices:
+class LinkedDevices:
     def __init__(self):
-        self.connections = [None, None]
+        self.connections = [None, None, None]
 
         self.link = LocalLink()
         self.controllers = [
             Controller('C1', link = self.link),
-            Controller('C2', link = self.link)
+            Controller('C2', link = self.link),
+            Controller('C3', link = self.link)
         ]
         self.devices = [
             Device(
@@ -321,12 +322,16 @@ class TwoDevices:
                 host    = Host(self.controllers[0], AsyncPipeSink(self.controllers[0]))
             ),
             Device(
-                address = 'F5:F4:F3:F2:F1:F0',
+                address = 'F1:F2:F3:F4:F5:F6',
                 host    = Host(self.controllers[1], AsyncPipeSink(self.controllers[1]))
+            ),
+            Device(
+                address = 'F2:F3:F4:F5:F6:F7',
+                host    = Host(self.controllers[2], AsyncPipeSink(self.controllers[2]))
             )
         ]
 
-        self.paired = [None, None]
+        self.paired = [None, None, None]
 
 
 # -----------------------------------------------------------------------------
@@ -339,7 +344,7 @@ async def async_barrier():
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
 async def test_read_write():
-    [client, server] = TwoDevices().devices
+    [client, server] = LinkedDevices().devices[:2]
 
     characteristic1 = Characteristic(
         'FDB159DB-036C-49E3-B3DB-6325AC750806',
@@ -416,7 +421,7 @@ async def test_read_write():
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
 async def test_read_write2():
-    [client, server] = TwoDevices().devices
+    [client, server] = LinkedDevices().devices[:2]
 
     v = bytes([0x11, 0x22, 0x33, 0x44])
     characteristic1 = Characteristic(
@@ -466,7 +471,7 @@ async def test_read_write2():
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
 async def test_subscribe_notify():
-    [client, server] = TwoDevices().devices
+    [client, server] = LinkedDevices().devices[:2]
 
     characteristic1 = Characteristic(
         'FDB159DB-036C-49E3-B3DB-6325AC750806',
@@ -631,12 +636,49 @@ async def test_subscribe_notify():
     assert not c3._called_2
 
 
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_mtu_exchange():
+    [d1, d2, d3] = LinkedDevices().devices[:3]
+
+    d3.gatt_server.max_mtu = 100
+
+    d3_connections = []
+    @d3.on('connection')
+    def on_d3_connection(connection):
+        d3_connections.append(connection)
+
+    await d1.power_on()
+    await d2.power_on()
+    await d3.power_on()
+
+    d1_connection = await d1.connect(d3.random_address)
+    assert len(d3_connections) == 1
+    assert d3_connections[0] is not None
+
+    d2_connection = await d2.connect(d3.random_address)
+    assert len(d3_connections) == 2
+    assert d3_connections[1] is not None
+
+    d1_peer = Peer(d1_connection)
+    d2_peer = Peer(d2_connection)
+
+    d1_client_mtu = await d1_peer.request_mtu(220)
+    assert d1_client_mtu == 100
+    assert d1_connection.att_mtu == 100
+
+    d2_client_mtu = await d2_peer.request_mtu(50)
+    assert d2_client_mtu == 50
+    assert d2_connection.att_mtu == 50
+
+
 # -----------------------------------------------------------------------------
 async def async_main():
     await test_read_write()
     await test_read_write2()
     await test_subscribe_notify()
     await test_characteristic_encoding()
+    await test_mtu_exchange()
 
 
 # -----------------------------------------------------------------------------