Documentation in beta. Some text and images will be reworked as the app settles into 1.0. If a section reads stale, flag it via the feedback form.

FFB-Bridge

User manual — Single-page printable edition
v1.0.0-beta.2 · Revised 2026-04-23 · Windows 10+ / modern Linux (evdev) · MSFS 2024 / X-Plane 11–12
Download PDF Or use your browser's “Save as PDF” — the print stylesheet flips to light mode and hides the nav chrome.
Contents
  1. About this manual
  2. Install
  3. First launch
  4. Connecting MSFS 2024
  5. Connecting X-Plane 11 / 12
  6. Dashboard
  7. Tuning
  8. Profiles
  9. Diagnostics
  10. Doctor
  11. Mock SimConnect
  12. Force effects reference
  13. Tuning guide
  14. Troubleshooting
  15. Support bundles
  16. Licence and disclaimer

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.

Installed menu entry on KDE Plasma; other XDG-compatible desktops pick it up identically.
Figure 2.1. Installed menu entry on KDE Plasma; other XDG-compatible desktops pick it up identically.

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.

Safety acknowledgement. Shown on first launch only, and required before the bridge can run.
Figure 3.1. Safety acknowledgement. Shown on first launch only, and required before the bridge can run.
Welcome dialog. Click “Take the tour” or “Skip tour”.
Figure 3.2. Welcome dialog. Click “Take the tour” or “Skip tour”.

The Dashboard opens with the device detected and the arm toggle off. Forces do not reach the stick until you explicitly arm. The 32-pixel telemetry strip along the top of the content area shows IAS, G, Mach, pitch/roll force output, data age, and tick rate; the master arm state lives as a coloured pill in the bottom-left of the sidebar.

Dashboard in its initial state.
Figure 3.3. Dashboard in its initial state.

Click the arm toggle (top-right) or press Space to arm. The toggle has three states: disarmed (grey), Ready to engage (soft blue pulse), armed (solid blue with a lightning glyph).

Arm toggle states.
Figure 3.4. Arm toggle states.
Close-button dialog. Minimize to tray keeps the bridge running; Quit releases the stick.
Figure 3.5. Close-button dialog. Minimize to tray keeps the bridge running; Quit releases the stick.
Safety. The first arm snaps the stick to the trimmed centre position. Make sure nothing — hands, cables, the dog — is resting on or against the stick when you arm.

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.

System tray menu.
Figure 3.4. System tray menu.

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:

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:

Doctor's SimConnect row.
Figure 4.1. Doctor's SimConnect row.
Fix dialog on Linux, showing the parallel unprivileged port entry about to be merged.
Figure 4.2. Fix dialog on Linux, showing the parallel unprivileged port entry about to be merged.

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 chip goes green within milliseconds.

Dashboard chips connected to X-Plane (in the capture we're in Mock mode; in a real X-Plane session the Sim chip reads “X-Plane” with the version detected).
Figure 5.1. Dashboard chips connected to X-Plane (in the capture we're in Mock mode; in a real X-Plane session the Sim chip reads “X-Plane” with the version detected).

A 3-second staleness watchdog covers the UDP no-disconnect problem: if no datarefs arrive for three seconds, the Sim chip 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.

Doctor's X-Plane probe row.
Figure 5.2. Doctor's X-Plane probe row.

Chapter 6Dashboard

Dashboard layout — telemetry panel, force-output bars, arm toggle with connection chips.
Figure 6.1. Dashboard layout — telemetry panel, force-output bars, arm toggle with connection chips.

Left panel: live telemetry. Radial gauges for airspeed, altitude and G-load; BiBars for elevator and aileron deflection; numeric readouts for pitch, bank and AoA. The UI refreshes at ~20 Hz — a decimated view of the 50 Hz control loop.

Centre: force-output meters. Pitch and roll forces as fractions of full authority, trim markers showing the shifted centre. Small badges below the bars light up when individual effects are contributing.

Force-output meters with three effect badges lit.
Figure 6.2. Force-output meters with three effect badges lit.

Right: arm toggle, connection chips (Device, Sim, Profile), and a strip of the last few log lines. The arm toggle refuses to arm if no sim is connected and no device is open.

Connection chips.
Figure 6.3. Connection chips.

Chapter 7Tuning

Tuning page: master-gain accent card, thirteen effect sliders grouped by subsystem, per-slider dirty indicators.
Figure 7.1. Tuning page: master-gain accent card, thirteen effect sliders grouped by subsystem, per-slider dirty indicators.

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. Mostly you leave this at 100% and tune the per-effect sliders; it exists for quick “quieter overall” trims without touching the profile values underneath.

Master-gain card.
Figure 7.2. Master-gain card.

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) · 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 Dirty indicators

Amber dots next to each slider value appear when the slider differs from the loaded profile. A matching amber dot on the profile picker summarises “this profile has unsaved changes”.

Two sliders dirty — runway rumble and engine rumble.
Figure 7.3. Two sliders dirty — runway rumble and engine rumble.

7.4 Saving

Save (Ctrl+S) overwrites the active profile. Save as… (Ctrl+Shift+S) opens a dialog to save under a new name. Starter presets are read-only and only Save-as is enabled for them.

Chapter 8Profiles

Profiles page: starter presets on the left, saved profiles on the right.
Figure 8.1. Profiles page: starter presets on the left, saved profiles on the right.

Profiles are YAML 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.

Actions: Load, Duplicate, Rename, Delete. Starter presets are read-only; use Duplicate to get an editable copy.

Starter presets list.
Figure 8.2. Starter presets list.

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

Diagnostics page — metrics cards, event log, support-bundle export.
Figure 9.1. Diagnostics page — metrics cards, event log, support-bundle export.

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.

Metrics grid close-up.
Figure 9.2. Metrics grid close-up.

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.

Event log.
Figure 9.3. Event log.

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

Bundle-exported banner.
Figure 9.4. Bundle-exported banner.

Chapter 10Doctor

Doctor page. Each row is one check.
Figure 10.1. Doctor page. Each row is one check.

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).

