Skip to content

About

A lightweight input-mapping solution that translates signals from generic Chinese controllers into keyboard inputs, allowing effortless emulator gameplay using MacOS without tedious configuration.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

26 Commits

Folders and files

Repository files navigation

Universal Controller HUB

Platform Python License

A Python app that makes generic USB gamepads (the cheap "SNES clone" kind) work on macOS by reading raw USB HID data and translating button presses into keyboard events — with a retro terminal-style desktop interface.

Universal Controller HUB — system ready

The Problem

I bought a pair of generic SNES-style USB controllers — the no-brand kind you find everywhere online — to play emulated games on my Mac. They power on, macOS lists them under System Information > USB... and that's it. No game or emulator can see them.

The reason is that macOS's native GameController framework only exposes controllers it officially recognizes (MFi, Xbox, PlayStation, Switch Pro). A generic gamepad with a no-name vendor ID is invisible to it, so apps like the Delta emulator never know the controller exists. There are no macOS drivers for these clones, and the vendor tools — when they exist at all — are Windows-only.

So the controllers worked perfectly as USB devices, but were useless as game controllers.

The Idea

Instead of fighting the controller stack, bypass it completely:

  1. Every gamepad — no matter how cheap — is a USB HID device that constantly sends byte reports describing its state.
  2. If you read those raw bytes directly from the USB port, you don't need macOS to "recognize" anything.
  3. Games don't need a controller. They need input. So translate each button press into a keyboard key — to the emulator, the controller is just a very fast typist.

The catch: every clone uses a different byte layout, so hardcoding offsets would only ever support one specific device. That's solved by a calibration step that learns any controller's layout in about a minute, instead of shipping a database of vendor IDs.

How It Works

1. Detection (engines/controllerGetter.py) Scans all connected HID devices with hid.enumerate() and matches product names against keywords (gamepad, joystick, controller, snes, retrolink). No hardcoded Vendor/Product IDs, and duplicate USB interfaces (macOS often lists the same device twice) are filtered out.

2. Calibration (engines/configurator.py) For each controller, the app first captures the idle state (the report bytes while nothing is pressed). Then it walks you through pressing each button — when a button is held, it diffs the current report against the idle report and records which byte changed and how:

"A": { "index": 5, "idle_value": 15, "mask": 32 }

That triplet — byte index, XOR mask, idle value — is all that's needed to recognize the button later. Profiles for up to 2 controllers are saved to profiles.json.

3. Translation (engines/translator.py) A non-blocking loop reads 64-byte reports from each controller and checks every calibrated button:

is_pressed = ((report[index] ^ idle_value) & mask) == mask

Key events are sent through pynput only on state transitions (press edge / release edge). One press() keeps the key held down at the OS level until release() — spamming presses every loop iteration would flood the macOS event queue and cause input lag. If a controller drops mid-game, the loop closes the handle and quietly retries until it reconnects, without killing the session.

4. The interface (main.py) A CustomTkinter window styled like a retro terminal. The engines just print() what they're doing — the UI hijacks sys.stdout and parses those lines into status changes, so the backend stays a plain console program with zero UI dependencies. A 1-second heartbeat monitors connected controllers and calibration state, enabling/disabling buttons accordingly.

Screenshots

Calibration — the LIVE MONITOR shows exactly which button to hold, big enough to read from the couch:

Calibration in progress

Translator running — every controller press is logged and flashed on the monitor as it's converted to a keystroke:

Translator running

No controller connected — the HUB detects hot-plugs every second and unlocks the buttons when a gamepad appears:

No controller detected

Features

  • Works with unsupported controllers — raw HID reading bypasses the GameController framework entirely.
  • Universal calibration — learns any controller's byte layout; no vendor ID databases.
  • 2-player multiplayer — independent calibration profile and key map per controller.
  • Hold-state support — proper press/release edges, essential for running and jumping in platformers.
  • Hot-plug resilient — controllers are detected every second and auto-reconnect after USB glitches.
  • Standalone app — can be bundled as UniversalGamepad.app with PyInstaller, no Python required.

Requirements

  1. macOS with Python 3.x
  2. Homebrew, to install the C-level HID library:
    brew install hidapi

Installation

git clone https://github.com/joaopege1/controllerTranslator.git
cd controllerTranslator
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Note: use the hidapi Python package, not hid. Both provide the hid module, but only hidapi links correctly against Homebrew's library on macOS.

Usage

  1. Plug in your controller(s) — up to 2.
  2. Launch the app:
    python3 main.py
  3. First run only: grant Accessibility permission so the app can send keystrokes. System Settings > Privacy & Security > Accessibility → enable your terminal (or the app), then relaunch.
  4. Click CALIBRATE INPUTS and follow the LIVE MONITOR: keep your hands off while it captures the idle state, then press and hold each button as prompted.
  5. Click START TRANSLATOR, minimize the window, and open your emulator. Done — the controller now types.

Calibration is per-controller, not per-session: profiles.json is reused until you calibrate again.

Key Mappings

Defaults are defined in PLAYER_KEY_MAPS inside engines/translator.py:

Button Player 1 Player 2
D-pad Arrow keys W A S D
A / B V / C L / K
X / Y F / X I / J
L / R 1 / 2 Q / E
Start / Select 3 / 4 Enter / Space

Edit the list to match your emulator — plain strings for letter keys ('w') or pynput's Key.enter style for special keys.

Building the Standalone App

pip install pyinstaller
pyinstaller UniversalGamepad.spec

The bundle lands in dist/UniversalGamepad.app. When running as a bundled app, profiles.json is resolved next to the .app so profiles stay portable.

Project Layout

main.py                     # Retro HUD interface + stdout parser + heartbeat
engines/
  controllerGetter.py       # HID scan and keyword-based controller detection
  configurator.py           # Guided calibration, writes profiles.json
  translator.py             # HID → keyboard translation loop
  paths.py                  # Single source of truth for profiles.json location
mappingAndTesting/
  unlimitedOutputs.py       # Stream raw HID reports (reverse-engineering aid)
  mappingInputs.py          # Button detection / mapping verification
  mapping.py                # Notes on raw HID patterns for button combos

Troubleshooting

  • Unable to load any of the following libraries: libhidapi.dylib — run brew install hidapi, and make sure the Python package is hidapi (pip uninstall hid && pip install hidapi).
  • Log shows "Pressed" but the game ignores it — Accessibility permission is missing. Grant it and relaunch.
  • Buttons map to the wrong actions — recalibrate. Every clone has a different byte layout; that's exactly what calibration solves.
  • Second controller not detected — plug both in before pressing START, and confirm both appear in System Information > USB.
  • Reverse-engineering a stubborn controller — use mappingAndTesting/unlimitedOutputs.py (set its Vendor/Product ID) to watch the raw HID reports live.

License

MIT

About

A lightweight input-mapping solution that translates signals from generic Chinese controllers into keyboard inputs, allowing effortless emulator gameplay using MacOS without tedious configuration.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages