Earle F. Philhower, III
7aa1c08d17
Move the Joystick, Keyboard, and Mouse into a base class which handles the operation/input, and a subclass which will implement the reporting as a HID device via USB, Bluetooth Classic, or Bluetooth Low Energy (BLE). Reduce copies of library code and makes maintainability much better.
436 lines
8.2 KiB
Markdown
436 lines
8.2 KiB
Markdown
# Joystick library
|
|
|
|
## Methods
|
|
|
|
### `Joystick.begin()`
|
|
|
|
Must be called before starting using the Joystick emulation. To end control, use `Joystick.end()`.
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.begin()
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
None.
|
|
|
|
#### Returns
|
|
|
|
None.
|
|
|
|
#### Example
|
|
|
|
```
|
|
#include <Joystick.h>
|
|
|
|
void setup() {
|
|
pinMode(2, INPUT_PULLUP);
|
|
}
|
|
|
|
void loop() {
|
|
// Initialize the Joystick library when button is pressed
|
|
if (digitalRead(2) == LOW) {
|
|
Joystick.begin();
|
|
}
|
|
}
|
|
```
|
|
|
|
#### See also
|
|
|
|
|
|
* [Joystick.button()](#joystickbutton)
|
|
* [Joystick.end()](#joystickend)
|
|
* [Joystick.send_now()](#joysticksend_now)
|
|
* [Joystick.position()](#joystickposition)
|
|
* [Joystick.X()](#joystickx)
|
|
* [Joystick.hat()](#joystickhat)
|
|
* [Joystick.use8bit()](#joystickuse8bit)
|
|
* [Joystick.useManualSend()](#joystickuseManualSend)
|
|
|
|
### `Joystick.button()`
|
|
|
|
Updates a button of the USB joystick.
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.button(1,true);
|
|
delay(250);
|
|
Joystick.button(1,false);
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
* `button`: number of Joystick button, which status should be changed
|
|
* `val`: state of button, `true` for pressed, `false` for released
|
|
|
|
#### Returns
|
|
|
|
None.
|
|
|
|
#### Example
|
|
|
|
```
|
|
#include <Joystick.h>
|
|
|
|
void setup() {
|
|
pinMode(2, INPUT_PULLUP);
|
|
Joystick.begin();
|
|
}
|
|
|
|
void loop() {
|
|
uint8_t i = 1; //counter for the button number 1-32
|
|
if (digitalRead(2) == LOW) { //if button is pressed
|
|
Joystick.button(i,true); //"press" the Joystick button
|
|
delay(250); //wait for 0.25s
|
|
Joystick.button(i,false); //"release" the Joystick button
|
|
i = i + 1; //increment & use next Joystick button number
|
|
if(i > 32) i = 1; //we have 32 buttons available, wrap-around
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Notes
|
|
|
|
* Up to 32 buttons are available, numbered as button 1 to button 32.
|
|
* If manual_send is active, call `Joystick.send_now()` to send an update to the host.
|
|
|
|
#### See also
|
|
|
|
* [Joystick.send_now()](#joysticksend_now)
|
|
* [Joystick.useManualSend()](#joystickuseManualSend)
|
|
* [Joystick.X()](#joystickx)
|
|
* [Joystick.hat()](#joystickhat)
|
|
|
|
|
|
### `Joystick.end()`
|
|
|
|
Stops emulating the Joystick connected to a computer. To start control, use `Joystick.begin()`.
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.end()
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
None.
|
|
|
|
#### Returns
|
|
|
|
None.
|
|
|
|
#### Example
|
|
|
|
```
|
|
#include <Joystick.h>
|
|
|
|
void setup() {
|
|
pinMode(2, INPUT_PULLUP);
|
|
// Initiate the Joystick library
|
|
Joystick.begin();
|
|
}
|
|
|
|
void loop() {
|
|
// If the button is pressed, send a button 1 press / release
|
|
if (digitalRead(2) == LOW) {
|
|
Joystick.button(1,true);
|
|
delay(250);
|
|
Joystick.button(1,false);
|
|
// Then end the Joystick emulation
|
|
Joystick.end();
|
|
}
|
|
}
|
|
```
|
|
|
|
#### See also
|
|
|
|
* [Joystick.begin()](#joystickbegin)
|
|
|
|
### `Joystick.use8bit()`
|
|
|
|
Switch axis value range between 10bit and 8bit.
|
|
* Default: 10bit, range for an axis from 0 to 1023
|
|
* 8bit mode: range from -127 to 127.
|
|
|
|
__Note:__ due to the gamepad descriptor of tinyUSB, the maximum range is -127/127. 10bit mode enables mapping, not a higher resolution.
|
|
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.use8bit(true)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
* `mode`: true, if values from -127/127 are used. False to use a range from 0 to 1023.
|
|
|
|
#### Returns
|
|
|
|
None.
|
|
|
|
#### Example
|
|
|
|
```
|
|
#include <Joystick.h>
|
|
|
|
void setup() {
|
|
pinMode(2, INPUT_PULLUP);
|
|
Joystick.begin();
|
|
}
|
|
|
|
void loop() {
|
|
//send middle position in default 10bit mode
|
|
Joystick.position(512,512);
|
|
delay(250);
|
|
//enable 8bit mode
|
|
Joystick.use8bit(true);
|
|
//send middle position in 8bit mode
|
|
Joystick.position(0,0);
|
|
delay(250);
|
|
|
|
//send maximum left in 10bit mode
|
|
Joystick.use8bit(false);
|
|
Joystick.position(0,0);
|
|
delay(250);
|
|
//enable 8bit mode
|
|
Joystick.use8bit(true);
|
|
//send left position in 8bit mode
|
|
Joystick.position(-127,-127);
|
|
}
|
|
```
|
|
|
|
#### See also
|
|
|
|
* [Joystick.position()](#joystickposition)
|
|
* [Joystick.X()](#joystickx)
|
|
* [Joystick.Y()](#joysticky)
|
|
* [Joystick.Z()](#joystickz)
|
|
* [Joystick.Zrotate()](#joystickrotate)
|
|
* [Joystick.slider()](#joystickslider)
|
|
* [Joystick.sliderLeft()](#joysticksliderleft)
|
|
* [Joystick.sliderRight()](#joysticksliderright)
|
|
|
|
|
|
### `Joystick.useManualSend()`
|
|
|
|
To fully control transmitting the USB-HID reports, enable manual sending.
|
|
If disabled, each call to a function updating the Joystick status (buttons, all axis, hat)
|
|
will send a HID report. If you update in a loop, the time between updates (at least 1ms) is too short and something might be not transmitted correctly.
|
|
If enabled, update all your axis values, buttons, hat and then send one report via `Joystick.send_now()`.
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.useManualSend(true)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
* `mode`: false is sending report each Joystick update, true enables manual sending via send_now().
|
|
|
|
#### Returns
|
|
|
|
None.
|
|
|
|
#### Example
|
|
|
|
```
|
|
#include <Joystick.h>
|
|
|
|
void setup() {
|
|
pinMode(2, INPUT_PULLUP);
|
|
Joystick.begin();
|
|
}
|
|
|
|
void loop() {
|
|
if (digitalRead(2) == LOW) {
|
|
// send data in 4 different reports
|
|
Joystick.button(1,true);
|
|
Joystick.button(2,true);
|
|
Joystick.button(3,true);
|
|
Joystick.button(4,true);
|
|
|
|
//enable manual send
|
|
Joystick.useManualSend(true);
|
|
|
|
//send same data in one report
|
|
Joystick.button(1,false);
|
|
Joystick.button(2,false);
|
|
Joystick.button(3,false);
|
|
Joystick.button(4,false);
|
|
Joystick.send_now();
|
|
}
|
|
}
|
|
```
|
|
|
|
#### See also
|
|
|
|
* [Joystick.send_now()](#joysticksend_now)
|
|
|
|
|
|
|
|
### `Joystick.send_now()`
|
|
|
|
Send a HID report now. Used together with manual sending, see `Joystick.useManualSend()`.
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.send_now()
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
None.
|
|
|
|
#### Returns
|
|
|
|
None.
|
|
|
|
#### Example
|
|
|
|
```
|
|
#include <Joystick.h>
|
|
|
|
void setup() {
|
|
pinMode(2, INPUT_PULLUP);
|
|
Joystick.begin();
|
|
//enable manual sending in setup
|
|
Joystick.useManualSend(true);
|
|
}
|
|
|
|
void loop() {
|
|
if (digitalRead(2) == LOW) {
|
|
// update all buttons, but nothing is sent to the host
|
|
for(uint8_t i = 1; i<=32; i++) Joystick.button(i,true);
|
|
Joystick.X(256);
|
|
Joystick.sliderLeft(0);
|
|
|
|
//now send in one HID report
|
|
Joystick.send_now();
|
|
}
|
|
}
|
|
```
|
|
|
|
#### See also
|
|
|
|
* [Joystick.useManualSend()](#joystickusemanualsend)
|
|
|
|
|
|
### `Joystick.X()`
|
|
|
|
Update X axis.
|
|
__Note:__ If [manual send](#joystickusemanualsend) is active, the value is sent to the host only after calling [send_now](#joysticksend_now).
|
|
__Note:__ If in 10bit mode (default), the parameter is interpreted from 0 to 1023.
|
|
In 8bit mode from -127 to 127. The internal resolution is always 8bit. Change setting with [use8bit](#joystickuse8bit).
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.X(0)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
* `val`: value from 0 to 1023 (default) or -127 to 127 (8bit mode)
|
|
|
|
#### Returns
|
|
|
|
None.
|
|
|
|
#### Example
|
|
|
|
```
|
|
#include <Joystick.h>
|
|
|
|
void setup() {
|
|
pinMode(2, INPUT_PULLUP);
|
|
Joystick.begin();
|
|
}
|
|
|
|
void loop() {
|
|
if (digitalRead(2) == LOW) {
|
|
Joystick.X(256);
|
|
delay(500);
|
|
Joystick.X(512);
|
|
}
|
|
}
|
|
```
|
|
|
|
#### See also
|
|
|
|
* [Joystick.Y()](#joysticky)
|
|
* [Joystick.Z()](#joystickz)
|
|
* [Joystick.Zrotate()](#joystickrotate)
|
|
* [Joystick.slider()](#joystickslider)
|
|
* [Joystick.sliderLeft()](#joysticksliderleft)
|
|
* [Joystick.sliderRight()](#joysticksliderright)
|
|
* [Joystick.send_now()](#joysticksend_now)
|
|
* [Joystick.position()](#joystickposition)
|
|
* [Joystick.hat()](#joystickhat)
|
|
* [Joystick.use8bit()](#joystickuse8bit)
|
|
* [Joystick.useManualSend()](#joystickuseManualSend)
|
|
|
|
### `Joystick.Y()`
|
|
|
|
Update Y axis. Please refer to [Joystick.X()](#joystickx).
|
|
|
|
### `Joystick.Z()`
|
|
|
|
Update Z axis. Please refer to [Joystick.X()](#joystickx).
|
|
|
|
### `Joystick.Zrotate()`
|
|
|
|
Update Z rotate axis. Please refer to [Joystick.X()](#joystickx).
|
|
|
|
### `Joystick.sliderLeft()`
|
|
|
|
Left slider value. Please refer to [Joystick.X()](#joystickx).
|
|
|
|
### `Joystick.sliderRight()`
|
|
|
|
Right slider value. Please refer to [Joystick.X()](#joystickx).
|
|
|
|
### `Joystick.slider()`
|
|
|
|
Same as [Joystick.sliderLeft()](#joysticksliderleft).
|
|
|
|
### `Joystick.position()`
|
|
|
|
Sets X and Y axis in one call. If autosending is active, one report is generated. Please refer to [Joystick.X()](#joystickx).
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.position(512,512)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
* `X`: value from 0 to 1023 (default) or -127 to 127 (8bit mode); for X axis
|
|
* `Y`: value from 0 to 1023 (default) or -127 to 127 (8bit mode); for Y axis
|
|
|
|
#### See also
|
|
|
|
* [Joystick.X()](#joystickx)
|
|
* [Joystick.Y()](#joysticky)
|
|
|
|
### `Joystick.hat()`
|
|
|
|
Set the hat value to selection angle or rest position.
|
|
|
|
#### Syntax
|
|
|
|
```
|
|
Joystick.hat(-1), // released/rest position
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
* `angle` Angle value from 0-360 degrees or -1 for released resting position. Mapped to 8 different directions.
|