wasm-simulator/docs/architecture.md

WASM CNC simulator architecture

Native code boundary

The wasm core should expose a small C ABI and hide all LinuxCNC internals. The browser should never call LinuxCNC classes directly. This keeps the UI independent from whether the backend is LinuxCNC RS274, Fanuc preprocessing, Siemens preprocessing, or a future independent interpreter.

Current ABI entry points:

• cnc_sim_create
• cnc_sim_destroy
• cnc_sim_reset
• cnc_sim_set_dialect
• cnc_sim_load_config_json
• cnc_sim_parse_program
• cnc_sim_last_error

The event callback emits normalized CncSimEvent records. JavaScript can transform those records into JSON, binary buffers, or renderable typed arrays.

LinuxCNC integration plan

1. Build a native CanonEventSink that implements all functions declared in canon.hh.
2. Link the sink with src/emc/rs274ngc and src/emc/nml_intf instead of the task controller.
3. Stub or remove Python remap support for the first browser target.
4. Compile with Emscripten after replacing dlopen, Python, HAL and filesystem-only features.
5. Compare event output with native LinuxCNC using the same G-code corpus.

Dialect expansion

LinuxCNC support should be the baseline. Fanuc and Siemens support should be implemented as dialect adapters, not by forking the simulator core.

Fanuc high-priority items:

• Macro B variables and expression semantics
• G65, G66, G67 macro calls
• common fixed cycles
• cutter compensation and work offsets
• lathe cycles where required

Siemens high-priority items:

• named variables and arithmetic expressions
• CYCLE* canned cycles
• TRANS, ROT, SCALE, MIRROR
• TRAORI and CYCLE800
• frame and workpiece coordinate transforms

Commercial simulator parity

Feature parity needs more than G-code parsing:

• exact toolpath display with modal state inspection
• configurable machine kinematics and limits
• holder, fixture and stock collision detection
• material removal simulation
• time estimation with acceleration and lookahead
• diagnostics for unsupported controller-specific words
• reproducible comparison tests for each controller dialect

Five-axis and RTCP

The first RTCP implementation is a geometry kernel, not the full LinuxCNC motion controller. It treats programmed XYZ as the tool-center point, applies A/B/C orientation to a local tool vector, and computes the compensated pivot/spindle point needed to keep the tool tip fixed.

RTCP is opt-in through config JSON. When enabled, the original motion events remain programmed tool-tip motion and an additional rtcp-pivot event is emitted for each rapid/feed/arc event. This keeps the ABI useful for both toolpath display and machine-axis/pivot visualization.

Current files:

• core/src/rtcp_kinematics.h
• core/src/rtcp_kinematics.cpp
• core/tests/rtcp_kinematics_smoke.cpp

The next integration step is to add machine configuration for rotary topology, pivot offsets, tool length sources, and rotation order, then apply RTCP compensation while converting LinuxCNC Canon motion events into renderable machine/tool-tip trajectories.