README.md

Python driver for Nintendo Switch Joy-Con

We are referring to dekuNukem/Nintendo_Switch_Reverse_Engineering

Install

pip install joycon-python hidapi pyglm

Linux users who only see JoyCons through evdev can install the optional dependency:

pip install evdev

Usage

Quick status check

cd joycon-python/
python -m pyjoycon.joycon

or use as module

from pyjoycon import JoyCon, get_R_id

joycon_id = get_R_id()
joycon = JoyCon(*joycon_id)

joycon.get_status()

If your Linux system exposes JoyCon as four evdev devices (L, R, Limu, Rimu), pyjoycon can map these evdev nodes back to hidraw automatically.

You can force this backend explicitly:

from pyjoycon import JoyCon, get_R_id

joycon_id = get_R_id(backend="evdev")
joycon = JoyCon(*joycon_id)
print(joycon.get_status())

Backend options for get_device_ids / get_L_id / get_R_id are:

• auto (default): use hidapi first, then evdev fallback.
• hid: only hidapi enumeration.
• evdev: only evdev to hidraw mapping.

Ubuntu hid-nintendo Compatibility

This modified version is intended to improve compatibility on recent Ubuntu systems that use the built-in hid-nintendo driver, especially for third-party (clone) Joy-Con controllers.

In this setup, controllers are often visible as evdev nodes like:

• Joy-Con (L)
• Joy-Con (L) (IMU)
• Joy-Con (R)
• Joy-Con (R) (IMU)

pyjoycon now supports discovering those evdev devices and mapping them back to their corresponding hidraw nodes, so regular JoyCon APIs can still be used.

Recommended on Ubuntu for clone controllers:

• install evdev
• use backend="evdev" explicitly when selecting device IDs
• ensure your user has read/write permission for /dev/hidraw* (udev rules)

Status values

{
  'battery': {
    'charging': 0,
    'level': 2
  },
  'buttons': {
    'right': {
      'y': 0,
      'x': 0,
      'b': 0,
      'a': 0,
      'sr': 0,
      'sl': 0,
      'r': 0,
      'zr': 0
    },
    'shared': {
      'minus': 0,
      'plus': 0,
      'r-stick': 0,
      'l-stick': 0,
      'home': 0,
      'capture': 0,
      'charging-grip': 0
    },
    'left': {
      'down': 0,
      'up': 0,
      'right': 0,
      'left': 0,
      'sr': 0,
      'sl': 0,
      'l': 0,
      'zl': 0
    }
  },
  'analog-sticks': {
    'left': {
      'horizontal': 0,
      'vertical': 0
    },
    'right': {
      'horizontal': 2170,
      'vertical': 1644
    }
  },
  'accel': {
    'x': 879,
    'y': 1272,
    'z': 549
  },
  'gyro': {
    'x': -354,
    'y': -7,
    'z': 281
  }
}

You need cython-hidapi to use Bluetooth / HID connection in Python.

Alternatively, you can use hid instead if cython-hidapi fails to find your JoyCons.

If you are on Linux you most likely will need to add udev rules for switch devices to make it work. These rules will work just fine.

Gyroscope

We have a specialized class which tracks the gyroscope for you, and exposes this tracked state in a simplified manner:

from pyjoycon import GyroTrackingJoyCon, get_R_id
import time

joycon_id = get_R_id()
joycon = GyroTrackingJoyCon(*joycon_id)
for i in range(20):
    print("joycon pointer:  ", joycon.pointer)
    print("joycon rotation: ", joycon.rotation)
    print("joycon direction:", joycon.direction)
    print()
    time.sleep(0.05)

Button events

We have a specialized class which tracks the state of the JoyCon buttons and provides changes as events. Here is an example of how it could be used with pygame:

from pyjoycon import ButtonEventJoyCon, get_R_id
import pygame

joycon_id = get_R_id()
joycon = ButtonEventJoyCon(*joycon_id)

...

while 1:
    pygame.time.wait(int(1000/60))

    ...

    for event_type, status in joycon.events():
        print(event_type, status)

    ...

    pygame.display.flip()

Combining multiple JoyCon helper classes

import pyjoycon

class MyJoyCon(
        pyjoycon.GyroTrackingJoyCon,
        pyjoycon.ButtonEventJoyCon,
    ): pass

Environments

• macOS Mojave (10.14.6)
• Python (3.7.4)
• hidapi (0.7.99.post21)