{"id":22049006,"url":"https://github.com/schnoog/joystick_esp32s2","last_synced_at":"2025-05-08T23:06:49.793Z","repository":{"id":166030168,"uuid":"624134432","full_name":"schnoog/Joystick_ESP32S2","owner":"schnoog","description":"Joystick library for ESP32 S2 \u0026 S3 devices (native USB) for the Arduino framework.","archived":false,"fork":false,"pushed_at":"2025-04-22T12:55:01.000Z","size":294,"stargazers_count":66,"open_issues_count":5,"forks_count":7,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-08T23:06:49.172Z","etag":null,"topics":["arduino","arduino-library","esp32","esp32-s2","esp32-s3","usb-joystick"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schnoog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"zenodo":null}},"created_at":"2023-04-05T20:21:39.000Z","updated_at":"2025-05-05T15:56:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"6baf324b-29bd-47b3-8a9f-f98c575709a1","html_url":"https://github.com/schnoog/Joystick_ESP32S2","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schnoog%2FJoystick_ESP32S2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schnoog%2FJoystick_ESP32S2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schnoog%2FJoystick_ESP32S2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schnoog%2FJoystick_ESP32S2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schnoog","download_url":"https://codeload.github.com/schnoog/Joystick_ESP32S2/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253160777,"owners_count":21863629,"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":["arduino","arduino-library","esp32","esp32-s2","esp32-s3","usb-joystick"],"created_at":"2024-11-30T14:14:01.430Z","updated_at":"2025-05-08T23:06:49.785Z","avatar_url":"https://github.com/schnoog.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP32-S2/S3 Joystick Library\n\n##### based on Matthew Heironimus great Arduino Joystick lirary \n\n#### Version 0.9 - forked from Version 2.1.1\n\n\n\nThis will not work with Arduino IDE 1.6.5 (or below) or with non ESP32-S2/S3 devices (e.g. Arduino UNO, Arduino MEGA, etc.).\n\nTo use this library you need to have Arduino core for the ESP32 installed (https://github.com/espressif/arduino-esp32)\n\n## Features\n\nThe joystick or gamepad can have the following features:\n- Buttons (default: 32)\n- Up to 2 Hat Switches\n- X, Y, and/or Z Axis (up to 16-bit precision)\n- X, Y, and/or Z Axis Rotation (up to 16-bit precision)\n- Rudder (up to 16-bit precision)\n- Throttle (up to 16-bit precision)\n- Accelerator (up to 16-bit precision)\n- Brake (up to 16-bit precision)\n- Steering (up to 16-bit precision)\n\n#### Known issues\nUnfortunately there is an issue with the Arduino-ESP32 core library which can cause problems if you use the HID joystick and the serial interface at the same time.\nExecuting Serial.print or Serial.println, yes even initializing the serial console with Serial.begin() is prone to cause timing issue for the USB data transfer.\n\n\n## Installation Instructions\n### Library manager\nJust search for **Joystick_ESP32S2** in the library manager of your installation of ArduinoIDE or PlatformIO and install it. \n### Manual installation\nThe following instructions can be used to install the latest version of the library in the Arduino IDE (thanks to [@per1234](https://github.com/per1234) for this update):\n\n1. Download https://github.com/schnoog/Joystick_ESP32S2/archive/master.zip\n2. In the Arduino IDE, select `Sketch` \u003e `Include Library` \u003e `Add .ZIP Library...`.  Browse to where the downloaded ZIP file is located and click `Open`. The Joystick library's examples will now appear under `File` \u003e `Examples` \u003e `Joystick`.\n\nPlease keep in mind that a manual installation is not updated by the library manager of your IDE.\n\n## USB Setup\nIf you only want to play arround with it, I propose to enable USB CDC on boot.\nThis can be done quite easily\n* **ArduinoIDE**: There's an option in the tools menue to enable USB CDC on boot\n* **PlatformIO**:  Set the option within the platformio.ini of your project\n```\nbuild_flags =\n\t....\n    -DARDUINO_USB_CDC_ON_BOOT=1\n``` \n\nIf you want to change your joysticks name, USB product id or vendor id, please consult the\n[USBOPTIONS.md](USBOPTIONS.md) or have a look into the **Joystick_WithCustomPIDandVID** example provided with this library\n\n## Examples\n\n### Simple example\n\n```C++\n#include \u003cJoystick_ESP32S2.h\u003e\n\n// Create the Joystick\nJoystick_ Joystick;\n\n// Constant that maps the physical pin to the joystick button.\nconst int pinToButtonMap = 9;\n\nvoid setup() {\n\t// Initialize Button Pins\n\tpinMode(pinToButtonMap, INPUT_PULLUP);\n\n\t// Initialize Joystick Library\n\tJoystick.begin();\n}\n\n// Last state of the button\nint lastButtonState = 0;\n\nvoid loop() {\n\n\t// Read pin values\n\tint currentButtonState = !digitalRead(pinToButtonMap);\n\tif (currentButtonState != lastButtonState)\n\t{\n\tJoystick.setButton(0, currentButtonState);\n\tlastButtonState = currentButtonState;\n\t}\n\n\tdelay(50);\n}\n```\n\n### Included Examples\n\nThe following example Arduino sketch files are included in this library:\n\n#### Simple Samples\n\n- `JoystickButton` - Creates a Joystick and maps pin 9 to button 0 of the joystick, pin 10 to button 1, pin 11 to button 2, and pin 12 to button 3.\n- `JoystickKeyboard` - Creates a Joystick and a Keyboard. Maps pin 9 to Joystick Button 0, pin 10 to Joystick Button 1, pin 11 to Keyboard key 1, and pin 12 to Keyboard key 2.\n- `GamepadExample` - Creates a simple Gamepad with an Up, Down, Left, Right, and Fire button.\n- `FunduinoJoystickShield` - Creates a simple Gamepad using a Funduino Joystick Shield (https://protosupplies.com/product/funduino-joystick-shield-v1-a/).\n- `ArcadeStickExample` - Simple arcade stick example that demonstrates how to read twelve Arduino Pro Micro digital pins and map them to the library (thanks to [@nebhead](https://github.com/nebhead) for this example). NOTE: This sketch is for the Arduino Pro Micro only.\n\n#### Used for Testing\n\n- `JoystickTest` - Simple test of the Joystick library. It exercises many of the Joystick library’s functions when pin A0 is grounded.\n- `MultipleJoystickTest` - Creates 4 Joysticks using the library (each with a slightly different configuration) and exercises the first 16 buttons (if present), the X axis, and the Y axis of each joystick when pin A0 is grounded.\n- `FlightControllerTest` - Creates a Flight Controller and tests 32 buttons, the X and Y axis, the Throttle, and the Rudder when pin A0 is grounded.\n- `HatSwitchTest` - Creates a joystick with two hat switches. Grounding pins 4 - 11 cause the hat switches to change position.\n- `DrivingControllerTest` - Creates a Driving Controller and tests 4 buttons, the Steering, Brake, and Accelerator when pin A0 is grounded.\n\n## Joystick Library API\n\nThe following API is available if the Joystick library in included in a sketch file.\n\n### Joystick\\_(...)\n\nConstructor used to initialize and setup the Joystick. The following optional parameters are available:\n\n- `uint8_t hidReportId` - Default: `0x03` - Indicates the joystick's HID report ID. This value must be unique if you are creating multiple instances of Joystick. Do not use `0x01` or `0x02` as they are used by the built-in Arduino Keyboard and Mouse libraries.\n- `uint8_t joystickType` - Default: `JOYSTICK_TYPE_JOYSTICK` or `0x04` - Indicates the HID input device type. Supported values:\n  - `JOYSTICK_TYPE_JOYSTICK` or `0x04` - Joystick \n  - `JOYSTICK_TYPE_GAMEPAD` or `0x05` - Gamepad\n  - `JOYSTICK_TYPE_MULTI_AXIS` or `0x08` - Multi-axis Controller \n- `uint8_t buttonCount` - Default: `32` - Indicates how many buttons will be available on the joystick.\n- `uint8_t hatSwitchCount` - Default: `2` - Indicates how many hat switches will be available on the joystick. Range: `0` - `2`\n- `bool includeXAxis` - Default: `true` - Indicates if the X Axis is available on the joystick.\n- `bool includeYAxis` - Default: `true` - Indicates if the Y Axis is available on the joystick.\n- `bool includeZAxis` - Default: `true` - Indicates if the Z Axis (in some situations this is the right X Axis) is available on the joystick.\n- `bool includeRxAxis` - Default: `true` - Indicates if the X Axis Rotation (in some situations this is the right Y Axis) is available on the joystick.\n- `bool includeRyAxis` - Default: `true` - Indicates if the Y Axis Rotation is available on the joystick.\n- `bool includeRzAxis` - Default: `true` - Indicates if the Z Axis Rotation is available on the joystick.\n- `bool includeRudder` - Default: `true` - Indicates if the Rudder is available on the joystick.\n- `bool includeThrottle` - Default: `true` - Indicates if the Throttle is available on the joystick.\n- `bool includeAccelerator` - Default: `true` - Indicates if the Accelerator is available on the joystick.\n- `bool includeBrake` - Default: `true` - Indicates if the Brake is available on the joystick.\n- `bool includeSteering` - Default: `true` - Indicates if the Steering is available on the joystick.\n\nThe following constants define the default values for the constructor parameters listed above:\n\n- `JOYSTICK_DEFAULT_REPORT_ID` is set to `0x03`\n- `JOYSTICK_DEFAULT_BUTTON_COUNT` is set to `32`\n- `JOYSTICK_DEFAULT_HATSWITCH_COUNT` is set to `2`\n\n### Joystick.begin(bool initAutoSendState)\n\nStarts emulating a game controller connected to a computer. By default, all methods update the game controller state immediately. If `initAutoSendState` is set to `false`, the `Joystick.sendState` method must be called to update the game controller state.\n\n### Joystick.end()\n\nStops the game controller emulation to a connected computer (Note: just like the Arduino `Keyboard.h` and `Mouse.h` libraries, the `end()` function does not actually do anything).\n\n### Joystick.setXAxisRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the X axis. Default: `0` to `1023`\n\n### Joystick.setXAxis(int32_t value)\n\nSets the X axis value. See `setXAxisRange` for the range.\n\n### Joystick.setYAxisRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Y axis. Default: `0` to `1023`\n\n### Joystick.setYAxis(int32_t value)\n\nSets the Y axis value. See `setYAxisRange` for the range.\n\n### Joystick.setZAxisRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Z axis. Default: `0` to `1023`\n\n### Joystick.setZAxis(int32_t value)\n\nSets the Z axis value. See `setZAxisRange` for the range.\n\n### Joystick.setRxAxisRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the X axis rotation. Default: `0` to `1023`\n\n### Joystick.setRxAxis(int32_t value)\n\nSets the X axis rotation value. See `setRxAxisRange` for the range.\n\n### Joystick.setRyAxisRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Y axis rotation. Default: `0` to `1023`\n\n### Joystick.setRyAxis(int32_t value)\n\nSets the Y axis rotation value. See `setRyAxisRange` for the range.\n\n### Joystick.setRzAxisRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Z axis rotation. Default: `0` to `1023`\n\n### Joystick.setRzAxis(int32_t value)\n\nSets the Z axis rotation value. See `setRzAxisRange` for the range.\n\n### Joystick.setRudderRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Rudder. Default: `0` to `1023`\n\n### Joystick.setRudder(int32_t value)\n\nSets the Rudder value. See `setRudderRange` for the range.\n\n### Joystick.setThrottleRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Throttle. Default: `0` to `1023`\n\n### Joystick.setThrottle(int32_t value)\n\nSets the Throttle value. See `setThrottleRange` for the range.\n\n### Joystick.setAcceleratorRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Accelerator. Default: `0` to `1023`\n\n### Joystick.setAccelerator(int32_t value)\n\nSets the Accelerator value. See `setAcceleratorRange` for the range.\n\n### Joystick.setBrakeRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Brake. Default: `0` to `1023`\n\n### Joystick.setBrake(int32_t value)\n\nSets the Brake value. See `setBrakeRange` for the range.\n\n### Joystick.setSteeringRange(int32_t minimum, int32_t maximum)\n\nSets the range of values that will be used for the Steering. Default: `0` to `1023`\n\n### Joystick.setSteering(int32_t value)\n\nSets the Steering value. See `setSteeringRange` for the range.\n\n### Joystick.setButtons32(uint32_t states)\n\nSets 32 button states at once, no for loop needed. For example `Joystick.setButtons32(ButtonStates);` // maximum buttons 32(0-32). Button 0 will appear as button 1, if your buttons start at button one then use `\u003e\u003e 1` after button states in brackets\n\n### Joystick.setButton(uint8_t button, uint8_t value)\n\nSets the state (`0` or `1`) of the specified button (range: `0` - (`buttonCount - 1`)). The button is the 0-based button number (i.e. button #1 is `0`, button #2 is `1`, etc.). The value is `1` if the button is pressed and `0` if the button is released.\n\n### Joystick.pressButton(uint8_t button)\n\nPress the indicated button (range: `0` - (`buttonCount - 1`)). The button is the 0-based button number (i.e. button #1 is `0`, button #2 is `1`, etc.).\n\n### Joystick.releaseButton(uint8_t button)\n\nRelease the indicated button (range: `0` - (`buttonCount - 1`)). The button is the 0-based button number (i.e. button #1 is `0`, button #2 is `1`, etc.).\n\n### Joystick.setHatSwitch(int8_t hatSwitch, int16_t value)\n\nSets the value of the specified hat switch. The hatSwitch is 0-based (i.e. hat switch #1 is `0` and hat switch #2 is `1`). The value is from 0° to 360°, but in 45° increments. Any value less than 45° will be rounded down (i.e. 44° is rounded down to 0°, 89° is rounded down to 45°, etc.). Set the value to `JOYSTICK_HATSWITCH_RELEASE` or `-1` to release the hat switch.\n\n### Joystick.sendState()\n\nSends the updated joystick state to the host computer. Only needs to be called if `AutoSendState` is `false` (see `Joystick.begin` for more details).\n\nSee the [Wiki](https://github.com/MHeironimus/ArduinoJoystickLibrary/wiki) for more details on things like FAQ, supported boards, testing, etc.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschnoog%2Fjoystick_esp32s2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschnoog%2Fjoystick_esp32s2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschnoog%2Fjoystick_esp32s2/lists"}