FreeJoy: build your own USB cockpit panel without writing firmware

What FreeJoy does for you

FreeJoy is freely available, configurable firmware for homemade game controllers. A button box, pedals, a joystick or a throttle can become a USB game controller. For supported features, the configurator takes the place of writing your own program: assign pins, select switch behaviour, calibrate axes and transfer the settings to the device.

This saves work on USB reports, input processing and standard control functions. You still plan the mechanics, wire the controls and assign them in your game. You do not need previous coding experience to start. Connect one button, watch its response and add the next component after that test works. A custom display is a different, complementary project; the AI and programming guide explains that route.

Check the board and software versions first

The original project targets the STM32F103C8, commonly on a Blue Pill board. Board colour is not a compatibility test. An F401 or F411 Black Pill, ESP32 or Arduino Uno cannot simply use the same firmware. Verify the chip marking, schematic, memory requirements and instructions for the exact firmware image. A similarly labelled clone is not automatically a supported substitute.

ST officially specifies 64 KB of flash for the F103C8. The 1.7.3b0 release file inspected here as data stays within that 64 KB range; it does not require an assumed extension to 128 KB. You must still check the actual board and use its appropriate installation procedure.

Checked on 18 October 2026: the official release pages mark firmware v1.7.3b0 and Qt Configurator 1.7.3b0 as the latest releases, titled 1.7.3. Use a matching pair. Do not import an old configuration or copy old wiring without checking its version; release notes document an earlier change to I²C pin assignments. The microcontroller comparison helps with selection. A faster processor does not make a board compatible with a firmware built for another chip.

USB HID, DirectInput and DX buttons

HID means Human Interface Device. With the appropriate firmware, FreeJoy identifies as a USB game controller and uses the Windows HID infrastructure. After setup, the configurator does not need to remain open for normal controller input. That is useful in a cockpit: connect the panel, check that the device is present and load the simulator bindings you saved.

DirectInput is a Windows interface that games can use to read controllers. A “DX button” is a reported joystick button, not a ready-made command such as “lower landing gear”. The simulator assignment gives it that meaning. XInput is a different interface; a game supporting only XInput need not recognise this controller. Older games may also accept fewer buttons than FreeJoy provides. Test your intended game as well as Windows device detection before committing to a large panel.

Plan a manageable cockpit panel

Our example uses four pushbuttons, one maintained on/off switch, an incremental encoder with a pushbutton and a 10 kΩ linear potentiometer. The requirement is four individual commands, separate on/off actions for an available simulator function, two adjustment directions and one continuous axis. Confirm that your particular aircraft or vehicle provides the intended bindings before choosing panel labels.

The pin plan below is a proposal for a fresh, suitable Blue Pill setup. Configure the listed digital pins as Button_Gnd and connect each contact to shared ground. The potentiometer outer terminals connect to 3.3 V and GND; its wiper connects to A0. Wire with power disconnected. Check the markings and available functions on your own board and keep USB, programming connections and interfaces already in use reserved.

From an empty board to the first input

On an existing controller, first save its configuration and record its firmware. For a new board, the project documents initial programming through ST-Link or USB-UART. Follow the appropriate official instructions for boot state, supply and firmware file. A USB cable alone does not turn an empty board into a FreeJoy controller. See understanding and loading firmware for the underlying process.

Once the firmware is running, read the device configuration, assign only B12 as Button_Gnd and use “Write Config to Device”. Press the first button and identify its number in the physical button display. Assign that input to a normal logical button, write again and verify the response. “Save Config to File” creates an additional computer backup; it does not replace writing to the device. Disconnect and reconnect the controller and repeat the test before adding more wiring.

Physical contacts and logical buttons

A physical button is a detected contact. A logical button is the signal created for the computer. Their numbers need not match, so record the control name, physical input and logical output in separate columns. One physical input can serve several logical functions. For a maintained switch, ToggleSwich_On can generate a pulse when it closes and ToggleSwich_Off another when it opens. Bind these to separate on/off commands only when the simulator offers them.

Button_normal follows the contact; Button_Toggle alternates a stored logical state with successive presses. Debouncing rejects contact chatter, Delay Timer postpones activation, and Press Timer sets the logical activation duration where applicable. Begin with defaults and change one setting at a time. Too much debounce can discard a deliberate short press; a long pulse may behave like holding a game command. Test startup with the maintained switch already on, as well as changing it after the simulator starts.

More functions and more connections

The project documents up to 128 digital inputs, eight axes, four POV hats and five shift modifiers. These are feature limits, not a promise that every possible combination fits the available pins and resources. Radio groups retain a selected logical function; sequential modes step through assigned functions with repeated presses. Shift modifiers offer another control layer. Label these layers so that using the panel does not require guesswork during a flight.

