ESP32 MicroPython Joystick

This tutorial instructs you how to use a joystick with ESP32 and MicroPython. In detail, we will learn:

ESP32 MicroPython and Joystick

Hardware Preparation

1×ESP-WROOM-32 Dev Module
1×USB Cable Type-C
1×Joystick
1×Jumper Wires
1×Breadboard
1×(Recommended) Screw Terminal Expansion Board for ESP32

Or you can buy the following sensor kits:

1×DIYables Sensor Kit (30 sensors/displays)
1×DIYables Sensor Kit (18 sensors/displays)
Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you.
Additionally, some of these links are for products from our own brand, DIYables.

Overview of Joystick

You might have seen a joystick used to control games, toys, or even large machines like excavators. The joystick consists of two potentiometers arranged in a square pattern and a button. It provides the following outputs:

  • A range of 0 to 4095 for the horizontal (left-right) position.
  • A range of 0 to 4095 for the vertical (up-down) position.
  • The button's status, either ON (HIGH) or OFF (LOW).

By combining the two analog values, the joystick generates 2-D coordinates that are centered when the joystick is at rest. You can determine the actual direction of these coordinates using a test code, which we'll cover in the next section. Some applications may utilize all three outputs, while others may only use a few.

Pinout

A joystick has five pins:

  • GND pin: Connects to ground (0V).
  • VCC pin: Connects to the 3.3V supply of the ESP32.
  • VRX pin: Provides an analog value for the horizontal position (X-coordinate); connect this pin to an ADC pin on the ESP32.
  • VRY pin: Provides an analog value for the vertical position (Y-coordinate); connect this pin to an ADC pin on the ESP32.
  • SW pin: Connected to the joystick's pushbutton, which is normally open. Use a pull-up resistor to keep this pin HIGH when the button is not pressed and LOW when it is pressed.
Joystick Pinout

How It Works

  • Left/Right Movement:
    • Moving the joystick left or right changes the voltage at the VRX pin.
    • Moving it left reduces the voltage to 0 volts, while moving it right increases the voltage to 3.3 volts.
    • The ESP32 measures this voltage and converts it to a number between 0 and 4095, where 0V corresponds to 0, and 3.3V corresponds to 4095.
  • Up/Down Movement:
    • Moving the joystick up or down affects the voltage at the VRY pin.
    • Moving it up decreases the voltage to 0 volts, and moving it down raises the voltage to 3.3 volts.
    • The ESP32 reads this voltage and converts it to a number from 0 to 4095, similar to the VRX pin.
  • Combined Movements:
    • Moving the joystick in any direction changes the voltage at both the VRX and VRY pins, depending on its position along each axis.
  • Pressing the Joystick:
    • Pressing the joystick down activates an internal button.
    • A pull-up resistor connected to the SW pin causes the voltage at this pin to drop from 3.3V to 0V when pressed.
    • The ESP32 interprets this as a digital signal, reading HIGH (3.3V) when not pressed and LOW (0V) when pressed.

    When the joystick is moved, it adjusts the voltages at the VRX and VRY pins, which the ESP32 reads as values from 0 to 4095. Pressing the joystick changes the voltage at the SW pin, and the ESP32 detects this change as either HIGH or LOW.

Wiring Diagram

  • How to connect ESP32 and joystick using breadboard
The wiring diagram between ESP32 MicroPython Joystick

This image is created using Fritzing. Click to enlarge image

How to connect ESP32 and joystick

How To Program For Joystick

Fortunately, DIYables has developed a joystick library that greatly simplifies the process of using a joystick with the ESP32.

ESP32 MicroPython Code - Reads Joystick's state

The following MicroPython script:

  • Reads analog values from a joystick.
  • Checks if the joystick's thumb is pressed or released.
  • Reads the joystick's thumb press count.
