How to install and use NXBT (Switch 1 and Switch 2 supported)

[TheStonedModder]

Wow thanks for this, I actually ordered an ESP32-S3 for pokemon automation, but I didnt see any macro mode on their page. While I'm working with typenoob to get nxbt working on my switch 2, I guess it is worth exploring something that is at least more reliable.

Where can I follow the progress you and type noob are making ? I’d love to see updates if possible

Because I’d much prefer to use NXBT in the end aha

 

[laceptable]

Where can I follow the progress you and type noob are making ? I’d love to see updates if possible

Because I’d much prefer to use NXBT in the end aha

Sorry for the misunderstanding, I'm not qualified to do any of the work, by working together I meant he's helping me try and solve this problem haha. He is reviewing and providing me with solutions to try, and I'm sure if it ever work he will update the community too! That guy is great!

 

[fangamer]

great！is there any possbile run as a docker?

 

[laceptable]

Where can I follow the progress you and type noob are making ? I’d love to see updates if possible

Because I’d much prefer to use NXBT in the end aha

Hey, I have good news! I managed to get my Pi zero 2W to work with switch 2!
typenoob provided me with something to try and it may be the key to making it work!

You'll need to change the address of your bluetooth.


Here are the steps that I recalled to the best of my ability:

1. Install bdaddr

wget https://github.com/thxomas/bdaddr/archive/refs/heads/master.zip
unzip master.zip
cd bdaddr-master
make

2. Change the address of your bluetooth device to 7C:BB:8A:XX:XX:XX where XX can be any HEX characters (like F0 for example)

sudo ./bdaddr -i hci0 -r 7C:BB:8A:XX:XX:XX

You should see something like

Manufacturer:   Broadcom Corporation (15)
Device address: B8:27:EB:89:DA:DA
New BD address: 7C:BB:8A:XX:XX:XX

Address changed - Device reset successully

3. Reset and restart bluetooth

sudo hciconfig hci0 reset
sudo systemctl restart bluetooth.service

4. Check the new bluetooth address

bluetoothctl

then

 list

You should see

Controller 7C:BB:8A:XX:XX:XX raspberrypi [default]

Note: "raspberrypi" will instead be whatever your device's hostname is. It also means that your device is no longer alias as a Pro Controller.

5. Run nxbt test while you're on the change grip screen

 sudo nxbt test

The controller was detected on my switch 2, I hope it does for you too!

Huge props to typenoob on github who made the repo to work on the go, and helping me debug this situation for the past 2-3 days. Please thank him if this worked for you!

 

[Zevgor]

uhm im getting an error trying to run the executable saying "/usr/local/bin/nxbt: 1 : Syntax error: Unterminated quote string"
this is on ubuntu jammy jellyfish

I am also having this issue. Here is my full log:

Any advice on resolving this?

 

[Crimson0verlord]

I am able to access the webui thru <username>.local as I have my pi recieving internet thru my pc, however when I click "Create Controller", it says "LOADING" and then a few seconds or so later it says "CRASHED". So I looked thru the replies on this post and tried the test command. It errored out as seen in the first image attached:

I also tried @laceptable 's steps and the image below is the result of running the first set of commands in his post

i'm going to attempt to install dependencies "libbluetooth-dev bluez bluez-tools" and try the make again

Update: I was able to get stuff working proper. It is working amazingly! I'm planning on using my Switch 2 in junction with this setup and my Shadowcast to allow me to play my Switch 2 over a moonlight game stream connection. Is there a way I can make a bat file that digitally creates a pro controller and sets the input as xinput? I'd like to map it to a launch option under a custom title in moonlight. I would also need a way for RPiOS to auto accept the Switch pairing request without user intervention other than opening the moonlight title

 

[zlsrdkpf6]

Hi, while I'm just using the original version of nxbt and not the version used here, I had a question. While running macros on it, I noticed the macros often don't work properly with some inputs not timed as they should have or some presses just missing. Could it be an issue with my hardware or is it a known issue with nxbt?

 

[Corgi0718ffO]

it seems that I can sucessfully run the tui(cannot run webapp), but there no reaction in my nintendo switch 2. Anyone knows why? (sry my english is bad)

Post automatically merged: Nov 4, 2025

i manually connected my switch via bluetoothctl, so everything works as expected now!

how dose it work? I have the same problem, please teache me!

 

[dldjr9131]

