> ## Documentation Index
> Fetch the complete documentation index at: https://dcc-5ccd5152.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://developer.mozilla.org/en-US/docs/Web/API/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
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.
Navigate to **Throttle** in the main navigation. BigFred detects connected gamepads automatically in the background. No extra driver or plugin is needed.
Tap the **gamepad icon** (🎮) in the throttle header bar. If the icon has a coloured border, gamepad control is already active for this session.
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.
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.
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
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.
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.
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.
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.