FFB-Bridge

Chapter 1About this manual

This manual covers FFB-Bridge, a userspace bridge that drives the Microsoft Sidewinder Force Feedback 2 joystick from Microsoft Flight Simulator 2024 and X-Plane 11 / 12 on Windows 10+ and modern Linux. It is the single-file edition of the per-page manual at ffb-bridge.com/docs — same content, laid out for reading end to end and for printing to PDF.

The OS chips Windows, Linux, and Both mark paragraphs that apply to only one platform. Menus and buttons are in bold; filenames and shortcuts are in code.

Chapter 2Install

2.1 Windows installer

After signing up on the home page, click the Windows link in the emailed download. Save FfbBridge-Setup-x64.exe and double-click it. On first launch SmartScreen warns “Unrecognised app” — click More info, then Run anyway. The installer is unsigned until 1.0.

The Inno Setup wizard installs into %LOCALAPPDATA%\Programs\FfbBridge by default. No administrator permission required — this is a per-user install. A Start Menu shortcut lands in the FFB-Bridge group.

To uninstall, open Apps & features, find FFB-Bridge, and choose Uninstall. Your profiles under %APPDATA%\ffb-bridge are kept for a later reinstall; remove that folder for a clean slate.

2.2 Linux AppImage

Save the AppImage from the emailed link, make it executable, and register menu entries:

chmod +x FfbBridge-x86_64.AppImage
mkdir -p ~/Applications
mv FfbBridge-x86_64.AppImage ~/Applications/
~/Applications/FfbBridge-x86_64.AppImage --install

The --install flag writes the .desktop file and icons into XDG directories so FFB-Bridge shows up in your application menu. Uninstall with --uninstall.

2.3 udev rule (Linux)

So the bridge can open the stick without a polkit prompt on every launch, install the following udev rule. The Doctor page has a one-click installer that uses pkexec to write it; you can also install by hand:

# /etc/udev/rules.d/99-ffb-bridge.rules
SUBSYSTEM=="input", ATTRS{idVendor}=="045e", ATTRS{idProduct}=="001b", TAG+="uaccess"

On NixOS, add it to configuration.nix under services.udev.extraRules, then sudo nixos-rebuild switch and replug the stick.

Chapter 3First launch

First-launch flow is three modals back-to-back: a physical-hazard Safety acknowledgement, then the Welcome tour, then the Dashboard. The safety modal blocks dismissal until you tick the “I understand” checkbox; Welcome can be skipped and replayed later from the Help page.

The Dashboard opens with the device detected and the arm gauge in the top strip reading DISARMED. Forces do not reach the stick until you explicitly arm. The strip across the top of the window is the operational cockpit: brand block, ARM gauge (centre, the visual hero), Sim · Device · Mode lamps, and the Profile picker + Tune / Save button on the right. Live flight numbers (IAS, G, Mach, pitch / roll force, data age, tick rate) live in a thin tape along the bottom of the content area.

Click the ARM gauge in the strip to arm. The gauge has three states: DISARMED (warm border at rest, neutral glyph), ARMED (amber gradient + bright glyph), FAULTED (red — see § 3.4). Esc cancels the arm-confirmation dialog if you change your mind before confirming. There are no other global keyboard shortcuts; the bridge is mouse / tray-driven by design.

Safety. The first arm snaps the stick to the trimmed centre position. Make sure nothing — hands, cables, anything loose on the desk — is resting on or against the stick when you arm.

3.4 Recovering from a fault

If a prerequisite drops while you're armed — most often the stick gets unplugged or the sim crashes — the gauge flips to FAULTED and forces stop. The matching lamp goes red so the cause is unambiguous: DEVICE for an unplug, SIM for a sim drop. Click the gauge to acknowledge and reset back to DISARMED; restoring the missing prerequisite then lets you re-arm. The open Diagnostics link next to the gauge takes you to the event log if you want the full story before resetting.

