The Pirate Ray

The Pirate Ray is Makerspace Næstved's clean-room effort to build an open-source, safe desktop workflow for its laser equipment. The first target is the JPT 100 W E2/M7 MOPA fiber laser with a JCZ/EZCAD2-compatible controller and the currently assumed 110 x 110 mm lens.

The destination is the useful core of a LightBurn-like workflow: import or create geometry, assign operations and MOPA parameters, preview and validate the job, and eventually run it through independently auditable machine backends. The project is not trying to evade LightBurn licensing or copy its proprietary code or assets.

Where we are now

Phase 0 has established a reproducible evidence and research baseline:

the original installer material is preserved privately with SHA-256 manifests and Git LFS;
sanitized analysis covers the EZCAD2 installation, 110/300 configurations, correction data, material libraries, and relevant configuration files;
the physical controller has been passively identified by Windows as USBLMCV4, USB 9588:9899, with device revision descriptor 0005;
LightBurn 2.1.03 exports now confirm the JPT JCZFiber/LibUSB profile, 110 x 110 mm work area, Q-pulse-width support, and the exact serialized setting name QPulseWidth;
the Eduard X1550 export confirms a Ruida/Serial profile and 1500 x 1000 mm work area;
the development computer has no compatible controller driver installed;
no USB endpoint has been opened and no controller command, galvo movement, framing, marking, or laser output has occurred;
the public tests, provenance checks, leak guard, and clean-clone validation pass.

Phase 0 remains open while we collect known-working LightBurn projects, device screenshots, the closed-application preferences folder, machine photos, and operator notes directly from the actual control computer. The bundle and exported preferences are already preserved and analyzed.

The offline M1 reuse proofs now pass as one consolidated acceptance checkpoint: the Rayforge/MeerK40t path has deterministic mock encoding, fail-closed JCZ profile and parameter gates, list buffering, cancellation/recovery, layer and recipe semantics, and a transport-free workflow preview. The remaining gates are a private known-working .lbrn2 project and a reviewed Windows GTK runtime for the packaged no-device workflow test. See the Phase 0 status and Rayforge GUI preflight.

The important discovery

We do not need to begin with a blank-sheet LightBurn clone:

MeerK40t already includes BalorMK, an MIT-licensed JCZ/EZCAD2 galvo implementation with MOPA pulse width, frequency control, status/abort behavior, and a mock USB connection. Its source targets the same 9588:9899 USB identity observed on our controller.
Rayforge already supplies most of the modern desktop product: editor, projects, geometry, LightBurn import, material recipes, simulation, pre-flight checks, packaging, and an addon architecture. Its job model already represents frequency and pulse width.

The leading route is therefore either to use and improve MeerK40t directly or to build a Rayforge JCZ/Balor addon using the narrowest practical layer from BalorMK. This remains a proposed decision until the offline proofs in ADR 0002 have passed.

Next steps

The initial offline architecture spikes have passed. The next work remains hardware-free:

collect known-working .lbrn2 projects and the remaining screenshots, photos, preferences folder and operator notes;
obtain or produce a reviewed Windows Rayforge build artifact without installing a toolchain through this repository;
run and record the packaged no-device desktop interaction checklist;
accept, revise, or reject the proposed reuse architecture from evidence;
write and review a separate hardware protocol before any live controller communication.

An independent desktop application is the fallback only if both existing platforms fail concrete, documented requirements.

Repository boundary

This public repository contains source code, plans, decisions, tests, tools, and sanitized research. Raw machine data, serial numbers, LightBurn exports, and third-party material with unclear redistribution rights live in the separate private ThePirateRay-PrivateStash repository. Google Drive is not a project workspace or development destination.

Project map

Validation

The repository uses only Python's standard library for Phase 0 tooling:

python -m unittest discover -s tests -v
python scripts/check_public_repo.py .

The checks verify manifest integrity, public/private evidence contracts, disallowed binary types, private identifiers, local user paths, and other likely data leaks. They do not certify hardware safety.

Rayforge source and its Windows build stack are not vendored or downloaded by these checks. The exact upstream revision is recorded in upstreams/rayforge.json; run scripts/prepare_rayforge_build.ps1 explicitly to populate the ignored build cache. The repository does not install the Windows toolchain; bundle creation requires an already reviewed runtime.

Safety boundary

Simulation precedes equivalent hardware behavior.
Read-only precedes state change; state change precedes motion; motion precedes emission.
Machine, source, lens, correction profile, units, and parameter ranges must match before a job can be armed.
Unknown configuration or protocol fields are never guessed or replayed.
Vendor executables, DLLs, and drivers from the evidence snapshot are never run as part of analysis.

No project license has been selected yet. Until that decision is recorded, the contents are not offered under an open-source license.

7.2 KiB Raw Blame History