1# BTstack Port for POSIX Systems with libusb Library 2 3## Compilation 4The quickest way to try BTstack is on a Linux or OS X system with an 5additional USB Bluetooth dongle. It requires 6[pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/) 7and [libusb-1.0](http://libusb.info) or higher to be 8installed. 9 10On a recent Debian-based system, all you need is: 11 12 sudo apt-get install gcc git cmake ninja-build pkg-config libusb-1.0 portaudio19-dev 13 14 15When everything is ready, you compile all examples with make: 16 17 make 18 19or using CMake + Ninja: 20 21 mkdir build 22 cd build 23 cmake -G Ninja .. 24 ninja 25 26## Environment Setup 27 28### Linux 29 30On Linux, the USB Bluetooth dongle is usually not accessible to a regular user. 31 32You can add a udev rule for your dongle to extend access rights to user processes. 33 34For this, create `/etc/udev/rules.d/btstack.rules` and add this 35 36 # Match all devices from CSR 37 SUBSYSTEM=="usb", ATTRS{idVendor}=="0a12", MODE="0666" 38 39 # Match all devices from Realtek 40 SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", MODE="0666" 41 42 # Match Cypress Semiconductor / Broadcom BCM20702A, e.g. DeLOCK Bluetooth 4.0 dongle 43 SUBSYSTEM=="usb", ATTRS{idVendor}=="0a5c", ATTRS{idProduct}=="21e8", MODE="0666" 44 45 # Match Asus BT400 46 SUBSYSTEM=="usb", ATTRS{idVendor}=="0b05", ATTRS{idProduct}=="17cb", MODE="0666" 47 48 # Match Laird BT860 / Cypress Semiconductor CYW20704A2 49 SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{idProduct}=="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### Broadcom/Cypress/Infineon Controllers 71During startup BTstack queries the Controlle for the Local Name, which is set to the Controller type (e.g. 'BCM20702A). 72The chipset support uses this information to look for a local PatchRAM file of that name and uploads it. 73 74### Realtek Controllers 75During startup, the libusb HCI transport implementations reports the USB Vendor/Product ID, which is then forwarded to the Realtek chipset support. 76The chipset support contains a mapping between USB Product ID and ( Patch, Configuration ) files. If found, these are 77uploaded. 78 79 80## Running the examples 81 82BTstack's HCI USB transport will try to find a suitable Bluetooth module and use it. 83 84On 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. 85 86 $ ./le_counter 87 Packet Log: /tmp/hci_dump.pklg 88 BTstack counter 0001 89 Packet Log: /tmp/hci_dump_6.pklg 90 USB device 0x0a12/0x0001, path: 06 91 Local version information: 92 - HCI Version 0x0006 93 - HCI Revision 0x22bb 94 - LMP Version 0x0006 95 - LMP Subversion 0x22bb 96 - Manufacturer 0x000a 97 BTstack up and running on 00:1A:7D:DA:71:01. 98 99If 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. 100 101Example running le_streamer and le_streamer_client in two processes, using CSR Bluetooth dongles at USB path 6 and 4: 102 103 ./le_streamer -u 6 104 Specified USB Path: 06 105 Packet Log: /tmp/hci_dump_6.pklg 106 USB device 0x0a12/0x0001, path: 06 107 Local version information: 108 - HCI Version 0x0006 109 - HCI Revision 0x22bb 110 - LMP Version 0x0006 111 - LMP Subversion 0x22bb 112 - Manufacturer 0x000a 113 BTstack up and running on 00:1A:7D:DA:71:01. 114 To start the streaming, please run the le_streamer_client example on other device, or use some GATT Explorer, e.g. LightBlue, BLExplr. 115 116 $ ./le_streamer_client -u 4 117 Specified USB Path: 04 118 Packet Log: /tmp/hci_dump_4.pklg 119 USB device 0x0a12/0x0001, path: 04 120 Local version information: 121 - HCI Version 0x0006 122 - HCI Revision 0x22bb 123 - LMP Version 0x0006 124 - LMP Subversion 0x22bb 125 - Manufacturer 0x000a 126 BTstack up and running on 00:1A:7D:DA:71:02. 127 Start scanning! 128