Skip to content

Troubleshooting

Jump to bottom
P0k3sm0t edited this page May 26, 2026 · 2 revisions

Troubleshooting

Use this page when something is not working and you need a quick path to the likely cause.

App will not start

Start with the launcher or manual Python command for your operating system.

Windows manual launch:

python app.py

Linux/macOS manual launch:

python3 app.py

Read the console error. Install requirements if needed:

python -m pip install -r requirements.txt

Check whether another copy is already using the same port.

If the Linux/macOS launcher says Permission denied, run:

chmod +x start-ray5-pilot.sh
./start-ray5-pilot.sh

If Linux reports that pip or ensurepip is missing inside .venv, install venv support, remove the broken .venv, and run again:

sudo apt update
sudo apt install python3-venv python3-pip
rm -rf .venv
./start-ray5-pilot.sh

Dashboard opens but Ray5 is offline

Check:

  • Ray5 is powered on.
  • Ray5 IP is correct in Settings.
  • Computer and Ray5 are on the same network.
  • Ray5 native ESP32 page opens in a browser.
  • WebSocket settings are correct.

Known live status values:

Port: 8849
Path: /
Subprotocol: arduino

SD files do not show

Check:

  • Status card says Ray5 HTTP reachable.
  • Ray5 is idle.
  • SD card is inserted and readable by the Ray5.
  • SD auto-refresh is not paused due to busy state or safety lockout.
  • SD file actions are enabled in Settings if needed.

Upload fails

Check:

  • Ray5 SD card is installed.
  • Ray5 is not busy.
  • Filename is not too long or strange.
  • Upload settings are not rewriting in a way the firmware dislikes.
  • Try preserve original file content.

File rejected as 3D-printer G-code

Open the file and check for commands such as:

M104
M109
M140
M190
G1 E...

Those are common 3D-printer commands. Export laser G-code instead.

Frame is wrong

Check:

  • G-code origin in design software.
  • Workspace min/max in Settings.
  • File bounds shown by Ray5 Pilot.
  • Whether the file uses unusual G92 coordinate changes.

Manual controls do not move

Check:

  • Status card state.
  • Alarm state.
  • Connection state.
  • Unlock/Clear Alarm if appropriate.
  • Jog step/feed values.

Camera does not work

Check:

  • Camera URL in Settings.
  • Camera stream opens outside Ray5 Pilot.
  • Click Test Camera.
  • Click Reload Camera.
  • Confirm video is enabled.

If live video works but snapshots fail, confirm the app was fully restarted after updates. Newer camera capture uses the live preview frame first when available, then falls back to the configured camera method.

If ffmpeg errors mention authentication, check the RTSP username/password and special characters. Ray5 Pilot keeps the configured URL unchanged and handles fallback encoding at runtime, but the camera must still accept the credentials.

Overlay is wrong

If it is skewed or warped, redo Camera Overlay Calibration.

If it is the right shape but shifted, use Camera Overlay Alignment.

If it imports at the wrong size in laser software, check final size and DPI.

Timelapse fails

Check:

  • Timelapse enabled in Settings.
  • Camera works.
  • Snapshot interval is valid.
  • Disk folder is writable.
  • Recoverable Sessions has frames available.

If the live preview is active, timelapse should be able to use the live frame cache. If timelapse falls back to ffmpeg or OpenCV, check camera URL, RTSP transport, and ffmpeg availability.

Safety lockout appears

Do not clear immediately. Physically check the Ray5 first.

Clear only after confirming:

  • The laser is off.
  • The machine is idle or safe.
  • The Ray5 screen agrees with what you expect.

Update fails

Ray5 Pilot only installs trusted GitHub Release ZIP assets with checksum verification. If update fails:

  • Try again later.
  • Download the release manually.
  • Do not install a failed checksum download.
  • Start Ray5 Pilot manually if it did not restart.

What to include in a bug report

Include:

  • Ray5 Pilot version.
  • What page failed.
  • What button/action you clicked.
  • Screenshot of the Status card.
  • Relevant console log lines.
  • Whether the native Ray5 ESP32 page works.
  • Do not share private camera URLs, passwords, Wi-Fi details, or full unredacted config files.

Clone this wiki locally