# 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 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 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 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 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 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 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 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.