# AI First Officer — SimConnect Bridge
## Installation & Setup Manual

The **SimConnect Bridge** is a tiny program that runs on your Windows flight‑sim
PC. It reads live data from Microsoft Flight Simulator (speed, altitude, gear,
flaps, position, radios…) and relays it to the AI First Officer website so your
copilot can see exactly what your aircraft is doing in real time. It also lets
you talk to the copilot with a Push‑To‑Talk key without leaving the sim.

Your browser cannot talk to MSFS on its own — the bridge is the translator in
between. You only install it once; after that it's two double‑clicks before each
flight.

---

## Table of contents
1. [What you need](#1-what-you-need)
2. [Download the bridge](#2-download-the-bridge)
3. [One‑time installation](#3-one-time-installation)
4. [Start it before each flight](#4-start-it-before-each-flight)
5. [Confirm it's connected](#5-confirm-its-connected)
6. [Push‑To‑Talk](#6-push-to-talk)
7. [Running the website on a different PC (optional)](#7-running-the-website-on-a-different-pc-optional)
8. [Updating the bridge](#8-updating-the-bridge)
9. [Uninstalling](#9-uninstalling)
10. [Troubleshooting](#10-troubleshooting)
11. [FAQ & notes](#11-faq--notes)

---

## 1. What you need

| Requirement | Details |
|---|---|
| **Windows 10 or 11** | The bridge must run on the same PC as MSFS. |
| **Microsoft Flight Simulator** | 2020 or 2024. |
| **An AI First Officer account** | Signed in, with an active plan or trial, at <https://copilot.atlantic-iot.com/aicopilot/>. |

> **No Node.js, no installers.** The package ships with a bundled Node runtime
> (`AIFOBridge.exe`) and all of its dependencies, so there is nothing to install —
> you just download, extract, and run it.

---

## 2. Download the bridge

1. Sign in to the app: <https://copilot.atlantic-iot.com/aicopilot/>
2. Open **Settings** (the gear icon).
3. Find the **SimConnect Bridge** section and click **Download**
   (this is the `ai-first-officer.zip` package).
4. Save it somewhere permanent, e.g. `C:\AIFirstOfficer\`.
   **Don't run it from inside the .zip** — extract it first (right‑click →
   *Extract All…*).

After extracting you'll have this next to each other:

```
INSTALL.bat               ← ⭐ double-click this ONCE — one-click installer
ai-first-officer/
├─ bridge/
│   ├─ AIFOBridge.exe     ← bundled Node runtime (no install!)
│   ├─ start-bridge.bat   ← starts the bridge (the installer makes a shortcut)
│   ├─ node_modules/      ← bundled dependencies
│   ├─ bridge.js
│   ├─ package.json
│   └─ INSTALL.md         ← this manual
├─ manifest.json
└─ README.txt
```

---

## 3. One‑time installation — just run `INSTALL.bat` ⭐

**Double‑click `INSTALL.bat`** (it sits next to the `ai-first-officer` folder).
It does everything for you:

1. **Finds your MSFS Community folder automatically** — Microsoft Store /
   Game Pass and Steam, MSFS 2020 and 2024 (it reads the path from the sim's
   own `UserCfg.opt`, so custom install drives work too).
2. **Copies the package** into the Community folder.
3. **Creates a Desktop shortcut** — *"AI First Officer Bridge"* — so starting
   it before each flight is one double‑click.
4. Offers to **start the bridge right away**.

If it can't detect your sim it simply asks you to paste the Community folder
path. Re-running `INSTALL.bat` later is safe — it just updates the files
(that's also how you install updates).

> **Manual alternative:** you can still do it by hand — copy the whole
> `ai-first-officer/` folder into your MSFS **Community** folder (or anywhere,
> each flight. Nothing else to install either way: the package ships a bundled
> Node runtime (`AIFOBridge.exe`) and all dependencies — never install Node.js
> or run `npm`.

---

## 4. Start it before each flight

Do these in order, every time you fly:

1. **Launch Microsoft Flight Simulator** and load a flight — get all the way
   **into the cockpit** (past the main menu and loading screen).
2. **Double‑click the *"AI First Officer Bridge"* shortcut on your Desktop**
   (created by `INSTALL.bat`; the same as running `bridge/start-bridge.bat`).
   This:
   - starts the bridge, and
   - opens the AI First Officer website in your browser automatically.
3. **Leave the bridge window open** for the whole flight. Minimize it if you
   like, but don't close it — closing it stops the data.

The bridge window will print something like:

```
============================================
   AI First Officer - SimConnect Bridge
============================================
WebSocket Server starting on port 8080...
[SimConnect] Connected to MSFS successfully!
  Bridge is RUNNING. Keep this window open.
```

> If you start the bridge **before** MSFS is ready, that's fine — it retries the
> connection every 5 seconds and connects as soon as the sim is in the cockpit.

---

## 5. Confirm it's connected

In the website, look at the **SimConnect** status indicator (top of the app):

| Indicator | Meaning |
|---|---|
| 🟢 **Green** | Bridge running **and** MSFS connected — live data is flowing. |
| 🟡 **Connecting / spinner** | The app is trying to reach the bridge. |
| 🔴 **Red** | The bridge isn't running, or MSFS isn't in the cockpit yet. |

When it's green, your live speed, altitude, heading and flight phase appear on
the dashboard and the copilot starts using real telemetry.

---

## 6. Push‑To‑Talk

The bridge watches your keyboard globally so you can speak to the copilot
**without alt‑tabbing out of the sim**.

- **Default key: Right Alt.** Hold it to talk, release to send.
- You can rebind it in the website under **Settings → Push To Talk Key** —
  click the field, then press the key you want.
- Because this needs to read the keyboard system‑wide, some antivirus tools may
  ask for permission the first time — allow it.

---

## 7. Running the website on a different PC (optional)

By default everything is on one PC, and the app connects to the bridge at
`127.0.0.1` (this same machine). If you run the **browser on a different
computer** from MSFS (e.g. a tablet or second monitor PC):

1. Find the **LAN IP** of the sim PC (run `ipconfig` → IPv4 Address, e.g.
   `192.168.1.50`).
2. In the website, open **Settings → SimConnect Bridge IP** and enter that IP.
3. On the sim PC, allow **port 8080** through Windows Firewall (the first time
   the bridge runs, Windows may prompt — choose **Allow access** on private
   networks).
4. Both devices must be on the **same local network**.

> The bridge always talks to MSFS on the local machine, so the **bridge must run
> on the same PC as the sim** — only the browser can be elsewhere.

---

## 8. Updating the bridge

1. Download the latest package from the app's **Settings → SimConnect Bridge**.
2. Extract it over (or replace) your old folder. That's it — the new bundle
   already includes the matching runtime and dependencies.

---

## 9. Uninstalling

The bridge doesn't write to the Windows registry or install a service — it's
self‑contained (it doesn't even install Node.js). To remove it, just **delete the
folder** you extracted.

---

## 10. Troubleshooting

| Symptom | Likely cause & fix |
|---|---|
| Website shows a **red** SimConnect dot | The bridge window isn't open, **or** MSFS isn't loaded into the cockpit yet. Start `start-bridge.bat` and make sure you're flying. |
| Won't connect to MSFS | Make sure you're on **Windows** and MSFS is running past the main menu. Restart MSFS, then restart the bridge. |
| Windows SmartScreen / antivirus warning on first run | The bundled `AIFOBridge.exe` is just the official Node runtime. Choose **More info → Run anyway**, and allow it through your antivirus/firewall. |
| **"Port 8080 is already in use"** / `EADDRINUSE` | Another copy of the bridge is already running, or another app is using port 8080. Close any extra bridge windows and start it just once; if unsure, reboot and run `start-bridge.bat` again. (The website always connects on port 8080.) |
| Push‑To‑Talk does nothing | Allow the bridge through your antivirus, and confirm the PTT key in **Settings** matches (default **Right Alt**). |
| Browser on another PC can't connect | Enter the sim PC's LAN IP in **Settings → SimConnect Bridge IP**, allow **port 8080** in Windows Firewall, and confirm both are on the same network (see §7). |
| Data is connected but **voice/AI doesn't respond** | That's a separate system (OpenAI), not the bridge. The bridge only provides telemetry. |

To read detailed bridge logs, open **Command Prompt** in the bridge folder and
run `AIFOBridge.exe bridge.js` directly — every connection and error is printed there.

---

## 11. FAQ & notes

- **Does the bridge send my data anywhere?** It opens a local WebSocket on your
  own PC (port 8080) and sends MSFS telemetry to the AI First Officer website
  page you have open. It does not upload your flight to anyone else.
- **Do I need to install anything?** No — Node and all dependencies are bundled.
  Each flight you only run `start-bridge.bat` (§4).
- **Can I run it on Mac/Linux?** No. SimConnect is Windows‑only, so the bridge
  must run on the Windows PC running MSFS.
- **It worked yesterday, red dot today.** Open MSFS first and get into the
  cockpit, then start the bridge — order matters, though the bridge will also
  catch up on its own within a few seconds.

---

*Need help? In the app go to **Settings → SimConnect Bridge**, or read this guide
online at <https://copilot.atlantic-iot.com/simbridge.html>.*
