adafruit-mirror/arduino-pico
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
arduino-pico/libraries/Joystick/docs/api.md
Earle F. Philhower, III bd902a93f5
Add true 10- and 16-bit joystick modes (#2276) 
Fixes #2275

Adds `Joystick.use10bit` and `Joystick.use16bit` methods.  10-bit is
unsigned from 0...1023 while 16-bit is signed -32767..32767.
Defines a new HID descriptor to support the increased resolution.
2024-07-18 16:07:29 -07:00

8.2 KiB
Raw Permalink Blame History

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()

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

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.use10bit()

Joystick.use16bit()

Set axis value range to 10-bit (0...1024) or 16-bit (-32767...32767).

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()

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.X()

Update X axis. Note: If manual send is active, the value is sent to the host only after calling send_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.

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()

Update Y axis. Please refer to Joystick.X().

Joystick.Z()

Update Z axis. Please refer to Joystick.X().

Joystick.Zrotate()

Update Z rotate axis. Please refer to Joystick.X().

Joystick.sliderLeft()

Left slider value. Please refer to Joystick.X().

Joystick.sliderRight()

Right slider value. Please refer to Joystick.X().

Joystick.slider()

Same as Joystick.sliderLeft().

Joystick.position()

Sets X and Y axis in one call. If autosending is active, one report is generated. Please refer to Joystick.X().

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