NXBT Installation Guide on Surface Pro (Linux Mint)​

If it helps others, these are the steps I took to install NXBT on a Surface Pro running Linux Mint. This guide specifically addresses compatibility issues with modern Python versions by forcing the use of Python 3.11.

---

1. System Setup and Python 3.11 Installation​

Modern Linux distributions often default to Python 3.12, which is incompatible with NXBT. We'll use the Deadsnakes PPA to safely install the required Python 3.11 alongside your system packages.

• 1.1 Add PPA & Update
  • sudo add-apt-repository ppa:deadsnakes/ppa -y &amp;&amp; sudo apt update
• 1.2 Install Python
  • sudo apt install pkg-config build-essential python3.11 python3.11-venv python3.11-dev libdbus-glib-1-dev libdbus-1-dev libgirepository1.0-dev libcairo2-dev -y
• 1.3 Create Environment
  • python3.11 -m venv nxbt_env

---

2. Dependency Pinning (The "Golden Set" Fix)​

This crucial step installs the NXBT application and pins conflicting libraries to specific, compatible versions to prevent all known crashes on Python 3.11 (e.g., ImportError: escape, Eventlet TypeError).

Note: Replace /home/$USER with /home/yourusername if you prefer to type the full path instead of using the $USER variable.

• 2.1 Pin Web Frameworks
  • /home/$USER/nxbt_env/bin/pip install --force-reinstall "werkzeug==2.0.3" "flask==2.0.3" "jinja2==3.0.3" "itsdangerous==2.0.1"
• 2.2 Install App & Fix Network
  • /home/$USER/nxbt_env/bin/pip install --force-reinstall nxbt psutil dbus-python "eventlet&gt;=0.33.3" "dnspython&gt;=2.0.0" blessed greenlet cryptography Flask-SocketIO pynput

---

3. Running the Application & Web Interface​

The application is now fully prepared. We launch it using the absolute path to prevent the "command not found" error and ensure the correct Python environment is used.

• 3.1 Launch Web App
  • sudo /home/$USER/nxbt_env/bin/nxbt webapp

Successful Output: The application is running when you see the message: wsgi starting up on http://0.0.0.0:8000

Access the web interface: Open your web browser and navigate to: http://localhost:8000

 

[bankbn]

