4 Axis USB Joystick
June 24, 2026 ยท View on GitHub
This is a simple USB Joystick written in CircuitPython, using the Joystick_XL library. Nothing particularly complex, most of the heavy lifting is done by Joystick_XL, but I'm making the repository public just in case anyone finds it useful
It should work with any microcontroller that support USB and CircuitPython. It uses CircuitPython rather than MicroPython because it requires support for USB HID.
This uses the easily available Jh-D400X-R2 joystick (Aliexpress, Amazon,...)
Building
- Install CircuitPython
- Clone the Joystick_XL repository and copy the python files to the folder lib/joystick_xl on the board filesystem
- Clone this repository and copy boot.py. code.py, and config.py to the board filesystem
- Wire up the joystick
config.py supports several different variants
Hardwired Pico2 version
The original version of this was a simple 4 axis joystick with a single button, handwired to a Raspberry Pi Pico2, as follows:
| GP3 (pin 5) | joystick button (blue wire) |
| 3V3 (pin 36) | positive reference on joystick pots: red wire and left pot terminals |
| GND (pin 33) | other blue wire, black wire, and negative potentiometer reference (right pot terminals) |
| ADC2 (pin 34) | white wire |
| ADC1 (pin 32) | center terminal (wiper) on tilt pot |
| ADC0 (pin 31) | center terminal on pan pot |
Homebrew 4 axis joystick
Handwired board
Pico2 Pinouts
Joystick wiring
PCB Version
As a follow-on I've built a couple PCB based versions. The latest uses the Waveshare RP2040-Zero microcontroller, which has the advantage over the Pico2 of supporting 4 ADC channels.
The KiCad files for the PCB are in the KiCad folder. You will need to download the RP2040-ZERO symbols from SnapMagic
RP2040-Zero Based controller PCB design
RP2040-Zero Based Controller
Use
I use this with my VISCA Game Controller app for controlling Ethernet connected PTZ cameras.
Under normal use, the code does not export the CircuitPython filesystem to the connected computer. If you want to edit the code, you can cause it to export the filesystem by holding down the joystick button for 5 seconds after plugging in the USB connector. Alternatively, you can use (Thonny)[https://thonny.org/] and access the filesystem over the USB serial port.