IMPORTANT NOTE: This article is for Arduino IDE version 1.6.6 (or above). To add a USB Game Controller to an Arduino Leonardo or Micro using Arduino IDE version 1.6.5 (or below) see the following postings: Add USB Game Controller to Arduino Leonardo or Micro and Add Up To 3 USB Game Controllers to Arduino Leonardo or Micro.
Introduction
- X, Y, and Z axis
- 32 buttons
- X, Y, and Z axis rotation
- Rudder
- Throttle
- 2 Point of View Hat Switches
Installing the Library
The latest version of the Arduino library that allows the Arduino Leonardo and Micro to appear as a Game Controller can be downloaded from the following GitHub repository:https://github.com/MHeironimus/ArduinoJoystickLibrary/tree/version-1.0
This GitHub repository actually contains three different versions of the Arduino Joystick Library:
- Joystick - Causes the Arduino to appear as single Game Controller
- Joystick2 - Causes the Arduino to appear as two, simple Game Controllers
- Joystick3 - Causes the Arduino to appear as three, simple Game Controllers
Copy the Joystick (and/or Joystick2 and/or Joystick3) folder from GitHub to the Arduino Libraries folder (typically located at %userprofile%\Documents\Arduino\libraries). The library (or libraries) should now appear in the Arduino IDE list of libraries.
Running the Test Sketch
Included in the library is a test sketch, called UsbJoystickTest.ino (or UsbJoystick2Test.ino or UsbJoystick3Test.ino). This sketch should be loaded, compiled, and uploaded to the Arduino Leonardo or Micro using the Arduino IDE (version 1.6.6 or above).
The following steps are for Windows 7. If you have a different version of Windows or a different operating system, these steps may differ.
Go to the Windows Control Panel and select “Hardware and Sound”.
Then select “Devices and Printers”.
The Arduino Leonardo or Arduino Micro should appear in the list of devices.
Next right mouse click on the Arduino Leonardo or Arduino Micro to display the settings menu.
Select “Game controller settings” to get to the “Game Controllers” dialog.
The Arduino Leonardo or Micro should appear in the list of installed game controllers. Select the Arduino Leonardo or Micro and click the Properties button to display the game controller test dialog.
While this dialog has focus, ground pin A0 on the Arduino to activate the test script. The test script will test the game controller functionality in the following order:
- 32 buttons
- throttle and rudder
- X and Y Axis
- Z Axis
- 2 Hat Switches
- X and Y Axis Rotation
Joystick Library API
Now that the Joystick library is available to the Arduino IDE, an Arduino Leonardo or Arduino Micro can be used for custom game controller projects. The following describes the complete Joystick library. The simpler library that is used for the Joystick2 and Joystick3 libraries is documented at the end of this posting.
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.
Joystick.setXAxis(byte value)
Sets the X axis value. Range -127 to 127 (0 is center).
Joystick.setYAxis(byte value)
Sets the Y axis value. Range -127 to 127 (0 is center).
Joystick.setZAxis(byte value)
Sets the Z axis value. Range -127 to 127 (0 is center).
Joystick.setXAxisRotation(int value)
Sets the X axis rotation value. Range 0° to 360°.
Joystick.setyAxisRotation(int value)
Sets the Y axis rotation value. Range 0° to 360°.
Joystick.setZAxisRotation(int value)
Sets the Z axis rotation value. Range 0° to 360°.
Joystick.setButton(byte button, byte value)
Sets the state (0 or 1) of the specified button (0 - 31). 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(byte button)
Press the indicated button (0 - 31). The button is the 0-based button number (i.e. button #1 is 0, button #2 is 1, etc.).
Joystick.releaseButton(byte button)
Release the indicated button (0 - 31). The button is the 0-based button number (i.e. button #1 is 0, button #2 is 1, etc.).
Joystick.setThrottle(byte value)
Sets the throttle value. Range 0 to 255.
Joystick.setRudder(byte value)
Sets the rudder value. Range 0 to 255.
Joystick.setHatSwitch(byte hatSwitch, int 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.).
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).
Joystick2 and Joystick3 Library API
The joystickIndex is 0-based (i.e. the first game controller has a joystickIndex of 0, the second has a joystickIndex of 1, and the third has a joystickIndex of 2).
Joystick[joystickIndex].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[joystickIndex].sendState method must be called to update the game controller state.
Joystick[joystickIndex].end()
Stops the game controller emulation to a connected computer.
Joystick[joystickIndex].setXAxis(byte value)
Sets the X axis value. Range -127 to 127 (0 is center).
Joystick[joystickIndex].setYAxis(byte value)
Sets the Y axis value. Range -127 to 127 (0 is center).
Joystick[joystickIndex].setButton(byte button, byte value)
Sets the state (0 or 1) of the specified button (0 - 15). 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[joystickIndex].pressButton(byte button)
Press the indicated button (0 - 15). The button is the 0-based button number (i.e. button #1 is 0, button #2 is 1, etc.).
Joystick[joystickIndex].releaseButton(byte button)
Release the indicated button (0 - 15). The button is the 0-based button number (i.e. button #1 is 0, button #2 is 1, etc.).
Joystick[joystickIndex].sendState()
Sends the updated joystick state to the host computer. Only needs to be called if AutoSendState is false (see Joystick[joystickIndex].begin for more details).