I finally get it working. I found it's not about the Bluetooth adapter (I have totally bought at least 3 different ones).
I used Pi4 with Debian 11 (image: https://downloads.raspberrypi.org/r...2023-05-03-raspios-bullseye-arm64-full.img.xz)
Which I can get BlueZ v5.55:

$ bluetoothctl --version
bluetoothctl: 5.55
$

At least, I know it's not Bluetooth adapter issue. RPi 4 build-in is working with the proper driver.
But I still want to run it on Pi 5... have to figure out how to do that easily.

View attachment 535938

NXBT on Switch 2 (Success on Debian VM on Windows + USB BT Dongle)​

note: my English isn’t very strong, so I used ChatGPT to help translate/write this post.
Just wanted to share a quick success story in case anyone else is stuck like I was.

I’m totally new to Linux and initially followed the usual NXBT “premade binary” guide, but I kept running into confusing issues—especially around architecture and Bluetooth. The big turning point was realizing my setup was x86_64 (VM on a Windows PC), so the aarch64 binary didn’t apply to me.

Huge thanks to Mike72 for mentioning they used an RPi4—that gave me the push to try a clean Debian setup, and it ended up working!

What worked for me (Debian Bookworm VM on Windows)​

• My main PC is Windows (host), and I ran Debian Bookworm inside a VM.
• I used a TP-Link Bluetooth USB Adapter and attached it to the VM using USB passthrough (critical—without it, Debian won’t see a controller).
• At first, bluetoothctl show returned: “No default controller available”

One thing that slowed me down: some guides mention that when you boot the VM you may need to unplug/replug (or re-attach) the USB device so the VM can detect it properly. I wanted to confirm detection with lsusb, but I didn’t realize at the time that Debian minimal doesn’t include lsusb by default, so I couldn’t check. I only found out later that I needed to install it first (usbutils). After that, I could finally confirm the dongle was visible inside the VM.

Even after the dongle showed up in lsusb, Bluetooth still didn’t work at first because firmware was missing. After enabling the proper Debian repo components and installing the Realtek firmware package, then restarting Bluetooth, the controller finally appeared and NXBT could run normally.

After that, I launched:

• sudo nxbt webapp (or sudo nxbt test)
  and paired from Controllers → Change Grip/Order on the Switch. Connection worked.

Also, just to be clear: I’m not using NXBT for macros. I’m using it to help play with friends via Parsec (controller input setup / remote play).

If you’re trying this in a VM on Windows: don’t skip USB passthrough, and if bluetoothctl shows no controller, you’re probably missing firmware or the dongle isn’t actually attached to the VM.

Thanks again Mike72 for the inspiration—Debian ended up being a solid path to success!

 

[mimikyu778]

I am able to access the webui thru <username>.local as I have my pi recieving internet thru my pc, however when I click "Create Controller", it says "LOADING" and then a few seconds or so later it says "CRASHED". So I looked thru the replies on this post and tried the test command. It errored out as seen in the first image attached:
View attachment 536895
I also tried @laceptable 's steps and the image below is the result of running the first set of commands in his post

i'm going to attempt to install dependencies "libbluetooth-dev bluez bluez-tools" and try the make again

Update: I was able to get stuff working proper. It is working amazingly! I'm planning on using my Switch 2 in junction with this setup and my Shadowcast to allow me to play my Switch 2 over a moonlight game stream connection. Is there a way I can make a bat file that digitally creates a pro controller and sets the input as xinput? I'd like to map it to a launch option under a custom title in moonlight. I would also need a way for RPiOS to auto accept the Switch pairing request without user intervention other than opening the moonlight title

I'm getting this same error using rPi 4 on the latest imager provided os. Reinstalled everything from both the main post and your listed dependancies and still nothing. Any help would be appreicated!

 

[mixxald]

I got this working perfectly on my Switch Lite and used it for quite some time. But now I changed it for a Switch 2 and am unable to get it to connect. I get no errors once or ever, the pi just can't connect to the switch 2 neither with the demo nor the webapp. I've tried resetting my Pi completely and reinstalling the SO but it made no difference.

Post automatically merged: Mar 17, 2026

Hey, I have good news! I managed to get my Pi zero 2W to work with switch 2!
typenoob provided me with something to try and it may be the key to making it work!

You'll need to change the address of your bluetooth.


Here are the steps that I recalled to the best of my ability:

1. Install bdaddr

wget https://github.com/thxomas/bdaddr/archive/refs/heads/master.zip
unzip master.zip
cd bdaddr-master
make

2. Change the address of your bluetooth device to 7C:BB:8A:XX:XX:XX where XX can be any HEX characters (like F0 for example)

sudo ./bdaddr -i hci0 -r 7C:BB:8A:XX:XX:XX

You should see something like

Manufacturer:   Broadcom Corporation (15)
Device address: B8:27:EB:89:DA:DA
New BD address: 7C:BB:8A:XX:XX:XX

Address changed - Device reset successully

3. Reset and restart bluetooth

sudo hciconfig hci0 reset
sudo systemctl restart bluetooth.service

4. Check the new bluetooth address

bluetoothctl

then

 list

You should see

Controller 7C:BB:8A:XX:XX:XX raspberrypi [default]

Note: "raspberrypi" will instead be whatever your device's hostname is. It also means that your device is no longer alias as a Pro Controller.

5. Run nxbt test while you're on the change grip screen

 sudo nxbt test

The controller was detected on my switch 2, I hope it does for you too!

Huge props to typenoob on github who made the repo to work on the go, and helping me debug this situation for the past 2-3 days. Please thank him if this worked for you!

I followed these steps but my switch 2 still did not found any controller.

Edit: I noticed that after I ran the nxbt test and let it time out when I listed the Bluetooth the name reverted back to 'Pro Controller'. It says:

[bluetoothctl]> list
Controller 7C:BB:8A:F0:F0:F0 Pro Controller [default]

 

[Myithspa25]

Got to the line "sudo nxbt webapp" but it errors saying "/usr/local/bin/nxbt: 1: Syntax error: Unterminated quoted string"
Update: Never mind, I just installed the wrong one (aarch64 is the one in the guide, i needed amd64)

Post automatically merged: Today at 1:16 AM

You need to find that devices actual IP address and visit that with the :8000 after instead of 0.0.0.0

So 192.268.45:8000 for example

268 isn't within the IP range, did you mean 168? Also, how do I find the IP?

Post automatically merged: Today at 1:23 AM

Managed to get the webapp open, but I have no idea how to connect to the switch.