1:material-linux: LINUX PLATFORM 2=============================== 3 4In 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. 5 6Using Bumble With BlueZ 7----------------------- 8 9A Bumble virtual controller can be attached to the BlueZ stack. 10Attaching a controller to BlueZ can be done by either simulating a UART HCI interface, or by using the VHCI driver interface if available. 11In 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. 12 13### Using VHCI 14 15With 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. 16 17!!! example "Attaching a virtual controller" 18 With the example app `run_controller.py`: 19 ``` 20 PYTHONPATH=. python3 examples/run_controller.py F6:F7:F8:F9:FA:FB examples/device1.json vhci 21 ``` 22 23 You should see a 'Virtual Bus' controller. For example: 24 ``` 25 $ hciconfig 26 hci0: Type: Primary Bus: Virtual 27 BD Address: F6:F7:F8:F9:FA:FB ACL MTU: 27:64 SCO MTU: 0:0 28 UP RUNNING 29 RX bytes:0 acl:0 sco:0 events:43 errors:0 30 TX bytes:274 acl:0 sco:0 commands:43 errors:0 31 ``` 32 33 And scanning for devices should show the virtual 'Bumble' device that's running as part of the `run_controller.py` example app: 34 ``` 35 pi@raspberrypi:~ $ sudo hcitool -i hci2 lescan 36 LE Scan ... 37 F0:F1:F2:F3:F4:F5 Bumble 38 ``` 39 40### Using HCI Sockets 41 42HCI sockets provide a way to send/receive HCI packets to/from a Bluetooth controller managed by the kernel. 43The HCI device referenced by an `hci-socket` transport (`hciX`, 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. 44You can bring a HCI controller `UP` or `DOWN` with `hciconfig`. 45 46!!! tip "List all available controllers" 47 The command 48 ``` 49 $ hciconfig 50 ``` 51 lists all available HCI controllers and their state. 52 53 Example: 54 55 ``` 56 pi@raspberrypi:~ $ hciconfig 57 hci1: Type: Primary Bus: USB 58 BD Address: 00:16:A4:5A:40:F2 ACL MTU: 1021:8 SCO MTU: 64:1 59 DOWN 60 RX bytes:84056 acl:0 sco:0 events:51 errors:0 61 TX bytes:1980 acl:0 sco:0 commands:90 errors:0 62 63 hci0: Type: Primary Bus: UART 64 BD Address: DC:A6:32:75:2C:97 ACL MTU: 1021:8 SCO MTU: 64:1 65 DOWN 66 RX bytes:68038 acl:0 sco:0 events:692 errors:0 67 TX bytes:20105 acl:0 sco:0 commands:843 errors:0 68 ``` 69 70!!! tip "Disabling `bluetoothd`" 71 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 72 ``` 73 $ hciconfig hci0 down 74 ``` 75 (or `hciX` 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: 76 ``` 77 $ sudo systemctl stop bluetooth.service 78 ``` 79 You can always re-start the daemon with 80 ``` 81 $ sudo systemctl start bluetooth.service 82 ``` 83 84### Using a Simulated UART HCI 85 86### Bridge to a Remote Controller 87 88 89Using Bumble With Bluetooth Controllers 90--------------------------------------- 91 92A Bumble application can interface with a local Bluetooth controller. 93If your Bluetooth controller is a standard HCI USB controller, see the [USB Transport page](../transports/usb.md) for details on how to use HCI USB controllers. 94If your Bluetooth controller is a standard HCI UART controller, see the [Serial Transport page](../transports/serial.md). 95Alternatively, a Bumble Host object can communicate with one of the platform's controllers via an HCI Socket. 96 97`<details to be filled in>` 98 99### Raspberry Pi 4 :fontawesome-brands-raspberry-pi: 100 101You can use the Bluetooth controller either via the kernel, or directly to the device. 102 103#### Via The Kernel 104 105Use an HCI Socket transport 106 107#### Directly 108In 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). 109 110``` 111$ sudo systemctl stop hciuart 112``` 113should detach the controller from the stack, after which you can use the HCI UART with Bumble. 114 115!!! tip "Check the device name for the UART and at what speed it should be opened" 116 ``` 117 $ sudo systemctl status hciuart 118 ``` 119 should show the speed at which the UART should be opened. 120 For example: 121 ``` 122 $ sudo systemctl status hciuart 123 hciuart.service - Configure Bluetooth Modems connected by UART 124 Loaded: loaded (/lib/systemd/system/hciuart.service; enabled; vendor preset: enabled) 125 Active: active (running) since Fri 2021-06-18 02:17:28 BST; 1min 10s ago 126 Process: 357 ExecStart=/usr/bin/btuart (code=exited, status=0/SUCCESS) 127 Main PID: 586 (hciattach) 128 Tasks: 1 (limit: 4915) 129 CGroup: /system.slice/hciuart.service 130 └─586 /usr/bin/hciattach /dev/serial1 bcm43xx 3000000 flow - 131 ``` 132 When run before stopping the `hciuart` service, shows that on this board, the UART device is `/dev/serial` and the speed is `3000000` 133 134!!! example "Example: scanning" 135 ``` 136 python3 run_scanner.py serial:/dev/serial1,3000000 137 ``` 138 139