{"id":34559964,"url":"https://github.com/joypad-ai/joypad-os","last_synced_at":"2026-05-30T08:04:19.933Z","repository":{"id":65113762,"uuid":"537996945","full_name":"joypad-ai/joypad-os","owner":"joypad-ai","description":"Universal controller firmware core for adapters and custom controllers.","archived":false,"fork":false,"pushed_at":"2026-05-26T16:36:04.000Z","size":45909,"stargazers_count":1421,"open_issues_count":72,"forks_count":62,"subscribers_count":15,"default_branch":"main","last_synced_at":"2026-05-26T18:23:09.323Z","etag":null,"topics":["3do","bluetooth","controller","dinput","gamecube","nuon","pcengine","switch","tinyusb","usb","usb-hid","xbox-one","xinput"],"latest_commit_sha":null,"homepage":"https://joypad.ai","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joypad-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"RobertDaleSmith","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-09-18T04:12:07.000Z","updated_at":"2026-05-26T16:46:57.000Z","dependencies_parsed_at":"2023-10-17T04:54:46.356Z","dependency_job_id":"a2d2c2fe-c6ea-4696-9ba7-6a22324a8dfe","html_url":"https://github.com/joypad-ai/joypad-os","commit_stats":null,"previous_names":["robertdalesmith/usbretro","joypad-ai/joypad-core","joypad-ai/joypad-os"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/joypad-ai/joypad-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joypad-ai%2Fjoypad-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joypad-ai%2Fjoypad-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joypad-ai%2Fjoypad-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joypad-ai%2Fjoypad-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joypad-ai","download_url":"https://codeload.github.com/joypad-ai/joypad-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joypad-ai%2Fjoypad-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33684419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3do","bluetooth","controller","dinput","gamecube","nuon","pcengine","switch","tinyusb","usb","usb-hid","xbox-one","xinput"],"created_at":"2025-12-24T08:52:57.607Z","updated_at":"2026-05-30T08:04:19.928Z","avatar_url":"https://github.com/joypad-ai.png","language":"C","funding_links":["https://github.com/sponsors/RobertDaleSmith"],"categories":["C"],"sub_categories":[],"readme":"# Joypad OS\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/images/logo_solid.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/images/logo_solid_black.svg\"\u003e\n    \u003cimg alt=\"Joypad OS\" src=\"docs/images/logo_solid_black.svg\" width=\"300\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe Open-Source Firmware Platform for Game Controllers and Adapters\u003c/strong\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Build controller adapters, custom controllers, and assistive input devices — \u003cbr\u003eon microcontrollers, not computers.\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/joypad-ai/joypad-os/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/downloads/joypad-ai/joypad-os/total?style=for-the-badge\u0026label=Downloads\" alt=\"Downloads\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/joypad-ai/joypad-os/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/joypad-ai/joypad-os?style=for-the-badge\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/joypad-ai/joypad-os/actions/workflows/build.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/joypad-ai/joypad-os/.github/workflows/build.yml?style=for-the-badge\" alt=\"CI Status\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.joypad.ai/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docs-docs.joypad.ai-blue?style=for-the-badge\" alt=\"Documentation\" /\u003e\u003c/a\u003e\n  \u003ca href=\"http://community.joypad.ai/\"\u003e\u003cimg src=\"https://img.shields.io/discord/1133112432684978256?style=for-the-badge\u0026logo=discord\u0026label=Discord\" alt=\"Discord\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is Joypad OS?\n\nJoypad 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.\n\n**What you can build with it:**\n\n- **Controller adapters** — Use any modern USB or Bluetooth controller on retro consoles (GameCube, Dreamcast, PCEngine, 3DO, and more) or convert retro controllers to USB\n- **Custom controllers** — Wire up buttons, sticks, and sensors to a microcontroller and get a USB gamepad that works everywhere\n- **Assistive gaming setups** — Merge multiple input devices (switches, joysticks, eye trackers) into a single controller output using flexible input routing\n- **Wireless adapters** — Turn any Bluetooth controller into a wired USB gamepad for low-latency play\n\nUnder 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.\n\nFormerly known as **USBRetro**.\n\n---\n\n## I Have an Adapter — How Do I Update It?\n\n1. **Download** the latest `.uf2` for your adapter from [Releases](https://github.com/joypad-ai/joypad-os/releases)\n2. **Enter bootloader**: Hold BOOT + connect USB-C (or double-tap reset)\n3. **Drag** the `.uf2` file onto the `RPI-RP2` drive that appears\n4. **Done** — the drive ejects and your adapter is running the new firmware\n\n**[Full installation guide](docs/getting-started/installation.md)** — troubleshooting, LED status codes, profile switching\n\n---\n\n## I Want to Build Something — Where Do I Start?\n\n### Quick Start (RP2040)\n\n```bash\n# Install ARM toolchain (macOS)\nbrew install --cask gcc-arm-embedded cmake git\n\n# Clone and initialize\ngit clone https://github.com/joypad-ai/joypad-os.git\ncd joypad-os \u0026\u0026 make init\n\n# Build an adapter\nmake usb2gc_kb2040     # USB/BT → GameCube\nmake usb2usb_feather   # USB/BT → USB HID\nmake bt2usb_pico_w     # Bluetooth → USB\nmake snes2usb_kb2040   # SNES controller → USB\n```\n\n### ESP32-S3\n\n```bash\nmake init-esp                   # One-time ESP-IDF setup\nmake bt2usb_esp32s3             # Build\nmake flash-bt2usb_esp32s3       # Flash\n```\n\n### nRF52840\n\n```bash\nmake init-nrf                               # One-time NCS setup\nmake bt2usb_seeed_xiao_nrf52840             # Build\nmake flash-bt2usb_seeed_xiao_nrf52840       # Flash\n```\n\nOutput: `releases/joypad_\u003ccommit\u003e_\u003capp\u003e_\u003cboard\u003e.uf2`\n\n**[Full build guide](docs/getting-started/building.md)** — prerequisites, all targets, ESP32/nRF setup, troubleshooting\n\n---\n\n## What Can It Do?\n\n### Console Adapters\n\nUse any USB or Bluetooth controller on retro consoles:\n\n| Console | Apps | Highlights | Build | Docs |\n|---------|------|-----------|-------|------|\n| **PCEngine / TurboGrafx-16** | usb2pce | Multitap (5 players), mouse, 2/3/6-button | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/usb2pce.md) |\n| **GameCube / Wii** | usb2gc, bt2gc | Profiles, rumble, keyboard mode | [Build](docs/hardware/builds/usb2gc.md) | [Guide](docs/apps/usb2gc.md) |\n| **Sega Dreamcast** | usb2dc | Rumble, analog triggers, 4 players | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/usb2dc.md) |\n| **N64** | bt2n64 | Rumble pak emulation, profiles, BT | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/bt2n64.md) |\n| **Nuon DVD Players** | usb2nuon, bt2nuon | Controller, spinner (Tempest 3000), IGR | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/usb2nuon.md) |\n| **3DO Interactive Multiplayer** | usb23do | 8 players, mouse, extension passthrough | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/usb23do.md) |\n| **Neo Geo / SuperGun** | usb2neogeo | 7 profiles, 1L6B arcade layouts | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/usb2neogeo.md) |\n| **Casio Loopy** | usb2loopy | 4 players (experimental) | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/usb2loopy.md) |\n\n### USB \u0026 Wireless Adapters\n\n| Adapter | What It Does | Platforms | Build | Docs |\n|---------|-------------|-----------|-------|------|\n| **USB2USB** | USB/BT controller → USB gamepad (XInput, PS3/4, Switch, etc.) | RP2040, nRF52840 | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/usb2usb.md) |\n| **BT2USB** | Bluetooth controller → wired USB gamepad | Pico W, ESP32-S3, nRF52840 | [Pico W](docs/hardware/builds/bt2usb-pico-w.md) | [Guide](docs/apps/bt2usb.md) |\n| **WiFi2USB** | WiFi controller (JOCP) → USB gamepad | Pico W | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/wifi2usb.md) |\n\n### Native Controller Adapters\n\nConvert retro controllers to USB or bridge them to other consoles:\n\n| Adapter | From → To | Build | Docs |\n|---------|----------|-------|------|\n| **SNES2USB** | SNES/NES → USB | [KB2040](docs/hardware/builds/snes2usb-kb2040.md) | [Guide](docs/apps/snes2usb.md) |\n| **NES2USB** | NES → USB | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/nes2usb.md) |\n| **N642USB** | N64 → USB | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/n642usb.md) |\n| **GC2USB** | GameCube → USB | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/gc2usb.md) |\n| **NEOGEO2USB** | Neo Geo arcade stick → USB | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/neogeo2usb.md) |\n| **LodgeNet2USB** | LodgeNet hotel controllers → USB | [Pico](docs/hardware/builds/lodgenet2usb-pico.md) | [Guide](docs/apps/lodgenet2usb.md) |\n| **N642DC** | N64 → Dreamcast | [KB2040](docs/hardware/builds/n642dc-kb2040.md) | [Guide](docs/apps/n642dc.md) |\n| **N642Nuon** | N64 → Nuon | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/n642nuon.md) |\n| **SNES23DO** | SNES → 3DO | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/snes23do.md) |\n| **LodgeNet2N64** | LodgeNet → N64 | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/lodgenet2n64.md) |\n| **LodgeNet2GC** | LodgeNet → GameCube | [DIY](docs/hardware/diy.md) | [Guide](docs/apps/lodgenet2gc.md) |\n\n### Custom Controllers\n\nWire up GPIO buttons and analog sticks to build your own USB gamepad:\n\n```bash\nmake controller_fisherprice_v1_kb2040  # Digital buttons → USB HID\nmake controller_fisherprice_v2_kb2040  # Buttons + analog stick → USB HID\nmake controller_macropad               # Adafruit MacroPad → USB HID\nmake controller_btusb_pico_w           # GPIO+JoyWing → BLE+USB HID (Pico W)\nmake controller_btusb_rp2040_abb       # GPIO+USB Host → USB HID (ABB Passthrough)\n```\n\n---\n\n## Supported Input Devices\n\n- **Xbox** — OG, 360, One, Series X|S (USB + Bluetooth)\n- **PlayStation** — Classic, DS3, DS4, DualSense (USB + Bluetooth)\n- **Nintendo** — Switch Pro, Switch 2 Pro, Joy-Con, NSO GameCube, GameCube adapter (USB + Bluetooth)\n- **8BitDo** — PCE 2.4g, M30, NeoGeo, BT adapters\n- **Other** — Hori, Logitech, Google Stadia, Sega Astro City, generic HID\n- **Peripherals** — USB keyboards, mice, hubs, Bluetooth dongles\n- **Native** — SNES, N64, GameCube, Neo Geo, LodgeNet hotel controllers (directly wired)\n\n**[Full controller compatibility list](docs/hardware/controllers.md)**\n\n---\n\n## How It Works\n\n```\nAny Input                        Router                       Any Output\n─────────                        ──────                       ──────────\nUSB controllers ──┐                                           ┌──→ Retro consoles\nBluetooth ────────┤                                           ├──→ USB gamepad\nWiFi ─────────────┼──→  normalize  →  route  →  translate  ──┼──→ XInput / PS4 / Switch\nSNES / N64 / GC ──┤         ↓                                ├──→ Keyboard + mouse\nGPIO buttons ─────┘    profile_apply()                        └──→ Custom outputs\n                    (button remapping)\n```\n\n- **Router** — SIMPLE (1:1), MERGE (all→one), or BROADCAST (all→all) modes\n- **Profiles** — Per-app button remapping, cycled via SELECT + D-pad\n- **Dual-Core** — Core 0 handles input, Core 1 handles timing-critical output (RP2040)\n- **PIO** — Programmable I/O for console protocols (GameCube joybus, Dreamcast maple, etc.)\n\n**[Architecture overview](docs/overview/architecture.md)** | **[Data flow](docs/overview/data-flow.md)**\n\n---\n\n## Platforms\n\n| Platform | Chip | What Runs On It | Bluetooth | Build System |\n|----------|------|----------------|-----------|--------------|\n| **RP2040** | ARM Cortex-M0+ (dual-core) | All console adapters, USB output, custom controllers | Classic BT + BLE (Pico W) or via dongle | pico-sdk |\n| **ESP32-S3** | Xtensa LX7 (dual-core) | bt2usb | BLE only | ESP-IDF |\n| **nRF52840** | ARM Cortex-M4 | bt2usb, usb2usb | BLE only | nRF Connect SDK |\n\n---\n\n## Documentation\n\n| Section | What's There |\n|---------|-------------|\n| **[Installation Guide](docs/getting-started/installation.md)** | Flashing firmware, troubleshooting, LED codes |\n| **[Build Guide](docs/getting-started/building.md)** | Dev setup for macOS/Linux/Windows, all build targets |\n| **[Supported Controllers](docs/hardware/controllers.md)** | USB, Bluetooth, keyboards, mice, dongles |\n| **[Supported Boards](docs/hardware/boards.md)** | RP2040, ESP32-S3, nRF52840 board comparison |\n| **[Wiring Guide](docs/hardware/wiring.md)** | USB host port + console connector pinouts |\n| **[DIY Builds](docs/hardware/diy.md)** | Build your own, where to buy parts |\n| **[ESP32-S3](docs/platforms/esp32.md)** | ESP-IDF setup, TinyUF2, architecture |\n| **[nRF52840](docs/platforms/nrf52840.md)** | nRF Connect SDK setup, debugging |\n| **[Architecture](docs/overview/architecture.md)** | How it works — data flow, router, I/O layers |\n| **[Data Flow](docs/overview/data-flow.md)** | Input-to-output pipeline walkthrough |\n| **[Protocol Reference](docs/protocols/3DO_PBUS.md)** | 3DO PBus, GameCube Joybus, Nuon Polyface, PCEngine |\n\n---\n\n## Community \u0026 Support\n\n- **Discord**: [community.joypad.ai](http://community.joypad.ai/) - Community chat\n- **Issues**: [GitHub Issues](https://github.com/joypad-ai/joypad-os/issues) - Bug reports\n- **Email**: support@controlleradapter.com - Product support\n\n---\n\n## Acknowledgements\n\n- [Ha Thach](https://github.com/hathach/) - [TinyUSB](https://github.com/hathach/tinyusb)\n- [David Shadoff](https://github.com/dshadoff) - [PCEMouse](https://github.com/dshadoff/PC_Engine_RP2040_Projects/tree/main/PCEMouse) foundation\n- [FCare](https://github.com/FCare) - [USBTo3DO](https://github.com/FCare/USBTo3DO) 3DO protocol implementation\n- [mackieks](https://github.com/mackieks) - [MaplePad](https://github.com/mackieks/MaplePad) Dreamcast Maple Bus implementation\n- [Ryzee119](https://github.com/Ryzee119) - [tusb_xinput](https://github.com/Ryzee119/tusb_xinput/)\n- [SelvinPL](https://github.com/SelvinPL/) - [lufa-hid-parser](https://gist.github.com/SelvinPL/99fd9af4566e759b6553e912b6a163f9)\n- [JonnyHaystack](https://github.com/JonnyHaystack/) - [joybus-pio](https://github.com/JonnyHaystack/joybus-pio)\n- [OpenStickCommunity](https://github.com/OpenStickCommunity) - [GP2040-CE](https://github.com/OpenStickCommunity/GP2040-CE) USB device output modes\n\n---\n\n## License\n\nJoypad OS is licensed under the **Apache-2.0 License**.\n\nThe **Joypad** name and branding are trademarks of Joypad Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoypad-ai%2Fjoypad-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoypad-ai%2Fjoypad-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoypad-ai%2Fjoypad-os/lists"}