Skip to content

FAQ

Jump to bottom
P0k3sm0t edited this page May 18, 2026 · 6 revisions

Ray5 Pilot FAQ

This page answers common Ray5 Pilot questions.

Ray5 Pilot is a local web controller for the Longer Ray5 laser engraver using the ESP3D-style HTTP/WebSocket interface.

v1.1.2 Questions

Why is it called Firmware Settings instead of Machine Settings?

Firmware Settings reads, backs up, and edits Ray5/GRBL controller $ settings stored in the controller firmware. It was previously labeled Machine Settings, but Firmware Settings is clearer and avoids confusion with Ray5 Pilot's normal Settings page.

What is communication-loss safety lockout?

It is a conservative safety state that appears if Ray5 Pilot loses communication while a job may still be active or recently started. Verify the Ray5 screen and machine state before clearing it.

Why did SD auto-refresh stop during a job?

SD auto-refresh pauses during active/busy states such as Run, Hold, Jog, Door, and communication-loss safety lockout. This avoids repeated SD list requests while the controller may be busy.

Why does Pause or Resume work even if the controller response is unusual?

Pause and Resume use GRBL real-time commands: ! and ~. These commands may not return normal ok text from the Ray5/ESP3D HTTP endpoint even when the machine responds correctly.

Why does timelapse wait after a job ends?

The Timelapse final frame delay lets the laser head finish parking before Ray5 Pilot captures one last frame. Set the delay to 0 for immediate stop/build behavior.

Why did a loaded timelapse disappear after I deleted it?

If the currently loaded timelapse is deleted, Ray5 Pilot clears the Video / Camera card so the browser does not keep replaying stale cached media.

General

What is Ray5 Pilot?

Ray5 Pilot is a local web controller for Longer Ray5 laser engravers.

It provides:

  • Dashboard controls
  • Camera preview
  • Camera overlay tools
  • Timelapse support
  • Imported Jobs
  • Watched folder auto-import
  • SD Card Files management
  • Manual Controls
  • Firmware Settings
  • Live Console
  • Update tools
  • Workflow helpers for compatible laser software

Is Ray5 Pilot a design program?

No.

Ray5 Pilot does not replace laser design software.

Use your preferred laser software to design and generate laser G-code, then use Ray5 Pilot to import, upload, frame, run, monitor, and manage files.

What laser software can I use with Ray5 Pilot?

Ray5 Pilot is intended to work with compatible laser G-code.

You may be able to use G-code generated by:

  • LightBurn
  • LaserGRBL
  • LaserWeb
  • OpenBuilds CAM
  • Inkscape laser extensions
  • Other GRBL-compatible laser software

The important requirement is that the final file is compatible laser G-code for your Ray5.

Does Ray5 Pilot support other laser brands?

Ray5 Pilot is built around the Longer Ray5 ESP3D-style HTTP/WebSocket behavior.

Other machines might work only if they expose compatible endpoints and GRBL-style behavior. Support for other brands is not guaranteed.

Setup

What URL do I open?

Default local URL:

http://127.0.0.1:5050

What Ray5 ports are commonly used?

Common Longer Ray5 values:

HTTP port: 8848
WebSocket port: 8849

Should I bind Ray5 Pilot to 0.0.0.0?

Only if you understand the risk.

Default:

127.0.0.1

means local computer only.

Binding to:

0.0.0.0

allows other LAN devices to access Ray5 Pilot.

Do not expose Ray5 Pilot to the internet. No authentication is currently included.

Should I upload config.json to GitHub?

No.

config.json is local/private.

It may contain:

  • Ray5 IP address
  • camera URLs
  • camera credentials
  • local paths
  • personal settings

Keep it private.

Dashboard

Why does the Status card show Offline?

Common causes:

  • Ray5 is powered off.
  • Ray5 IP address changed.
  • Ray5 is on a different network.
  • HTTP port is wrong.
  • WebSocket port is wrong.
  • Ray5 is not ready yet.
  • Wi-Fi/extender isolation problem.

Check:

Settings → Ray5 Network
Dashboard → Status / System Check

Why does Camera Test Passed show Unknown?

Ray5 Pilot marks camera health based on backend-confirmed real camera operations.

It may show Unknown if:

  • camera has not been tested yet
  • live stream has not produced a real frame
  • camera is disabled
  • camera URL was just changed
  • no snapshot/test has been performed

Try Test Camera or take a snapshot.

Why does the Status card show an update?

Ray5 Pilot checks the GitHub main-branch VERSION file once at startup.

The Dashboard Status card may show:

Update: Up to date
Update: Update available: x.x.x
Update: Unable to check

This is informational only. To update, go to:

Settings → Support

Imported Jobs

What are Imported Jobs?

Imported Jobs are local Ray5 Pilot job files.

They are stored in the local imported jobs folder and can be:

  • framed
  • uploaded to SD
  • uploaded and run
  • deleted locally

What is the watched folder?

The watched folder lets you save G-code directly from laser software into Ray5 Pilot.

Workflow:

Laser software
→ save/export G-code to watched folder
→ Ray5 Pilot auto-imports
→ Imported Jobs

Why did my file get rejected?

Ray5 Pilot includes a 3D-printer G-code safety scanner.

It may reject files containing:

M104
M109
M140
M190
G1 E...

Re-export the file as laser G-code.

SD Card Files

What is the difference between Imported Jobs and SD Card Files?

Imported Jobs = local files inside Ray5 Pilot
SD Card Files = files stored on the Ray5 SD card

Why does the SD file list not load?

