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.
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.
Instead of fighting the controller stack, bypass it completely:
- Every gamepad — no matter how cheap — is a USB HID device that constantly sends byte reports describing its state.
- If you read those raw bytes directly from the USB port, you don't need macOS to "recognize" anything.
- 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.
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) == maskKey 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.
Calibration — the LIVE MONITOR shows exactly which button to hold, big enough to read from the couch:
Translator running — every controller press is logged and flashed on the monitor as it's converted to a keystroke:
No controller connected — the HUB detects hot-plugs every second and unlocks the buttons when a gamepad appears:
- 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.appwith PyInstaller, no Python required.
- macOS with Python 3.x
- Homebrew, to install the C-level HID library:
brew install hidapi
git clone https://github.com/joaopege1/controllerTranslator.git
cd controllerTranslator
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtNote: use the
hidapiPython package, nothid. Both provide thehidmodule, but onlyhidapilinks correctly against Homebrew's library on macOS.
- Plug in your controller(s) — up to 2.
- Launch the app:
python3 main.py
- 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.
- 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.
- 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.
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.
pip install pyinstaller
pyinstaller UniversalGamepad.specThe bundle lands in dist/UniversalGamepad.app. When running as a bundled app, profiles.json is resolved next to the .app so profiles stay portable.
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
Unable to load any of the following libraries: libhidapi.dylib— runbrew install hidapi, and make sure the Python package ishidapi(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.



