ESP32 UNO - Joystick

Components You Need

Or you can buy the following kits:

The Thumb Joystick at a Glance

By the end of this part, you know what the module sends to the board.

Joysticks sit on game pads, RC toy remotes and the control levers of heavy machines such as diggers. The small module used here packs two potentiometers, mounted at 90 degrees to each other, and one push switch under the stick.

Put X and Y together and you get a 2-D point. A spring pulls the stick back to the middle, so at rest both numbers sit near the center of the range. The first sketch below shows you which side is left, right, up and down on your module. A project may use all three outputs or only one or two of them.

Pinout

Match these five pins before you plug in any jumper wire.

With a pull-up resistor on SW, the pin stays HIGH until you press the stick, then drops to LOW.

Good to know: feed the module from 3.3V. The axis pins output a voltage between 0V and VCC, and ESP32 Uno pins are NOT 5V tolerant.

How It Works

Here you see how a stick position becomes a number in your code.

Each axis is a voltage divider. Moving the stick slides the wiper, and the ESP32 Uno ADC converts that voltage to a 12-bit number. A diagonal push changes VRX and VRY at the same time, each one by how far the stick traveled on its own axis. Pressing the stick closes the internal switch, so SW is pulled to ground and reads LOW.

Good to know: the ESP32 Uno ADC is 12-bit, so the scale ends at 4095, not 1023.

ESP32 Uno Pinout

Your sketch never uses the printed label (A1, A0, D2); it uses the GPIO number behind it. Find those three headers in the diagram below first.

How to Connect the Joystick

By the end of this part, the joystick is wired and powered.

This image is created using Fritzing. Click to enlarge image

Good to know: never connect the joystick VCC to 5V. At 5V the axis pins can push 5V into the ESP32 Uno analog inputs and damage them.

Reading a Joystick in Code

By the end of this part, you know the two tools each sketch below uses.

Step 1 — The two axes

Read each axis with analogRead(). Pass the GPIO number of the header, not its label.

Step 2 — The stick click

The SW pin is just a push button. The ezButton library switches on the internal pull-up of D2 (GPIO26) and filters contact bounce. More button details are in ESP32 Uno - Button.

Raw readings are rarely the final goal. The examples below turn them into values your project can act on.

ESP32 Uno Code

Pick the sketch that matches your goal. Start with the first one, since it shows how your module is turned.

Sketch 1 — Print the X and Y Numbers

This sketch samples both axes five times per second and prints them.

Good to know: the analogSetAttenuation(ADC_11db) line in setup() lets the ESP32 Uno analog pins measure the full swing, from 0V up to about 3.3V. Without a wide range, the readings hit 4095 when the stick is only half way, and the joystick values look wrong.

Upload and Test

1. First time with this board? Set it up with ESP32 Uno - Getting Started before you continue.
2. Build the circuit by following the wiring table above.
3. Plug in the USB Type-C cable between the ESP32 Uno and your computer.
4. Select the board in Arduino IDE: pick ESP32 Dev Module and the COM port of the board (CH340).
5. Paste the sketch into a new Arduino IDE window.
6. Send the sketch to the board with the Upload arrow. If it stops at "Connecting...", pull the VRY wire for a moment.
7. Push the stick to its edge and sweep it around in a full circle, either way.
8. Open the Serial Monitor at 9600 baud and watch the numbers.

1. Pro tip: put a small piece of tape on the module and mark the side where X shows 0 as "L" and the side where Y shows 0 as "U". The opposite edges are right and down.

Sketch 2 — X, Y and the Stick Click

This sketch adds the stick click. It prints X, Y and the button level each loop, plus one line on every press and release.

Upload and Test

1. Open Library Manager from the left sidebar (the Libraries icon).
2. Search for “ezButton”; the right one is made by ArduinoGetStarted.com.
3. Hit Install and wait for it to finish.

• Search for ezButton created by ArduinoGetStarted.com and click the Install button.

1. Paste the sketch into Arduino IDE.
2. Upload it to the ESP32 Uno.
3. Tilt the stick in each direction.
4. Click the stick straight down, then let go.
5. Read the Serial Monitor.

1. Pro tip: this sketch prints with no delay, so the monitor scrolls fast. Turn off autoscroll in the Serial Monitor to read one line at a time.

Sketch 3 — Turn Stick Moves into Direction Commands

This sketch checks each axis against a low and a high limit. The limits 1600 and 3200 match the 12-bit scale, so the rest zone near the middle sends nothing.

Upload and Test

1. Paste the sketch into Arduino IDE.
2. Upload it to the ESP32 Uno.
3. Push the stick to each side and to a corner.
4. Read the Serial Monitor.

1. Pro tip: the loop has no delay, so one push prints many lines. Add delay(100); at the end of loop() while you test.

Sketch 4 — Aim Two Servos with the Stick

Map each axis to an angle and you can aim a pan-tilt bracket with two servos. That build has its own page: ESP32 Uno - Joystick controls Servo Motor.

