> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wokwi/wokwi-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Analog Joystick

> Analog Joystick with two axes (horizontal/vertical) and integrated push button

Analog Joystick with two axes (horizontal/vertical) and an integrated push button.

## Pin names

<ParamField path="VCC" type="Power">
  Positive power supply
</ParamField>

<ParamField path="VERT" type="Analog Output">
  Vertical axis output (analog)
</ParamField>

<ParamField path="HORZ" type="Analog Output">
  Horizontal axis output (analog)
</ParamField>

<ParamField path="SEL" type="Digital I/O">
  Push button
</ParamField>

<ParamField path="GND" type="Ground">
  Ground
</ParamField>

The idle position voltage is VCC/2. Moving the joystick along the vertical axis changes the voltage of the VERT pin from 0 volts (bottom) to VCC (top). Moving the joystick along the horizontal axis changes the voltages of the HORZ pin from 0 volts (right) to VCC (left).

The SEL pin is normally open (floating). Clicking on the center of the joystick shorts the SEL pin to ground. The joystick's button simulates [bouncing](/parts/wokwi-pushbutton#bouncing) by default. You can disable bouncing by setting the "bounce" attribute to "0".

## Attributes

<ParamField path="bounce" type="string" default="">
  Set to "0" to disable bouncing
</ParamField>

## Operating the Joystick

You can operate the joystick with your mouse by moving cursor over the joystick. You'll see four arrows, corresponding to the four movement directions,
and a circle in the middle. Click on one of the arrows to move the joystick shaft in that direction, and on the circle in the middle to press the
joystick's push button (connected to the SEL pin).

To operate the joystick with the keyboard, first focus on it (using the tab key or by clicking on it with the mouse), then use the arrow keys to move
the shaft of the joystick, and the space key to press the joystick's push button (connected to the SEL pin). It's possible to combine multiple keys
at once, e.g. left arrow and top arrow, to move the shaft in a diagonal direction. You can also press on the space key while holding down the arrows
to press the joystick while moving the shaft.

<Note>
  Partial movement and touch control are not currently supported. We'd love to see them supported though - so if you are up to the task, there's [an open issue waiting for your love](https://github.com/wokwi/wokwi-elements/issues/62).
</Note>

## Using the Joystick in Arduino

| Joystick Pin | Arduino Pins             | Example code pin |
| ------------ | ------------------------ | ---------------- |
| VCC          | 5V                       |                  |
| VERT         | any analog pin (A0...A5) | A0               |
| HORZ         | any analog pin (A0...A5) | A1               |
| SEL          | any digital pin          | 2                |
| GND          | GND                      |                  |

To use the Joystick in Arduino, connect the VERT and the HORZ pins to analog pins (A0...A6), and configure these pins as input. Read the joystick position using `analogRead()`.

```cpp theme={null}
#define VERT_PIN A0
#define HORZ_PIN A1
#define SEL_PIN  2

void setup() {
  pinMode(VERT_PIN, INPUT);
  pinMode(HORZ_PIN, INPUT);
  pinMode(SEL_PIN, INPUT_PULLUP);
}

void loop() {
  int vert = analogRead(VERT_PIN);
  int horz = analogRead(HORZ_PIN);
  bool selPressed = digitalRead(SEL_PIN) == LOW;
  // horz goes from 0 (right) to 1023 (left)
  // vert goes from 0 (bottom) to 1023 (top)
  // selPressed is true is the joystick is pressed
}
```

## Joystick Position Table

The following table shows the different joystick position and the corresponding HORZ / VERT values, as returned by `analogRead()`:

| Position     | HORZ | VERT |
| ------------ | ---- | ---- |
| Top-Left     | 1023 | 1023 |
| Top          | 512  | 1023 |
| Top-Right    | 0    | 1023 |
| Left         | 1023 | 512  |
| Center       | 512  | 512  |
| Right        | 0    | 512  |
| Bottom-Left  | 1023 | 0    |
| Bottom       | 512  | 0    |
| Bottom-Right | 0    | 0    |

## Using map()

You can use the [map() function](https://www.arduino.cc/reference/en/language/functions/math/map/) to re-map the values to a different range.
For instance, `map(analogRead(HORZ_PIN), 0, 1023, -100, 100)` will return -100 when the joystick is all the way to the right, 0 when the joystick
in centered, and 100 when the joystick is all the way to the left.

## Automation controls

The joystick can be controlled using [Automation Scenarios](/wokwi-ci/automation-scenarios). It exposes the following controls:

<ParamField path="x" type="float">
  Set the x value of the joystick (-1 to 1, 0 is centered)
</ParamField>

<ParamField path="y" type="float">
  Set the y value of the joystick (-1 to 1, 0 is centered)
</ParamField>

<ParamField path="pressed" type="int">
  Set to 1 to press the button, 0 to release it.
</ParamField>

## Simulator examples

* [Etch-a-sketch](https://wokwi.com/projects/296234816685212169) - A simple drawing game using a MAX7219 LED Dot Matrix