Skip to content

Latest commit

 

History

History
106 lines (76 loc) · 4.64 KB

Windows-and-macOS-Installation.md

File metadata and controls

106 lines (76 loc) · 4.64 KB
Raw

Windows and macOS Installation

To support the necessary Bluetooth APIs leveraged within NXBT, installation within a Virtual Machine (VM) is necessary. To install on Windows or macOS using a VM, please follow the instructions below.

Prerequisites

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.
  • VirtualBox v6 or above
    • If you don't have this, you can install VirtualBox here
  • VirtualBox Extension Pack
  • Vagrant
    • Available to download here
  • Python 3

Additionally, please ensure that VBoxManage (a CLI that ships with VirtualBox) is available on your system path. Eg: A help message should be displayed if VBoxManage is entered into Terminal (macOS) or Command Prompt (Windows). If you don't see a help message, please add VirtualBox's installation directory to your system path.

Installation

  1. Clone the NXBT repo to a location of your choosing:

    git clone https://github.com/Brikwerk/nxbt

  2. Navigate inside the cloned directory and run the Vagrant setup tool.

    cd nxbt
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)

  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:

    vagrant up

  5. After the VM has fully completed its setup, you can SSH into the terminal. Please note that your terminal's current working directory must be in the same directory at the Vagrantfile you generated earlier.

    # SSHing into the VM
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.

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

    > lsusb
# Something like the following will be printed
# if your USB 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

    Next, use bluetoothctl to test if Bluetooth is functional with the adapter:

    > sudo bluetoothctl
# bluetoothctl should print something like below
# if the adapter is functional
Agent registered
[CHG] Controller XX:XX:XX:XX:XX:XX Pairable: yes
# You can additionally run the `show` command in
# bluetoothctl to list your adapters stats as a final check
> [bluetooth]# show
Controller XX:XX:XX:XX:XX:XX (public)
    Name: ubuntu2010.localdomain
    ...

    If you're not able to see your adapter within the VM or the adapter isn't functional, please refer to the troubleshooting section below.

  8. If the above checks pass, NXBT should be functional within your VM. You can run NXBT commands as normal while SSHed into the VM:

    # Eg:
sudo nxbt test

  9. Finally, Vagrant exposes the following other commands to halt the VM and completely destroy it:

    # Stop the VM but don't destroy it
vagrant halt
# Completely destroy the VM
vagrant destroy

Troubleshooting

My USB Bluetooth adapter won't show up inside the VM

First, halt your VM (vagrant halt) and unplug your adapter. Next, restart the VM (vagrant up) and SSH into it (vagrant ssh). Plug the Bluetooth adapter in and check if it's listed with lsusb. If the adapter still isn't listed, unplug the adapter again and manually add a USB passthrough with the VirtualBox application. Instructions on this can be found here under the "For persistent device connection to VM" section.

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).