Closing the window (X button) hides to the tray; the bridge keeps running. Use the tray menu to arm / disarm / show / quit. On GNOME Wayland there is no tray — the window hides silently and you'll need to use Alt+Tab or the desktop menu to get it back.

Chapter 4Connecting MSFS 2024

MSFS talks to FFB-Bridge over SimConnect TCP. On Windows this works out of the box; on Linux under Proton the default port (500) can't be bound and a one-click Doctor fix adds a parallel unprivileged port.

4.1 Where SimConnect.xml lives

The file's location depends on the MSFS install source:

• Windows Steam %APPDATA%\Microsoft Flight Simulator 2024\SimConnect.xml
• Windows Store / Xbox %LOCALAPPDATA%\Packages\Microsoft.Limitless_8wekyb3d8bbwe\LocalCache\SimConnect.xml
• Linux Steam + Proton ~/.steam/steam/steamapps/compatdata/2537590/pfx/drive_c/users/steamuser/AppData/Roaming/Microsoft Flight Simulator 2024/SimConnect.xml

FFB-Bridge detects the correct path automatically. Override with FFB_BRIDGE_MSFS_CONFIG or FFB_BRIDGE_MSFS_PREFIX if you run MSFS from a non-standard location.

4.2 Doctor's one-click fix

Open Doctor. The SimConnect config row shows the detected XML path and the port the bridge is targeting. Three outcomes:

• Green — matching entry found, nothing to do.
• Amber Use port :X — entry at a different port; the button adopts it.
• Red Fix… — no usable entry; the dialog shows exactly what it will add.

All fix operations are additive — existing entries are never overwritten. If the XML is unparseable, a timestamped backup is taken first.

Chapter 5Connecting X-Plane 11 / 12

Zero-config. X-Plane accepts UDP RREF subscribes on 127.0.0.1:49000 by default; FFB-Bridge subscribes on launch and data flows. If X-Plane is running when you start the bridge, the SIM lamp in the top strip goes green within milliseconds.

A 3-second staleness watchdog covers the UDP no-disconnect problem: if no datarefs arrive for three seconds, the SIM lamp turns red. Loading a new flight re-establishes automatically.

Firewalls rarely interfere on loopback, but if Doctor's X-Plane probe is red and X-Plane is genuinely running, check for a firewall blocking UDP 49000. See chapter 14 for the recovery flow.

Chapter 6Dashboard

Operational state — arm, sim, device, mode, profile — is no longer on this page. It moved into the persistent top strip so it stays visible while you're on Tuning, Diagnostics, or anywhere else. The Dashboard is the live explanation surface: what the sim is reporting, what dynamic channels are active, and what baseline spring state the stick is holding.

Left panel: flight state. A row of three numeric readouts — airspeed (kt), G-load (g, turning amber outside the normal range), Mach — over a pair of BiBars for elevator and aileron deflection. Below the bars, smaller readouts for elevator trim, ground state, and stall warning. The UI refreshes at ~20 Hz — a decimated view of the 50 Hz control loop.

The bottom of the left panel is a list of effect-group toggles: Stick feel, Engine rumble, Airframe buffet, Ground roll, Mechanical shoulders, Axis load, and Autopilot follow. Each row has a checkbox, a live status, and a compact level bar. Use these as quick mutes for in-flight A/B comparisons; per-effect gains stay on Tuning. Toggle state is part of the active profile.

Right panel: stick activity. The headline names the strongest dynamic contributors, the stacked bar groups them by family, and the active-channel chips show individual values when they matter. The centring spring is treated as the baseline feel, so the active list focuses on changes above that baseline: trim centre, G-load spring changes, axis load, engine rumble, ground roll, buffets, and mechanical one-shots. Axis-load bars show signed pitch / roll force; the centring-spring section shows coefficient, deadband, and pitch / roll centre.

Chapter 7Tuning

Every slider change applies on the next 50 Hz tick; you can fly with the Tuning page pinned on a second monitor and adjust effects while they're happening.

