1# BTstack Port for QT with USB Bluetooth Dongle 2 3Uses libusb Library on macOS and Linux and WinUSB on Windows. 4Windows is supported with the MinGW Kit. 5 6Windows with MSVC or Embedded (bare metal) platforms not supported yet. 7 8## Compilation 9 10On all platforms, you'll need Qt Python 3 installed. 11On macOS/Linux [libusb-1.0](http://libusb.info) or higher is required, too. 12 13When everything is ready, you can open the provided CMakelists.txt project in Qt Creator and run any of the provided examples. 14See Qt documentation on how to compile on the command line or with other IDEs 15 16## Environment Setup 17 18## Windows 19 20To allow WinUSB to access an USB Bluetooth dongle, you need to install a special device driver to make it accessible to user space processes. 21 22It works like this: 23 24- Download [Zadig](http://zadig.akeo.ie) 25- Start Zadig 26- Select Options -> “List all devices” 27- Select USB Bluetooth dongle in the big pull down list 28- Select WinUSB in the right pull down list 29- Select “Replace Driver” 30 31### Linux 32 33On Linux, the USB Bluetooth dongle is usually not accessible to a regular user. You can either: 34- run the examples as root 35- add a udev rule for your dongle to extend access rights to user processes 36 37To add an udev rule, please create `/etc/udev/rules.d/btstack.rules` and add this 38 39 # Match all devices from CSR 40 SUBSYSTEM=="usb", ATTRS{idVendor}=="0a12", MODE="0666" 41 42 # Match DeLOCK Bluetooth 4.0 dongle 43 SUBSYSTEM=="usb", ATTRS{idVendor}=="0a5c", ATTRS{device}=="21e8", MODE="0666" 44 45 # Match Asus BT400 46 SUBSYSTEM=="usb", ATTRS{idVendor}=="0b05", ATTRS{device}=="17cb", MODE="0666" 47 48 # Match Laird BT860 / Cypress Semiconductor CYW20704A2 49 SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{device}=="f901", MODE="0666" 50 51### macOS 52 53On macOS, the OS will try to use a plugged-in Bluetooth Controller if one is available. 54It's best to to tell the OS to always use the internal Bluetooth Contoller. 55 56For this, execute: 57 58 sudo nvram bluetoothHostControllerSwitchBehavior=never 59 60and then reboot to activate the change. 61 62Note: if you get this error, 63 64 libusb: warning [darwin_open] USBDeviceOpen: another process has device opened for exclusive access 65 libusb: error [darwin_reset_device] ResetDevice: device not opened for exclusive access 66 67and you didn't start another instance and you didn't assign the USB Controller to a virtual machine, 68macOS uses the plugged-in Bluetooth Controller. Please configure NVRAM as explained and try again after a reboot. 69 70 71## Running the examples 72 73BTstack's HCI USB transport will try to find a suitable Bluetooth module and use it. 74 75On start, BTstack will try to find a suitable Bluetooth module. It will also print the path to the packet log as well as the USB path. 76 77 $ ./le_counter 78 Packet Log: /tmp/hci_dump.pklg 79 BTstack counter 0001 80 USB Path: 06 81 BTstack up and running on 00:1A:7D:DA:71:13. 82 83If you want to run multiple examples at the same time, it helps to fix the path to the used Bluetooth module by passing -u usb-path to the executable. 84 85Example running le_streamer and le_streamer_client in two processes, using Bluetooth dongles at USB path 6 and 4: 86 87 ./le_streamer -u 6 88 Specified USB Path: 06 89 Packet Log: /tmp/hci_dump_6.pklg 90 USB Path: 06 91 BTstack up and running on 00:1A:7D:DA:71:13. 92 To start the streaming, please run the le_streamer_client example on other device, or use some GATT Explorer, e.g. LightBlue, BLExplr. 93 94 $ ./le_streamer_client -u 4 95 Specified USB Path: 04 96 Packet Log: /tmp/hci_dump_4.pklg 97 USB Path: 04 98 BTstack up and running on 00:1A:7D:DA:71:13. 99 Start scanning! 100