Video Tutorial

See the ESP32 Uno build in action in the video below.

Code Explanation

This part maps each key line to its job.

The result is a clean set of direction flags that you can hook to motors, a cursor or a game.

ESP32 Uno vs UNO R4 for This Project

This shows what changes when you move this joystick project from the UNO R4 to the ESP32 Uno.

The header positions are the same, so the same wiring works as long as you move the joystick VCC wire to 3.3V. Watch the A0 boot pin during uploads.

Go Wireless: Joystick Position on Your Phone

By the end of this part, you have an idea for a wireless joystick build.

The ESP32 Uno has WiFi and Bluetooth (Classic and BLE) on board. Stream the X and Y numbers to a phone and watch them move on a live plot, or send direction commands to a robot across the room. If you use WiFi, move VRX and VRY to A2 and A3 (GPIO35 and GPIO34) first, because A0 and A1 are ADC2 pins and stop reading while WiFi runs. You can also skip the hardware stick and use an on-screen joystick in the phone app.

• ESP32 Uno - Web Plotter
• ESP32 Uno - Web Monitor
• ESP32 Uno - Web Joystick
• ESP32 Uno - Bluetooth Joystick

Try These Next

• Add a dead zone around the center so tiny hand shakes give no command.
• Use the stick click to switch between "slow" and "fast" mode.
• Drive two servos with the axes, as in the servo page linked above.

Function References

• pinMode()
• digitalRead()
• analogRead()
• Serial

Troubleshooting

FAQ

How does a 2-axis thumb joystick sense position?

It holds two potentiometers, one per axis. The stick turns both wipers, so each one outputs a voltage between 0V and VCC. The ESP32 Uno converts each voltage to a number from 0 to 4095.

Is 3.3V enough to run the joystick module?

Yes. The module is only two potentiometers and a switch, so it works at any voltage. At 3.3V, the full stick travel still gives the full 0 to 4095 scale, and the ESP32 Uno inputs stay safe.

Do I need a resistor on the SW pin?

No. The ezButton library turns on the internal pull-up of D2 (GPIO26). The pin reads 1 when the stick is free and 0 when you click it.

Why are my joystick numbers four times bigger than in older Uno sketches?

The ESP32 Uno ADC is 12-bit (0 to 4095), while the UNO R4 uses 10-bit (0 to 1023) by default. Multiply old thresholds by 4. That is why this page uses 1600 and 3200 instead of 400 and 800.

What is the analogSetAttenuation(ADC_11db) line in the joystick code for?

This line widens what the ESP32 Uno analog pins can measure to roughly 0 to 3.3V, so stick edge to stick edge spans the whole 0 to 4095 scale. Leave it out and the numbers top out long before the edge. Sketches for the UNO R4 never have this line, because only the ESP32 Uno family needs it. Never let VRX or VRY go above 3.3V.

Can I read the joystick while the ESP32 Uno is on WiFi?

Not on A0 and A1. They are ADC2 pins (GPIO2 and GPIO4), and ADC2 cannot be read while WiFi is on. Move VRX and VRY to A2 to A5 (GPIO35, 34, 36, 39) or to GPIO32/33, and change the pin numbers in the code.

Can the SW pin go on A2 to A5?

Only with an extra part. A2 to A5 (GPIO35, 34, 36, 39) are input only and have no internal pull-up. Add a 10kΩ resistor from SW to 3.3V, or keep SW on a normal digital header like D2.

How do I connect two joysticks to one ESP32 Uno?

Give the second stick two more analog pins (for example A2 and A3) and one more digital pin for its click. Copy the reading lines with new pin names, and make a second ezButton object.

What if my joystick project needs more pins than the Uno headers give?

The ESP32 Uno has a few extra holes near the power header. GPIO32 and GPIO33 offer I/O, PWM and analog on ADC1, so they also read while WiFi is on. GPIO15 offers I/O, PWM and analog on ADC2. Add a short pin header to the holes you need, then use the plain GPIO number in your sketch. For a second joystick or a WiFi build, put the axes on GPIO32 and GPIO33. Two warnings: (1) GPIO15 and GPIO0 (the IO0 pin at the unused Uno NC position) are boot strapping pins, and a wrong connection can stop the board from booting or uploading code, so use GPIO32/33 first; (2) never use the six holes under the digital header (SD0 to SD3, CMD, CLK = GPIO6 to GPIO11), because they connect to the flash chip and using them crashes the board.

Do UNO joystick shields fit the ESP32 Uno?

Most of them fit, because the header layout is the same. Check that the shield powers its sticks from 3.3V, or that its analog outputs never go above 3.3V. Then map each shield pin to its GPIO with the pinout diagram.

Can I control a servo or a robot car with this joystick?

Yes. Use map() to turn 0 to 4095 into 0 to 180 degrees for a servo, or use the direction commands to drive motors. The ESP32 Uno servo page uses the ESP32Servo library.

Learn More

• ESP32 UNO - Joystick - Servo Motor