7.1 Master gain

A single multiplier applied after all effects, displayed as a percentage from 0% to 100%. 100% is the designed level (and the default); lower values attenuate every dynamic output at once. There's no “boost” above 100% — that ceiling is the one the per-effect gain sliders work up to. Beta.11 drives the device at 95% of bridge authority underneath this slider, leaving 5% headroom.

7.2 Slider groups

Top to bottom: Centring spring (base, G-gain, min/max clamps, deadband) · Aerodynamic loading (pitch gain, roll gain) · Stick feel (rate damping, control-edge bonus, stick drop) · Ground effects (runway rumble, touchdown thump, gear bumps, brake shudder) · Aero buffets (stall, overspeed, Mach, spoiler, turbulence) · Powerplant (engine rumble, reverse rumble) · One-shots (gear deploy, flap step) · Autopilot (back-drive gain, rate limit). See chapter 12 for the full reference.

7.3 Stick drop

Stick drop models the gravity bias on an unloaded elevator at low airspeed — what makes a parked GA aircraft's yoke sit slightly forward of centre. Two sliders: Force (how hard the bias pulls) and Fade airspeed (the kts at which the bias has decayed to zero). Defaults are Cessna-class — drop Force toward 0 to silence on jet or fly-by-wire profiles.

7.4 TrimRelief (alt-trim mode)

A toggle under Stick feel that changes how trim and stick force interact. With TrimRelief off (the default), pitch / roll trim shifts the spring's centre but airspeed loading still fights total surface deflection — a trimmed aircraft with neutral stick pushes against you. With TrimRelief on, airspeed loading is computed against (elevator − trim) and the spring centre tracks trim with full authority. At a trimmed steady state with neutral stick, you feel zero force — and release lets the stick hold the trimmed position the way a real cable-rigged stick does. Existing profiles tuned around the legacy behaviour stay untouched. Closer to the XPforce / FSforce model if that's the mental model you're after.

7.5 Slider interaction

Drag the thumb, click anywhere along the track to jump there, or click once to focus and then use the wheel / arrow keys. Hovering and scrolling does not capture the wheel — the slider has to be focused first — so you can scroll the page past hovered sliders without nudging them.

7.6 Dirty indicators and resets

When a slider differs from the loaded profile, a back-arrow reset glyph appears next to its value; click it to revert just that slider. Each section header carries a matching glyph that resets every slider in the section. A Discard button on the Profile card reverts everything at once. The amber dot on the profile picker summarises “this profile has unsaved changes”. Resets are local-only — they don't touch the saved profile.

7.7 Saving

Save overwrites the active profile. Save as… opens a dialog to save under a new name. Starter presets are read-only; Save as creates the editable aircraft tune you will keep.

Chapter 8Profiles

Saved profiles are JSON files under %APPDATA%\ffb-bridge\profiles\ (Windows) or ~/.config/ffb-bridge/profiles/ (Linux, honouring $XDG_CONFIG_HOME). Each file is one profile. Copy them between machines or share them with others by emailing the file.

Starters and saved profiles share one list. Actions: Use selected profile, Duplicate selected, Delete selected, and Refresh. Starter presets are read-only; use Duplicate or Save as to get an editable copy.

Built-in starters are named after the MSFS aircraft: Cessna 172 Skyhawk (G1000), Daher TBM 930, Beechcraft King Air 350i, Airbus A320neo, and Boeing 747-8 Intercontinental. Switching profiles applies on the next 50 Hz tick without disarming. The profile picker on Tuning shows an amber dot for unsaved changes — save before loading another profile or you'll discard the changes.

Chapter 9Diagnostics

Four metric cards at the top: Control-loop rate (target 50 Hz), Pipeline latency (µs), Effects active (count), Reassertions (counter). Each has a 60 s sparkline.

