Skip to content

Latest commit

 

History

History
79 lines (53 loc) · 3.53 KB

usb.md

File metadata and controls

79 lines (53 loc) · 3.53 KB

USB TRANSPORT

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>
  • usb:<vendor>:<product>#<index>
  • usb:<bus>-<port_numbers>

with <index> as a 0-based index (0 being the first one) to select amongst all the matching devices when there are more than one. In the usb:<index> form, matching devices are the ones supporting Bluetooth HCI, as declared by their Class, Subclass and Protocol. In the usb:<vendor>:<product>#<index> form, matching devices are the ones with the specified <vendor> and <product> identification.

<vendor> and <product> are a vendor ID and product ID in hexadecimal.

with <port_numbers> as a list of all port numbers from root separated with dots .

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

`usb:0`
The first Bluetooth HCI dongle that's declared as such by Class/Subclass/Protocol

`usb:04b4:f901/0016A45B05D8`
The USB dongle with `<vendor>` equal to `04b4`, `<product>` equal to `f901` and `<serial>` equal to `0016A45B05D8`

`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.

`usb:3-3.4.1`
The BT USB dongle on bus 3 on port path 3, 4, 1.

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, using the synchronous API of libusb, whereas the default implementation is based on 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.

Libusb

The libusb-1.0 shared library is required to use both usb and pyusb transports. This library should be installed automatically with Bumble, as part of the libusb_package Python package. If your OS or architecture is not supported by libusb_package, you can install a system-wide library with brew install libusb for Mac or apt install libusb-1.0-0 for Linux.

Listing Available USB Devices

With usb_probe

You can use the usb_probe tool to list all the USB devices attached to your host computer. The tool will also show the usb:XXX transport name(s) you can use to reference each device.

With lsusb

On Linux and macOS, the lsusb tool serves a similar purpose to Bumble's own usb_probe tool (without the Bumble specifics)

Installing lsusb

On Mac: brew install lsusb On Linux: sudo apt-get install usbutils

Using lsusb

$ lsusb
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 014: ID 0b05:17cb ASUSTek Computer, Inc. Broadcom BCM20702A0 Bluetooth

The device id for the Bluetooth interface in this case is 0b05:17cb.