README.md
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