Raspberry Pi Pico - Joystick
In this guide, we will learn how to use a joystick with Raspberry Pi Pico. In detail, we will find out:
- How a joystick work
- How to connect a joystick to a Raspberry Pi Pico
- How to program Raspberry Pi Pico to read values from Joystick
- How to program Raspberry Pi Pico to translate joystick's data into useful data (like XY coordinates or motor directions)
Hardware Preparation
| 1 | × | Raspberry Pi Pico W | |
| 1 | × | Raspberry Pi Pico (Alternatively) | |
| 1 | × | Micro USB Cable | |
| 1 | × | Joystick | |
| 1 | × | Jumper Wires | |
| 1 | × | Breadboard | |
| 1 | × | (Optional) Screw Terminal Expansion Board for Raspberry Pi Pico |
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
You may have seen a joystick used for controlling games, toys, or even big machines like excavators.
The joystick has two potentiometers set in a square pattern and one button. It provides these outputs:
- A range from 0 to 1023 for the horizontal (left-right) position
- A range from 0 to 1023 for the vertical (up-down) position
- The button's status, either ON (HIGH) or OFF (LOW)
When you mix two analog values, they create 2-D coordinates. These coordinates are at the center when the joystick is still. You can discover the real direction of the coordinates by using a test code, which we will discuss in the next section.
Some applications may use all three outputs, while others may use only a few.
Pinout
A joystick has five pins.
- GND pin: connect to GND (0V)
- VCC pin: connect to VCC (3.3V) of Raspberry Pico
- VRX pin: provides an analog value for horizontal position (X-coordinate), connect this pin to an ADC pin of Raspberry Pico.
- VRY pin: provides an analog value for vertical position (Y-coordinate), connect this pin to an ADC pin of Raspberry Pico.
- SW pin: connected to the joystick's pushbutton. Generally open. Use a pull-up resistor to keep this pin HIGH when button is not pressed and LOW when pressed.
How It Works
- Left/Right Movement:
- Moving the joystick left or right changes the electrical signal (voltage) at the VRX pin.
- Moving it to the left reduces the voltage to 0 volts.
- Moving it to the right raises the voltage to 3.3 volts.
- The Raspberry Pi Pico measures this voltage and turns it into a number from 0 to 1023. Therefore, 0V is 0, and 5V is 1023.
- Up/Down Movement:
- Moving the joystick up or down alters the voltage at the VRY pin.
- Shifting it up decreases the voltage to 0 volts.
- Shifting it down increases the voltage to 3.3 volts.
- The Raspberry Pi Pico also reads this voltage, changing it into a number from 0 to 1023, similarly to VRX pin.
- Combined Movements:
- Moving the joystick in any direction changes the voltage at both VRX and VRY pins depending on its position along each axis.
- Pressing the Joystick:
- Pushing the joystick down activates an internal button.
- Connecting a pull-up resistor to the SW pin will cause the voltage at this pin to drop from 5V to 0V when pressed.
- The Raspberry Pi Pico detects this as a digital signal, showing HIGH (5V) when not pressed and LOW (0V) when pressed.
When you move the joystick, it adjusts the voltages at VRX and VRY. The Raspberry Pi Pico reads these changes as numbers from 0 to 1023. Pressing the joystick alters the voltage at the SW pin, and the Raspberry Pi Pico detects this as either HIGH or LOW.
Wiring Diagram
This image is created using Fritzing. Click to enlarge image
How To Program For Joystick
Fortunately, DIYables has developed a joystick library that greatly simplifies the process of using a joystick with the Raspberry Pi Pico.
Raspberry Pi Pico Code - Reads Joystick's state
The below MicroPython script does:
- Reads analog values from a joystick.
- Checks if the joystick's thump is presed or released
- Reads the joystick's thump press count
"""
This Raspberry Pi Pico MicroPython code was developed by newbiely.com
This Raspberry Pi Pico code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/raspberry-pico/raspberry-pi-pico-joystick
"""
from DIYables_MicroPython_Joystick import Joystick
import time
# Initialize the joystick with the corresponding pins for X, Y, and button
joystick = Joystick(pin_x=26, pin_y=27, pin_button=22)
# 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.05) # Delay to reduce the output frequency
Detailed Instructions
Please follow these instructions step by step:
- Ensure that Thonny IDE is installed on your computer.
- Ensure that MicroPython firmware is installed on your Raspberry Pi Pico.
- If this is your first time using a Raspberry Pico, refer to the Raspberry Pi Pico - Getting Started tutorial for detailed instructions.
- Connect the joystick to the Raspberry Pi Pico according to the provided diagram.
- Connect the Raspberry Pi Pico to your computer using a USB cable.
- Launch the Thonny IDE on your computer.
- On Thonny IDE, select MicroPython (Raspberry Pi Pico) Interpreter by navigating to Tools Options.
- In the Interpreter tab, select MicroPython (Raspberry Pi Pico) from the drop-down menu.
- Ensure the correct port is selected. Thonny IDE should automatically detect the port, but you may need to select it manually (e.g., COM3 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.
- Copy the above code and paste it to the Thonny IDE's editor.
- Save the script to your Raspberry Pi Pico by:
- Click the Save button, or use Ctrl+S keys.
- In the save dialog, you will see two sections: This computer and Raspberry Pi Pico. Select Raspberry Pi Pico
- Save the file as main.py
- Click the green Run button (or press F5) to run the script. The script will execute.
- 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: 2003, Y: 2088, pressed count: 0
Joystick Position - X: 1977, Y: 2076, pressed count: 0
Joystick Position - X: 1980, Y: 2078, pressed count: 0
Joystick Position - X: 802, Y: 2076, pressed count: 0
Joystick Position - X: 1201, Y: 2062, pressed count: 0
Joystick Position - X: 1362, Y: 2060, pressed count: 0
Joystick Position - X: 463, Y: 2079, pressed count: 0
Joystick Position - X: 21, Y: 18, pressed count: 0
Button Pressed
Joystick Position - X: 22, Y: 18, pressed count: 0
Joystick Position - X: 21, Y: 19, pressed count: 0
Joystick Position - X: 21, Y: 20, pressed count: 0
Joystick Position - X: 21, Y: 18, pressed count: 0
Joystick Position - X: 21, Y: 19, pressed count: 0
Button Released
Joystick Position - X: 9, Y: 18, pressed count: 1
Joystick Position - X: 20, Y: 791, pressed count: 1
Joystick Position - X: 22, Y: 901, pressed count: 1
Joystick Position - X: 1130, Y: 2061, pressed count: 1
Joystick Position - X: 1699, Y: 2067, pressed count: 1
Joystick Position - X: 2000, Y: 2054, pressed count: 1
Button Pressed
Joystick Position - X: 1972, Y: 2061, pressed count: 1
Joystick Position - X: 1982, Y: 2077, pressed count: 1
Joystick Position - X: 1992, Y: 2074, pressed count: 1
Joystick Position - X: 1992, Y: 2078, pressed count: 1
Joystick Position - X: 1992, Y: 2077, pressed count: 1
Joystick Position - X: 1981, Y: 4095, pressed count: 1
Button Released
Joystick Position - X: 3124, Y: 4095, pressed count: 2
Joystick Position - X: 4066, Y: 4095, pressed count: 2
Joystick Position - X: 1998, Y: 2063, pressed count: 2
Joystick Position - X: 1130, Y: 4095, pressed count: 2
Joystick Position - X: 20, Y: 4095, pressed count: 2
Button Pressed
Joystick Position - X: 21, Y: 4095, pressed count: 2
Joystick Position - X: 21, Y: 4095, pressed count: 2
Joystick Position - X: 1976, Y: 2082, pressed count: 2
Joystick Position - X: 1974, Y: 2072, pressed count: 2
Button Released
Joystick Position - X: 1997, Y: 2062, pressed count: 3
MicroPython (Raspberry Pi Pico) • Board CDC @ COM29 ≡
- While using the joystick, check out the in the Shell at the bottom of Thonny. If the X value is 0, remember that this means left; otherwise, it means right. If the Y value is 0, this position is up; otherwise, it is down.
Note that while the theoretical range for the X/Y values is from 0 to 4095, in practice, the values typically do not reach these extremes due to the mechanical characteristics of the joystick. This variation is normal and acceptable for typical applications.
If you name your script main.py and save it to the root directory of the Raspberry Pi Pico, it will automatically run each time the Pico is powered on or reset. This is useful for standalone applications that need to start running immediately upon power-up. If you name your script another name other than main.py, you will need to manually run it from Thonnys's Shell.
Converts analog value to MOVE LEFT/RIGHT/UP/DOWN commands
The below MicroPython script converts analog values into commands: MOVE_LEFT, MOVE_RIGHT, MOVE_UP, MOVE_DOWN.
"""
This Raspberry Pi Pico MicroPython code was developed by newbiely.com
This Raspberry Pi Pico code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/raspberry-pico/raspberry-pi-pico-joystick
"""
from DIYables_MicroPython_Joystick import Joystick
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
# Initialize the joystick with the corresponding pins for X, Y, and button (GP26-ADC0, GP27-ADC1, GP22)
joystick = Joystick(pin_x=26, pin_y=27, pin_button=22)
# 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 open it in Thonny IDE.
- Save the script to your Raspberry Pi Pico.
- 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 (Raspberry Pi Pico) • Board CDC @ COM29 ≡
※ 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 Raspberry Pi Pico - Joystick Controls Servo Motor tutorial.