Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/MHeironimus/ArduinoJoystickLibrary
An Arduino library that adds one or more joysticks to the list of HID devices an Arduino Leonardo or Arduino Micro can support.
https://github.com/MHeironimus/ArduinoJoystickLibrary
arduino-leonardo arduino-library arduino-micro gamepad joystick-library
Last synced: 3 months ago
JSON representation
An Arduino library that adds one or more joysticks to the list of HID devices an Arduino Leonardo or Arduino Micro can support.
- Host: GitHub
- URL: https://github.com/MHeironimus/ArduinoJoystickLibrary
- Owner: MHeironimus
- License: lgpl-3.0
- Created: 2015-11-19T14:10:12.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2024-03-17T04:30:41.000Z (10 months ago)
- Last Synced: 2024-11-05T03:42:47.865Z (3 months ago)
- Topics: arduino-leonardo, arduino-library, arduino-micro, gamepad, joystick-library
- Language: C++
- Homepage:
- Size: 137 KB
- Stars: 2,124
- Watchers: 134
- Forks: 411
- Open Issues: 123
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- AwesomeCppGameDev - ArduinoJoystickLibrary
README
# Arduino Joystick Library
#### Version 2.1.1
This library can be used with Arduino IDE 1.6.6 or above (see [Wiki - Testing Details](https://github.com/MHeironimus/ArduinoJoystickLibrary/wiki/Testing-Details) for more information) to add one or more joysticks (or gamepads) to the list of HID devices an [Arduino Leonardo](https://www.arduino.cc/en/Main/ArduinoBoardLeonardo) or [Arduino Micro](https://www.arduino.cc/en/Main/ArduinoBoardMicro) (or any Arduino clone that is based on the ATmega32u4) can support. This library will also work with the [Arduino Due](https://www.arduino.cc/en/Main/ArduinoBoardDue), thanks to [@Palakis](https://github.com/Palakis). A complete list of supported boards can be found in the [Wiki - Supported Boards](https://github.com/MHeironimus/ArduinoJoystickLibrary/wiki/Supported-Boards). This will not work with Arduino IDE 1.6.5 (or below) or with non-32u4 based Arduino devices (e.g. Arduino UNO, Arduino MEGA, etc.).
## Features
The joystick or gamepad can have the following features:
- Buttons (default: 32)
- Up to 2 Hat Switches
- X, Y, and/or Z Axis (up to 16-bit precision)
- X, Y, and/or Z Axis Rotation (up to 16-bit precision)
- Rudder (up to 16-bit precision)
- Throttle (up to 16-bit precision)
- Accelerator (up to 16-bit precision)
- Brake (up to 16-bit precision)
- Steering (up to 16-bit precision)
## Installation Instructions
The 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):
1. Download https://github.com/MHeironimus/ArduinoJoystickLibrary/archive/master.zip
2. In the Arduino IDE, select `Sketch` > `Include Library` > `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` > `Examples` > `Joystick`.
## Examples
### Simple example
```C++
#include
// Create the Joystick
Joystick_ Joystick;
// Constant that maps the physical pin to the joystick button.
const int pinToButtonMap = 9;
void setup() {
// Initialize Button Pins
pinMode(pinToButtonMap, INPUT_PULLUP);
// Initialize Joystick Library
Joystick.begin();
}
// Last state of the button
int lastButtonState = 0;
void loop() {
// Read pin values
int currentButtonState = !digitalRead(pinToButtonMap);
if (currentButtonState != lastButtonState)
{
Joystick.setButton(0, currentButtonState);
lastButtonState = currentButtonState;
}
delay(50);
}
```
### Included Examples
The following example Arduino sketch files are included in this library:
#### Simple Samples
- `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.
- `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.
- `GamepadExample` - Creates a simple Gamepad with an Up, Down, Left, Right, and Fire button.
- `FunduinoJoystickShield` - Creates a simple Gamepad using a Funduino Joystick Shield (https://protosupplies.com/product/funduino-joystick-shield-v1-a/).
- `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.
#### Used for Testing
- `JoystickTest` - Simple test of the Joystick library. It exercises many of the Joystick library’s functions when pin A0 is grounded.
- `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.
- `FlightControllerTest` - Creates a Flight Controller and tests 32 buttons, the X and Y axis, the Throttle, and the Rudder when pin A0 is grounded.
- `HatSwitchTest` - Creates a joystick with two hat switches. Grounding pins 4 - 11 cause the hat switches to change position.
- `DrivingControllerTest` - Creates a Driving Controller and tests 4 buttons, the Steering, Brake, and Accelerator when pin A0 is grounded.
## Joystick Library API
The following API is available if the Joystick library in included in a sketch file.
### Joystick\_(...)
Constructor used to initialize and setup the Joystick. The following optional parameters are available:
- `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.
- `uint8_t joystickType` - Default: `JOYSTICK_TYPE_JOYSTICK` or `0x04` - Indicates the HID input device type. Supported values:
- `JOYSTICK_TYPE_JOYSTICK` or `0x04` - Joystick
- `JOYSTICK_TYPE_GAMEPAD` or `0x05` - Gamepad
- `JOYSTICK_TYPE_MULTI_AXIS` or `0x08` - Multi-axis Controller
- `uint8_t buttonCount` - Default: `32` - Indicates how many buttons will be available on the joystick.
- `uint8_t hatSwitchCount` - Default: `2` - Indicates how many hat switches will be available on the joystick. Range: `0` - `2`
- `bool includeXAxis` - Default: `true` - Indicates if the X Axis is available on the joystick.
- `bool includeYAxis` - Default: `true` - Indicates if the Y Axis is available on the joystick.
- `bool includeZAxis` - Default: `true` - Indicates if the Z Axis (in some situations this is the right X Axis) is available on the joystick.
- `bool includeRxAxis` - Default: `true` - Indicates if the X Axis Rotation (in some situations this is the right Y Axis) is available on the joystick.
- `bool includeRyAxis` - Default: `true` - Indicates if the Y Axis Rotation is available on the joystick.
- `bool includeRzAxis` - Default: `true` - Indicates if the Z Axis Rotation is available on the joystick.
- `bool includeRudder` - Default: `true` - Indicates if the Rudder is available on the joystick.
- `bool includeThrottle` - Default: `true` - Indicates if the Throttle is available on the joystick.
- `bool includeAccelerator` - Default: `true` - Indicates if the Accelerator is available on the joystick.
- `bool includeBrake` - Default: `true` - Indicates if the Brake is available on the joystick.
- `bool includeSteering` - Default: `true` - Indicates if the Steering is available on the joystick.
The following constants define the default values for the constructor parameters listed above:
- `JOYSTICK_DEFAULT_REPORT_ID` is set to `0x03`
- `JOYSTICK_DEFAULT_BUTTON_COUNT` is set to `32`
- `JOYSTICK_DEFAULT_HATSWITCH_COUNT` is set to `2`
### Joystick.begin(bool initAutoSendState)
Starts 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.
### Joystick.end()
Stops 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).
### Joystick.setXAxisRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the X axis. Default: `0` to `1023`
### Joystick.setXAxis(int32_t value)
Sets the X axis value. See `setXAxisRange` for the range.
### Joystick.setYAxisRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Y axis. Default: `0` to `1023`
### Joystick.setYAxis(int32_t value)
Sets the Y axis value. See `setYAxisRange` for the range.
### Joystick.setZAxisRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Z axis. Default: `0` to `1023`
### Joystick.setZAxis(int32_t value)
Sets the Z axis value. See `setZAxisRange` for the range.
### Joystick.setRxAxisRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the X axis rotation. Default: `0` to `1023`
### Joystick.setRxAxis(int32_t value)
Sets the X axis rotation value. See `setRxAxisRange` for the range.
### Joystick.setRyAxisRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Y axis rotation. Default: `0` to `1023`
### Joystick.setRyAxis(int32_t value)
Sets the Y axis rotation value. See `setRyAxisRange` for the range.
### Joystick.setRzAxisRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Z axis rotation. Default: `0` to `1023`
### Joystick.setRzAxis(int32_t value)
Sets the Z axis rotation value. See `setRzAxisRange` for the range.
### Joystick.setRudderRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Rudder. Default: `0` to `1023`
### Joystick.setRudder(int32_t value)
Sets the Rudder value. See `setRudderRange` for the range.
### Joystick.setThrottleRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Throttle. Default: `0` to `1023`
### Joystick.setThrottle(int32_t value)
Sets the Throttle value. See `setThrottleRange` for the range.
### Joystick.setAcceleratorRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Accelerator. Default: `0` to `1023`
### Joystick.setAccelerator(int32_t value)
Sets the Accelerator value. See `setAcceleratorRange` for the range.
### Joystick.setBrakeRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Brake. Default: `0` to `1023`
### Joystick.setBrake(int32_t value)
Sets the Brake value. See `setBrakeRange` for the range.
### Joystick.setSteeringRange(int32_t minimum, int32_t maximum)
Sets the range of values that will be used for the Steering. Default: `0` to `1023`
### Joystick.setSteering(int32_t value)
Sets the Steering value. See `setSteeringRange` for the range.
### Joystick.setButton(uint8_t button, uint8_t value)
Sets 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.
### Joystick.pressButton(uint8_t button)
Press 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.).
### Joystick.releaseButton(uint8_t button)
Release 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.).
### Joystick.setHatSwitch(int8_t hatSwitch, int16_t value)
Sets 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.
### Joystick.sendState()
Sends the updated joystick state to the host computer. Only needs to be called if `AutoSendState` is `false` (see `Joystick.begin` for more details).
See the [Wiki](https://github.com/MHeironimus/ArduinoJoystickLibrary/wiki) for more details on things like FAQ, supported boards, testing, etc.