Event log fills the lower half of the page. Level colours: INF / DBG neutral, WRN amber, ERR / FTL red. About 2,000 lines of rolling scroll-back; filter by substring with the bar at the top of the log.

The Export support bundle button produces a single ZIP for feedback reports. See chapter 15 for the complete contents list.

Chapter 10Doctor

10.1 Hardware compatibility

The first card hosts an Invert axis polarity toggle and a live drag-pad polarity test. Different production runs of the FFB2 read polarity differently; the test verifies which way yours runs by driving the stick from a 2-axis drag-pad in real time. Click Start, move the puck, click Stop, then answer “Did the stick follow the puck?” — Yes makes no change, No auto-flips the toggle. The toggle is install-level and flips both pitch and roll axes together.

10.2 Software-blended periodics

The bridge has two ways to dispatch periodic and one-shot effects to the FFB2. Hardware mode — the fresh-install default — uses DirectInput hardware effects, but beta.11 keeps that topology deliberately small: one vector constant, one two-axis spring, and a lazy three-slot periodic pool. The firmware still drives periodic waveforms at native rate; the bridge reuses those physical slots for runway, engine, buffet, and one-shot cues. Software-blended periodics on the same Doctor row keeps only the continuous force / centering hardware path and synthesises periodic / one-shot cues in C# at 200 Hz, folding the result into the constant-force outputs.

Hardware mode is crisper and lower-latency on the highest- frequency effects because the firmware drives them faster than the bridge's tick rate. Software blending is the compatibility fallback for failed hardware probes, classified hardware-effect crashes, or users who deliberately prefer it; a generic unclean exit does not force software blending by itself. Its high-frequency edges can feel a little softer. Restart-required either way — the dispatcher reads the mode at startup. Use Test hardware effects to try the compact hardware topology safely in a separate worker process.

10.3 Health checks

Checks: Device, udev rule (Linux), SimConnect config, SimConnect reachability, X-Plane reachability, Runtime health, Crash log. Row status dots are green / amber / red / grey (not applicable).

Where a fix is obvious, the row offers an inline action — Install udev rule, Use port :X, Fix…. The Fix dialog shows exactly what will change before it's applied, and never overwrites existing entries.

Linux actions that write system paths route through pkexec. Exit codes: 0 = success, 126 = user dismissed the prompt, 127 = auth failure / no polkit agent.

Chapter 11Mock SimConnect

The bridge has three input sources: Live (real sim), Mock (UI-driven sliders), Idle (no data). Mock is a first-class peer — arm, dispatch, reassertion, and stale-watchdog all run identically.

Use Mock to feel individual effects in isolation, tune profiles without flying, or demo the bridge without a sim installed. Four one-click scenario presets snap every slider to plausible values for Taxi / Takeoff roll / Cruise / Landing flare.

Live and Mock are mutually exclusive. A detected real sim locks Mock out with an explanatory banner.

HelpHelp page

The in-app Help page is the compact reference for the current run. It shows setup state, points you through the get-flying flow, gives the recommended tuning order, and links out to the pages that own each workflow: Dashboard for live force visibility, Tuning for sliders, Profiles for library management, Doctor for health checks, and Diagnostics for support bundles.

Chapter 12Force effects reference

The fourteen effects shipped with v1.0.0-beta.11:

1. Centring spring — stiffens with G-load, deadband scales with airspeed, centre shifts with trim.
2. Airspeed-loaded pitch force — constant pitch-axis force scaled by airspeed² × elevator offset.
3. Airspeed-loaded roll force — same model on the roll axis, independently tuned.
4. Rate damping — opposing force proportional to body-axis rotation rates (p, q); viscous damping.
5. Stick drop — gravity bias on the elevator at low airspeed; pulls stick forward when parked, fades by Fade airspeed (default 30 kts).
6. Autopilot back-drive — spring centre tracks AP commanded deflection, rate-limited.
7. Runway rumble — continuous periodic force scaled by ground speed and surface type (grass 1.5–1.9×, ice 0.3–0.5×).
8. Touchdown thump — single impulse on on-ground transition, amplitude scaled by vertical speed.
9. Brake shudder — low-frequency rumble proportional to brake deflection, gated on-ground.
10. Gear bumps — discrete impulses during taxi under ~40 kt.
11. Aero buffets — five sub-effects (stall, overspeed, Mach, spoiler, turbulence) sharing a buffet generator.
12. Engine rumble — continuous periodic force scaled by per-engine RPM × combustion flag.
13. Reverse-thrust rumble — rollout rumble when reverse is engaged, scaled by ground speed.
14. Mechanical one-shots — gear-deploy and flap-step shudders on any transition, both directions.

