Skip to content

Troubleshooting

Jump to bottom
P0k3sm0t edited this page May 23, 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

  1. Start with manual Python launch:
python app.py
  1. Read the console error.
  2. Install requirements if needed:
pip install -r requirements.txt
  1. Check whether another copy is already using the same port.

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.

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.

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