ForeFlight-Shirley Bridge

A bridge application that connects flight simulators using the ForeFlight Protocol to the Shirley protocol for flight instruments.

Fly Shirley - AI Copilot, Trainer and Assistant (https://airplane.team/)

Overview

This application allows any flight simulator that supports ForeFlight's UDP protocol to connect to Shirley-compatible flight instruments. It acts as a protocol converter and data bridge between the two systems.

It was developed to be used with Aerofly FS4 Flight Simulator from IPACS (TM).

Features

• Receives UDP data packets from flight simulators (on port 49002) using ForeFlight's protocol
• Hosts a WebSocket server (on port 2992) using Shirley's protocol
• Performs all necessary unit conversions (meters to feet, m/s to knots, etc.)
• Provides both a GUI mode and CLI mode for operation
• Real-time display of flight data in the GUI

Requirements

• Python 3.7 or higher
• Required packages:
  • websockets (installed via pip)
  • Standard library modules: asyncio, tkinter, socket, json, threading, logging

Installation

1. Clone this repository:

git clone https://github.com/yourusername/ForeFlight-Shirley-Bridge.git
cd ForeFlight-Shirley-Bridge

2. Install the required dependencies:

pip install -r requirements.txt

Note: tkinter is usually included with Python installation. If not available, install it using your system package manager:

• Ubuntu/Debian: sudo apt-get install python3-tk
• macOS: Included with Python from python.org
• Windows: Included with standard Python installation

Usage

GUI Mode (Default)

Run the application with the graphical interface:

python ForeFlight-Shirley-Bridge.py

The GUI displays:

• Connection status (red/green indicator)
• Real-time flight data (position, altitude, speed, attitude)
• Server information (UDP and WebSocket endpoints)

CLI Mode

Run the application in command-line interface mode:

python ForeFlight-Shirley-Bridge.py --cli

Advanced Configuration

Command Line Arguments

# Run with custom ports
python ForeFlight-Shirley-Bridge.py --cli --udp-port 50000 --ws-port 3000

# Run with debug logging
python ForeFlight-Shirley-Bridge.py --cli --log-level DEBUG

# Save logs to file
python ForeFlight-Shirley-Bridge.py --cli --log-file bridge.log

# Custom WebSocket configuration
python ForeFlight-Shirley-Bridge.py --ws-host localhost --ws-port 8080 --ws-path /api/v2

# View all options
python ForeFlight-Shirley-Bridge.py --help

Environment Variables

You can also configure the bridge using environment variables:

# Linux/macOS
export FF_SHIRLEY_UDP_PORT=50000
export FF_SHIRLEY_WS_PORT=3000
export FF_SHIRLEY_LOG_LEVEL=DEBUG
export FF_SHIRLEY_LOG_FILE=bridge.log
python ForeFlight-Shirley-Bridge.py --cli

# Windows (PowerShell)
$env:FF_SHIRLEY_UDP_PORT=50000
$env:FF_SHIRLEY_WS_PORT=3000
python ForeFlight-Shirley-Bridge.py --cli

Available environment variables:

• FF_SHIRLEY_UDP_PORT - UDP port for ForeFlight data (default: 49002)
• FF_SHIRLEY_WS_HOST - WebSocket server host (default: 0.0.0.0)
• FF_SHIRLEY_WS_PORT - WebSocket server port (default: 2992)
• FF_SHIRLEY_WS_PATH - WebSocket server path (default: /api/v1)
• FF_SHIRLEY_LOG_LEVEL - Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
• FF_SHIRLEY_LOG_FILE - Optional log file path

Protocol Details

ForeFlight Input Format

The bridge expects ForeFlight-compatible UDP packets on port 49002:

• XGPS: XGPS<sim_name>,<longitude>,<latitude>,<altitude_msl_meters>,<track_true_north>,<groundspeed_m/s>
• XATT: XATT<sim_name>,<true_heading>,<pitch_degrees>,<roll_degrees>

Reference: ForeFlight Connect API

Shirley Output Format

Data is served via WebSocket (ws://0.0.0.0:2992/api/v1) in JSON format:

{
  "position": {
    "latitudeDeg": float,
    "longitudeDeg": float,
    "mslAltitudeFt": float,
    "gpsGroundSpeedKts": float
  },
  "attitude": {
    "rollAngleDegRight": float,
    "pitchAngleDegUp": float,
    "trueHeadingDeg": float
  }
}

Reference: Sim Interface - Airplane-Team FlyShirley

Simulator Configuration

Aerofly FS4 Setup

Aerofly FS4 supports the ForeFlight protocol natively. To enable it:

1. Open Aerofly FS4
2. Go to Settings → General
3. Enable "Send Flight Data to ForeFlight" or similar option
4. The simulator will broadcast UDP packets on port 49002 (default)
5. Start the bridge application
6. Start flying in Aerofly FS4

The bridge will automatically detect and process the data.

Other Simulators

Any flight simulator that supports the ForeFlight protocol can work with this bridge. Common simulators include:

• X-Plane: Install the ForeFlight Link plugin
• Microsoft Flight Simulator: Use third-party ForeFlight bridge tools
• Prepar3D/FSX: Install FSUIPC with ForeFlight support

Troubleshooting

Issue: "No data received" or "Disconnected" status

Possible causes and solutions:

1. Simulator not sending data

   • Verify ForeFlight protocol is enabled in your simulator settings
   • Check that the simulator is running and in flight
   • Restart the simulator after enabling ForeFlight support

2. Port conflict

   • Ensure no other application is using port 49002 (UDP)
   • Check with: netstat -an | grep 49002 (Linux/macOS) or netstat -an | findstr 49002 (Windows)
   • Use a different port: python ForeFlight-Shirley-Bridge.py --cli --udp-port 50000

3. Firewall blocking

   • Allow UDP port 49002 in your firewall
   • Allow the Python executable through your firewall
   • On Windows: Check Windows Defender Firewall settings

4. Network interface issues

   • If running simulator on a different computer, use --ws-host to specify the correct IP
   • Ensure both devices are on the same network

Issue: Shirley/WebSocket client cannot connect

Possible causes and solutions:

1. Port not accessible

   • Verify WebSocket server is running: check the console logs
   • Ensure port 2992 (default) is not blocked by firewall
   • Try connecting to ws://localhost:2992/api/v1 first

2. Wrong URL or path

   • The default WebSocket URL is ws://0.0.0.0:2992/api/v1
   • Verify you're using the correct path (/api/v1)
   • Check console output for the actual WebSocket URL being served

3. Network binding issues

   • Try binding to localhost only: --ws-host localhost
   • Or bind to a specific IP: --ws-host 192.168.1.100

Issue: Data validation errors in logs

Possible causes:

• Corrupted or invalid data from the simulator
• The bridge includes data validation and will reject invalid values:
  • Latitude: -90° to 90°
  • Longitude: -180° to 180°
  • Altitude: -500m to 50,000m
  • Pitch: -90° to 90°
  • Roll: -180° to 180°
  • Ground speed: 0 to 350 m/s (~680 knots)

Solution: Check simulator data quality. Use --log-level DEBUG to see detailed validation messages.

Issue: High CPU usage

Possible causes and solutions:

1. Too many log messages

   • Reduce logging level: --log-level WARNING or --log-level ERROR
   • Default is INFO which is reasonable for most cases

2. Debug mode enabled

   • Don't use --log-level DEBUG in production
   • DEBUG mode logs every single packet

Getting Help

If you encounter issues:

1. Run with debug logging: python ForeFlight-Shirley-Bridge.py --cli --log-level DEBUG --log-file debug.log
2. Check the log file for error messages
3. Verify your simulator is actually sending ForeFlight protocol data
4. Open an issue on GitHub with:
   • Your Python version (python --version)
   • Your operating system
   • Simulator name and version
   • Debug log file
   • Exact command line used

Statistics and Monitoring

The bridge tracks the following statistics (visible in CLI mode with INFO or DEBUG logging):

• UDP Server: Packets received, XGPS count, XATT count, error count
• WebSocket Server: Total connections, messages sent, send errors, active connections
• Data Validation: Invalid data warnings (when data is out of acceptable ranges)

To view detailed statistics, run with DEBUG logging:

python ForeFlight-Shirley-Bridge.py --cli --log-level DEBUG

License

This software is released under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Copyright (c) 2025 Juan Luis Gabriel