1:material-linux: LINUX PLATFORM
2===============================
3
4Using Bumble With Physical Bluetooth Controllers
5------------------------------------------------
6
7A Bumble application can interface with a local Bluetooth controller on a Linux host.
8The 3 main types of physical Bluetooth controllers are:
9
10  * Bluetooth USB Dongle
11  * HCI over  UART (via a serial port)
12  * Kernel-managed Bluetooth HCI (HCI Sockets)
13
14!!! tip "Conflicts with the kernel and BlueZ"
15    If your use a USB dongle that is recognized by your kernel as a supported Bluetooth device, it is
16    likely that the kernel driver will claim that USB device and attach it to the BlueZ stack.
17    If you want to claim ownership of it to use with Bumble, you will need to set the state of the corresponding HCI interface as `DOWN`.
18    HCI interfaces are numbered, starting from 0 (i.e `hci0`, `hci1`, ...).
19
20    For example, to bring `hci0` down:
21    ```
22    $ sudo hciconfig hci0 down
23    ```
24
25    You can use the `hciconfig` command with no arguments to get a list of HCI interfaces seen by
26    the kernel.
27
28    Also, if `bluetoothd` is running on your system, it will likely re-claim the interface after you
29    close it, so you may need to bring the interface back `UP` before using it again, or to disable
30    `bluetoothd` altogether (see the section further below about BlueZ and `bluetoothd`).
31
32### Using a USB Dongle
33
34See the [USB Transport page](../transports/usb.md) for general information on how to use HCI USB controllers.
35
36!!! tip "USB Permissions"
37    By default, when running as a regular user, you won't have the permission to use
38    arbitrary USB devices.
39    You can change the permissions for a specific USB device based on its bus number and
40    device number (you can use `lsusb` to find the Bus and Device numbers for your Bluetooth
41    dongle).
42
43    Example:
44    ```
45    $ sudo chmod o+w /dev/bus/usb/001/004
46    ```
47    This will change the permissions for Device 4 on Bus 1.
48
49    Note that the USB Bus number and Device number may change depending on where you plug the USB
50    dongle and what other USB devices and hubs are also plugged in.
51
52    If you need to make the permission changes permanent across reboots, you can create a `udev`
53    rule for your specific Bluetooth dongle. Visit [this Arch Linux Wiki page](https://wiki.archlinux.org/title/udev) for a
54    good overview of how you may do that.
55
56### Using HCI over UART
57
58See the [Serial Transport page](../transports/serial.md) for general information on how to use HCI over a UART (serial port).
59
60### Using HCI Sockets
61
62HCI sockets provide a way to send/receive HCI packets to/from a Bluetooth controller managed by the kernel.
63See the [HCI Socket Transport page](../transports/hci_socket.md) for details on the `hci-socket` tansport syntax.
64
65The HCI device referenced by an `hci-socket` transport (`hci<X>`, where `<X>` is an integer, with `hci0` being the first controller device, and so on) must be in the `DOWN` state before it can be opened as a transport.
66You can bring a HCI controller `UP` or `DOWN` with `hciconfig hci<X> up` and `hciconfig hci<X> up`.
67
68!!! tip "HCI Socket Permissions"
69    By default, when running as a regular user, you won't have the permission to use
70    an HCI socket to a Bluetooth controller (you may see an exception like `PermissionError: [Errno 1] Operation not permitted`).
71
72    If you want to run without using `sudo`, you need to manage the capabilities by adding the appropriate entries in `/etc/security/capability.conf` to grant a user or group the `cap_net_admin` capability.
73    See [this manpage](https://manpages.ubuntu.com/manpages/bionic/man5/capability.conf.5.html) for details.
74
75    Alternatively, if you are just experimenting temporarily, the `capsh` command may be useful in order
76    to execute a single command with enhanced permissions, as in this example:
77
78
79    ```
80    $ sudo capsh --caps="cap_net_admin+eip cap_setpcap,cap_setuid,cap_setgid+ep" --keep=1 --user=$USER --addamb=cap_net_admin  -- -c "<path/to/executable> <executable-args>"
81    ```
82    Where `<path/to/executable>` is the path to your `python3` executable or to one of the Bumble bundled command-line applications.
83
84!!! tip "List all available controllers"
85    The command
86    ```
87    $ hciconfig
88    ```
89    lists all available HCI controllers and their state.
90
91    Example:
92
93    ```
94    pi@raspberrypi:~ $ hciconfig
95    hci1:	Type: Primary  Bus: USB
96        BD Address: 00:16:A4:5A:40:F2  ACL MTU: 1021:8  SCO MTU: 64:1
97        DOWN
98        RX bytes:84056 acl:0 sco:0 events:51 errors:0
99        TX bytes:1980 acl:0 sco:0 commands:90 errors:0
100
101    hci0:	Type: Primary  Bus: UART
102        BD Address: DC:A6:32:75:2C:97  ACL MTU: 1021:8  SCO MTU: 64:1
103        DOWN
104        RX bytes:68038 acl:0 sco:0 events:692 errors:0
105        TX bytes:20105 acl:0 sco:0 commands:843 errors:0
106    ```
107
108!!! tip "Disabling `bluetoothd`"
109    When the Bluetooth daemon, `bluetoothd`, is running, it will try to use any HCI controller attached to the BlueZ stack, automatically. This means that whenever an HCI socket transport is released, it is likely that `bluetoothd` will take it over, so you will get a "device busy" condition (ex: `OSError: [Errno 16] Device or resource busy`). If that happens, you can always use
110    ```
111    $ hciconfig hci0 down
112    ```
113    (or `hci<X>` with `<X>` being the index of the controller device you want to use), but a simpler solution is to just stop the `bluetoothd` daemon, with a command like:
114    ```
115    $ sudo systemctl stop bluetooth.service
116    ```
117    You can always re-start the daemon with
118    ```
119    $ sudo systemctl start bluetooth.service
120
121Bumble on the Raspberry Pi
122--------------------------
123
124### Raspberry Pi 4 :fontawesome-brands-raspberry-pi:
125
126You can use the Bluetooth controller either via the kernel, or directly to the device.
127
128#### Via The Kernel
129
130Use an HCI Socket transport (see section above)
131
132#### Directly
133
134In order to use the Bluetooth controller directly on a Raspberry Pi 4 board, you need to ensure that it isn't being used by the BlueZ stack (which it probably is by default).
135
136```
137$ sudo systemctl stop hciuart
138```
139should detach the controller from the stack, after which you can use the HCI UART with Bumble.
140
141!!! tip "Check the device name for the UART and at what speed it should be opened"
142    ```
143    $ sudo systemctl status hciuart
144    ```
145    should show the speed at which the UART should be opened.
146    For example:
147    ```
148    $ sudo systemctl status hciuart
149     hciuart.service - Configure Bluetooth Modems connected by UART
150      Loaded: loaded (/lib/systemd/system/hciuart.service; enabled; vendor preset: enabled)
151      Active: active (running) since Fri 2021-06-18 02:17:28 BST; 1min 10s ago
152     Process: 357 ExecStart=/usr/bin/btuart (code=exited, status=0/SUCCESS)
153    Main PID: 586 (hciattach)
154       Tasks: 1 (limit: 4915)
155      CGroup: /system.slice/hciuart.service
156              └─586 /usr/bin/hciattach /dev/serial1 bcm43xx 3000000 flow -
157    ```
158    When run before stopping the `hciuart` service, shows that on this board, the UART device is `/dev/serial` and the speed is `3000000`
159
160!!! example "Example: scanning"
161    ```
162    python3 run_scanner.py serial:/dev/serial1,3000000
163    ```
164
165
166Using Bumble With BlueZ
167-----------------------
168
169In addition to all the standard functionality available from the project by running the python tools and/or writing your own apps by leveraging the API, it is also possible on Linux hosts to interface the Bumble stack with the native BlueZ stack, and with Bluetooth controllers.
170
171A Bumble virtual controller can be attached to the BlueZ stack.
172Attaching a controller to BlueZ can be done by either simulating a UART HCI interface, or by using the VHCI driver interface if available.
173In both cases, the controller can run locally on the Linux host, or remotely on a different host, with a bridge between the remote controller and the local BlueZ host, which may be useful when the BlueZ stack is running on an embedded system, or a host on which running the Bumble controller is not convenient.
174
175### Using VHCI
176
177With the [VHCI transport](../transports/vhci.md) you can attach a Bumble virtual controller to the BlueZ stack. Once attached, the controller will appear just like any other controller, and thus can be used with the standard BlueZ tools.
178
179!!! example "Attaching a virtual controller"
180    With the example app `run_controller.py`:
181    ```
182    python3 examples/run_controller.py F6:F7:F8:F9:FA:FB examples/device1.json vhci
183    ```
184
185    You should see a 'Virtual Bus' controller. For example:
186    ```
187    $ hciconfig
188    hci0:	Type: Primary  Bus: Virtual
189        BD Address: F6:F7:F8:F9:FA:FB  ACL MTU: 27:64  SCO MTU: 0:0
190        UP RUNNING
191        RX bytes:0 acl:0 sco:0 events:43 errors:0
192        TX bytes:274 acl:0 sco:0 commands:43 errors:0
193    ```
194
195    And scanning for devices should show the virtual 'Bumble' device that's running as part of the `run_controller.py` example app:
196    ```
197    pi@raspberrypi:~ $ sudo hcitool -i hci2 lescan
198    LE Scan ...
199    F0:F1:F2:F3:F4:F5 Bumble
200    ```
201
202    ```
203
204### Using a Simulated UART HCI
205
206### Bridge to a Remote Controller
207