TourBox Node.js Driver (Linux Only)

An unofficial Linux driver for the original (2018) TourBox hardware, written in Node.js.

Note: This driver is specifically designed for the old TourBox model (2018). It has NOT been tested with TourBox Neo or Elite, and likely will not work with them (as they use different protocols). Use at your own risk.

Features

• System Tray Icon: Quick access to settings.
• Web-based Configuration: Configure your device via a web UI.
• Wayland Support: Works on KDE Wayland (requires kdotool). (actually, I haven't test it on X11)
• Profile Switching: Automatic profile switching based on active window.

Installation

Method 1: NPM Global Install (Recommended)

You can install the driver globally using npm. This is the easiest method.

npm install -g old-tourbox-linux

After installation, you can run the driver with:

old-tourbox-linux

Note: You may need to fix permissions or install dependencies manually (see below).

Method 2: Manual Installation

If you prefer to run from source or need the install.sh helper:

1. Clone the repository:

   git clone https://github.com/hocti/old-tourbox-linux.git
   cd old-tourbox-linux

2. Run the install script (this will install dependencies and setup permissions):

   ./install.sh

3. Start the driver:

   npm start

Manual Setup & Prerequisites

If you installed via npm -g or encounter permission issues, you may need to manually install system libraries and configure permissions.

1. Install Required Libraries

The driver relies on uinput for simulating key presses and specific tools for window detection.

Debian/Ubuntu:

sudo apt install libinput-tools
# For KDE Wayland support:
pip install kdotool

Arch Linux:

sudo pacman -S libinput
# For KDE Wayland support:
pip install kdotool

2. Configure Permissions (Udev Rules)

To access the TourBox device and create virtual input devices without sudo, you need to configure udev rules.

Create a file /etc/udev/rules.d/99-tourbox.rules with the following content:

# TourBox Device Access
SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", MODE="0666", GROUP="dialout"
# Uinput Access
KERNEL=="uinput", MODE="0660", GROUP="input", OPTIONS+="static_node=uinput"

Then reload rules and add your user to the groups:

sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -aG input $USER
sudo usermod -aG dialout $USER

You must log out and log back in for group changes to take effect.

Anyways

This project is 95% written by Gemini Pro 3 using Vibe Coding.

I planned to get a usable version by vibe coding in around 4~6 hours, but finally I spent 4 days. If I knew even with vibe coding it's still such hard work, I wouldn't have started this project. Because it seems like I'm the only one who needs this thing. (I don't know if there are other people who need this, but I haven't seen anyone else talking about it.)

Btw the tourbox icon is stolen from the official website, and the setting page's toubox svg is copy from here.

License

ISC