JoystickXL for CircuitPython

Description

This CircuitPython driver simulates a really big USB HID joystick device - up to 8 axes, 128 buttons and 4 hat (POV) switches. If you want to build a custom game controller with a lot of inputs - I'm looking at you, space/flight sim pilots, racing sim drivers and virtual farmers - JoystickXL can help.

Requirements

This driver relies on features that were introduced in CircuitPython version 7.x You must be running CircuitPython 7.0.0 or newer on your device in order to use JoystickXL.

• This driver was made for devices running Adafruit CircuitPython. For a list of compatible devices, see circuitpython.org.
• There are no dependencies on any other CircuitPython drivers, libraries or modules.
• Pre-compiled (.mpy) versions of JoystickXL are available in the releases section for CircuitPython versions 8.x and 9.x.

Limitations

• A wired USB connection to the host device is required. Bluetooth connectivity is not supported at this time.
• Axis data is reported with 8-bit resolution (values ranging from 0-255).
• Only one JoystickXL device can be defined per CircuitPython board. You cannot have a single board report as two or more independant joysticks.
• JoystickXL's reporting frequency - thus, input latency - is affected by many factors, including processor speed, the number of inputs that need to be processed, and the latency of any external input peripherals that are being used. The reporting frequency is going to be significantly higher on a Metro M4 Express using on-board GPIO than it is on a QT-PY using I2C/SPI-based I/O expanders.

Host OS/Software Compatibility

On Windows 10/11, all 8 axes 128 buttons and 4 hat switches are supported at the operating system level, and JoystickXL has been tested and confirmed to work with the following games:

• Microsoft Flight Simulator (2020) (All inputs)
• Elite Dangerous (Limited to 32 buttons)
• Star Citizen (All inputs)
• Digital Combat Simulator (DCS) World (All inputs)
• EverSpace 2 (All inputs - hat switches are considered to be axes)
• Forza Horizon 4 (All inputs)
• BeamNG.drive (Limited to 7 axes and 1 hat switch)
• Farming Simulator 19 (Limited to 7 axes, 24 buttons and 1 hat switch)

Note that any game-specific input limitations mentioned above are - to the best of my knowledge - a result of the game's joystick implementation, and are not unique to JoystickXL.

On Linux, a very limited amount of testing has been done on a Raspberry Pi 4B using jstest (part of the joystick package). The first 7 axes and 80 buttons work correctly. Axis 8 does not register any events, nor do any buttons beyond the first 80. Only a single hat switch sort of works, but it gets interpreted as two axes rather than an actual hat switch. Other Linux platforms/distributions/applications have not been tested.

No testing has been done on an Apple/Mac platform.

Documentation

Full documentation is available at https://circuitpython-joystickxl.readthedocs.org.

Installation

1. Download the latest release of JoystickXL that corresponds to the version of CircuitPython you're running. (i.e. joystick_xl_x.x.x_cp8 for CircuitPython 8.x)
2. Extract the files from the downloaded .zip archive.
3. Copy the joystick_xl folder to the lib folder on your device's CIRCUITPY drive.

For additional information on installing libraries, see Adafruit's Welcome to CircuitPython Guide.

Using JoystickXL

1. Create/modify boot.py on your CircuitPython device to enable the required custom USB HID device.

   """boot.py"""
   import usb_hid
   from joystick_xl.hid import create_joystick
   
   # enable default CircuitPython USB HID devices as well as JoystickXL
   usb_hid.enable(
     (
       usb_hid.Device.KEYBOARD,
       usb_hid.Device.MOUSE,
       usb_hid.Device.CONSUMER_CONTROL,
       create_joystick(axes=2, buttons=2, hats=1),
     )
   )

2. Use JoystickXL in code.py like this:

   """code.py"""
   import board
   from joystick_xl.inputs import Axis, Button, Hat
   from joystick_xl.joystick import Joystick
   
   js = Joystick()
   
   js.add_input(
       Button(board.D9),
       Button(board.D10),
       Axis(board.A2),
       Axis(board.A3),
       Hat(up=board.D2, down=board.D3, left=board.D4, right=board.D7),
   )
   
   while True:
       js.update()

   See the examples and API documentation for more information.

Testing JoystickXL Devices

Not all platforms/games/applications support joystick devices with high input counts. Before you spend any time writing code or building hardware for a custom controller, you should make sure the software that you want to use it with is compatible.

Fortunately, JoystickXL has a built-in testing module that can be run right from the CircuitPython Serial Console/REPL to verify compatibility with an operating system, game or application - no input wiring or code.py required!

See the compatibility and testing documentation for more information.

Contributing

If you have questions, problems, feature requests, etc. please post them to the Issues section on Github. If you would like to contribute, please let me know.

Acknowledgements

A massive thanks to Adafruit and the entire CircuitPython team for creating and constantly improving the CircuitPython ecosystem.

Frank Zhao's Tutorial about USB HID Report Descriptors was the starting point for my journey into USB HID land.

The tools and documentation provided by the USB Implementors Forum were an excellent resource, especially in regards to the creation of the required USB HID descriptor. The following resources were particularly useful:

• HID Descriptor Tool
• Device Class Definition for HID
• HID Usage Tables