joymote 0.0.4

Use Joy-Con or Pro Controller as remote control of Linux machine.

Joymote

Use a Joy-Con or Pro Controller as a remote control of your Linux machine.

Joy-Con and Pro Controller can be connected to Linux machine via Bluetooth. Joymote listens for button presses and analog stick movements, then translates them into keyboard input, mouse movement, or custom commands defined by you. With Joymote, your game controller becomes a powerful input device for controlling your desktop.

Requirements

• Python
• uinput module

  • Check whether the uinput module is loaded, by running:

    lsmod | grep uinput
    

    If it is loaded, you will see a line like uinput 20480 0.

  • You can manually load the module by running:

    sudo modprobe uinput
    

  • You can also run the following command to load uinput modules automatically on boot.

    sudo bash -c "cat uinput > /etc/modules-load.d/uinput.conf"
    

  • Make sure you have the permission to access /dev/uinput.

Installation

Using pip

pip install joymote

From source

git clone https://github.com/kkoyung/joymote.git joymote
cd joymote
# check out different version by tags, if you want
pip install .

Usage

1. Copy the example configuration file to ~/.config/joymote/config.toml.

   wget -o ~/.config/joymote/config.toml https://raw.githubusercontent.com/kkoyung/joymote/refs/heads/main/config.toml
   

2. Connect controllers via Bluetooth.

3. Start joymote.

   joymote
   

4. By default, Joymote does nothing. Check out config.toml and change it to configure Joymote's behaviours upon pressing buttons on the controller.

Joymote can detect newly connected controllers without restarting, so you can run it as daemon in the background. For example, run it as a systemd unit.

Connect controllers via Bluetooth

The controllers can connect to your Linux machine via Bluetooth, just like usual Bluetooth devices.

1. Press and hold down the SYNC button (the tiny button between SL and SR on Joy-Con, or the tiny button between L and R button on Pro Controller) for at least one second to enter pairing mode.
2. Enable Bluetooth of your computer, and scan new devices.
3. Find a device named "Joy-Con (L)", "Joy-Con (R)", or "Pro Controller". Pair and connect to it.

Development

1. Clone the repository.

   git clone https://github.com/kkoyung/joymote.git joymote
   cd joymote
   

2. Run the code.

   uv run joymote
   # or
   python -m venv .venv
   source .venv/bin/activate
   python install .
   python -m joymote
   

Pairing two Joy-Con as one device (Optional)

Use joycond, which is a userspace daemon, to combine Joy-Cons into a single device.

• Install and start. For example, if you are on Arch Linux, you can run

  yay -S joycond-git
  sudo systemctl enable --now joycond
  

• Then, follow this instruction to pair the controller.

Disclaimer

Nintendo®, Nintendo Switch®, Joy-Con®, and Pro Controller® are registered trademarks of Nintendo of America Inc. This project is an independent work and is not affiliated with, endorsed by, or sponsored by Nintendo. All trademarks are the property of their respective owners.