{"id":16133431,"url":"https://github.com/fasteddy516/circuitpython_joystickxl","last_synced_at":"2025-03-16T09:32:53.322Z","repository":{"id":107991494,"uuid":"382173540","full_name":"fasteddy516/CircuitPython_JoystickXL","owner":"fasteddy516","description":"Turn a CircuitPython device into a joystick controller with lots of inputs.","archived":false,"fork":false,"pushed_at":"2025-03-06T03:34:20.000Z","size":377,"stargazers_count":22,"open_issues_count":11,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-16T00:41:26.873Z","etag":null,"topics":["circuitpython","joystick","usb","usb-hid"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fasteddy516.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["fasteddy516"]}},"created_at":"2021-07-01T22:48:23.000Z","updated_at":"2025-03-12T20:10:31.000Z","dependencies_parsed_at":"2024-02-20T15:27:26.901Z","dependency_job_id":"39940e4c-742d-4347-b893-b5db02efcc09","html_url":"https://github.com/fasteddy516/CircuitPython_JoystickXL","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasteddy516%2FCircuitPython_JoystickXL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasteddy516%2FCircuitPython_JoystickXL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasteddy516%2FCircuitPython_JoystickXL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fasteddy516%2FCircuitPython_JoystickXL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fasteddy516","download_url":"https://codeload.github.com/fasteddy516/CircuitPython_JoystickXL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243852449,"owners_count":20358268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circuitpython","joystick","usb","usb-hid"],"created_at":"2024-10-09T22:44:39.950Z","updated_at":"2025-03-16T09:32:52.959Z","avatar_url":"https://github.com/fasteddy516.png","language":"Python","funding_links":["https://github.com/sponsors/fasteddy516"],"categories":[],"sub_categories":[],"readme":"JoystickXL for CircuitPython\n============================\n.. image:: https://img.shields.io/github/license/fasteddy516/CircuitPython_JoystickXL\n    :target: https://github.com/fasteddy516/CircuitPython_JoystickXL/blob/master/LICENSE\n    :alt: License\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000\n    :target: https://github.com/psf/black\n    :alt: Black\n\n.. image:: https://readthedocs.org/projects/circuitpython-joystickxl/badge/?version=latest\n    :target: https://circuitpython-joystickxl.readthedocs.io/en/latest/?badge=latest\n    :alt: Documentation Status\n\n.. image:: https://img.shields.io/static/v1?logo=visualstudiocode\u0026label=\u0026message=Open%20in%20Visual%20Studio%20Code\u0026labelColor=2c2c32\u0026color=007acc\u0026logoColor=007acc\n    :target: https://open.vscode.dev/fasteddy516/CircuitPython_JoystickXL\n    :alt: Open in Visual Studio Code\n\n\nDescription\n===========\nThis CircuitPython driver simulates a *really big* USB HID joystick device - up\nto 8 axes, 128 buttons and 4 hat (POV) switches.  If you want to build a custom\ngame controller with a lot of inputs - *I'm looking at you, space/flight sim\npilots, racing sim drivers and virtual farmers* - JoystickXL can help.\n\n\nRequirements\n============\n*This driver relies on features that were introduced in CircuitPython\nversion 7.x*  **You must be running CircuitPython 7.0.0 or newer\non your device in order to use JoystickXL.**\n\n* This driver was made for devices running `Adafruit CircuitPython \u003chttps://www.adafruit.com/circuitpython\u003e`_.\n  For a list of compatible devices, see `circuitpython.org \u003chttps://circuitpython.org/downloads\u003e`_.\n\n* There are no dependencies on any other CircuitPython drivers, libraries or modules.\n\n* Pre-compiled (``.mpy``) versions of JoystickXL are available in the `releases \u003chttps://github.com/fasteddy516/CircuitPython_JoystickXL/releases\u003e`_\n  section for CircuitPython versions 8.x and 9.x.  \n\n\nLimitations\n===========\n* A wired USB connection to the host device is required.  *Bluetooth\n  connectivity is not supported at this time.*\n\n* Axis data is reported with 8-bit resolution (values ranging from 0-255).\n\n* Only one JoystickXL device can be defined per CircuitPython board.  *You\n  cannot have a single board report as two or more independant joysticks.*\n\n* JoystickXL's reporting frequency - thus, input latency - is affected by\n  many factors, including processor speed, the number of inputs that need\n  to be processed, and the latency of any external input peripherals that\n  are being used.  The reporting frequency is going to be significantly\n  higher on a Metro M4 Express using on-board GPIO than it is on a QT-PY\n  using I2C/SPI-based I/O expanders. \n  \n\nHost OS/Software Compatibility\n==============================\nOn **Windows 10/11**, all 8 axes 128 buttons and 4 hat switches are supported at\nthe operating system level, and JoystickXL has been tested and confirmed to work\nwith the following games:\n\n* **Microsoft Flight Simulator (2020)** *(All inputs)*\n* **Elite Dangerous** *(Limited to 32 buttons)*\n* **Star Citizen** *(All inputs)*\n* **Digital Combat Simulator (DCS) World** *(All inputs)*\n* **EverSpace 2** *(All inputs - hat switches are considered to be axes)*\n* **Forza Horizon 4** *(All inputs)*\n* **BeamNG.drive** *(Limited to 7 axes and 1 hat switch)*\n* **Farming Simulator 19** *(Limited to 7 axes, 24 buttons and 1 hat switch)*\n\n*Note that any game-specific input limitations mentioned above are - to the\nbest of my knowledge - a result of the game's joystick implementation, and are\nnot unique to JoystickXL.*\n\nOn **Linux**, a very limited amount of testing has been done on a Raspberry Pi\n4B using ``jstest`` (part of the ``joystick`` package).  The first 7 axes and\n80 buttons work correctly.  Axis 8 does not register any events, nor do any\nbuttons beyond the first 80.  Only a single hat switch *sort of* works, but it\ngets interpreted as two axes rather than an actual hat switch.  Other Linux\nplatforms/distributions/applications have not been tested.\n\nNo testing has been done on an **Apple/Mac** platform.\n\n\nDocumentation\n=============\nFull documentation is available at `\u003chttps://circuitpython-joystickxl.readthedocs.org\u003e`_.\n\n\nInstallation\n============\n1. Download the `latest release of JoystickXL \u003chttps://github.com/fasteddy516/CircuitPython_JoystickXL/releases/latest\u003e`_\n   that corresponds to the version of CircuitPython you're running.  (i.e.\n   ``joystick_xl_x.x.x_cp8`` for CircuitPython 8.x)\n2. Extract the files from the downloaded .zip archive.\n3. Copy the ``joystick_xl`` folder to the ``lib`` folder on your device's\n   ``CIRCUITPY`` drive.\n\nFor additional information on installing libraries, see Adafruit's\n`Welcome to CircuitPython Guide \u003chttps://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries\u003e`_.\n\n\nUsing JoystickXL\n================\n1. Create/modify ``boot.py`` on your CircuitPython device to enable the\n   required custom USB HID device.\n\n   .. code:: python\n\n      \"\"\"boot.py\"\"\"\n      import usb_hid\n      from joystick_xl.hid import create_joystick\n\n      # enable default CircuitPython USB HID devices as well as JoystickXL\n      usb_hid.enable(\n        (\n          usb_hid.Device.KEYBOARD,\n          usb_hid.Device.MOUSE,\n          usb_hid.Device.CONSUMER_CONTROL,\n          create_joystick(axes=2, buttons=2, hats=1),\n        )\n      )\n\n2. Use JoystickXL in ``code.py`` like this:\n\n   .. code:: python\n     \n      \"\"\"code.py\"\"\"\n      import board\n      from joystick_xl.inputs import Axis, Button, Hat\n      from joystick_xl.joystick import Joystick\n   \n      js = Joystick()\n   \n      js.add_input(\n          Button(board.D9),\n          Button(board.D10),\n          Axis(board.A2),\n          Axis(board.A3),\n          Hat(up=board.D2, down=board.D3, left=board.D4, right=board.D7),\n      )\n\n      while True:\n          js.update()\n\n   See the `examples \u003chttps://circuitpython-joystickxl.readthedocs.io/en/latest/examples.html\u003e`_\n   and `API documentation \u003chttps://circuitpython-joystickxl.readthedocs.io/en/latest/api.html\u003e`_\n   for more information.\n\n\nTesting JoystickXL Devices\n==========================\nNot all platforms/games/applications support joystick devices with high input\ncounts.  **Before you spend any time writing code or building hardware for a\ncustom controller, you should make sure the software that you want to use it\nwith is compatible.**\n\nFortunately, JoystickXL has a built-in testing module that can be run right\nfrom the CircuitPython Serial Console/REPL to verify compatibility with an\noperating system, game or application - *no input wiring or code.py required!*\n\nSee the\n`compatibility and testing documentation \u003chttps://circuitpython-joystickxl.readthedocs.io/en/latest/start.html#verifying-compatibility\u003e`_\nfor more information.\n\n\nContributing\n============\nIf you have questions, problems, feature requests, etc. please post them to the \n`Issues section on Github \u003chttps://github.com/fasteddy516/CircuitPython_JoystickXL/issues\u003e`_.\nIf you would like to contribute, please let me know.\n\n\nAcknowledgements\n============================\nA massive thanks to Adafruit and the entire CircuitPython team for creating and\nconstantly improving the CircuitPython ecosystem.  \n\nFrank Zhao's \n`Tutorial about USB HID Report Descriptors \u003chttps://eleccelerator.com/tutorial-about-usb-hid-report-descriptors/\u003e`_\nwas the starting point for my journey into USB HID land.\n\nThe tools and documentation provided by the `USB Implementors Forum \u003chttps://www.usb.org/\u003e`_\nwere an excellent resource, especially in regards to the creation of the\nrequired USB HID descriptor.  The following resources were particularly useful:\n\n* `HID Descriptor Tool \u003chttps://www.usb.org/document-library/hid-descriptor-tool\u003e`_\n* `Device Class Definition for HID \u003chttps://www.usb.org/document-library/device-class-definition-hid-111\u003e`_\n* `HID Usage Tables \u003chttps://www.usb.org/document-library/hid-usage-tables-122\u003e`_\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffasteddy516%2Fcircuitpython_joystickxl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffasteddy516%2Fcircuitpython_joystickxl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffasteddy516%2Fcircuitpython_joystickxl/lists"}