""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-joystick """ from DIYables_MicroPython_Joystick import Joystick from machine import Pin, ADC import time VRX_PIN = 39 # The ESP32 pin GPIO39 (ADC3) connected to VRX pin of joystick VRY_PIN = 36 # The ESP32 pin GPIO36 (ADC0) connected to VRY pin of joystick SW_PIN = 17 # The ESP32 pin GPIO17 connected to SW pin of joystick adc_vrx = ADC(Pin(VRX_PIN)) adc_vry = ADC(Pin(VRY_PIN)) # Set the ADC width (resolution) to 12 bits adc_vrx.width(ADC.WIDTH_12BIT) adc_vry.width(ADC.WIDTH_12BIT) # Set the attenuation to 11 dB, allowing input range up to ~3.3V adc_vrx.atten(ADC.ATTN_11DB) adc_vry.atten(ADC.ATTN_11DB) joystick = Joystick(pin_x=VRX_PIN, pin_y=VRY_PIN, pin_button=SW_PIN) # Configure the debounce time if necessary (default is 50ms) joystick.set_debounce_time(100) # debounce time set to 100 milliseconds while True: joystick.loop() # Must be called frequently to process button debouncing # Read the analog values from the X and Y axes x_value = joystick.read_x() y_value = joystick.read_y() press_count = joystick.get_press_count() # Check if the button has been pressed or released if joystick.is_pressed(): print("Button Pressed") if joystick.is_released(): print("Button Released") # Print the joystick's X and Y coordinates, and pressed count print(f'Joystick Position - X: {x_value}, Y: {y_value}, pressed count: {press_count}') time.sleep(0.1) # Delay to reduce the output frequency

Detailed Instructions

Here’s instructions on how to set up and run your MicroPython code on the ESP32 using Thonny IDE:

  • Make sure Thonny IDE is installed on your computer.
  • Confirm that MicroPython firmware is loaded on your ESP32 board.
  • If this is your first time using an ESP32 with MicroPython, check out the ESP32 MicroPython Getting Started guide for step-by-step instructions.
  • Connect the joystick to the ESP32 according to the provided diagram.
  • Connect the ESP32 board to your computer with a USB cable.
  • Open Thonny IDE on your computer.
  • In Thonny IDE, go to Tools Options.
  • Under the Interpreter tab, choose MicroPython (ESP32) from the dropdown menu.
  • Make sure the correct port is selected. Thonny IDE usually detects it automatically, but you might need to select it manually (like COM12 on Windows or /dev/ttyACM0 on Linux).
  • Navigate to the Tools Manage packages on the Thonny IDE.
  • Search “DIYables-MicroPython-Joystick”, then find the Joystick library created by DIYables.
  • Click on DIYables-MicroPython-Joystick, then click Install button to install Joystick library.
ESP32 MicroPython Joystick library
  • Copy the provided MicroPython code and paste it into Thonny's editor.
  • Save the code to your ESP32 by:
    • Clicking the Save button or pressing Ctrl+S.
    • In the save dialog, choose MicroPython device.
    • Name the file main.py.
  • Click the green Run button (or press F5) to execute the script.
  • Slide the joystick left, right, up, or down.
  • Push down on the top of the joystick.
  • Check out the message in the Shell at the bottom of Thonny.
Shell x
>>> %Run -c $EDITOR_CONTENT
MPY: soft reboot MPY: soft reboot Joystick Position - X: 1808, Y: 1869, pressed count: 0 Joystick Position - X: 1415, Y: 1872, pressed count: 0 Joystick Position - X: 0, Y: 0, pressed count: 0 Joystick Position - X: 0, Y: 590, pressed count: 0 Joystick Position - X: 0, Y: 786, pressed count: 0 Joystick Position - X: 0, Y: 1088, pressed count: 0 Joystick Position - X: 0, Y: 1872, pressed count: 0 Joystick Position - X: 0, Y: 2320, pressed count: 0 Joystick Position - X: 0, Y: 4095, pressed count: 0 Joystick Position - X: 0, Y: 4095, pressed count: 0 Joystick Position - X: 834, Y: 4095, pressed count: 0 Joystick Position - X: 1802, Y: 4095, pressed count: 0 Joystick Position - X: 2924, Y: 4095, pressed count: 0 Joystick Position - X: 4095, Y: 4095, pressed count: 0 Joystick Position - X: 4095, Y: 0, pressed count: 0 Joystick Position - X: 4095, Y: 0, pressed count: 0 Joystick Position - X: 2672, Y: 0, pressed count: 0 Joystick Position - X: 1152, Y: 0, pressed count: 0 Joystick Position - X: 0, Y: 0, pressed count: 0 Joystick Position - X: 0, Y: 1872, pressed count: 0 Joystick Position - X: 0, Y: 4095, pressed count: 0 Joystick Position - X: 0, Y: 4095, pressed count: 0 Joystick Position - X: 4095, Y: 1879, pressed count: 0 Joystick Position - X: 1800, Y: 1883, pressed count: 0 Joystick Position - X: 1805, Y: 1873, pressed count: 0 Joystick Position - X: 4095, Y: 4095, pressed count: 0 Joystick Position - X: 1803, Y: 1870, pressed count: 0 Joystick Position - X: 1797, Y: 1872, pressed count: 0 Button Pressed Joystick Position - X: 1801, Y: 1873, pressed count: 0 Button Pressed Joystick Position - X: 1803, Y: 4095, pressed count: 0 Button Released Joystick Position - X: 1801, Y: 4095, pressed count: 1 Joystick Position - X: 1797, Y: 4095, pressed count: 1 Joystick Position - X: 1805, Y: 4095, pressed count: 1 Joystick Position - X: 1805, Y: 1869, pressed count: 1 Joystick Position - X: 1802, Y: 1877, pressed count: 1 Joystick Position - X: 1802, Y: 1871, pressed count: 1 Button Pressed Joystick Position - X: 1804, Y: 1872, pressed count: 1 Joystick Position - X: 1799, Y: 1861, pressed count: 1 Joystick Position - X: 1805, Y: 1870, pressed count: 1 Joystick Position - X: 1806, Y: 1877, pressed count: 1 Button Released Joystick Position - X: 1805, Y: 1866, pressed count: 2 Joystick Position - X: 1808, Y: 1859, pressed count: 2 Button Pressed Joystick Position - X: 1799, Y: 1874, pressed count: 2 Joystick Position - X: 1808, Y: 1876, pressed count: 2 Joystick Position - X: 1803, Y: 1874, pressed count: 2 Joystick Position - X: 4095, Y: 4095, pressed count: 2 Button Released Joystick Position - X: 4095, Y: 4095, pressed count: 3 Joystick Position - X: 4095, Y: 4095, pressed count: 3
MicroPython (ESP32) • CP2102 USB To UART Bridge Controller @ COM12 ≡

When using the joystick, observe the message in the Shell at the bottom of Thonny. If the X value is 0, it indicates a left position; otherwise, it indicates right. If the Y value is 0, it represents an upward position; otherwise, it indicates downward.

Keep in mind that although the theoretical range for X/Y values is from 0 to 4095, in practice, the values may not reach these extremes due to the joystick's mechanical characteristics. This variation is normal and acceptable for most applications.

※ NOTE THAT:

This tutorial demonstrates how to use the adc.read() function to read values from an ADC (Analog-to-Digital Converter) connected to a joystick. The ESP32's ADC is suitable for projects that do not require high precision. However, if your project needs accurate measurements, keep the following in mind:

  • The ESP32 ADC is not perfectly accurate and may require calibration for precise results. Each ESP32 board may vary slightly, so calibration is necessary for each individual board.
  • Calibration can be challenging, especially for beginners, and might not always yield the exact results you desire.

For projects requiring high precision, consider using an external ADC (e.g., ADS1115) with the ESP32 or opt for an Arduino, which has a more reliable ADC. If you still wish to calibrate the ESP32 ADC, refer to the ESP32 ADC Calibration Driver.

Converts analog value to MOVE LEFT/RIGHT/UP/DOWN commands

The below MicroPython code converts analog values into commands: MOVE_LEFT, MOVE_RIGHT, MOVE_UP, MOVE_DOWN.

""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-joystick """ from DIYables_MicroPython_Joystick import Joystick from machine import Pin, ADC import time # Constants for threshold values LEFT_THRESHOLD = 1000 RIGHT_THRESHOLD = 3000 UP_THRESHOLD = 1000 DOWN_THRESHOLD = 3000 # Command constants COMMAND_NO = 0x00 COMMAND_LEFT = 0x01 COMMAND_RIGHT = 0x02 COMMAND_UP = 0x04 COMMAND_DOWN = 0x08 VRX_PIN = 39 # The ESP32 pin GPIO39 (ADC3) connected to VRX pin of joystick VRY_PIN = 36 # The ESP32 pin GPIO36 (ADC0) connected to VRY pin of joystick SW_PIN = 17 # The ESP32 pin GPIO17 connected to SW pin of joystick adc_vrx = ADC(Pin(VRX_PIN)) adc_vry = ADC(Pin(VRY_PIN)) # Set the ADC width (resolution) to 12 bits adc_vrx.width(ADC.WIDTH_12BIT) adc_vry.width(ADC.WIDTH_12BIT) # Set the attenuation to 11 dB, allowing input range up to ~3.3V adc_vrx.atten(ADC.ATTN_11DB) adc_vry.atten(ADC.ATTN_11DB) joystick = Joystick(pin_x=VRX_PIN, pin_y=VRY_PIN, pin_button=SW_PIN) # Configure the debounce time if necessary (default is 50ms) joystick.set_debounce_time(100) # debounce time set to 100 milliseconds def check_commands(x_value, y_value): command = COMMAND_NO # Check for left/right commands if x_value < LEFT_THRESHOLD: command |= COMMAND_LEFT elif x_value > RIGHT_THRESHOLD: command |= COMMAND_RIGHT # Check for up/down commands if y_value < UP_THRESHOLD: command |= COMMAND_UP elif y_value > DOWN_THRESHOLD: command |= COMMAND_DOWN return command while True: x_value = joystick.read_x() y_value = joystick.read_y() command = check_commands(x_value, y_value) if command & COMMAND_LEFT: print("COMMAND LEFT") if command & COMMAND_RIGHT: print("COMMAND RIGHT") if command & COMMAND_UP: print("COMMAND UP") if command & COMMAND_DOWN: print("COMMAND DOWN") time.sleep(0.5) # Delay to reduce the output frequency

Detailed Instructions

  • Copy the above code and paste it into the editor of Thonny IDE.
  • Save the script to your ESP32 board.
  • Click the green Run button (or press F5) to execute the script.
  • Move the joystick left, right, up, down, or in any direction.
  • Check out the message in the Shell at the bottom of Thonny.
Shell x
>>> %Run -c $EDITOR_CONTENT
MPY: soft reboot MPY: soft reboot COMMAND UP COMMAND RIGHT COMMAND DOWN COMMAND DOWN COMMAND DOWN COMMAND RIGHT COMMAND DOWN COMMAND RIGHT COMMAND DOWN COMMAND LEFT COMMAND DOWN
MicroPython (ESP32) • CP2102 USB To UART Bridge Controller @ COM12 ≡

※ NOTE THAT:

There might be no command, one command, or even two commands at the same time, like UP and LEFT together.

Converts analog values to angles to control two servo motors

Learn detail in this ESP32 MicroPython Joystick Controls Servo Motor tutorial.

Video Tutorial

※ OUR MESSAGES

  • As freelancers, We are AVAILABLE for HIRE. See how to outsource your project to us
  • Please feel free to share the link of this tutorial. However, Please do not use our content on any other websites. We invested a lot of effort and time to create the content, please respect our work!