OpenFlight User Guide: Running the Simulator

This guide provides step-by-step instructions on how to configure and run the OpenFlight flight simulator.

1. Prerequisites:

• Julia: Ensure you have Julia installed on your system. You can download it from julialang.org. The simulator requires specific Julia packages (like HTTP, WebSockets, YAML, JSON, etc.). The program is designed to automatically install these if they are missing the first time you run it.

• Web Browser: A modern web browser (like Edge, Chrome, or Firefox) is required to view the 3D simulation frontend.

• Project Files: You need the complete OpenFlight project folder structure as provided.

2. Configuration (Optional):

Before running, you can customize the simulation by editing the default_mission.yaml file located in the main project directory (✈_OPENFLIGHT). Key parameters you might want to change include:

• aircraft_name: Change this to the filename (e.g., piper_pa18.yaml) of a different aircraft model located in the 🏭_HANGAR/📜_Aero_data/ directory.

• initial_velocity: Starting airspeed in meters per second.

• initial_altitude: Starting altitude in meters.

• start_flight_data_recording_at: Simulation time (in seconds) to begin recording flight data.

• finish_flight_data_recording_at: Simulation time (in seconds) to stop recording flight data.

• scenery_complexity: Set to 0 (checkered ground), 1 (basic terrain/runway), 2 (adds buildings), or 3 (adds trees, lighthouses, turbines, dynamic sea). Higher numbers require more graphical resources.

• show_force_vectors, show_velocity_vectors, show_trajectory: Set to "true" or "false" (as strings) to toggle these visualization aids.

3. Running the Julia Backend:

• Open a Julia terminal or IDE.

• Navigate to the main project directory (✈_OPENFLIGHT). You can use the cd("path/to/your/✈_OPENFLIGHT") command within Julia.

• Run the main script by executing:
  include("OpenFlight.jl")
  
  

• What to Expect:

• The script will first check for required Julia packages. If any are missing, it will attempt to install them automatically (this only happens on the first run).

• It will then load the default_mission.yaml configuration.

• It will find an available network port (usually starting from 8000) for the WebSocket connection and print the selected port number.

• It will synchronize parameters from the mission file to the JavaScript frontend.

• It will attempt to automatically open the simulation frontend (✅_front_end_and_client.html) in your default web browser (or Edge/Chrome/Firefox).

• Finally, it will print messages indicating the WebSocket server is running and waiting for a connection (e.g., "Starting WebSocket server on port 8000...", "Server running. Press Ctrl+C to stop.").

4. Using the Simulator Frontend:

• Automatic Launch: If the Julia script successfully launched your browser, the simulation should load automatically.

• Manual Launch: If the browser doesn't open automatically, manually open the file src/🟡JAVASCRIPT🟡/✅_front_end_and_client.html within the project structure using your web browser.

• Connection: Once the page loads, the JavaScript frontend will connect to the Julia WebSocket server. You should see the 3D environment and the aircraft.

• Controls:

• Keyboard: (Default mappings - check 3.1_🕹_joystick_gamepad.js or the pause menu for current settings)

• Pitch: A / Q

• Roll: O / P

• Yaw: K / L

• Thrust: Keys 1-9 (10% increments)

• Camera Change: I / U / Y / T

• Pause/Resume: Spacebar

• Reset Simulation: R

• Gamepad/Joystick: Connect a compatible controller before launching. Controls typically map to:

• Pitch/Roll: Right Stick

• Yaw/Throttle: Left Stick / Joystick Twist

• Camera/Pause/Reset: Varies by controller (check pause menu).

• Pause Menu: Pressing Spacebar (or the gamepad pause button) pauses the simulation and displays a controls help panel.

• Loading Custom Aircraft:

• Click the "Load Aircraft (.glb)" button in the top-left data panel.

• Select a .glb 3D model file from your computer.

• The simulator will attempt to load the model. Predefined transformations (scale, rotation, position offsets) and light/propeller placements are applied based on specific filenames (e.g., piper_pa18.glb, pc9.glb). If the filename isn't recognized, default transformations are used.

5. Stopping the Simulation:

• Go back to the Julia terminal where you ran OpenFlight.jl.

• Press Ctrl+C.

• Confirm if prompted. This will shut down the Julia WebSocket server.

• You can then close the browser tab running the frontend.

6. Simulation Output:

• If flight data recording was active (based on the time interval set in default_mission.yaml), a CSV file containing detailed telemetry will be saved in the 📊_Flight_Test_Data subfolder within the main project directory.

• The filename will include a timestamp, e.g., simulation_data_YYYY-MM-DD_@_HHh-MM-SS.csv.

Enjoy your flight!