MumenController is a multi-target no_std Rust firmware workspace for wired Nintendo Switch fight sticks and arcade controllers, supporting both the Teensy 4.0 (ARM Cortex-M7) and the SparkFun Pro Micro / Arduino Leonardo (ATmega32U4).
It implements the licensed HORI Pokken Tournament DX Pro Pad USB HID report format (0x0F0D:0x0092, 86-byte report descriptor, 8-byte input and output reports) first proven in UnlicProController, allowing the Nintendo Switch and PC hosts to recognize the controller natively over USB without proprietary handshakes.
MumenController/
├── crates/
│ ├── mumen-core/ # Hardware-agnostic no_std core (#![forbid(unsafe_code)], host-tested)
│ │ └── src/
│ │ ├── hid.rs # 86-byte HORI/Switch HID report descriptor & 8-byte SwitchReport
│ │ ├── socd.rs # Neutral, PrimaryPriority (Up/Left), and LastWin SOCD resolvers
│ │ ├── debounce.rs # Compact shift-register switch debouncer (2 bytes/switch)
│ │ └── input.rs # LogicalInputs, Dpad/Analog/Smash modes, Shift & Lock handling
│ ├── firmware-teensy40/ # Teensy 4.0 (NXP i.MX RT1062, Cortex-M7) RTIC v2 firmware
│ │ └── src/
│ │ ├── main.rs # USB_OTG1 High-Speed HID ISR + 1 ms Systick scan task
│ │ └── pins.rs # Real iomuxc + gpio::Input / ADC1 wiring across 5 layout features
│ └── firmware-promicro/ # SparkFun Pro Micro / Leonardo (ATmega32U4) AVR firmware
│ └── src/
│ ├── main.rs # 48 MHz PLL init + USB_GEN/USB_COM interrupt-driven HID
│ └── pins.rs # 16 pull-up switch inputs + Red/Blue mode indicator LEDs
└── .github/workflows/ci.yml # zizmor security audit, mumen-core tests, Teensy & AVR release builds
- Zero-Allocation, Hardware-Agnostic Engine: Pure
no_stdRust with#![forbid(unsafe_code)]and zero HAL dependencies, unit-tested on the host (cargo test -p mumen-core). - SOCD Cleaning: Configurable Simultaneous Opposing Cardinal Directions resolution (
Neutral,PrimaryPriorityfor Up/Left priority, and edge-trackedLastWin). Default HitBox profile resolvesLeft + Right -> NeutralandUp + Down -> Up. - Directional Modes:
- Hardware Toggle Switches (Teensy 4.0
layout-standard): Dedicated toggle inputs route directional switches to the D-pad (HAT), Left Stick, or Right Stick. - Software Mode Cycling (
SHIFT + HOMErising-edge chord on Pro Micro andlayout-d16s): Cycles betweenDpad,Analog(Left Stick, or Right Stick whileShiftis held), andSmash(full stick throw0/255, or half-tilt64/192walk/tilt modifier whileShiftis held).
- Hardware Toggle Switches (Teensy 4.0
- Tournament Lock Switch: Suppresses menu buttons (
Plus/Start,Minus/Select,Home,Capture) when engaged to prevent accidental tournament disqualifications. - Prompt-Detection (Eager) Debouncing: Zero-tick edge delay (
0 µsadded latency on switch closure) with a 4 ms contact-bounce lockout window, modeled on the positive-edge response analyzed by Loïc WydD Petit on inputlag.science.
The input pipeline in MumenController is designed around the controller latency methodology and empirical findings published by Loïc (WydD) Petit at inputlag.science:
-
Zero-Delay Eager ("Prompt-Detection") Debouncing (
crates/mumen-core/src/debounce.rs):- As demonstrated on inputlag.science/controller/results (comparing the Brook UFB Positive Edge at 1.0 ms avg / 95% on-time vs. Negative Edge at 3.9 ms avg / 78% on-time), a traditional 4-sample shift-register debouncer adds a deterministic 3–4 ms delay before reporting a button press.
-
mumen_core::Debouncerinstead transitions immediately on the first sample (0ticks of delay) when the lockout timer is0, and then locks out subsequent mechanical contact bounce for 4 ms (20 × 200 µsticks on Teensy 4.0;4 × 1 msSOF ticks on ATmega32U4).
-
Sub-Millisecond (
200 µs/ 5 kHz) Scanning & Immediate USB Endpoint Priming (crates/firmware-teensy40):- inputlag.science/controller notes: "Every additional sampling is bad for lag. Try to keep the polling of the actual button either using a synchronous method on the USB polling or using a fast sampling (500µs is enough)."
- On Teensy 4.0, the RTIC
Systickmonotonic runs at 10 kHz andscan_inputssamples all GPIO pads every200 µs(5 kHz) — 2.5× faster than the 500 µs recommendation — bounding internal sampling jitter to$[0, 0.2],\text{ms}$ (0.1 msaverage). - Whenever
scan_inputsdetects a state change (next_report != prev_report), it immediately primes the USB IN endpoint if idle, and theUSB_OTG1ISR immediately re-primes the IN endpoint with the latest 200 µs sample as soon as the host consumes a packet. - For the analog stick layout (
layout-a4d17),ADC1is configured for native 8-bit resolution (ResolutionBits::Res8), 1-sample hardware averaging (AveragingCount::Avg1), andConversionSpeed::Fastto minimize blocking conversion overhead.
-
1000 Hz (
bInterval = 1) Native USB Polling & Synchronous Sampling (crates/firmware-promicro):- Both
firmware-teensy40andfirmware-promicrodeclarebInterval = 1in the USB HID endpoint descriptor, requesting the fastest legal polling rate under both Full-Speed (1 ms/ 1000 Hz) and High-Speed (125 µs/ 8000 Hz microframe) USB 2.0 schedulers. - On the ATmega32U4 Pro Micro, switches are sampled synchronously inside the 1 kHz USB SOF / endpoint interrupt right before loading the 8-byte report into the hardware FIFO.
- Both
| Stage | Teensy 4.0 (firmware-teensy40) |
Pro Micro (firmware-promicro) |
Reference |
|---|---|---|---|
| Switch Debounce Delay | 0.0 ms (4 ms bounce lockout) | 0.0 ms (4 ms bounce lockout) | inputlag.science |
| Internal Scan Interval | 0.20 ms (5 kHz RTIC task) | Synchronous on 1 kHz USB SOF |
inputlag.science ( |
USB Endpoint bInterval |
1 (125 µs HS / 1 ms FS) |
1 (1 ms FS / 1000 Hz) |
inputlag.science Methodology |
| Theoretical Avg Lag (1 kHz host) | ~0.6 ms (~96% on-time @ 60 fps) | ~0.5–1.0 ms (~94–96% on-time @ 60 fps) | 16.67 ms frame window |
All momentary button and directional switches are wired between the MCU pin and GND (using internal pull-up resistors).
Select a layout at compile time with --no-default-features --features <layout>:
| Input | layout-standard (default) |
layout-alternate |
layout-d16 |
layout-d16s |
layout-a4d17 |
|---|---|---|---|---|---|
| A | P14 | P11 | P0 | P0 | P0 |
| B | P11 | P14 | P1 | P1 | P1 |
| X | P9 | P9 | P2 | P2 | P2 |
| Y | P16 | P16 | P3 | P3 | P3 |
| L (L1) | P15 | P15 | P4 | P4 | P4 |
| R (R1) | P10 | P10 | P5 | P5 | P5 |
| ZL (L2) | P12 | — | P6 | P6 | P6 |
| ZR (R2) | P13 | — | P7 | P7 | P7 |
| L3 | P3 | — | — | — | P11 |
| R3 | P2 | — | — | — | P12 |
| Minus (Select) | P18 | P18 | P8 | P8 | P8 |
| Plus (Start) | P17 | P17 | P9 | P9 | P9 |
| Home | P8 | P8 | P10 | P10 | P10 |
| Capture | — | — | P11 | — | — |
| Shift | — | — | — | P11 | — |
| D-pad Up | P1 | P1 | P12 | P12 | P13 |
| D-pad Down | P6 | P6 | P13 | P13 | P14 |
| D-pad Left | P7 | P7 | P14 | P14 | P15 |
| D-pad Right | P19 | P19 | P15 | P15 | P16 |
| Analog Left Toggle | P4 | — | — | — | — |
| Analog Right Toggle | P5 | — | — | — | — |
| Tournament Lock | P0 (100k pull-down) | — | — | — | — |
| Left Stick X / Y (ADC1) | — | — | — | — | P17 / P18 |
| Right Stick X / Y (ADC1) | — | — | — | — | P19 / P20 |
Select a layout with --no-default-features --features <layout>:
layout-promicro-standard(default): MatchesUnlicProController.layout-promicro-classic: PermutesL/R/ZL/ZRandMinus/Plus/Homemasks to match the legacyorigin/hidwiring.
| Input / Indicator | Pro Micro Pin | ATmega32U4 Port | Notes |
|---|---|---|---|
| A | D3 |
PD0 |
Internal pull-up (active low to GND) |
| B | D1 (TX0) |
PD3 |
Internal pull-up |
| X | A0 |
PF7 |
Internal pull-up |
| Y | D15 (SCK) |
PB1 |
Internal pull-up |
| L (LB) | A1 |
PF6 |
Internal pull-up |
| R (RB) | D5 |
PC6 |
Internal pull-up |
| ZL (LT) | A2 |
PF5 |
Internal pull-up |
| ZR (RT) | D0 (RX1) |
PD2 |
Internal pull-up |
| Minus (Select) | D14 (MISO) |
PB3 |
Internal pull-up |
| Plus (Start) | D10 |
PB6 |
Internal pull-up |
| Home | D16 (MOSI) |
PB2 |
Internal pull-up |
| Shift | D2 |
PD1 |
Internal pull-up (SHIFT + HOME cycles modes) |
| Up / Down / Left / Right | D7 / D8 / D6 / D9 |
PE6 / PB4 / PD7 / PB5 |
Internal pull-up |
| Red Mode LED | A3 |
PF4 |
Output (Analog = Red, Smash = Red+Blue) |
| Blue Mode LED | D4 |
PD4 |
Output (Dpad = Blue, Smash = Red+Blue) |
cargo test -p mumen-corerustup target add thumbv7em-none-eabihf
rustup component add llvm-tools-preview
cargo install cargo-binutils
cd crates/firmware-teensy40
# Build default layout (layout-standard), or pass --no-default-features --features layout-d16s
cargo build --release
# Convert ELF to Intel HEX for Teensy Loader
cargo objcopy --release -- -O ihex mumen-teensy40.hexFlash mumen-teensy40.hex using Teensy Loader or teensy_loader_cli --mcu=TEENSY40 -w mumen-teensy40.hex.
Requires avr-gcc, avr-libc, binutils-avr, and the Rust nightly toolchain with rust-src (for -Z build-std=core on avr-none):
rustup toolchain install nightly --profile minimal --component rust-src
cd crates/firmware-promicro
cargo +nightly build --release
# Convert ELF to Intel HEX and flash with avrdude
avr-objcopy -O ihex -R .eeprom ../../target/avr-none/release/firmware-promicro.elf mumen-promicro.hex
avrdude -p atmega32u4 -c avr109 -P /dev/ttyACM0 -U flash:w:mumen-promicro.hex:iGitHub Actions (.github/workflows/ci.yml) runs on every push, pull request, and semantic version tag (vMAJOR.MINOR.PATCH):
-
Workflow Security Audit: Static analysis via
zizmorwith SHA-pinned actions and least-privilegeGITHUB_TOKENpermissions. -
Version & Ancestry Validation: Single-sourced
[workspace.package] versionin rootCargo.toml. When avMAJOR.MINOR.PATCHtag is pushed, CI verifies that:- the tag matches the semantic version pattern
^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$, - the tag version matches
Cargo.toml's[workspace.package] version, and - the tagged commit is an ancestor of
main.
- the tag matches the semantic version pattern
-
Formatting & Core Unit Tests:
cargo fmt --all -- --checkandcargo test -p mumen-core. -
Multi-Target Firmware Builds &
.hexPackaging: Builds all 5 Teensy 4.0 layout features and both ATmega32U4 Pro Micro layout features in release mode, converts each ELF to a versioned Intel.heximage (mumen-teensy40-${VERSION}-${layout}.hexandmumen-promicro-${VERSION}-${layout}.hex) withSHA256SUMS, and uploads them as workflow artifacts. -
Automated GitHub Releases: Pushing a verified
vMAJOR.MINOR.PATCHtag onmainautomatically publishes a GitHub Release with all 7 pre-built.hexfirmware blobs andSHA256SUMS.
- Loïc (WydD) Petit — inputlag.science (Controller Lag, Methodology, Results, and
loic.petit/usblag) — Primary research reference for the controller's prompt-detection debouncing, sub-500 µs internal sampling rate, synchronous USB endpoint priming, andbInterval = 1polling configuration. nulvox/UnlicProController— Original C / LUFA fight stick implementation for the ATmega32U4 Pro Micro.
Dual-licensed under either of:
- Apache License, Version 2.0 (
LICENSE-APACHE) - MIT License (
LICENSE-MIT)
at your option.