laserdove

Experimental Python tooling to plan and drive dovetail joints on laser cutting machines with a stepper-based rotary jig. This is pre-production software: use at your own risk and double-check every motion before powering a laser.

• Always dry-run or simulate before sending motion to hardware.
• Keep the beam off (--movement-only or dummy backend) until you trust the job.
• You are responsible for all outcomes. Third-party laser software and firmware can behave unexpectedly; monitor every job and have an e-stop within reach.

• Plans tail/pin layouts and emits motion/laser commands for Ruida controllers.
• Supports dry-run, Tk simulation, and RD job saving for inspection.
• Rotary-aware Z offsets and origin capture to align with the controller’s current position.
• Dummy backends for safe development; GPIO-driven rotary for Raspberry Pi setups.

• Ruida-based controller reachable over Ethernet (tested against RDC6442G protocol).
• Raspberry Pi (or similar) with GPIO access to a step/dir stepper driver for the rotary.
• Stepper-driven rotary fixture for the workpiece.
• For simulation-only use, hardware is optional.

source .venv/bin/activate
pip install -e .          # runtime
# For dev/lint/tests
pip install -e ".[dev]"
# For 3D visualization (optional)
# pip install panda3d

cp example-config.toml config.toml   # adjust to your jig/laser

python -m laserdove.main --config config.toml --mode both --dry-run  # plan only

python -m laserdove.main --config config.toml --simulate  # Tk sim

python -m tools.panda3d_sim --config config.toml --mode both  # 3D Panda3D sim (install panda3d first)

python -m laserdove.main --config config.toml --mode both --simulate-viewer pygame --simulate-screenshots-dir sim_frames --simulate-screenshots-every-s 2  # capture pygame frames

python -m laserdove.main --config config.toml --mode tails --save-rd-dir rd_out --movement-only  # build RD safely

• Copy example-config.toml to config.toml and edit.
• Sections:
  • [joint]: geometry inputs (length, tails, angle, kerf, clearance).
  • [jig]: rotary geometry (axis distance, zero angle, rotation speed).
  • [machine]: speeds, powers, Z zeros, air assist, Z direction.
  • [backend]: hardware targets and GPIO pins (dummy vs Ruida/real rotary, host/port, RD save dir).
• CLI flags override TOML values.

• CLI/config: cli.py, config.py parse flags/TOML into RunConfig, set logging.
• Geometry: geometry.py pure math for tail layouts and kerf offsets.
• Planning: planner.py + model.py build command sequences for tails/pins and rotary Z offsets.
• Hardware abstraction: hardware/:
  • base.py interfaces + dummy executor,
  • sim.py Tk simulation,
  • ruida_* + rd_builder.py UDP transport and RD payloads,
  • rotary.py GPIO/logging rotary drivers.
• Visualization/tools: simulation_viewer.py, tools/rd_parser.py, tools/ruida_status_probe.py.
• Optional simulators: Tk viewer (--simulate + --simulate-viewer tk) and pygame dual-view (--simulate-viewer pygame, requires pygame) with rotary + Z-aware edge view.
• Validation: validation.py checks geometry, jig, and machine limits before execution.

• Pin flanks rotate to +β on the left and -β on the right so pins end up wider at the bottom of the mounted board and narrower at the top (helps reduce burning on the narrow faces).

To extend: add new motion types in planner.py/model.py, new hardware backends under hardware/, or new CLI/config fields in config.py plus example-config.toml.

• Lint/format: make lint (ruff check + format --check), autoformat with make format.
• Tests + coverage: make test (runs lint + pytest).
• Manual: python -m pytest, ruff check src tests tools.

• Save RD jobs: --save-rd-dir rd_out/ then inspect with tools/rd_parser.py path/to.rd.
• Ruida status probe: python -m tools.ruida_status_probe --host <ruida-ip> to poll status bits with movement-only jobs.
• Simulation: --simulate to visualize paths with pacing based on commanded speeds.
• 3D visualization: python -m tools.panda3d_sim --config config.toml --mode both to replay plans in Panda3D (install optional dependency panda3d).

• Community and research work informed this tooling, including:
  • MeerK40t Ruida stack (reference/meerk40t/).
  • StevenIsaacs/ruida-protocol-analyzer.
  • EduTech Wiki Ruida notes.
  • jnweiger/ruida-laser.
• Additional vendor and community docs live in reference/ for background only; they are not imported into runtime code.

This software is experimental and provided without any warranty or responsibility for damage or injury. Verify every setting, monitor your laser at all times, and proceed only if you accept full responsibility. Use dummy or simulated backends first, and keep an e-stop within reach.