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 operator-confirmed 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 is complete as an evidence baseline. The settings and device screenshots, bundle, exported preferences, closed-application local settings and three explicitly operator-verified projects are preserved and analyzed. The operator confirmed a 110 mm lens; other local test projects remain unverified. See the local settings acquisition and control-machine observation.

Three operator-verified projects now establish project-level frequency and QPulseWidth serialization. Correlation with the running LightBurn 2.1.03 UI establishes raw Hz to displayed kHz and direct ns pulse width; see the verified-project analysis. Missing pulse width still requires explicit resolution before executable import.

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 Windows build environment is installed and the pinned package has passed non-executing verification; the packaged no-device workflow test remains outstanding. See the Windows build record, Phase 0 status and Rayforge GUI preflight.

The first M3 deliverable is also available as a deliberately non-executable hardware-research protocol. Its public template and validator can establish only ready_for_review; they never authorize USB access or controller commands.

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 accepted route is a Rayforge JCZ addon with BalorMK retained as the pinned behavioral oracle and reference boundary. Packaged interaction remains an M1 release gate, not an architecture-decision gate; see ADR 0002.

Next steps

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

1. prepare the checksummed acceptance kit for the built and verified Windows Rayforge artifact;
2. run and record the packaged no-device desktop interaction checklist;
3. promote only evidence-backed vector MOPA imports through the existing fail-closed review boundary;
4. complete and independently review the M3 hardware-protocol template before seeking separate approval for 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

• Current continuation brief
• Project charter
• Product and research roadmap
• MOPA workbench UX requirements
• Current Phase 0 status
• Open-source reuse landscape
• LightBurn-to-Rayforge UX capability map
• Rayforge layer visibility and output spike
• Rayforge material-recipe model spike
• M1 no-device build and acceptance checkpoint
• Proposed Rayforge/BalorMK reuse decision
• Accepted project license and upstream boundary
• Upstream contract and license audit
• Live USB enumeration
• LightBurn device-export analysis
• LightBurn control-machine observation
• Sanitized machine profile
• 110/300 configuration comparison
• Data handling policy
• LightBurn collection checklist
• Repository boundary decision

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.

The Pirate Ray's original code and documentation are available under the MIT License. Bundled or referenced third-party material retains its own license and attribution requirements; see third_party/licenses/ and ADR 0003.