Home

FreeJoyX Wiki

FreeJoyX is a fork of the FreeJoy DIY USB HID game-controller firmware, extending the original with new button types, a richer gesture model, and additional configurator features.

User guide

• Button Types — what every entry in the Function dropdown does, with timing diagrams.
• Encoders — fast (hardware) vs slow (software) encoders, the 1×/2×/4× decode, queue mode, and how the slow-encoder path diverges from upstream FreeJoy.
• Gesture Coexistence — when TAP, DOUBLE_TAP, and NORMAL can share a physical input, and how the firmware resolves between them.
• Timer Model — global timers (tap_cutoff_ms, double_tap_window_ms) vs per-slot timers (delay_timer, press_timer). Which apply when.

Developer guide

• Repo Layout — how FreeJoyX (firmware) and FreeJoyXConfiguratorQt (configurator) relate, the shared common_*.h headers, and the manual sync discipline.
• Wire Format and Versioning — FIRMWARE_VERSION, the & 0xFFF0 compatibility mask, the legacy archive rule, and what counts as a wire-format change.
• Building from Source — toolchain, Makefile targets, how the build counter works.

Hardware

• Supported Boards — F103 BluePill (primary target) and F411 BlackPill (port in progress).

Project state

See README for the current shipping feature set and the issue tracker for in-flight work.