All fourteen sum into two outputs (pitch + roll force plus spring parameters). Master gain is applied last; an install-level pitch / roll polarity invert (Doctor's hardware-compatibility card) negates both axes together at the device-output edge if your hardware reads polarity reversed. The Dashboard separates the baseline spring from active dynamic channels so you can see which effects are contributing at any instant.

TrimRelief alt-trim mode changes the input to effects 1 (centring spring) and 2 / 3 (airspeed-loaded pitch / roll forces). With TrimRelief off (the default), they reference total surface deflection. With TrimRelief on, they reference (stick − trim) and the spring centre tracks trim with full authority — at a trimmed steady state with neutral stick, every force is zero and the stick holds at the trimmed position on release. Toggle on the Tuning page under Stick feel.

Software-blended periodics is a dispatch-mode choice, not a feature toggle. Either mode is fully tuned — same fourteen effects, same sliders. In hardware mode (the fresh-install default) the bridge allocates one vector constant, one two-axis spring, and a lazy Sine / Triangle / Triangle periodic pool. In software-blended mode the bridge keeps only the continuous force / centering hardware path and synthesises periodic / one-shot cues in C# at 200 Hz. Toggle on the Doctor page; restart-required.

Pause and stale-telemetry safety sit outside those fourteen effects. When MSFS pause, Active Pause, or frozen telemetry is detected, dynamic forces go quiet immediately and the stick holds a neutral default spring until live data resumes.

Chapter 13Tuning guide

Verify polarity first via Doctor's drag-pad polarity test (chapter 10) — if forces are reversed, every gain you set below will fight the wrong sign. Then work through the stages in order, saving the profile after each stage so you can fall back.

1. Master gain. Start at 100%. Fly cruise, look for motor saturation; if the stick feels harsh at full deflection, drop to 80% and repeat. There's no boost above 100% — that's the designed ceiling.
2. Centring spring. Release the stick at cruise: snappy vs sluggish. Then pull a 2 G turn: does it firm up?
3. Stick drop. Park the aircraft, engine off — the stick should sit slightly forward (modelling gravity on the unloaded elevator). Adjust Force for resting position, Fade airspeed for when it disappears in the takeoff roll. Set Force to 0 for jet / fly-by-wire profiles.
4. Pick a trim model. TrimRelief off (default) keeps legacy TrimFeel — airspeed loading fights total surface deflection, a trimmed aircraft pushes against you. TrimRelief on references (stick − trim) — at trim with neutral stick, zero force, stick holds on release. Pick before tuning loadings; switching mid-tune shifts the felt forces.
5. Aerodynamic loading. Push the stick without trimming; should feel like air pushing back. Verify across the speed envelope.
6. Ground effects. Taxi on paved vs grass. Brake. Plant a firm arrival.
7. Buffets. Power-off stall for the stall buffet; deploy spoilers for the spoiler buffet.
8. Mechanical one-shots. Retract / extend gear and flaps.
9. Powerplant. Idle vs takeoff power — should feel distinctly different.
10. Rate damping. If the stick rings back to centre, raise it. Too much and the stick feels dead.

Aircraft-type patterns: light singles want firm centring and moderate loading; aerobatic wants soft centring and low damping; heavy jets want heavy damping and strong AP back-drive; bush / STOL wants low centring base but high G-gain. Start from the built-in starter closest to your aircraft: Cessna 172 Skyhawk (G1000), Daher TBM 930, Beechcraft King Air 350i, Airbus A320neo, or Boeing 747-8 Intercontinental.

Chapter 14Troubleshooting

14.1 Stick doesn't move

In the top strip, confirm in order: (1) the ARM gauge reads ARMED (amber) — not Disarmed or Faulted; (2) the DEVICE lamp is green ("Ready"); (3) the SIM lamp is green ("Sim connected"). A red lamp points to the corresponding Doctor row.

14.2 MSFS connects but forces feel wrong

Load the starter closest to your aircraft. Most “wrong” feels come from a profile that was tuned for a different aircraft class. Third-party aircraft occasionally skip implementing standard SimVars — the bridge tolerates that (missing vars default to zero), but effects that depend on them will go quiet.

14.3 Tray icon doesn't appear (Linux)

Some desktops don't ship a tray host out of the box — GNOME Wayland is the big one. The bridge detects this and shows a banner explaining that close will quit the app directly instead of hiding. Install AppIndicator Support on GNOME to get a tray back; KDE, Xfce, Cinnamon, MATE, Budgie work out of the box.

14.4 Windows hardware-mode crash after arming

Pre-beta.10 builds could crash on some Windows / FFB2 stacks because hardware mode created a large retained DirectInput effect table. This was a bridge architecture bug, not MSFS or bad firmware. Beta.10 replaces that path with one vector constant, one two-axis spring, and a lazy three-slot periodic pool. If a beta.10-or-later build still crashes in hardware mode, run Doctor's Test hardware effects and switch to Software-blended periodics if the bridge offers that recovery.

14.5 Crash on launch

Next launch shows a crash-report dialog with the stack trace and an Open feedback form button that pre-attaches the crash log. If the app crashes before the dialog appears, pull the log by hand from %LOCALAPPDATA%\ffb-bridge\crashes\ (Windows) or ~/.local/share/ffb-bridge/crashes/ (Linux).

14.6 Forces disappear after pause or a long stutter

Beta.11 targets this directly. MSFS pause and Active Pause now suppress dynamic effects immediately, hold a neutral default spring while paused, and reupload spring parameters before replay after quiesce. If roll or pitch force still feels absent after resume, export a support bundle right away and note what the Dashboard showed under stick activity.

Chapter 15Support bundles

A support bundle is a single ZIP produced by Diagnostics → Export support bundle. The ZIP contains, and only contains:

• sysinfo.txt — OS, kernel, distro, CPU, RAM, .NET version, locale.
• session.log — full event log for the current session.
• last-crash.log — crash log if one exists.
• doctor.json — last Doctor scan in machine-readable form.
• tunables.yaml — the active profile at export time.
• simconnect-config.xml — MSFS's config, passwords stripped (MSFS sessions only).

Limits: 50 MB compressed total, 5 MB per entry, 30 entries max, 20 MB uncompressed total, UTF-8 text only (plus the XML). A typical bundle is under a megabyte.

The bundle never leaves your machine automatically — you choose when to attach it to a feedback report, and whether to send it.

Chapter 16Licence and disclaimer

FFB-Bridge is free software offered as-is with no warranty. Use at your own risk — the bridge drives physical hardware and bugs can produce unexpected forces. Treat every arm as a “hands clear” moment.

This is a solo project, independent of Microsoft and Laminar Research. “Microsoft Flight Simulator”, “SimConnect”, “Sidewinder”, and “X-Plane” are trademarks of their respective owners; they appear here for the sole purpose of identifying compatible products. Nothing on this page implies endorsement by either company.

The full FAQ and privacy policy live at ffb-bridge.com/#faq and ffb-bridge.com/privacy.

End of manual. Feedback on any section — text, figures, or tuning advice that didn't help you — ffb-bridge.com/feedback.