ESP32 MicroPython Joystick Servo Motor
This guide will demonstrate how to control two servo motors or a pan-tilt kit using an ESP32 and a joystick with MicroPython.
A joystick contains two control components, called potentiometers, arranged in a cross pattern, referred to as the X-axis and Y-axis. These potentiometers generate signals, the X-value and Y-value, which come from the VRX and VRY pins of the joystick. These signals are used to control two servo motors: the X-value controls servo motor #1, while the Y-value controls servo motor #2. When used with a pan-tilt kit, the two servo motors work together to move in three dimensions.
The application can be used in two ways:
- Use case 1: Moving the joystick controls the servo motors:
- The servo motors’ angles correspond to the joystick's left-right (X) and up-down (Y) movements.
- Releasing the joystick returns both it and the servo motors to their initial positions.
- Use case 2: Use the joystick to direct the servo motors:
- Moving the joystick left rotates servo motor #1 clockwise.
- Moving the joystick right rotates servo motor #1 counterclockwise.
- Moving the joystick upward rotates servo motor #2 clockwise.
- Moving the joystick downward rotates servo motor #2 counterclockwise.
- Releasing the joystick maintains the current positions of the servo motors.
- Pressing the joystick's button resets the servo motors to the center position.
- ESP32 MicroPython Getting Started tutorial
- How to connect ESP32 with joystick and servo motor using breadboard
- How to connect ESP32 with joystick and servo motor using screw terminal block breakout board
- 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 ESP32 board to the joystick and servo motor 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-Servo”, then find the Servo Motor library created by DIYables.
- Click on DIYables-MicroPython-Servo, then click Install button to install Servo Motor library.
- 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.
- 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.
- Push the joystick in any direction.
- Watch the servo motor spin.
- Check out the message in the Shell at the bottom of Thonny.
- 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.
- 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 in any direction.
- Observe the servo motor rotating.
- Check out the message in the Shell at the bottom of Thonny.
Hardware Preparation
| 1 | × | ESP-WROOM-32 Dev Module | |
| 1 | × | USB Cable Type-C | |
| 1 | × | Joystick | |
| 2 | × | Servo Motor | |
| 2 | × | (Optional) Pan-tilt kit with servo motor | |
| 1 | × | Jumper Wires | |
| 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.
Additionally, some of these links are for products from our own brand, DIYables.
Overview of Joystick and Servo Motor
If you're new to Joystick, Servo Motor, or MicroPython programming for the ESP32, I recommend checking out these tutorials:
These tutorials will provide you with a comprehensive understanding of Joystick and Servo Motor pinouts, how to connect these components to the ESP32, and how to effectively control their behavior using MicroPython code.
Wiring Diagram
This image is created using Fritzing. Click to enlarge image
ESP32 MicroPython Code
ESP32 MicroPython Code - The servo motors rotate according to the movement of the joystick's thump
"""
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-servo-motor
"""
from DIYables_MicroPython_Joystick import Joystick
from DIYables_MicroPython_Servo import Servo
from machine import Pin, ADC
import time
JOYSTICK_X_PIN = 36 # The ESP32 pin GPIO36 (ADC0) connected to VRX pin of joystick
JOYSTICK_Y_PIN = 39 # The ESP32 pin GPIO39 (ADC3) connected to VRY pin of joystick
BUTTON_PIN = 23 # The ESP32 pin GPIO23 connected to SW pin of joystick
SERVO_X_PIN = 13 # The ESP32 pin GPIO13 connected to Servo motor 1
SERVO_Y_PIN = 25 # The ESP32 pin GPIO25 connected to Servo motor 2
adc_vrx = ADC(Pin(JOYSTICK_X_PIN))
adc_vry = ADC(Pin(JOYSTICK_Y_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=JOYSTICK_X_PIN, pin_y=JOYSTICK_Y_PIN, pin_button=BUTTON_PIN)
# Initialize the two servos
xServo = Servo(SERVO_X_PIN) # Use the constant for the X servo pin
yServo = Servo(SERVO_Y_PIN) # Use the constant for the Y servo pin
# Function to map the joystick value to servo angle
def map_value(value, in_min, in_max, out_min, out_max):
return int((value - in_min) * (out_max - out_min) / (in_max - in_min) + out_min)
# Main loop
while True:
joystick.loop() # Must be called frequently to process joystick data
# Read the X and Y axis values (12-bit resolution from the library)
x_value = joystick.read_x()
y_value = joystick.read_y()
# Map the 12-bit values (0 to 4095) to servo angles (0 to 180 degrees)
x_angle = map_value(x_value, 0, 4095, 0, 180)
y_angle = map_value(y_value, 0, 4095, 0, 180)
# Move the servos to the mapped angles
xServo.move_to_angle(x_angle)
yServo.move_to_angle(y_angle)
# Print the joystick's X and Y values and the corresponding servo angles
print(f'Joystick X: {x_value}, Y: {y_value} => Servo X Angle: {x_angle}°, Y Angle: {y_angle}°')
time.sleep(0.05) # 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:
Shell x
>>> %Run -c $EDITOR_CONTENT
MPY: soft reboot
MicroPython (ESP32) • CP2102 USB To UART Bridge Controller @ COM12 ≡
※ 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:
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.
ESP32 MicroPython Code - Use the joystick to command servo motors
"""
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-servo-motor
"""
from DIYables_MicroPython_Joystick import Joystick
from DIYables_MicroPython_Servo import Servo
from machine import Pin, ADC
import time
JOYSTICK_X_PIN = 36 # The ESP32 pin GPIO36 (ADC0) connected to VRX pin of joystick
JOYSTICK_Y_PIN = 39 # The ESP32 pin GPIO39 (ADC3) connected to VRY pin of joystick
BUTTON_PIN = 23 # The ESP32 pin GPIO23 connected to SW pin of joystick
SERVO_X_PIN = 13 # The ESP32 pin GPIO13 connected to Servo motor 1
SERVO_Y_PIN = 25 # The ESP32 pin GPIO25 connected to Servo motor 2
adc_vrx = ADC(Pin(JOYSTICK_X_PIN))
adc_vry = ADC(Pin(JOYSTICK_Y_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=JOYSTICK_X_PIN, pin_y=JOYSTICK_Y_PIN, pin_button=BUTTON_PIN)
# Initialize the two servos
xServo = Servo(SERVO_X_PIN) # Use the constant for the X servo pin
yServo = Servo(SERVO_Y_PIN) # Use the constant for the Y servo pin
# Define commands
COMMAND_NO = 0x00
COMMAND_LEFT = 0x01
COMMAND_RIGHT = 0x02
COMMAND_UP = 0x04
COMMAND_DOWN = 0x08
# Define thresholds and intervals
LEFT_THRESHOLD = 1000
RIGHT_THRESHOLD = 3000
UP_THRESHOLD = 1000
DOWN_THRESHOLD = 3000
UPDATE_INTERVAL = 100 # 100ms
# Initialize variables
xAngle = 90 # The center position of servo #1
yAngle = 90 # The center position of servo #2
command = COMMAND_NO
last_update_time = time.ticks_ms()
# Function to ensure the angle stays within the 0 to 180 degree range
def limit_angle(angle):
if angle < 0:
return 0
elif angle > 180:
return 180
return angle
while True:
joystick.loop() # Process joystick data
current_time = time.ticks_ms()
if time.ticks_diff(current_time, last_update_time) > UPDATE_INTERVAL:
last_update_time = current_time
# Read X and Y analog values
x_value = joystick.read_x()
y_value = joystick.read_y()
# Reset command
command = COMMAND_NO
# Check left/right commands
if x_value < LEFT_THRESHOLD:
command |= COMMAND_LEFT
elif x_value > RIGHT_THRESHOLD:
command |= COMMAND_RIGHT
# Check up/down commands
if y_value < UP_THRESHOLD:
command |= COMMAND_UP
elif y_value > DOWN_THRESHOLD:
command |= COMMAND_DOWN
# Print and process commands
if command & COMMAND_LEFT:
print("COMMAND LEFT")
xAngle -= 1
if command & COMMAND_RIGHT:
print("COMMAND RIGHT")
xAngle += 1
if command & COMMAND_UP:
print("COMMAND UP")
yAngle -= 1
if command & COMMAND_DOWN:
print("COMMAND DOWN")
yAngle += 1
# Limit the angles to the range of 0 to 180 degrees
xAngle = limit_angle(xAngle)
yAngle = limit_angle(yAngle)
# Handle button press
if joystick.is_pressed():
print("The button is pressed")
xAngle = 90 # Reset to center position
yAngle = 90
# Move servos to the calculated angles
xServo.move_to_angle(xAngle)
yServo.move_to_angle(yAngle)
# Print servo angles to console
print(f"Servo Motor's Angle: {xAngle}°, {yAngle}°")
Detailed Instructions
Shell x
>>> %Run -c $EDITOR_CONTENT
MPY: soft reboot
MicroPython (ESP32) • CP2102 USB To UART Bridge Controller @ COM12 ≡
Code Explanation
Look at the explanations in the comments in the source code.