What you'll learn

Reading analog inputs with machine.ADC
A joystick as two potentiometers and a switch
12 bit readings, 0 to 4095
Reading a switch with Pin.PULL_UP

Difficulty: Beginner
Time: About 15 minutes
Board: ESP32-DevKitC V4
Parts: 3

How it works

A joystick module has two potentiometers, one for each direction, and a push switch. X goes to GPIO 36 (VP) and Y to GPIO 39 (VN). These read as 12 bit numbers from 0 to 4095. The switch goes to GPIO 14.

The script sets up both axes, then prints X, Y and Z once a second. Z is the switch: it uses a pull-up, so it reads 1 when idle and 0 when pushed.

Parts list

3 parts, plus the jumper wires. They retail for about $11.50; on Mokxi they're free.

1 × ESP32-DevKitC V4
1 × Thumb stickIn Claw Machine Kit, Spaceship Panel Kit.
1 × Power, 3.3 V

Kits that can build it

These 3 starter kits have every part in the circuit. Each kit's page lists what else it can build.

Wiring table

Every connection, pin by pin, read from the circuit itself. Each row joins the pin on the left to the pin on the right, by a jumper wire or a breadboard strip.

Part and pin	Connects to
Thumb stick pin VRX	ESP32-DevKitC V4 pin VP
Thumb stick pin VRY	ESP32-DevKitC V4 pin VN
Thumb stick pin SW	ESP32-DevKitC V4 pin 14
Thumb stick pin GND	Ground
Thumb stick pin VCC	3.3 V

The code

The MicroPython code exactly as the editor opens it. Change a line there and press Run: the board runs it on the official MicroPython firmware, with nothing to compile.

main.py · ESP32-DevKitC V4

# Joystick: X on GPIO 36, Y on GPIO 39 (12-bit, 0 to 4095) and the
# press switch on GPIO 14, which reads 0 when pushed.
from machine import ADC, Pin
import time

def axis(gpio):
    a = ADC(Pin(gpio))
    a.atten(ADC.ATTN_11DB)
    a.width(ADC.WIDTH_12BIT)
    return a

x, y = axis(36), axis(39)
z = Pin(14, Pin.IN, Pin.PULL_UP)

while True:
    print("X:", x.read(), "Y:", y.read(), "Z:", z.value())
    time.sleep(1)

Code walkthrough

The key functions of the sketch, and what each one does.

`axis` main.py

Builds an analog input for one GPIO pin. It creates an ADC, sets the attenuation to ADC.ATTN_11DB so it can read up to about 3.3 V, and sets 12 bit width. It returns the ADC, and the script calls it once for GPIO 36 and once for GPIO 39.

def axis(gpio):
    a = ADC(Pin(gpio))
    a.atten(ADC.ATTN_11DB)
    a.width(ADC.WIDTH_12BIT)
    return a

Troubleshooting

The usual mistakes with this circuit, and the fix for each.

Readings are stuck at the maximum This project
Check that VCC is on 3.3 V, not 5 V, and that VRX and VRY go to the VP and VN pins.
Z always reads 1 This project
Z reads 0 only while the stick is pushed down. Check that SW goes to GPIO 14.
The axis reads about half scale at rest instead of exactly zero, and the values drift a little, so the cursor or motor creeps. Thumb stick
Center is about half of the ADC range (about 512 on a 10 bit Arduino). Read it at startup and subtract that, then add a dead zone of a few counts.
The push button reads random values or always looks pressed. The switch pin is a plain contact to ground and has no pull-up on the stick. Thumb stick
Set the switch pin to INPUT_PULLUP and treat LOW as pressed. Debounce it in code. Power the stick from the same voltage as the ADC reference.
The board is not found, or upload fails with a connecting message. ESP32-DevKitC V4
Use a USB cable that carries data, not charge only. Pick the ESP32 Dev Module board. If it still fails, hold BOOT while uploading starts, then release.
Some pins never read right, or the board will not boot with a wire attached. ESP32-DevKitC V4
GPIO34 to 39 are input only and have no pull-ups. GPIO6 to 11 run the flash, so leave them alone. GPIO0, 2 and 12 are boot pins; avoid pulling them the wrong way at reset.