Check:

  • Ray5 is powered on.
  • SD card is inserted.
  • Ray5 HTTP reachable is Yes.
  • PAGEID captured is Yes.
  • Click Refresh SD Files.

Why is my file hard to find on the Ray5 screen?

The Ray5 touchscreen may not display long filenames clearly.

For screen use, keep full filenames:

24 characters or less, including extension

Enable:

Settings → Upload → Auto-shorten long Ray5 filenames

if needed.

Uploads and Filenames

Can Ray5 Pilot upload long filenames?

Yes, but the Ray5 screen may not display them clearly.

Ray5 Pilot can shorten uploaded filenames for screen compatibility.

Should I enable Preserve original file content?

Usually yes.

Recommended:

Settings → Upload → Preserve original file content

This uploads G-code bytes without rewriting the file.

Should I enable Convert M4 to M3?

Usually no.

Only enable it if your firmware or workflow specifically requires it.

Camera and Overlay

What is latest_raw.jpg?

latest_raw.jpg is the raw camera snapshot.

What is latest.jpg?

latest.jpg is the processed/corrected overlay image.

Use latest.jpg as the reference image in laser software.

Why does my overlay not line up?

Possible causes:

  • calibration points are wrong
  • work area size is wrong
  • source X/Y offset needs adjustment
  • scale needs tuning
  • fine rotation needs tuning
  • reference image is not scaled correctly in laser software

Use the Camera Overlay Configuration and Setup Guide.

Should the overlay image be output/engraved?

No.

When using the overlay as a reference image in laser software, set that layer/image so it is not output.

Timelapse

Does timelapse require a camera?

Yes.

Timelapse depends on a working camera or snapshot source.

What is the difference between manual and job timelapse?

Manual timelapse starts/stops when you click the dashboard buttons.

Job timelapse can be armed by:

Imported Upload + Run
SD Card Files → Start

and follows Ray5 state:

Run  = capture
Hold = pause
Idle = stop/save

Why did no MP4 get created?

MP4 creation may require ffmpeg.

If ffmpeg is missing, Ray5 Pilot should keep the captured frames and show/log a warning.

Manual Controls

What does Center do?

Center moves the laser head to the configured center of the work area.

Example:

390 x 360 work area
Center = X195 Y180

What does Go To Preset do?

Go To Preset moves to a configured X/Y location.

Configure it in:

Settings → Manual Controls

Are diagonal moves supported?

Yes.

Diagonal buttons send one combined XY jog command.

Firmware Settings

What does the Firmware Settings page do?

It reads and edits Ray5/GRBL controller settings.

It can:

  • read settings with $$
  • display known settings
  • download a raw backup
  • save changed settings
  • validate safe $number=value commands

Should I change Firmware Settings?

Only if you understand the setting.

Changing firmware settings can affect:

  • motion
  • limits
  • homing
  • acceleration
  • travel
  • laser behavior

Always download a backup first.

How do I restore a setting?

Use your downloaded backup.

Find the original line, such as:

$130=400.000

Then enter that value back into the Firmware Settings page and save.

Live Console

What can I send in the Live Console?

Safe diagnostic examples:

$$
$G
$I
?
M5

Motion or laser commands can be dangerous.

Should I paste a full G-code job into the console?

No.

Use Imported Jobs or SD Card Files instead.

Should I use console commands to change settings?

Use the Firmware Settings page instead whenever possible.

It provides backup, validation, and safer changed-only saves.

Updates

How does Check for Updates work?

It compares the local VERSION file with:

https://raw.githubusercontent.com/P0k3sm0t/Ray5-Pilot/main/VERSION

Does Check for Updates install anything?

No.

It only checks the version.

What does Download Latest Source do?

It opens/downloads:

https://github.com/P0k3sm0t/Ray5-Pilot/archive/refs/heads/main.zip

It does not install automatically.

What does Update Ray5 Pilot do?

When an update is available, the Settings Support card can show:

Update Ray5 Pilot

After user confirmation, Ray5 Pilot:

  • starts updater.py
  • shuts down app.py
  • backs up current source files
  • downloads main.zip
  • copies allowlisted files
  • preserves config/runtime folders
  • optionally runs pip install
  • restarts app.py
  • writes update status/logs

Does the updater preserve config.json?

Yes. The updater should preserve config.json.

Does the updater preserve runtime folders?

Yes. It should preserve folders like:

logs/
camera_captures/
timelapse/
imported_jobs/
watched_gcode/
rejected_jobs/

Should I update while a job is running?

No.

Ray5 Pilot should block updates if the Ray5 appears to be in Run or Hold, but you should still manually confirm the laser is not running or paused.

Safety

Is Ray5 Pilot safe to expose to the internet?

No.

Do not expose Ray5 Pilot to the internet. No authentication is currently included.

Can Test Fire be dangerous?

Yes.

Test Fire emits laser light.

Use eye protection, safe material, short duration, low power, and fire safety.

Keep Test Fire disabled unless needed.

What should I do if something goes wrong?

  1. Use Stop Job if reachable.
  2. Use physical power cutoff if needed.
  3. Do not wait for software if there is a fire or unsafe laser output.
  4. Check logs and status after stopping.
  5. Do not resume until the cause is understood.

Getting Help

When reporting an issue, include:

  • Ray5 Pilot version
  • what page/card has the issue
  • what you clicked
  • screenshot if UI-related
  • console/log output
  • System Check Yes/No values
  • whether Ray5 is online/offline
  • camera type/URL style, with credentials removed
  • whether it happens after restart

Do not post real passwords, tokens, private camera URLs, or full credentials.

Clone this wiki locally