Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add instructions for Windows machine + internal Bluetooth adapter #110

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add instructions for Windows machine + internal Bluetooth adapter #110

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/Windows-and-macOS-Installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ To support the necessary Bluetooth APIs leveraged within NXBT, installation with

Before continuing, please ensure you have the following:

- A **USB** Bluetooth Adapter
- Internal Bluetooth adapters are incompatible (generally) with the process that allows a VM to use external resources.
- A **USB** Bluetooth Adapter (for macOS)
- For internal Bluetooth adapters, Windows machines (generally) support disabling Bluetooth for themselves and allowing a VM to capture it, but macOS machines generally don't allow their own Bluetooth to be disabled and captured.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This stackexchange post combined with this VirtualBox ticket from 10 years ago appears to explain why this wouldn't work on macOS (or would require many more difficult workarounds).

- VirtualBox v6 or above
- If you don't have this, you can install VirtualBox [here](https://www.virtualbox.org/wiki/Downloads)
- VirtualBox Extension Pack
Expand All @@ -33,7 +33,7 @@ Additionally, please ensure that VBoxManage (a CLI that ships with VirtualBox) i
python3 vagrant_setup.py
```

3. Follow the tool's directions and choose the USB Bluetooth adapter you would like to use with NXBT. Additionally, you'll be able to choose between intalling NXBT from PyPi or from the cloned repository. Installing NXBT from the cloned repository allows for use of development version (as well as editing NXBT itself)
3. Follow the tool's directions and choose the Bluetooth adapter you would like to use with NXBT. Additionally, you'll be able to choose between installing NXBT from PyPi or from the cloned repository. Installing NXBT from the cloned repository allows for use of development version (as well as editing NXBT itself)

4. Once the Vagrant setup tool is finished, you should see a file called `Vagrantfile` located in the same directory as the setup tool. You should now be able to boot the VM with the following command:

Expand All @@ -48,14 +48,14 @@ Additionally, please ensure that VBoxManage (a CLI that ships with VirtualBox) i
vagrant ssh
```

6. Unplug the USB Bluetooth adapter from your machine and plug it back in. The allows for VirtualBox to properly claim and forward to the USB into the Vagrant VM.
6. If you are using a USB Bluetooth adapter, unplug it from your machine and plug it back in. This allows for VirtualBox to properly claim and forward the USB into the Vagrant VM. If you are using an internal Bluetooth adapter on Windows, go into Device Manager -> Bluetooth and toggle it (disable/enable). (Bluetooth should then completely disappear from the Device Manager menu, indicating that the VM has captured it.)

7. Inside the VirtualBox, check that your Bluetooth Adapter is available with `lsusb`:

```bash
> lsusb
# Something like the following will be printed
# if your USB Bluetooth adapter is available:
# if your Bluetooth adapter is available:
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 0a5c:21e9 Broadcom Corp. BCM20702A0 Bluetooth 4.0
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Expand Down Expand Up @@ -104,3 +104,7 @@ First, halt your VM (`vagrant halt`) and unplug your adapter. Next, restart the
### My adapter appears but Bluetooth isn't functional

Typically, restarting the VM resolves the issue. Make sure you unplug the adapter and plug it back in when the VM has fully booted (AKA when it's possible to SSH into it).

### Windows internal Bluetooth adapter doesn't work inside the VM / disappears from Device Manager even with the VM off / etc.

Try hard restarting your Windows machine (i.e. hold down the power button until it powers off). Note that selecting Shut down from the Start menu doesn't actually perform a full shutdown as Windows attempts to save some resources for faster startup.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, Windows.

17 changes: 10 additions & 7 deletions vagrant_setup.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,13 @@ def get_usb_devices():
product = find_line_items("Product", device)

if (len(productid) < 1 or len(vendorid) < 1 or
len(manufacturer) < 1 or len(product) < 1):
len(manufacturer) < 1):
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VBoxManage list usbhost on my Windows test machine says that the internal Bluetooth adapter doesn't have a Product name.

continue

productid = productid[0]
vendorid = vendorid[0]
manufacturer = manufacturer[0]
product = product[0]
product = product[0] if product != [] else ""

if len(productid) != 13 or len(vendorid) != 13:
continue
Expand All @@ -38,7 +38,8 @@ def get_usb_devices():
'product': product,
'manufacturer': manufacturer,
'productid': productid[8:12],
'vendorid': vendorid[8:12]
'vendorid': vendorid[8:12],
'name': f"{product} ({manufacturer})" if product else manufacturer,
})

return devices
Expand Down Expand Up @@ -87,7 +88,7 @@ def check_cli(name, cli_string, msg=None):
print("---")
devices = get_usb_devices()
for i, device in enumerate(devices):
print(f"{i:3}. {device['product']} ({device['manufacturer']})")
print(f"{i:3}. {device['name']}")
print()

# Choose a USB Bluetooth adapter
Expand Down Expand Up @@ -119,9 +120,11 @@ def check_cli(name, cli_string, msg=None):

vb_usb_filter = f"""vb.customize ["usbfilter", "add", "0",
"--target", :id,
"--name", "{adapter_info['product']} ({adapter_info['manufacturer']})",
"--product", "{adapter_info['product']}",
"--manufacturer", "{adapter_info['manufacturer']}",
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On my Windows test machine, I had to specifically delete the manufacturer name from the USB filter to get it to match. (Per this VirtualBox forum thread, the product id and vendor id are still there and should be sufficient.) I think the mismatch was something dumb like "Intel Corp." versus "Intel Corporation" versus "Intel" versus "Intel(R)".

"--name", "{adapter_info['name']}","""
if adapter_info['product']:
vb_usb_filter += f"""
"--product", "{adapter_info['product']}","""
vb_usb_filter += f"""
"--productid", "{adapter_info['productid']}",
"--vendorid", "{adapter_info['vendorid']}",]"""
vagrantfile = vagrantfile.replace("{{USB_FILTER}}", vb_usb_filter)
Expand Down