search

fasteddy516 / CircuitPython_JoystickXL

Turn a CircuitPython device into a joystick controller with lots of inputs.
MIT License
18 stars 7 forks source link
circuitpython joystick usb usb-hid

readme

JoystickXL for CircuitPython

.. image:: https://img.shields.io/github/license/fasteddy516/CircuitPython_JoystickXL :target: https://github.com/fasteddy516/CircuitPython_JoystickXL/blob/master/LICENSE :alt: License

.. image:: https://img.shields.io/badge/code%20style-black-000000 :target: https://github.com/psf/black :alt: Black

.. image:: https://readthedocs.org/projects/circuitpython-joystickxl/badge/?version=latest :target: https://circuitpython-joystickxl.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. image:: https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc :target: https://open.vscode.dev/fasteddy516/CircuitPython_JoystickXL :alt: Open in Visual Studio Code

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.

Limitations

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:

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 <https://github.com/fasteddy516/CircuitPython_JoystickXL/releases/latest>_ 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 <https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries>_.

Using JoystickXL

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

    .. code:: python

    """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:: python

    """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 <https://circuitpython-joystickxl.readthedocs.io/en/latest/examples.html> and API documentation <https://circuitpython-joystickxl.readthedocs.io/en/latest/api.html> 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 <https://circuitpython-joystickxl.readthedocs.io/en/latest/start.html#verifying-compatibility>_ for more information.

Contributing

If you have questions, problems, feature requests, etc. please post them to the Issues section on Github <https://github.com/fasteddy516/CircuitPython_JoystickXL/issues>_. 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 <https://eleccelerator.com/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 <https://www.usb.org/>_ were an excellent resource, especially in regards to the creation of the required USB HID descriptor. The following resources were particularly useful: