Doctor

The Doctor page is a one-stop health check. It runs a handful of probes against the device, the sim, and the host environment, and where there's an obvious fix it offers an inline action to apply it. Start here whenever something isn't working — odds are Doctor already knows what it is.

Hardware compatibility

The first card on the Doctor page is a hardware compatibility panel. It hosts two related controls: an Invert axis polarity toggle, and a live drag-pad polarity test. Both exist because different production runs of the Sidewinder Force Feedback 2 interpret force-feedback polarity differently — on some sticks, what the bridge thinks is “forward” physically pulls back, and vice-versa. The toggle is the install-level fix; the test is how you know whether to flip it.

Live polarity test

Click Start and a small X-Y drag-pad becomes active. Move the puck around, the stick follows in real time — the bridge auto-arms in Mock mode for the duration of the test so the prereqs check passes without a sim connection. Click Stop when you're done. A confirmation modal asks “Did the stick follow the puck?”:

Yes — polarity is correct, no change made.
No — the toggle flips automatically and every subsequent force on both pitch and roll axes is negated at the device-output edge.

Navigating away from the Doctor page mid-test silently stops it and restores your previous input source (Live or Idle) — no explicit Stop required.

Invert axis polarity (manual)

The toggle on the left of the card is the same setting the test would write. Use it directly if you already know your stick needs the flip — for instance, you've gone through this on a previous install and want to set it before testing. The setting is install-level, not per-profile: it lives in the bridge's preferences, applies to both pitch and roll axes together, and survives restarts.

Why both axes together

Earlier builds let pitch be inverted independently of roll. That didn't match how the FFB2's firmware quirks actually present — when one axis is reversed, both are. The toggle now flips them as a pair. Existing per-pitch settings are migrated forward on first launch.

Software-blended periodics

The bridge has two ways to dispatch periodic and one-shot effects (rumble, buffets, shudders…) to the FFB2. Hardware mode — the fresh-install default — uses DirectInput hardware effects, and 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 the periodic waveforms at native rate; the bridge simply reuses those physical slots for the current runway, engine, buffet, and one-shot cues. Software-blended periodics, the toggle on the same Doctor row, keeps only the continuous force / centering hardware path and synthesises periodic and 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 driver stacks that still crash in hardware mode, for failed probe results, or for users who deliberately prefer it. A generic unclean exit does not force software blending by itself. Both modes use the same fourteen effects with the same per-effect tuning sliders — the choice is a dispatch detail, not a feature toggle. Restart-required either way; the dispatcher reads the mode at startup.

Click Test hardware effects to try the compact hardware topology safely. Doctor starts a separate worker process, allocates the same vector constant, two-axis spring, and periodic pool the bridge uses in flight, then tears it down. If Windows' DirectInput/PID stack crashes, only the worker dies and the bridge stays open. If the test passes, Doctor and the runtime switch to the same hardware-mode state on the next launch, so the Doctor status and the actual dispatcher mode agree.

How checks are laid out

Every check row has four parts:

Status dot — green (pass), amber (warning), red (fail), grey (not applicable on this platform).
Title — what's being checked.
Detail — a one-line summary of what was found. Hover (or tap on touch) to see the full detail.
Action button — present only when there's something actionable. Examples: Install udev rule, Use port :5111, Fix….

The checks

Device

Confirms the Sidewinder Force Feedback 2 is visible to the OS and the bridge can open it exclusively. Fails if the VID/PID isn't present, or if another process is holding the handle.

Linux udev rule

Checks whether /etc/udev/rules.d/99-ffb-bridge.rules is present and matches the canonical content. When absent, the action is Install udev rule — this triggers a pkexec prompt to write the file into a privileged location.

NixOS exception

Doctor detects NixOS (by looking for /etc/NIXOS) and replaces the udev-rule row with an instruction to add the rule to configuration.nix instead. See Install for the snippet.

SimConnect config

Looks for MSFS's SimConnect.xml in the platform-appropriate location, parses it, and compares any enabled IPv4 entries against the port the bridge is using. Three possible outcomes:

Matching entry found. Green — nothing to do.
Entry at a different port. Amber — offers a Use port :X button to adopt that port.
No usable entry (or unparseable file). Red — offers a Fix… button that opens the install dialog (see below).

SimConnect reachability

Probes the configured TCP port. Sends a real SimConnect OPEN packet and inspects the response header so it can distinguish MSFS is listening from something else is listening.

X-Plane reachability

Sends a tiny RREF probe to 127.0.0.1:49000 and waits briefly for a dataref in response. Maps both timeout and Winsock's WSAECONNRESET (received when an ICMP port-unreachable was delivered) to “not running”.

Runtime

Checks that the control loop is ticking at its target 50 Hz. Warns if the last 60 s mean drops below 45 Hz.

Crash log

If there's a crash log from the last session, the row goes amber and offers Reveal to jump to it in your file manager, and Send via feedback form which pre-populates a feedback submission with the log attached.

Fix dialog

Fix… buttons don't apply changes directly — they open a dialog that shows exactly what's about to change, where, and (on Linux) what the auth prompt will ask you to approve.

The dialog is always additive: existing entries are never overwritten. If the target file is unparseable, the dialog explains that a timestamped backup will be taken first. Cancel is always the safe choice.

Linux pkexec behaviour

Actions that write to system paths (udev rules, anything under /etc) route through pkexec. You'll see your distro's normal polkit prompt — the same one that pops up for gparted or a package manager GUI. Exit codes Doctor interprets:

Exit	Meaning	Doctor reports
`0`	Success	Green check; row re-evaluates.
`126`	User dismissed the auth prompt	Amber “Cancelled” — try again when ready.
`127`	No polkit agent / auth failure	Red “Authentication failed.”

Tip

Running the bridge in a minimal environment (headless Linux, sway without a polkit agent) is fine — you just can't use Doctor's privileged fixes. Install the required files manually or start a polkit agent before launching the bridge.

When Doctor is green everywhere

The app should work. If it doesn't, Diagnostics' event log will show more detail than Doctor's one-line status. Head there next, or jump to Troubleshooting for common symptoms and fixes.