Controlling BigFred with a Gamepad or USB Controller

Connect a USB or Bluetooth gamepad to your device and map its axes and buttons to throttle speed, direction, emergency stop, and locomotive functions.

BigFred supports any USB HID gamepad or Bluetooth controller that your browser can see through the standard Gamepad API. That includes popular controllers such as Xbox, PlayStation, and generic USB gamepads, as well as dedicated model-railroad hand-held throttles that present as HID joysticks. Once mapped, you can walk freely around your layout and drive without touching the screen.

Supported Hardware

Any controller recognised by your browser’s Gamepad API will work. This covers:

• USB HID gamepads — plug in and the browser detects them immediately
• Bluetooth controllers — pair at the OS level first, then open the throttle page
• Dual-axis joysticks — any device with at least one analogue axis and a handful of buttons

Browser Gamepad API support is best in Chrome and Edge. Firefox also supports it. Safari support varies by version — if your controller is not detected, try Chrome.

Activating Gamepad Support

1. Connect your controller

   Plug in your USB gamepad, or pair your Bluetooth controller at the operating-system level before opening BigFred. The browser needs to see the device before the page loads — or you can connect it while the throttle page is already open and press any button to wake it up.

2. Open the throttle page

   Navigate to Throttle in the main navigation. BigFred detects connected gamepads automatically in the background. No extra driver or plugin is needed.

3. Open the gamepad mapping dialog

   Tap the gamepad icon (🎮) in the throttle header bar. If the icon has a coloured border, gamepad control is already active for this session.

4. Complete the safety acknowledgement

   The first time you open the dialog, BigFred shows a safety warning reminding you that axis-based speed control can cause unexpected movement. Read it and tap Acknowledge to continue.

5. Calibrate the idle range

   BigFred asks you to leave the speed axis at its natural resting position for 10 seconds while it learns the centre point. This idle calibration ensures that a spring-return stick does not cause unintended movement. Click Learn Idle Position, keep the stick still, and wait for the countdown to finish.

6. Configure your mapping

   The Settings screen opens. Assign axes and buttons to throttle actions (see below), then click Confirm to save.

The Mapping Dialog

The mapping dialog walks you through four screens in order:

Screen	Purpose
Warning	Safety acknowledgement — must be accepted before proceeding
Detect	Shown when no controller is connected; prompts you to plug one in
Idle calibration	Learns the resting position of the speed axis
Settings	Full axis and button assignment screen

Once calibration is complete, BigFred skips straight to Settings on subsequent openings.

Default Mapping

Out of the box, BigFred applies the following defaults when it first detects a new controller. You can change any of these in the mapping dialog.

Control	Default assignment	Notes
Speed axis	Axis 1 (left stick, vertical)	Inverted by default so pushing up increases speed
Axis inversion	On	Flip if your stick feels backwards
Axis enabled	On	Toggle off to use buttons only
Reverse button	Not assigned	Must be set manually
Stop (E-STOP) button	Not assigned	Must be set manually
Accelerate button	Not assigned	Discrete speed step up
Decelerate button	Not assigned	Discrete speed step down
Function buttons	None	Assign F0–F28 manually
Gamepad enabled	Off	You must explicitly enable after mapping

The axis index numbers correspond to the browser’s raw Gamepad API axis array. Axis 0 is typically the left stick horizontal, axis 1 is left stick vertical, axis 2 is right stick horizontal, and axis 3 is right stick vertical — but this varies by controller. Use the Learn Axis button to detect the correct axis by moving the stick.

Configuring the Mapping

Speed Axis

The speed axis translates an analogue stick position into a throttle speed from 0 to the current maximum. You can:

• Learn the axis — click Learn Axis and move the stick you want to use; BigFred detects the axis with the largest deflection automatically
• Invert — toggle Invert Axis if pushing the stick forward decreases speed instead of increasing it
• Disable the axis — toggle Axis Enabled off if you want to use accelerate/decelerate buttons only without any analogue input

Speed sensitivity controls how much of the axis range maps to full speed. The divisor slider ranges from ÷1.25 (most responsive — almost full range drives the locomotive to maximum) to ÷3 (finest control — the stick must travel much further to reach high speeds). Choose a lower divisor if you find the throttle too sensitive to small stick movements.

Axis toggle button — you can optionally assign a gamepad button that toggles the axis on and off at runtime. This lets you hold a dead-man button to enable the axis and release it to revert to buttons-only control.

Accelerate and Decelerate Buttons

These provide discrete speed steps as an alternative (or supplement) to the analogue axis. Each press of the assigned button adds or subtracts one speed step. The Speed Button Steps field (default 20) controls the number of equal steps across the full speed range; with 20 steps each press changes speed by roughly 5% of maximum.

Reverse and Stop Buttons

• Reverse — toggles direction between forward and reverse (equivalent to tapping the reverse arrow on screen)
• Stop — triggers an immediate emergency stop (equivalent to the on-screen Stop button)

Assigning Function Buttons

Each configured DCC function for the active vehicle appears in the Functions section of the mapping dialog. Click Assign next to a function, then press the physical button on your controller. BigFred binds that button to the function. If the button is already assigned to another action, BigFred shows a conflict error and rejects the assignment — clear the existing assignment first.

Saving the Mapping

When you click Confirm, BigFred saves the mapping to browser localStorage, keyed by the controller’s hardware ID. The mapping persists across sessions and browser restarts. If you connect the same controller again later, BigFred loads the saved mapping automatically.

Mappings are stored per-controller ID. If you use multiple controllers (for example, one at each operator station), each one gets its own independent mapping stored in the same browser.

Tips

Wireless freedom

Use a Bluetooth controller so you can walk the full length of your layout without being tethered to a screen. Pair it at the OS level, open the throttle page, and press any button to let the browser detect it.

Calibrate on every new controller

Even controllers of the same model can have slightly different centre points. Always run the idle calibration when you first use a new physical device to avoid unintended creep.

Disable the axis for shunting

Toggle Axis Enabled off and use only accelerate/decelerate buttons when shunting in a tight yard. Discrete steps give you more predictable control at very low speeds.

Check the gamepad icon

The gamepad icon in the throttle header turns highlighted when gamepad input is active. If it looks dim, open the mapping dialog and make sure the Enable Gamepad switch is on.