pstruebi/bumble_fork
1
0
Fork 0
forked from auracaster/bumble_mirror
Code Pull Requests Activity

formatting and linting automation

Browse Source 
Squashed commits:
[cd479ba] formatting and linting automation
[7fbfabb] formatting and linting automation
[c4f9505] fix after rebase
[f506ad4] rename job
[441d517] update doc (+7 squashed commits)
[2e1b416] fix invoke and github action
[6ae5bb4] doc for git blame
[44b5461] add GitHub action
[b07474f] add docs
[4cd9a6f] more linter fixes
[db71901] wip
[540dc88] wip
This commit is contained in:
Gilles Boccon-Gibod
2022-12-10 09:29:51 -08:00
parent 80fe2ea422
commit c2959dadb4
140 changed files with 2632 additions and 1346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/mkdocs/src/platforms/android.md
View File

@@ -2,13 +2,13 @@
===================================
Using Bumble with Android is not about running the Bumble stack on the Android
OS itself, but rather using Bumble with the Bluetooth support of the Android
OS itself, but rather using Bumble with the Bluetooth support of the Android
emulator.
The two main use cases are:
* Connecting the Bumble host stack to the Android emulator's virtual controller.
* Using Bumble as an HCI bridge to connect the Android emulator to a physical
* Using Bumble as an HCI bridge to connect the Android emulator to a physical
Bluetooth controller, such as a USB dongle
!!! warning
@@ -17,7 +17,7 @@ The two main use cases are:
version of the emulator you are using.
You will need version 31.3.8.0 or later.
The Android emulator supports Bluetooth in two ways: either by exposing virtual
The Android emulator supports Bluetooth in two ways: either by exposing virtual
Bluetooth controllers to which you can connect a virtual Bluetooth host stack, or
by exposing an way to connect your own virtual controller to the Android Bluetooth
stack via a virtual HCI interface.
@@ -25,7 +25,7 @@ Both ways are controlled via gRPC requests to the Android emulator.
## Launching the Emulator
If the version of the emulator you are running does not yet support enabling
If the version of the emulator you are running does not yet support enabling
Bluetooth support by default or automatically, you must launch the emulator from
the command line.
@@ -43,7 +43,7 @@ communicate link layer packets between them, thus creating a virtual radio netwo
Configuring a Bumble Device instance to use Root Canal as a virtual controller
allows that virtual device to communicate with the Android Bluetooth stack, and
through it with Android applications as well as system-managed profiles.
To connect a Bumble host stack to a Root Canal virtual controller instance, use
To connect a Bumble host stack to a Root Canal virtual controller instance, use
the bumble `android-emulator` transport in `host` mode (the default).
!!! example "Run the example GATT server connected to the emulator"
@@ -78,7 +78,7 @@ To connect a virtual controller to the Android Bluetooth stack, use the bumble `
## Other Tools
The `show` application that's included with Bumble can be used to parse and pretty-print the HCI packets
from an Android HCI "snoop log" (see [this page](https://source.android.com/devices/bluetooth/verifying_debugging)
from an Android HCI "snoop log" (see [this page](https://source.android.com/devices/bluetooth/verifying_debugging)
for details on how to obtain HCI snoop logs from an Android device).
Use the `--format snoop` option to specify that the file is in that specific format.
@@ -86,4 +86,3 @@ Use the `--format snoop` option to specify that the file is in that specific for
```shell
$ bumble-show --format snoop btsnoop_hci.log
```

26
docs/mkdocs/src/platforms/linux.md
View File

@@ -13,8 +13,8 @@ The 3 main types of physical Bluetooth controllers are:
!!! tip "Conflicts with the kernel and BlueZ"
If your use a USB dongle that is recognized by your kernel as a supported Bluetooth device, it is
likely that the kernel driver will claim that USB device and attach it to the BlueZ stack.
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`.
likely that the kernel driver will claim that USB device and attach it to the BlueZ stack.
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`.
HCI interfaces are numbered, starting from 0 (i.e `hci0`, `hci1`, ...).
For example, to bring `hci0` down:
@@ -36,7 +36,7 @@ See the [USB Transport page](../transports/usb.md) for general information on ho
!!! tip "USB Permissions"
By default, when running as a regular user, you won't have the permission to use
arbitrary USB devices.
You can change the permissions for a specific USB device based on its bus number and
You can change the permissions for a specific USB device based on its bus number and
device number (you can use `lsusb` to find the Bus and Device numbers for your Bluetooth
dongle).
@@ -69,9 +69,9 @@ You can bring a HCI controller `UP` or `DOWN` with `hciconfig hci<X> up` and `hc
By default, when running as a regular user, you won't have the permission to use
an HCI socket to a Bluetooth controller (you may see an exception like `PermissionError: [Errno 1] Operation not permitted`).
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.
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.
See [this manpage](https://manpages.ubuntu.com/manpages/bionic/man5/capability.conf.5.html) for details.
Alternatively, if you are just experimenting temporarily, the `capsh` command may be useful in order
to execute a single command with enhanced permissions, as in this example:
@@ -80,7 +80,7 @@ You can bring a HCI controller `UP` or `DOWN` with `hciconfig hci<X> up` and `hc
$ 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>"
```
Where `<path/to/executable>` is the path to your `python3` executable or to one of the Bumble bundled command-line applications.
!!! tip "List all available controllers"
The command
```
@@ -94,22 +94,22 @@ You can bring a HCI controller `UP` or `DOWN` with `hciconfig hci<X> up` and `hc
pi@raspberrypi:~ $ hciconfig
hci1: Type: Primary Bus: USB
BD Address: 00:16:A4:5A:40:F2 ACL MTU: 1021:8 SCO MTU: 64:1
DOWN
DOWN
RX bytes:84056 acl:0 sco:0 events:51 errors:0
TX bytes:1980 acl:0 sco:0 commands:90 errors:0
hci0: Type: Primary Bus: UART
BD Address: DC:A6:32:75:2C:97 ACL MTU: 1021:8 SCO MTU: 64:1
DOWN
DOWN
RX bytes:68038 acl:0 sco:0 events:692 errors:0
TX bytes:20105 acl:0 sco:0 commands:843 errors:0
```
!!! tip "Disabling `bluetoothd`"
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
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
```
$ hciconfig hci0 down
```
```
(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:
```
$ sudo systemctl stop bluetooth.service
@@ -181,13 +181,13 @@ With the [VHCI transport](../transports/vhci.md) you can attach a Bumble virtual
```
python3 examples/run_controller.py F6:F7:F8:F9:FA:FB examples/device1.json vhci
```
You should see a 'Virtual Bus' controller. For example:
```
$ hciconfig
hci0: Type: Primary Bus: Virtual
BD Address: F6:F7:F8:F9:FA:FB ACL MTU: 27:64 SCO MTU: 0:0
UP RUNNING
UP RUNNING
RX bytes:0 acl:0 sco:0 events:43 errors:0
TX bytes:274 acl:0 sco:0 commands:43 errors:0
```
@@ -204,5 +204,3 @@ With the [VHCI transport](../transports/vhci.md) you can attach a Bumble virtual
### Using a Simulated UART HCI
### Bridge to a Remote Controller

1
docs/mkdocs/src/platforms/macos.md
View File

@@ -11,4 +11,3 @@ To do that, use the following command:
sudo nvram bluetoothHostControllerSwitchBehavior="never"
```
A reboot shouldn't be necessary after that. See [Tech Note 2295](https://developer.apple.com/library/archive/technotes/tn2295/_index.html)

2
docs/mkdocs/src/platforms/windows.md
View File

@@ -7,7 +7,7 @@ USB HCI
To use a Bluetooth USB dongle on Windows, you need a USB dongle that does not require a vendor Windows driver (the dongle will be used directly through the [`WinUSB`](https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb) driver rather than through a vendor-supplied Windows driver).
In order to use the dongle, the `WinUSB` driver must be assigned to the USB device. It is likely that, by default, when you first plug in the dongle, it will be recognized by Windows as a Bluetooth USB device, and Windows will try to use it with its native Bluetooth stack. You will need to switch the driver, which can be done easily with the [Zadig tool](https://zadig.akeo.ie/).
In the Zadig tool, select your USB dongle device, and associate it with WinUSB.
In the Zadig tool, select your USB dongle device, and associate it with WinUSB.
Once the WinUSB driver is correctly assigned to your device, you can confirm that by checking the settings with the Windows Device Manager control panel. Your device should appear under "Universal Serial Bus Device" (not under "Bluetooth"), and inspecting the driver details, you should see `winusb.sys` in the list of driver files.
![USB Driver Details](winusb_driver.png)