SimConnect config row detail.
Figure 10.2. SimConnect config row detail.

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.

Fix dialog for SimConnect config install.
Figure 10.3. Fix dialog for SimConnect config install.

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

Mock SimConnect page.
Figure 11.1. Mock SimConnect page.

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.

Scenario preset bar.
Figure 11.2. Scenario preset bar.

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

Lockout banner.
Figure 11.3. Lockout banner.

Chapter 12Force effects reference

The thirteen effects shipped with v1.0.0-beta.2:

  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. Autopilot back-drive — spring centre tracks AP commanded deflection, rate-limited.
  6. Runway rumble — continuous periodic force scaled by ground speed and surface type (grass 1.5–1.9×, ice 0.3–0.5×).
  7. Touchdown thump — single impulse on on-ground transition, amplitude scaled by vertical speed.
  8. Brake shudder — low-frequency rumble proportional to brake deflection, gated on-ground.
  9. Gear bumps — discrete impulses during taxi under ~40 kt.
  10. Aero buffets — five sub-effects (stall, overspeed, Mach, spoiler, turbulence) sharing a buffet generator.
  11. Engine rumble — continuous periodic force scaled by per-engine RPM × combustion flag.
  12. Reverse-thrust rumble — rollout rumble when reverse is engaged, scaled by ground speed.
  13. Mechanical one-shots — gear-deploy and flap-step shudders on any transition, both directions.

All thirteen sum into two outputs (pitch + roll force plus spring parameters). Master gain is applied last. The Dashboard's effect-active badges below the force bars show which effects are contributing at any instant.

Chapter 13Tuning guide

Work through the stages in order, one at a time, 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. Aerodynamic loading. Push the stick without trimming; should feel like air pushing back. Verify across the speed envelope.
  4. Ground effects. Taxi on paved vs grass. Brake. Plant a firm arrival.
  5. Buffets. Power-off stall for the stall buffet; deploy spoilers for the spoiler buffet.
  6. Mechanical one-shots. Retract / extend gear and flaps.
  7. Powerplant. Idle vs takeoff power — should feel distinctly different.
  8. 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.

Chapter 14Troubleshooting

14.1 Stick doesn't move

Confirm in order: (1) arm toggle is ON; (2) Device chip is green; (3) Sim chip is green. Any red chip points to the corresponding Doctor row.

14.2 MSFS connects but forces feel wrong

Load the Cessna 172 starter as a known-good baseline. Most “wrong” feels come from a profile that was tuned for a different aircraft. 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 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).

Chapter 15Support bundles

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

Limits: 60 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.

Export flow — Diagnostics button, then the banner with Reveal / Open feedback form.
Figure 15.1. Export flow — Diagnostics button, then the banner with Reveal / Open feedback form.

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, privacy policy, and terms 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.

An unhandled error has occurred. Reload 🗙