ESP32-S3 board
The brain that runs your uploaded sketch.
01 First, know the pieces
What you need
Five things, one of them brand new. Tap Define on any part you haven't met — the answer opens as a field note you can read and dismiss without losing your place.
GPIO extension board
Spreads the pins into rows you can reach and label.
Joystick module
A thumb stick over two dials and a hidden push button.
5 jumper wires (F/M)
Female ends grip the module's header pins; male ends reach the board.
Arduino IDE
Uploads code and opens Serial Monitor.
02 Make the physical circuit
Chart the circuit
The official Freenove diagram is your chart — schematic on top, the same circuit built on a breadboard below. Click it to enlarge. Each connection tells you where the wire goes and why.
VRX
→GPIO 14
Carries the X potentiometer's voltage for the board to measure.
VRY
→GPIO 13
Carries the Y potentiometer's voltage the same way.
SW
→GPIO 12
The button under the stick pulls this pin LOW when you press.
+5V
→3.3V
Powers the module — the official diagram feeds this pin from the 3.3V rail.
GND
→GND
Gives board and module the same zero point.
Power from 3.3V. The module's pin is printed +5V, and the official diagram feeds it from the 3.3V rail — follow the diagram. Unplug USB before you move any wire.
03 One action at a time
Build it
This is the main path — you can finish the day without opening a single field note. Tap each step as you go to keep your place.
0 / 8 done
Seat the ESP32-S3 on the GPIO extension board and keep USB unplugged while you wire.
Push the five female jumper ends onto the module's header pins — the labels VRX, VRY, SW, +5V, and GND are printed beside them.
Connect
VRX → GPIO 14,VRY → GPIO 13, andSW → GPIO 12.Connect the module's
+5Vpin to the 3.3V rail andGND → GND, just as the chart shows.Compare every wire to the chart before you plug in USB.
Open
Sketch_13.1_Joystick.inoin Arduino IDE and upload it.Open Serial Monitor and set the baud rate to
115200.Glide the stick to its edges, then press it straight down like a button.
04 Read just enough code
Read the code
The loop is three reads and one print. Two pins are measured with analogRead, one with digitalRead, and printf lines all three up. Switch to MicroPython if you'd rather see the same idea in Python — the wiring never changes.
int xyzPins[] = {14, 13, 12}; //x,y,z pins
void setup() {
Serial.begin(115200);
pinMode(xyzPins[2], INPUT_PULLUP); //z axis is a button.
}
void loop() {
int xVal = analogRead(xyzPins[0]);
int yVal = analogRead(xyzPins[1]);
int zVal = digitalRead(xyzPins[2]);
Serial.printf("X,Y,Z: %d,\t%d,\t%d\n", xVal, yVal, zVal);
delay(500);
}int xyzPins[] = {14, 13, 12}One array holds all three pins — X on GPIO 14, Y on GPIO 13, Z on GPIO 12. pinMode(xyzPins[2], INPUT_PULLUP)Sets the button pin so it rests at 1 and a press pulls it to 0. analogRead(xyzPins[0])Measures the X potentiometer's voltage as a number from 0 to 4095. Serial.printf("X,Y,Z: %d,\t%d,\t%d\n", …)Prints all three values on one tab-separated line, twice a second. Optional side path · same circuit
xVal=ADC(Pin(14))
yVal=ADC(Pin(13))
zVal=Pin(12,Pin.IN,Pin.PULL_UP)
xVal.atten(ADC.ATTN_11DB)
xVal.width(ADC.WIDTH_12BIT)
print("X,Y,Z:",xVal.read(),",",yVal.read(),",",zVal.value())ADC(Pin(14))Wraps GPIO 14 in an ADC reader — the same measurement analogRead does in C.Pin(12,Pin.IN,Pin.PULL_UP)The button pin with the internal pull-up — 1 at rest, 0 while pressed.Same pins, same three values. This version prints once a second where the Arduino sketch prints twice. Run it in Thonny if MicroPython is set up; otherwise skip it — it should never block the Arduino-first path.
05 Understand, don't memorise
Two dials and a button in one grip
You already know every part inside this module. The joystick simply packs them under a single stick — the same arrangement lives inside every gamepad you've ever held.
Pots turn
Pushing the stick rotates two potentiometers set at right angles.
ADC reads
analogRead turns each pot's voltage into a number from 0 to 4095.
Button drops
INPUT_PULLUP holds GPIO 12 at 1 until a press pulls it to 0.
Serial prints
Twice a second the sketch prints all three values on one line.
The model
one joystick = two potentiometers at right angles + one push button
Two of the same dial
Each axis is the dial you've already read — one turned by side-to-side motion, one by forward-and-back. At rest both sit near the middle of their travel.
Why Z rests at 1
The internal pull-up holds the button pin HIGH with nothing connected in the module. Pressing the stick closes the switch to ground, so the reading drops to 0.
06 Know it worked
Test & debug
Success and recovery sit side by side, so you never have to go hunting when something looks off.
What you should see
X,Y,Z: 1917, 1846, 1X,Y,Z: 4095, 1852, 1X,Y,Z: 1921, 1839, 0
A new line lands twice a second. At rest both axes sit near mid-scale — anywhere around 1800–2200 is healthy, and your exact numbers will differ. A full push drives one axis toward 0 or 4095, and a straight-down press flips Z from 1 to 0.
If it doesn't
- One axis stuck at 0 or 4095? Reseat that axis's wire — VRX belongs on GPIO 14, VRY on GPIO 13.
- Z always 1? Check the SW wire on GPIO 12, then press straight down firmly — a sideways tilt won't click it.
- Both axes dead? Check the module's +5V and GND pins first.
- Blank monitor? Confirm 115200 baud, then the board and port.
- Upload fails? Swap in a data-capable USB cable.
07 Make the idea yours
Try this: chart your stick
Same working circuit, one new habit: learning your instrument's true numbers. It fits inside today's 20 minutes.
Find true centre
Let the stick rest and write down the X and Y values. Watch a few more lines land and count how far the numbers drift while nothing touches the stick.
Map the corners
Push the stick to north, south, east, and west, and record the X and Y pair at each full deflection. Sketch them as a compass with your centre numbers in the middle.
Logbook
08 Learn it with a hand on the tiller
Coach me through it
Every lesson ships with a code and a machine-readable packet, so an agent can guide you with full context.
Lesson code
TSK-DAY19-JOYSTICK
Context packet
How the agent should behave: guide one physical connection at a time, wait for you to confirm, explain terms on request, and always check wiring, board, port, and USB before changing code.