1USB TRANSPORT
2=============
3
4The USB transport interfaces with a local Bluetooth USB dongle.
5
6## Moniker
7The moniker for a USB transport is either:
8
9  * `usb:<index>`
10  * `usb:<vendor>:<product>`
11  * `usb:<vendor>:<product>/<serial-number>`
12  * `usb:<vendor>:<product>#<index>`
13  * `usb:<bus>-<port_numbers>`
14
15with `<index>` as a 0-based index (0 being the first one) to select amongst all the matching devices when there are more than one.
16In the `usb:<index>` form, matching devices are the ones supporting Bluetooth HCI, as declared by their Class, Subclass and Protocol.
17In the `usb:<vendor>:<product>#<index>` form, matching devices are the ones with the specified `<vendor>` and `<product>` identification.
18
19`<vendor>` and `<product>` are a vendor ID and product ID in hexadecimal.
20
21with `<port_numbers>` as a list of all port numbers from root separated with dots `.`
22
23In addition, if the moniker ends with the symbol "!", the device will be used in "forced" mode:
24the first USB interface of the device will be used, regardless of the interface class/subclass.
25This may be useful for some devices that use a custom class/subclass but may nonetheless work as-is.
26
27!!! examples
28    `usb:04b4:f901`
29    The USB dongle with `<vendor>` equal to `04b4` and `<product>` equal to `f901`
30
31    `usb:0`
32    The first Bluetooth HCI dongle that's declared as such by Class/Subclass/Protocol
33
34    `usb:04b4:f901/0016A45B05D8`
35    The USB dongle with `<vendor>` equal to `04b4`, `<product>` equal to `f901` and `<serial>` equal to `0016A45B05D8`
36
37    `usb:04b4:f901/#1`
38    The second USB dongle with `<vendor>` equal to `04b4` and `<product>` equal to `f901`
39
40    `usb:0B05:17CB!`
41    The BT USB dongle vendor=0B05 and product=17CB, in "forced" mode.
42
43    `usb:3-3.4.1`
44    The BT USB dongle on bus 3 on port path 3, 4, 1.
45
46
47## Alternative
48The library includes two different implementations of the USB transport, implemented using different python bindings for `libusb`.
49Using 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.
50
51## Libusb
52
53The `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.
54If 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.
55
56## Listing Available USB Devices
57
58### With `usb_probe`
59You can use the [`usb_probe`](../apps_and_tools/usb_probe.md) tool to list all the USB devices attached to your host computer.
60The tool will also show the `usb:XXX` transport name(s) you can use to reference each device.
61
62
63### With `lsusb`
64On Linux and macOS, the `lsusb` tool serves a similar purpose to Bumble's own `usb_probe` tool (without the Bumble specifics)
65
66#### Installing lsusb
67
68On Mac: `brew install lsusb`
69On Linux: `sudo apt-get install usbutils`
70
71#### Using lsusb
72
73```
74$ lsusb
75Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
76Bus 003 Device 014: ID 0b05:17cb ASUSTek Computer, Inc. Broadcom BCM20702A0 Bluetooth
77```
78
79The device id for the Bluetooth interface in this case is `0b05:17cb`.
80