diff --git a/README.md b/README.md index 3e2dd40..128e6a1 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ separate private `ThePirateRay-PrivateStash` repository. Start with: - [Project charter](docs/project-charter.md) +- [Product and research roadmap](docs/roadmap.md) - [Data handling policy](docs/data-handling.md) - [LightBurn collection checklist](docs/collection/lightburn.md) - [Sanitized machine profile](docs/research/machine-profile.yaml) diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..f06a21c --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,221 @@ +# Product and research roadmap + +Last updated: 2026-10-17 + +## Destination + +The long-term destination is an open-source desktop application that can +prepare and run laser jobs on Makerspace Næstved's equipment. It should offer +the useful core of a LightBurn-like workflow without copying proprietary code, +assets, or license-protected behavior: + +1. import or create geometry; +2. arrange it on an accurate representation of the work area; +3. assign process parameters and reusable material presets; +4. preview the resulting tool path and estimated job behavior; +5. validate the job against a machine profile and safety policy; +6. connect, frame, and run through an independently implemented machine + backend. + +The first hardware target is the JPT 100 W E2/M7 MOPA fiber laser with its +JCZ/EZCAD2 controller and 110 x 110 mm lens. CO2 and additional laser backends +come later. The project is not considered successful merely because it can +emit a laser command: it must make unsafe or mismatched configurations hard to +use accidentally. + +## First useful product + +The first useful release is deliberately smaller than a LightBurn clone. It is +an offline **galvo job workbench** that can: + +- load a sanitized JPT machine profile; +- import a small, documented vector subset; +- represent layers and MOPA parameters without losing their units; +- show the field boundary, geometry, hatch, order, and an approximate path; +- reject out-of-field geometry and invalid parameter combinations; +- save a portable, versioned project document; +- run the complete workflow against a deterministic simulated controller. + +This produces useful application architecture and test fixtures before any +hardware command is possible. The real controller backend remains absent or +physically gated until its protocol and safety behavior are supported by +evidence. + +## What the installer snapshot gives us + +The collected installer snapshot establishes: + +- the JCZ/EZCAD2 controller and `Lmcv2u` driver family; +- vendor-declared USB VID/PID values, pending live confirmation; +- known-good 110 mm and 300 mm configuration trees; +- exact hashes for the opaque, lens-specific `markcfg7` profiles; +- a shared correction file and observable workspace differences; +- software, manuals, and configuration artifacts that can be studied offline. + +It does **not** yet establish: + +- the command sequence used to discover or initialize the controller; +- how geometry, hatch settings, MOPA parameters, or timing are encoded on the + wire; +- which values are controller settings versus laser-source settings; +- status, interlock, error, abort, and recovery behavior; +- whether an apparently harmless query can move a galvo or arm emission; +- the exact LightBurn version and known-working LightBurn device profile. + +Consequently, treating a vendor DLL or opaque profile as a callable black box +would be premature and would make the safety boundary impossible to audit. + +## Milestones + +### M0 — Evidence baseline (current) + +Preserve and hash the installer snapshot, publish sanitized findings, and keep +public/private provenance verifiable. Complete M0 with one local collection +from the actual LightBurn control computer. The preferred transfer is a single +ZIP or a directly accessible local folder; Google Drive is not part of the +workflow. + +Exit criteria: + +- exact LightBurn version, bundle, preferences, screenshots, and working + project examples are present in PrivateStash; +- mounted lens, startup, interlock, and USB device identity are confirmed; +- sanitized metadata and new analysis are committed publicly; +- both repositories pass their clean-clone validation. + +### M1 — Offline application core + +Define technology-independent domain models before choosing hardware APIs: + +- versioned machine-profile, project, operation, and material-preset schemas; +- explicit physical units and coordinate transforms; +- geometry bounds and parameter validation; +- deterministic job planning and simulation interfaces; +- an append-only diagnostic/event model with automatic redaction; +- a controller interface with a simulator as its only implementation; +- tests built from synthetic fixtures and sanitized evidence. + +A small desktop technology spike should compare candidate stacks using one +vertical slice: open a project, render it, validate it, and run it against the +simulator. The stack decision belongs in an ADR after the spike, not before it. + +Exit criteria: a user can complete a representative JPT job workflow offline, +and automated tests prove that no production controller backend is linked or +reachable. + +### M2 — Configuration understanding + +Build read-only parsers and structural comparison tools for the relevant +EZCAD2 and LightBurn artifacts. Unknown binary fields remain unknown; the code +must preserve that distinction rather than infer values by trial and error. + +Priorities: + +1. parse documented text configuration and material libraries; +2. inspect known-working LightBurn projects and exports; +3. map equivalent concepts into the application's neutral domain model; +4. characterize opaque configuration files using comparisons across known + lens profiles and controlled, user-made setting changes; +5. publish only independently derived format notes and sanitized fixtures. + +Exit criteria: the app can report a configuration, explain which claims are +observed versus inferred, and detect a wrong-lens or unknown-profile condition +without writing to the machine. + +### M3 — Protocol discovery and read-only controller access + +This is a new, explicitly approved hardware-research phase. Begin with focused +research into documented APIs and existing clean-room implementations, then +use passive observation of known software where necessary. Captures and raw +third-party material stay private; derived protocol notes and synthetic tests +are public. + +The first real backend capabilities are limited to device enumeration, +identity, firmware/capability discovery, and status. Every operation receives +an evidence level and a safety classification. Unknown messages are recorded, +not replayed. + +Before touching the connected machine, write a test protocol that specifies: + +- how emission is physically prevented; +- which motion is possible and how the work area is cleared; +- an observer and accessible emergency stop; +- the precise allowed USB operations; +- abort conditions and rollback/recovery steps; +- what is captured and how it is sanitized. + +Exit criteria: the app recognizes the correct controller and reports status +without moving a galvo, arming the source, modifying persistent state, or +requiring proprietary executable code in the public build. + +### M4 — Controlled motion and marking experiments + +Add capabilities one at a time behind explicit feature gates: + +1. upload a synthetic no-output job, if supported; +2. exercise abort and recovery without emission; +3. perform controlled framing only after its galvo behavior is understood; +4. mark a minimal calibration primitive at a conservative, reviewed setting; +5. verify coordinate scale, orientation, timing, and MOPA parameters; +6. compare planned versus observed behavior and retain a test record. + +Machine limits and source parameters come from known-good evidence and physical +verification. They are never discovered through broad value sweeps. + +Exit criteria: a reviewed integration test can mark a known calibration job +repeatedly, stop safely, and reject incorrect machine/lens profiles. + +### M5 — Workshop-usable JPT release + +Turn the proven vertical slice into a workshop tool: + +- practical SVG/DXF import and editing; +- layers, hatch/fill, ordering, transforms, text strategy, and presets; +- framing, start/pause/abort, progress, and understandable diagnostics; +- configuration backup and recovery; +- onboarding, compatibility matrix, signed releases, and operator guidance; +- usability and safety tests with makerspace users. + +Advanced LightBurn features are selected from real workshop needs rather than +copied feature-for-feature. + +Exit criteria: trained users can prepare and run ordinary JPT jobs without +LightBurn, within a documented support envelope. + +### M6 — Additional laser backends + +Use the neutral job model and safety architecture to add the Eduard x1550 and +Bodor BCL503MU. Each controller family gets its own evidence, protocol, +capability, and hardware-validation track. A successful JPT backend does not +imply compatible safety or control behavior on either CO2 machine. + +## Immediate next work package + +The next work package should be small enough to review in a few commits: + +1. collect the pending LightBurn data from the control PC as one local archive; +2. record an ADR for the neutral job model and isolated controller backends; +3. define v1 schemas for machine profiles and offline projects; +4. implement validation plus a deterministic simulated controller; +5. build a minimal desktop vertical slice and use it to decide the UI/runtime + stack; +6. separately produce a written M3 hardware-research protocol before any USB + capture or controller command. + +Items 2–5 can proceed while item 1 is pending. Hardware work cannot proceed +until item 6 is reviewed and the physical setup is ready. + +## Decision rules + +- A simulator test precedes every equivalent hardware behavior. +- Read-only precedes state change; state change precedes motion; motion precedes + emission. +- Safety-relevant values require provenance and units. +- A profile mismatch fails closed. +- Unknown protocol fields are never filled by guesswork. +- Raw proprietary artifacts remain private; public tests use synthetic or + explicitly redistributable fixtures. +- Any bulk external-data operation is scoped and costed before it starts. More + than roughly ten remote file operations require an explicit warning and a + cheaper bulk-transfer alternative. + diff --git a/docs/status/phase-0.md b/docs/status/phase-0.md index e9b57fb..7895cfc 100644 --- a/docs/status/phase-0.md +++ b/docs/status/phase-0.md @@ -41,3 +41,8 @@ as an intermediate project workspace and do not generate Support Data. Phase 0 remains open until these control-machine artifacts are hashed, committed, pushed, and represented by sanitized public evidence. + +The work that does not depend on this acquisition can proceed in parallel. +The [product and research roadmap](../roadmap.md) defines the offline application +core, configuration analysis, protocol research, gated hardware experiments, +and workshop release as separate milestones.