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

# Pairing a WiThrottle or Engine Driver App with BigFred

> Connect WiThrottle, Engine Driver, or any WiThrottle-compatible app to BigFred over TCP and pair it to vehicles in your BigFred roster.

If you prefer to drive from your phone using a dedicated throttle app, BigFred's WiThrottle server has you covered. Point any WiThrottle-compatible app at BigFred, select the pairing sentinel locomotive, and your app session is linked to your BigFred account — giving you access to your full roster from a touch-optimised interface.

## Compatible apps

Any app that implements the WiThrottle TCP protocol will work, including:

* **WiThrottle** (iOS)
* **Engine Driver** (Android)
* Other iOS and Android apps that advertise WiThrottle protocol support

## Before you start

* Your phone or tablet must be on the **same WiFi network** as the BigFred server.
* Your admin must have enabled the **WiThrottle server** on the command station you want to use. If the command station does not appear in the Remotes dropdown, ask them to turn it on under **Admin → Command Stations**.

## How pairing works

BigFred uses a **sentinel locomotive** as the pairing trigger. Until your app session is paired to a BigFred account, BigFred presents a single entry in the app's loco list — a placeholder called **"Pair with BigFred"** at the configured sentinel DCC address (default: address **3**). When you select that address in your app, BigFred recognises the selection as a pairing intent and links the TCP session to your account.

Once paired, BigFred replaces the sentinel with your actual roster and you can drive any vehicle you have access to.

## Pairing your app

<Steps>
  <Step title="Open the Remotes page and start pairing">
    In BigFred, navigate to **Remotes** in the top menu. Select the command station you want to use from the dropdown. If the command station has both Z21 and WiThrottle enabled, click the **WiThrottle** tab.

    Optionally choose which vehicles the app is allowed to control:

    * Toggle **Allow all vehicles** to give the app access to your whole roster, or
    * Type vehicle names in the **Vehicles** field to restrict access to a specific set.

    Set the **Handset brake seconds** value if you want a longer or shorter idle timeout (6–60 seconds).

    Click **Generate Pairing**.
  </Step>

  <Step title="Note the server details and pairing address">
    BigFred enters pairing mode and displays:

    * The **server IP address** and **port** to enter in your app (default port: `12090`)
    * The **sentinel DCC address** to select when prompted (default: `3`)
    * A countdown showing how long the pairing window remains open (five minutes)

    Keep this screen visible while you configure your app.
  </Step>

  <Step title="Connect your app to BigFred">
    Open your WiThrottle-compatible app and navigate to its server connection screen. Enter:

    * **Server address** — the IP address shown on the BigFred Remotes page
    * **Port** — `12090` (or the custom port your admin configured)

    Connect. The app will establish a TCP connection to BigFred and present you with the loco selection screen.
  </Step>

  <Step title="Select the pairing sentinel locomotive">
    In your app's loco list you will see a single entry: **"Pair with BigFred"**. Select it (the address will match the sentinel address shown in BigFred, for example `3`).

    BigFred detects the selection and immediately pairs the session to your account. The status chip on the Remotes page changes to **Paired**.
  </Step>

  <Step title="Drive your rostered vehicles">
    Your app is now paired. BigFred updates the loco list in your app to show the vehicles in your roster. Select any vehicle to start driving — speed, direction, and function commands flow through BigFred to the DCC bus.
  </Step>
</Steps>

## Heartbeat and idle brake

WiThrottle clients must send a periodic heartbeat to keep the session alive. BigFred advertises a heartbeat window of **10 seconds** by default — most apps send their heartbeat automatically and you will not need to do anything. If the app stops sending heartbeats (for example, because it is backgrounded or WiFi drops), BigFred brakes the locomotive and marks the session as idle-braked after the configured timeout.

<Warning>
  Backgrounding your throttle app may suspend its network activity, which triggers the idle brake. Keep the app in the foreground while driving.
</Warning>

## Unpairing

To end your WiThrottle session:

* **From BigFred**: navigate to **Remotes**, find your session, and click **Unpair**, **or**
* **From the app**: disconnect from the server in your WiThrottle app's settings.

Either action releases the throttle slot and the locomotive stops receiving commands from the app.

<Tip>
  Once paired, you can switch to any vehicle in your BigFred roster directly from your app's loco list — you do not need to go back to BigFred's web UI. BigFred keeps the roster in sync with what the app sees.
</Tip>