Joypad OS

The Open-Source Firmware Platform for Game Controllers and Adapters

Build controller adapters, custom controllers, and assistive input devices —
on microcontrollers, not computers.

---

What is Joypad OS?

Joypad OS is firmware that runs on small microcontroller boards (RP2040, ESP32-S3, nRF52840) — the kind you'd find inside a controller or adapter, not on a PC. You flash it onto a chip and it handles everything: reading controllers, translating protocols, routing inputs to outputs, and managing button remapping.

What you can build with it:

• Controller adapters — Use any modern USB or Bluetooth controller on retro consoles (GameCube, Dreamcast, PCEngine, 3DO, and more) or convert retro controllers to USB
• Custom controllers — Wire up buttons, sticks, and sensors to a microcontroller and get a USB gamepad that works everywhere
• Assistive gaming setups — Merge multiple input devices (switches, joysticks, eye trackers) into a single controller output using flexible input routing
• Wireless adapters — Turn any Bluetooth controller into a wired USB gamepad for low-latency play

Under the hood, Joypad OS normalizes every input source into a common format, routes it through configurable player slots, and translates it into whatever output protocol the target needs — from retro console protocols bit-banged via PIO to modern USB HID and XInput.

Formerly known as USBRetro.

---

I Have an Adapter — How Do I Update It?

1. Download the latest .uf2 for your adapter from Releases
2. Enter bootloader: Hold BOOT + connect USB-C (or double-tap reset)
3. Drag the .uf2 file onto the RPI-RP2 drive that appears
4. Done — the drive ejects and your adapter is running the new firmware

Full installation guide — troubleshooting, LED status codes, profile switching

---

I Want to Build Something — Where Do I Start?

Quick Start (RP2040)

# Install ARM toolchain (macOS)
brew install --cask gcc-arm-embedded cmake git

# Clone and initialize
git clone https://github.com/joypad-ai/joypad-os.git
cd joypad-os && make init

# Build an adapter
make usb2gc_kb2040     # USB/BT → GameCube
make usb2usb_feather   # USB/BT → USB HID
make bt2usb_pico_w     # Bluetooth → USB
make snes2usb_kb2040   # SNES controller → USB

ESP32-S3

make init-esp                   # One-time ESP-IDF setup
make bt2usb_esp32s3             # Build
make flash-bt2usb_esp32s3       # Flash

nRF52840

make init-nrf                               # One-time NCS setup
make bt2usb_seeed_xiao_nrf52840             # Build
make flash-bt2usb_seeed_xiao_nrf52840       # Flash

Output: releases/joypad_os_<commit>_<app>_<board>.uf2

Full build guide — prerequisites, all targets, ESP32/nRF setup, troubleshooting

---

What Can It Do?

Console Adapters

Use any USB or Bluetooth controller on retro consoles:

USB & Wireless Adapters

Native Controller Adapters

Convert retro controllers to USB or bridge them to other consoles:

Custom Controllers

Wire up GPIO buttons and analog sticks to build your own USB gamepad:

make controller_fisherprice_v1_kb2040  # Digital buttons → USB HID
make controller_fisherprice_v2_kb2040  # Buttons + analog stick → USB HID
make controller_macropad               # Adafruit MacroPad → USB HID
make universal_pico_w           # GPIO+JoyWing → BLE+USB HID (Pico W)
make universal_rp2040_abb       # GPIO+USB Host → USB HID (ABB Passthrough)

---

Supported Input Devices

• Xbox — OG, 360, One, Series X|S (USB + Bluetooth)
• PlayStation — Classic, DS3, DS4, DualSense (USB + Bluetooth)
• Nintendo — Switch Pro, Switch 2 Pro, Joy-Con, NSO GameCube, GameCube adapter (USB + Bluetooth)
• 8BitDo — PCE 2.4g, M30, NeoGeo, BT adapters
• Other — Hori, Logitech, Google Stadia, Sega Astro City, generic HID
• Peripherals — USB keyboards, mice, hubs, Bluetooth dongles
• Native — SNES, N64, GameCube, Neo Geo, LodgeNet hotel controllers (directly wired)

Full controller compatibility list

---

How It Works

Any Input                        Router                       Any Output
─────────                        ──────                       ──────────
USB controllers ──┐                                           ┌──→ Retro consoles
Bluetooth ────────┤                                           ├──→ USB gamepad
WiFi ─────────────┼──→  normalize  →  route  →  translate  ──┼──→ XInput / PS4 / Switch
SNES / N64 / GC ──┤         ↓                                ├──→ Keyboard + mouse
GPIO buttons ─────┘    profile_apply()                        └──→ Custom outputs
                    (button remapping)

• Router — SIMPLE (1:1), MERGE (all→one), or BROADCAST (all→all) modes
• Profiles — Per-app button remapping, cycled via SELECT + D-pad
• Dual-Core — Core 0 handles input, Core 1 handles timing-critical output (RP2040)
• PIO — Programmable I/O for console protocols (GameCube joybus, Dreamcast maple, etc.)

Architecture overview | Data flow

---

Platforms

---

Documentation

---

Community & Support

• Discord: community.joypad.ai - Community chat
• Issues: GitHub Issues - Bug reports
• Email: support@controlleradapter.com - Product support

---

Acknowledgements

• Ha Thach - TinyUSB
• David Shadoff - PCEMouse foundation
• FCare - USBTo3DO 3DO protocol implementation
• mackieks - MaplePad Dreamcast Maple Bus implementation
• Ryzee119 - tusb_xinput
• SelvinPL - lufa-hid-parser
• JonnyHaystack - joybus-pio
• OpenStickCommunity - GP2040-CE USB device output modes

---

License

Joypad OS is licensed under the Apache-2.0 License.

The Joypad name and branding are trademarks of Joypad Inc.