Launcher Options

Launcher Options

This page explains the ways to start Ray5 Pilot on Windows, Linux, and macOS.

All launch methods start the same app. The launcher only changes how Ray5 Pilot is opened and how the Python environment is prepared.

Option 1: Manual Python launch

Use this when troubleshooting because the console stays visible.

Open Command Prompt or PowerShell inside the Ray5 Pilot folder and run:

python app.py

Then open:

http://127.0.0.1:5050

Keep the terminal window open. Closing it stops Ray5 Pilot.

Option 2: BAT launcher

The release includes:

Start_Ray5_Pilot.bat

Use this for normal Windows startup when you want a simple double-click launcher.

The BAT launcher is useful because it shows startup errors in a console window. If the browser does not open or the app fails to start, read the BAT window first.

Option 3: EXE launcher

Some releases include:

Ray5 Pilot.exe

The EXE is a convenience launcher. It does not replace the Ray5 Pilot source files and does not change how the laser is controlled.

Option 4: Linux/macOS shell launcher

The release includes:

start-ray5-pilot.sh

Use this for Linux or macOS startup from a terminal. From inside the Ray5 Pilot folder, make the script executable if needed:

chmod +x start-ray5-pilot.sh

Then run:

./start-ray5-pilot.sh

The shell launcher creates .venv if needed, checks that pip works inside the virtual environment, installs requirements, creates config.json from config.example.json if missing, opens the web UI when possible, and starts app.py.

On Debian, Ubuntu, Zorin, Linux Mint, and similar systems, Python may be installed without venv support. If the launcher reports that pip or ensurepip is missing, install venv support first:

sudo apt update
sudo apt install python3-venv python3-pip

If a broken .venv was already created, remove it and run the launcher again:

rm -rf .venv
./start-ray5-pilot.sh

Option 5: Linux/macOS manual Python launch

Use this when troubleshooting on Linux or macOS because the terminal output stays visible. From inside the Ray5 Pilot folder, run:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python app.py

Then open:

http://127.0.0.1:5050

If you do not want to use a virtual environment, you can run python3 app.py directly after installing requirements, but a .venv is recommended so Ray5 Pilot dependencies stay isolated from the system Python.

Desktop shortcut

You can create a desktop shortcut to the BAT, EXE, or shell launcher. Keep the shortcut pointing to the launcher inside the Ray5 Pilot folder so relative paths continue to work.

How to read launcher problems

Symptom	Meaning	Fix
Browser opens but page fails	App may not have started	Check the console window
python or python3 not found	Python is missing from PATH	Install Python or use full Python path
.venv/bin/python: No module named pip	Broken Linux/macOS virtual environment	Install python3-venv, remove .venv, rerun launcher
Permission denied on .sh	Shell launcher is not executable	Run chmod +x start-ray5-pilot.sh
Module import error	Requirements are missing	Run pip install -r requirements.txt
Port already in use	Another Ray5 Pilot copy is running	Close the old console or change port
Window opens then closes	Startup crashed	Start with manual Python launch to see the error

Troubleshooting

If Ray5 Pilot will not start, use manual Python launch first. It gives the clearest error output.

If two browser tabs open, check whether both the launcher and the app are opening the browser. Use only one auto-open behavior.

If the app starts but cannot reach the Ray5, the launcher is not the problem. Go to Status Card, Settings, and Troubleshooting.