A native Omarchy control panel for MOZA racing hardware. It combines Boxflat's Python settings with fast Rust rev lights powered by moza-rev. The themed interface follows OmaStats.
The preview combines real plugin panels over Omarchy's Ristretto wallpaper, in the same style as hyprmoncfg. Screenshots use simulated RPM and input values in an isolated capture host. They do not represent a live game or additional hardware testing.
Rev lights, pedal calibration, live inputs, wheelbase and pedal vibration settings
- Live RPM, configurable first/full thresholds (80–97% by default), LED count, on/off, and a hardware sweep test. A separate shift cue flashes at 95% of redline and 10 flashes per second by default, with adjustable timing and rate. Modern wheels also get saved colors and brightness. Changes apply without restarting.
- Wheelbase rotation, force feedback, damping, friction, inertia, protection, equalizer, force curve, soft limits, temperatures, and startup sound.
- Modern and legacy wheel settings: paddles, encoders, joystick modes, combinations, calibration, RPM/button colours, brightness, idle effects.
- Pedals, dashboards, H-pattern and sequential shifters, handbrakes, multifunction stalks and universal hubs, using Boxflat's existing controls.
- Pedal vibration for MOZA's Pedal Haptic Feedback module: engine, gear shift, TC, ABS, wheel spin, lockup, brake threshold, clutch bite point and road texture effects per pedal, driven by game telemetry with Pit House's timings.
- Guided pedal calibration beside live input and range controls. Previously shortened pedal limits can be expanded again from Home.
- Boxflat presets with device selection, default profiles and automatic application when a game process starts. Preset dialogs stay inside the panel.
- Generic HID detection fixes and Boxflat's device-specific input behaviour.
- Wheel and pedal indicators update at up to 120 Hz while the panel is open.
- A steering-wheel bar icon that appears only while the wheelbase is connected.
Unavailable controls are hidden or disabled using Boxflat's capability checks. This initial integration has been checked on an R12 with CS V2P (settings reads and physical LED sweep). Other pages share Boxflat's logic and have adapter coverage, but have not been tested on every hardware model. Firmware updates are outside Boxflat's supported feature set.
Requires Omarchy's Quickshell plugin host and Python 3.12 or newer:
omarchy plugin add https://github.com/crmne/omarchy-moza.git --enableOn a fresh installation, open the steering-wheel icon and choose Open setup terminal. It installs only the missing Boxflat dependencies and device-access rules through an Omarchy terminal, which may ask for your password. The plugin starts automatically afterward. Reconnect your devices if rules were installed. Existing rules are preserved. You can retry interrupted setup from the panel.
The required Arch packages are python-gobject, gtk4, libadwaita,
python-cairo, python-pyserial, python-yaml, python-evdev and python-psutil.
There is no pip environment, separate Boxflat checkout or Rust compiler needed
for the standard x86-64 installation. View the setup panel.
The repository bundles a reproducibly built, attested x86-64 Rust executable. For another architecture, build on that machine before enabling the plugin:
git clone https://github.com/crmne/omarchy-moza.git
cd omarchy-moza
mise install
make build install
omarchy plugin enable crmne.mozaBuilding needs Rust, mbx, a C toolchain, pkg-config and libudev development files.
mise install installs the pinned Rust and mbx versions; the system build
dependencies are base-devel and systemd-libs on Omarchy. Contributors who
do not use mise or mbx can run Cargo directly in rev/.
Close standalone Boxflat and stop standalone moza-rev first. They must not compete for device replies or UDP ports. System packages and device rules are installed only when you choose setup; nothing privileged runs at startup.
The steering-wheel icon appears when a wheelbase or pedal haptic module connects and disappears when both disconnect. It also appears when first-run setup is needed. The background service keeps watching for reconnection. Click the icon in the bar, or run:
omarchy-shell crmne.moza show 'Rev lights'
omarchy-shell crmne.moza show 'Vibration module'
omarchy-shell crmne.moza show Base
omarchy-shell crmne.moza status
omarchy-shell crmne.moza configure 80 97The Rust engine listens for Automobilista 2 / Project CARS, Wreckfest 2,
Codemasters legacy telemetry, BeamNG / OutGauge, Assetto Corsa and Forza.
Assetto Corsa uses the small CSP companion installed by
assetto-corsa-setup, sending
the current car's actual RPM, limiter and idle RPM to 127.0.0.1:9997.
Run the updated setup script with the game closed, then start a session.
This replaces AC's legacy UDP feed, which has no limiter and guessed a
7,000 RPM ceiling. Low-revving cars work without a fixed RPM floor, car
changes apply immediately, and over-revs never change the limit. Without
the companion or a valid car limiter, AC lights stay off rather than guessing.
No telemetry leaves the computer. Other games' setup and default ports
follow moza-rev. For AMS2, select Project CARS 2
UDP and frequency 1. Linux can also need the broadcast-routing setup in
moza-rev's documentation.
Occupied telemetry ports are reported in the rev-light page.
Thresholds are percentages of redline. With a 6,800 RPM redline, 80–97% lights the first LED at 5,440 RPM and fills the bar at 6,596 RPM.
Settings and Boxflat-compatible presets live in ~/.config/omarchy-moza/
(or $XDG_CONFIG_HOME/omarchy-moza/). Existing standalone Boxflat settings
are left alone. Copy chosen .yml presets to ~/.config/omarchy-moza/presets/
before starting the plugin to import them. Device settings are read from hardware.
The plugin runs while enabled, including with the panel closed. Boxflat's
standalone tray, window and autostart options are replaced by the plugin host.
Resets and profile loading retain Boxflat's behaviour. Colour fields accept
#RRGGBB.
On Rev lights, choose colors for the first, middle and last sections, using
the color menus or a custom #RRGGBB value. Saturated green (#00ff00), yellow
(#ffff00) and red (#ff0000) are the defaults. Custom RGB values are sent
unchanged.
Brightness (%) controls the whole strip. The preview uses the
same colors and brightness as the wheel. Test lights runs a short sweep,
then flashes the whole strip for one second.
Flash at (%) sets a separate shift cue, defaulting to 95% of the game's reported rev limit. The panel shows the corresponding RPM for the current car. Lower it for an earlier cue; Flashes per second adjusts the rate from 1 to 20, defaulting to 10. The whole strip flashes in your chosen colors, even if the progressive strip has not reached Full lights (%) yet. It returns to progressive lights below the flash point and clears when telemetry stops. This cue does not calculate the engine's optimum power-band shift point.
Colors and brightness are saved with the rev-light settings and restored after reconnecting, changing the LED count or running a wheel test. Wheel controls the wheel's static colors separately; reading those settings no longer replaces the live rev colors. Custom live colors and brightness require a modern wheel protocol; the controls are disabled on legacy wheels.
Plug MOZA's Pedal Haptic Feedback module straight into the computer with USB. Vibration module then shows Pit House's effects for the clutch, brake and throttle, each with an on/off switch, Test, and its frequency, intensity, trigger or RPM range. The defaults are Pit House's PHF-Official preset. A dot lights while an effect plays. Settings are saved in the plugin's settings folder and apply immediately.
Effects follow live telemetry, so each one needs its game to report the input:
| Game | Effects |
|---|---|
| Assetto Corsa (CSP companion, version 2) | All |
| Automobilista 2 / Project CARS 2 | All |
| Forza (Dash format) | All except ABS and TC, which Forza does not report |
| BeamNG.drive | Engine, gear shift, ABS, TC, brake threshold, bite point |
| Assetto Corsa Competizione, Le Mans Ultimate | All (needs the launch option below) |
| Wreckfest 2, Codemasters games | Engine only |
AMS2 does not report tyre sizes, so wheel spin and lockup start after the plugin has seen each car coast straight above 36 km/h for a moment. Choose Dash as Forza's Data Out format; Sled has no pedal inputs or gear. BeamNG's OutGauge has no wheel slip or suspension data.
These games publish telemetry only as Windows shared memory inside their
Proton prefix, which Linux programs cannot read. The plugin ships a small
helper, bin/omarchy-moza-shm.exe, that Proton starts next to the game and
stops with it. It only reads the game's telemetry and sends it to
127.0.0.1:9998. Its source is in shm-bridge/.
Automatic setup: while either game is installed but not set up, the top of the panel says so. Close Steam and choose Set up. It adds the helper to each game's launch options, keeping any you already have, and enables plugins in Le Mans Ultimate's settings. A backup of each changed file is saved next to it. Steam must be closed because it rewrites launch options when it exits. The panel leaves the files alone if Steam's configuration has a format it does not recognise.
Manual setup: in Steam, right-click the game, choose Properties →
General, and put this in front of any launch options you have, ending with
%command%:
PROTON_REMOTE_DEBUG_CMD=$HOME/.config/omarchy/plugins/crmne.moza/bin/omarchy-moza-shm.exe %command%
For Le Mans Ultimate, also enable Settings → Gameplay → Enable Plugins and restart the game.
PROTON_REMOTE_DEBUG_CMD is an undocumented Proton feature meant for a
debugger: Proton runs the given Windows program in the game's prefix just
before the game and stops it afterwards. It works in Valve's Proton 8 to 11 and
GE-Proton. If Valve removes it, these two games lose vibration and rev lights;
nothing else is affected.
Effects stop 300 ms after telemetry stops and when the plugin exits. A module connected behind a wheelbase is not supported yet; use its USB port. Assetto Corsa needs the companion from a current assetto-corsa-setup; the older companion sends RPM only. See pedal haptics for the protocol and Pit House's recorded behaviour.
On Home, choose Set max, wait for the full range to reopen, then hold the pedal at the position you want to count as fully pressed and choose Save max. You can increase a previously shortened maximum, including when the input bar already reads 100%. Set min works the same way at the released position. Saving changes only the selected limit. Cancel, a 30-second timeout, or closing the backend restores the previous limits. Keep the panel open until the result appears, and adjust pedals outside a driving session.
Home shows instructions only while setting a limit. Each Pedals tab starts with Calibration and range, followed by Response curve and Other settings. The first row is a live input bar and percentage for that pedal, so you can check the released and fully pressed positions without returning to Home.
On Pedals, choose the pedal and Calibrate. Keep it released during the three-second preparation countdown. During the seven-second Recording countdown, press it fully and release it. The instructions and current input stay visible while recording. Successful results clear after eight seconds; errors stay visible. If no movement was detected, the panel asks you to retry. Completed recording resets Range Start and Range End to 0–100%, so an old shortened limit does not constrain the new range. Curves, direction and brake sensor ratio are preserved. Brake calibration still requires Boxflat's opt-in under Other for supported pedals.
After calibration, check that releasing the pedal reads 0% and fully pressing it reads 100%. The recording result is not a firmware acknowledgement of sensor calibration. Cancelling after recording has begun restores the range limits but cannot undo sensor calibration, so run calibration again before driving.
Number and text fields read typed keys only and never the clipboard, so there is no paste. Focusing a number selects it for replacement; Up/Down or the arrows step it, Return or leaving the field applies it within range, and Escape restores it. Scrolling the panel never changes a value.
omarchy plugin disable crmne.moza
omarchy plugin remove crmne.mozaDisabling releases the devices. Removal leaves settings and presets intact.
mise install
make test
make validate
make buildSee architecture and coverage and binary provenance. Screenshots can be reproduced with the isolated capture host.
See upstream tracking and repository history for source
pins, verification and the Boxflat update command. Boxflat lives unmodified in
vendor/boxflat/, while plugin adaptations live in backend/.
This repository retains Boxflat's source and history. The adapter uses its actual Python controls and callbacks, without showing GTK windows; QML supplies the visible interface. Rust owns the wheelbase connection and drives rev lights directly. Python settings requests share that connection.
Boxflat is by Tomasz Pakuła and contributors (GPL-3.0). This integration uses the same license. moza-rev is by Francis De Brabandere and contributors (MIT; notice). The grouped card component comes from Carmine Paolino's OmaStats (MIT; notice). Neither this project nor Boxflat is affiliated with MOZA Racing.