For additional contacts, choose direct pins, a button matrix or supported shift registers. A matrix saves pins but needs correct rows, columns and diodes according to the project wiring; explicitly test simultaneous presses. With 74HC165 or CD4021 registers, configure Clock, Data and Latch to match the chip. The documentation recommends 3.3 V. A 74HC595 performs a different job and is not an interchangeable input device. The controls guide covers physical control choices.

Other documented features include four PWM lighting channels and up to 24 individual or matrix LEDs. Version 1.7.3 adds addressable WS2812b/PL9823 LEDs, button activation, timers for single-colour LEDs and external control of those LEDs through USB HID and the configurator. The project lists up to 50 addressable LEDs. UART TX reports can provide data to external devices. None of these features automatically provides the required simulator telemetry or a verified Cockpit Suite integration.

Encoders: turning is different from pressing

An incremental encoder supplies two offset signals. FreeJoy uses them to detect direction and produce two logical buttons or an axis change. A built-in pushbutton is a separate contact. The wiki distinguishes up to 15 ordinary encoders and one fast encoder; Fast_Encoder uses A8 and A9, rather than arbitrary spare pins. Our example uses an ordinary encoder on B6/B7 and its pushbutton on B8.

Assign its channels as Encoder_A and Encoder_B following the instructions. Turn ten detents slowly in each direction, then faster, and compare the number of reported steps. Reversed direction, double steps and missed steps suggest different causes: channel assignment, encoder type, contact quality or timing. The wiki gives a default encoder pulse time of 10 ms and recommends less than 50 ms. This is not a guaranteed optimum for every simulator; adjust only in response to a repeatable test.

Axes: from a sensor to useful travel

Configure A0 as the potentiometer's analogue source and map it to a logical axis, for example X. Disable unused axes. FreeJoy also supports documented digital sensors such as AS5600 and specific TLE501x variants, plus external ADCs including ADS1115 and MCP3201/02/04/08. The exact part, interface, channel and configuration version matter. Support for these parts does not mean that any Hall sensor or I²C module will work.

Watch the raw value first: movement should increase or decrease it consistently. Start calibration, move the control through its actual mechanical limits and save the result. A self-centring control also needs its resting centre captured; a throttle normally does not need an artificial centre point. The internal analogue inputs have 12-bit resolution. A larger numerical range in a USB report does not create additional sensor accuracy or improve the mechanics.

Tune deadzones, filters and curves

A centre deadzone suppresses small changes around the resting centre. A dynamic deadzone deals with small changes around the current value. Either can hide movements you intended, so start small and observe the effect. Seven filter levels smooth the reading but add lag; the project advises against levels above 3 for time-critical axes. A strong filter cannot repair a loose connection.

Inversion reverses direction. Curves change sensitivity across the travel: a softer centre may make fine control easier while changing the otherwise linear relationship. Prescaling, combined axes and button actions to adjust, centre or reset axes are further documented tools. Axis regions can also generate buttons. First obtain a reliable linear response, then add only the effect you need. Curves enabled both in FreeJoy and in the simulator combine, making troubleshooting harder.

Test in the simulator and locate faults

In Windows, open joy.cpl and select the game controller properties. Start with low-numbered buttons and the example axis. The classic display may not show every button on a large controller; an absent indicator beyond its range does not prove a hardware fault. Next assign a single simulator function and test pressing, holding, releasing, reconnecting and restarting. Each example-panel action should produce its documented result without changing neighbouring inputs.

If the raw contact is missing, inspect wiring and pin mode. If the physical input works but the logical one does not, inspect mapping, shift conditions and timers. If Windows responds but the game does not, check the selected device, button limits and duplicate bindings. A confirmed landing-gear state for an LED or OLED needs a separate data path: USB inputs do not create automatic return telemetry. Documented LED outputs and host control still need an appropriate simulator integration. See USB inputs and troubleshooting.

Develop your project with the community

After each successful stage, save the configuration, pin plan and a short test record. Photograph labelled connections before enclosure assembly. A useful help request might read: “B12 responds physically, logical button 1 stays off; firmware and configurator 1.7.3b0; shift disabled.” That gives someone a place to start. In the Cockpit Suite forum, we help with these questions and with 3D-printed cases, CNC-machined panels and laser work using LightBurn.

Cockpit Suite is a young project with software already available for supported simulators and devices. We aim for one shared software environment and straightforward setup for suitable combinations; this is not an unverified promise of FreeJoy integration. We want to work through problems with you and aim to reply the same day where possible, with late questions sometimes answered later. Practical experience from the European community and beyond helps improve our guides and supported workflows. A carefully documented first button is already a useful contribution.

Continue your build