Command step: inject custom G-Code and/or run OS commands in a workflow (with optional feedback/loops)

[knipknap]

Feature request: Command step (G-Code and OS commands) — evaluated

Submitted by AVRASM2. This request was evaluated against the current codebase; findings and a proposed phasing are included below.

The problem

Rayforge's workflow is built from geometry/material operations (contour, engrave, CNC toolpaths). There is no way to:

• inject user-defined G-Code at an arbitrary point in a job in a well-defined order;
• run an external program as part of a job (robot part loader, relay/pump over a serial port, sound player, post-processing script);
• react to the result of such a program (exit code / output) to branch or repeat.

Today users work around this by exporting the G-Code, hand-editing or post-processing it externally, and re-importing — repeating the whole cycle on any change.

Requested solution

A new "Command" step type that can be placed anywhere in a layer's workflow, before, between, or after operations, multiple times. It should support:

1. Send G-Code — a multi-line, templated block emitted at the step's position.
2. Execute an OS shell command — run a host program and optionally wait for it.
3. (stretch) React to feedback — read the called program's exit code / stdout and branch, loop, GOTO a marker, or use counters/variables (e.g. repeat a layer/job until all pieces are loaded).

Example from the requester:

Layer 1
  Command: G-code  G0 X0 Y0 Z0        # pre-position (multiple lines)
  Command: Run program: Robot.sh Move 1   # load first piece
  Command: Run program: echo start > /dev/ttyACM3  # fan & pumps on
  Contour
  Frame
  Engrave
Layer 2 ... Layer 3 ...
  Command: Run program: Robot.sh NextPiece ; IF return = 1 THEN Restart Job/Layer
  Command: Run program: echo stop > /dev/ttyACM3
  Command: Run program: spd-say 'I'm done!'   # operator alert

What already exists (important — this narrows the request)

• Machine "Hooks & Macros" are already implemented (machine/models/macro.py, pipeline/encoder/rust_helpers.py, UI under Machine Settings → Hooks & Macros). G-Code macros can be injected automatically at Layer Start/End and Workpiece Start/End. Macros support @include of other macros and templating (machine.*, layer.*, workpiece.*, job.*, wcs_offset[*]).
• Job Start/End G-Code is handled via the dialect preamble/postscript (legacy JOB_START/JOB_END hooks are auto-migrated to a custom dialect).
• Manual macro execution from the Macros menu exists (MachineCmd.execute_macro_by_uid), and the encoder can already emit arbitrary raw lines via macros.
• Addon hooks (core/hooks.py) are pluggy addon lifecycle hooks, not user event hooks. They are not what the requester saw in the UI. However, addons can already connect to the job-lifecycle signals (machine_cmd.job_started, machine.job_finished) to run code in rayforge_init/main_window_ready.

So "send G-Code" is largely covered today — but only at fixed lifecycle points, not as an ordered, per-step command, and never as an OS command.

Evaluation / feasibility

1. G-Code command as an ordered workflow step — moderate, safe, recommended first.
Steps are ordered in a Workflow and layers execute in document order, so a command step slots naturally into sequencing. Two obstacles:

• The pipeline builds compute nodes per (workpiece × step), and Pipeline._can_generate_job requires every job layer to have at least one visible step and at least one workpiece. A geometry-less command step does not fit this model and needs explicit core support (a non-geometry stage / handling at intent-build and aggregate time).
• raygeo's CommandType has no raw/custom command; the encoder emits only known op types. Raw lines can be passed through today via the macro/dialect mechanism, so the encoder side is mostly reusable, but the step→ops→encode path needs a defined representation.
  The G-Code half is host-interpretable and low-risk (still able to crash a machine, see Safety), so it is the best first increment.

2. OS shell command step — technically easy, security-sensitive.
Actually executing a program is just subprocess on the host, but it must not be a quiet default. It also does not belong in the G-Code stream; it runs around/alongside the job, so the pipeline model above does not directly apply — a cleaner first form is an addon reacting to job signals, before any core step exists.

3. Feedback / loops / GOTO / variables — large; a separate feature, not a step.
Rayforge compiles the document ahead of time into a linear G-Code stream and sends it to firmware. Most GRBL-style controllers have no variables, labels, or GOTO, so conditionals and loops cannot be expressed in the emitted job. Reacting to a program's result and repeating requires host-side job control (pause, re-run a layer/job, re-generate, branch) and a scripting model — a distinct design effort. spd-say/relay/sound are just the OS-command half, not control flow.

4. "Enhance the hooks to run OS commands" — mostly an addon, not core.
Because addons can already subscribe to job lifecycle signals, a "play a sound / trigger a relay at job end" addon can be written today with no core change. That is a good way to prove the OS-command path and its permissions UX before adding a user-facing shell step.

Proposed phasing

1. Core: "G-Code Command" step — a geometry-less step that injects a templated multi-line G-Code block at its workflow position. Reuse the existing macro expansion and encoder path. No OS execution. This delivers the pre-position / retract-Z / de-focus / rotary / pause use cases safely.
2. Addon: job lifecycle OS commands — run a program on job start/finish/layer events via the existing signals, with an explicit enable switch. Proves the shell path and safety model.
3. Core: opt-in "Shell Command" step — if still wanted after (2), add a step with an allow-list/explicit confirmation, clearly marked as machine-specific and non-portable.
4. Separate feature: host-side conditional/loop job control — branching/repeat based on program feedback, GOTO markers, counters. Needs its own design; not required for 1–3.

Safety and portability

• Arbitrary code execution: a .ryp project or a shared machine profile that embeds shell commands is a code-execution vector. Commands must require explicit opt-in, never auto-run from an untrusted project, and should be surfaced/confirmed before execution. Consider an allow-list and storing shell commands in machine config rather than the document.
• Machine safety: arbitrary G-Code (Z moves, G53, de-focus, rotary) can crash hardware. Command steps should be visually and textually flagged, and ideally gated by machine capability.
• Portability: the requester already noted that projects with command steps are machine-specific. Mark such steps/layers, and warn when opening a project that references programs or coordinates not present locally.

Additional context

The requester compared this to MeerK40t, which assigns steps to drawing colors in a single layer and allows commands in any order and number between operations.

could also have a step called "Command" and it would allow to A) send G-Code and B) execute OS Shellcommands, then it gets really powerful with maybe not much effort i hope! especially if it could also react on the feedback of a called program to make a Loop or other actions?
that would instantly beat MeerK40t by lightyears and maybe other tools too!
no clue if that could be an Addon or if that Command-Step needs to be baked into RF it self

[knipknap]

@AVRASM2 thinking about this more, i am not actually sure that the "invoke a local script with decisions based on the script result" is reasonably possible. The main issue: A device may not actually let you know when it is time to invoke the script. In general, the approach is:

1. Rayforge generates the full G-code (Ruida specific machine code in case of Ruida) to send to the machine
2. Rayforge sends the code to the machine
   1. Non-streaming drivers (e.g. Grbl network, Ruida): Rayforge sends all commands at once like a file. The machine executes the file autonomously. Rayforge only learns what is done by listening to asynchronous status reports. So for such drivers this feature is simply not possible.
   2. Streaming drivers. Here theoretically Rayforge could hold back part of the job when encountering a "shell command invocation" marker. But even here this can be tricky, at least the UI/project side then is: What should happen when you create a project with script invocation, then switch to another machine? The UI would need to adapt to driver capabilities - possible, but what to do with pre-existing macros that invoke scripts? This sounds like a bit of a rabbit hole that would affect all future testing and maintenance with new special cases.

Now invoking scripts asynchronously is a different matter alltogether - that should be much simpler, but those scripts could not affect a running job. (The security and adaptive UI part would still be a bit tricky, but solvable.)

[AVRASM2]

1st: there is NO pressure or rush, so take your time as i do take mine to brainstorm stuff 👍

...Now invoking scripts asynchronously is a different matter...

that would work with streaming devices as you have full control when that device gets its next commands
in that case it works like synchronously (rather "in order of steps") invoking stuff and halting if needed ?!

non-streaming devices it would do it too, but as soon commands are sent to the laser, it would directly invoke the next script, and that then has to take care (i.e. a Timer or feedback from sensors & bit of hackery on the machine and custom movements at the end) when to actually execute its job (controlling robot / loader / belt) and tell RF how to proceed (i.e. repeat or finish)

Non-streaming drivers

well, that would only allow "synchronous" execution at the beginning and the end of at least a layer or even only entire Job, not in between steps (no clue if layers are / could be handled as if they were mini-jobs in sequence)
(blocking until external tool finished - of course with a possibility to Abort stuff - ie. a Popup saying what it is doing with an "Abort Job" button)
i guess mostly that is fine as "in between layers" you mostly if at all, only want to change pump-speed or valves for airflow
--> not every laser supports that it self without hacking, and the idea would be to offload hacking to independent SW/HW that someone could hook to his Arduino or what ever he likes, not voiding lasers warranty...
worst case some Custom G-Codes could move the gantry/head against some Sensors to trigger external controls as workaround!
but that would suffice to have loading & repeat as well as a "i am finished"-notification possible

EXCEPT:
that Laser gets the entire Job and RF can't figure out what happens afterwards, maybe not even a "finished"-signal from the Laser
such a machine would sadly NOT benefit from this idea much, there only a Workaround with Sensors and moving gantry to them would work, and RF could simply wait until it gets feedback from the conditional called program, that gets triggered by the hardware when the Laser hits the "finish-sensor", and after that the loader figures out it has or can't load next piece, that gets back to the program and that returns True or False to RF, which then ends or repeats the job to the Laser
any other special wishes must be done with more sensors and hitting them, as RF can't see what that particular machine does

Streaming drivers. // What should happen when you create a project with script invocation, then switch to another machine?

good point, how likely it is to run multiple machines on 1 RF instance at the same time?
--> i for sure can't wrap my head around that idea, as usually i would run 3 different projects on 3 different machines that are 3 different wavelengths as well :-P (aka i don't have 3 same lasers)
btw: i was looking for a connect/disconnect button as it already choose the wrong machine with the same Port ;-)

also automation-batchjobs is something you won't really want to run on your main PC i guess?

i certainly have separate computers for my tools or they run off Memory-devices offline like 3DP
having many old(er) Laptops makes it really easy - especially for the dirty CNC ! (for sure i won't have the new expensive gear next to it and Metal-Chips going to mess them up)

Note

this project is nothing to be rushed, as it would like to be reliable at the end, stepping in small steps as feasible 👍
it is far better to brainstorm fist for that Command stuff
having Hooks / an Add-on to execute external stuff (maybe with conditions) would already allow basic automation (but with the same caveats in some cases again :-/

also note i only have GRBL based machines with streaming at the moment (and thus i tend to oversee that other issue a bit)

btw: how easy is it to write an Addon that calls external stuff? i'd like to stick my nose into that and write something...

curious what you think about the possibility that this feature might only be available to certain machines and for others there is a note "sadly this only works in a limited way due how that controller works, please see documentation what hardware-workarounds need to be combined to get it somewhat useful for your machine if you need that"

This sounds like a bit of a rabbit hole that would affect all future testing and maintenance with new special cases.

yes fair point, maybe for some machines it won't work easily or only with described workaround if at all
i guess as this is more of a poweruser feature, they should be able to hack a bit, as long they don't need to re-write the Firmware of their Laser at the end...
of course a newly added controller-type should get a warning "that feature might not work as expected as it is not tested against this controller, please use with care!"

best regards 😄

Note

maybe my reply is not 100% covering your concerns, then please let me know and ask me stuff so i can feed back into that brainstorm...

EDIT:
i also realized there is another workaround for machines that doesn't stream and gives no feedback to RF either:
in that case i would simply add a timer in my tools and block RF until my tool thinks "laser must be ready by now" and then further steps be done as needed (i.e. load next piece & tell RF to restart job or finish job and execute last commands to notify "i'm done" things)

while RF is "blocked" it shows that Popup that lets the user know, and optionally abort the job
aborting would KILL the called program off course and run the "aborted controlled job"-hook or command(s) defined to then safely reset connected gear so they don't try to do stuff

also i should mention that "Non-Conditional" calls could / should be "Non-Blocking" if possible/feasible
and if i need to wait: simply use a conditional call that True & False do the same: "continue" and no "goto" assigned

best regards again 😃

ps: sorry for many Edits, i hope you didn't have to read it 20 times 😟

[AVRASM2]

just in case anyone wants a "TLDR":

primary we need to figure out what needs to or can be done in Core to have such possibilities: inject G-Code and call programs maybe with & without return-evaluation in sequence in the first place
in a way it works with most devices, and if not, how people could work around and still leverage some advantages

non-streaming devices have issues if they don't report back to RF what the state is - so tooling needs to rely on timing or sensors!
--> even just a simple call to an Audio-Player or "Beeper" has an issue in that case as it would simply run while the Laser is still working asynchronously (you have to first call a sleeping tool/command as conditional to halt RF before you can proceed with a Sound-Program - or inject special parking-move to a sensor and a tool waits for that to happen trough a sensor)

then we can also figure out what can or needs or should to be an Addon instead (i.e. more advanced stuff than basic injection & calls)

but still any non-streaming device poses the risk of "issues" with workarounds - i believe having such capabilities somehow safely implemented can leverage a lot in any case - there is always the option to NOT USE it if it doesn't work in a specific case

best regards and have a good night! 😴

[knipknap]

I think we're aligned on the important parts. Feedback/loops are off the table for now (you pretty much worked out yourself why), and anything OS-command-related will be async first.

Here's what I'd build, in small steps:

1. "Command" step — place it anywhere in a layer's workflow, it injects templated machine code at exactly that position (same variables as macros). Covers your pre-positioning, pumps, defocus cases — and also replaces most layer start/end tricks, since you can just put one first or last in a layer.
2. Automation addon — runs shell commands on job start/finish, async. Opt-in with confirmation, stored in app settings, never in the project file (sharing a .ryp must never execute code on someone else's machine). This doubles as the addon example you asked about — a working skeleton is ~50 lines, so if you want to stick your nose in, this is the place :)
3. Maybe later: an opt-in shell-command step. Your non-streaming machines are right about the limitation — there, OS commands can only fire around the job, not synchronized with it. I'd document the sensor/timer workarounds in a docs page rather than build around them.

[AVRASM2]

Sounds nice, i am happy about any small improvements done in easy steps 😃

i just want to confirm that i understand the implemented way it will soon start working:

"Command" step ...it injects templated machine code...

so i can put templates / macros somewhere and then call those as a Step?
macros already have a place to enter in RF and could also called manually as is
but where would a template be stored? i guess they are local & global templates depending what belongs to the Machine-Setup and what is more to get the In-Process flow adjusted (that should/could travel with a project i expect, just worth alone as a "documentation" if other similar machine lacks a motorized-Z-axis - or if run on another different machine all injections should deactivate so a user can re-enable & check those Steps - and add/replace with his own global Templates ?)
(please feedback to refine!)

how is that planned? a Dropdown or a Textbox?
if it is a Textbox then a Macro / Template could be called like myInitMoveRotary() ?
(that would allow for variables/constants to be passed in the future)
but also i could then enter G-, M- & other Codes sent to Laser directly if that move is specific to get next step working under right conditions?
(like pre-position Z-Axis, and if the Laser-Controller supports: change Airflow or other HW connected to it with its specific Codes)
with direct-entry there is kind of a redundant way to local templates, but useful for a quick 1-2 different code
(moving Z-Axis should work on any machine, as you normally set Z to 0 at Focus before job is started)
(please feedback to refine!)

maybe some ideas or UX might be complicated or redundant, but if i can enter machine-code directly into that step and call a template / macro as well that would be nice
(Textbox would be easiest to implement for that, essentially like an Inline-Hook 👍 )

Automation addon

it makes 1000% sense to not be able to send rm -rf ~ to someone elses PC! (and F-UP their entire /home)
we DO NOT want a "Macro-Virus" - MS-Excel already is famous for that...

async: how async it actually is?
on a Non-Streaming machine it is 100% clear, that
Command
Engrave
Command
would run all in sequence, but after "Engrave" & sending data to Controller, it will directly fire next Command
(except: if Layers / Steps are handle-able as sub-jobs sent in sequence to controller, then we could i.e. change stuff between engraving & cutting - would not work on Filebased machines where you have to start them manually on the Laser itself, but if with G-Code those files can be started in sequence, then splitting works also there)
--> splitting is just as an idea worth considering

but on a Streaming machine?
it would be more synchronized i guess, BUT the command might fire after the last set of Codes has been transmitted, so the Laser would still move a few more seconds or minutes WHILE that command fires!
that is 100% fine, especially if it only notifies the operator to come back after 30mins of machining is about to end - wich is the most important thing I'll use that for now
(except you wait for the laser reporting it has ran out of buffer / finished execution: mostly it goes to IDLE after being done, then it would be fully synchronized for free)
(for Robotics i can also add delays on my side, and to re-start i would press a mouse-button with a small motor as a workaround - handled by the Loader-Controlbox)

Maybe later: an opt-in shell-command step...

yes, that can & should wait for now, it is good to have that on the roadmap for the future but NOT RUSHING that 👍
maybe i figure out my self how i can iterate on the base that is going to be implemented by you, how i then can add that my self
that way i can test that critical & probably most dangerous ? part trough in private without the risk that other people are going to mess with an unfinished and possibly dangerous feature
i guess i can simply then reuse the "Command-Step"-logic and alter a copy of that to handle OS stuff and other ideas
and if i am happy with my progress, would open a Pull-Request that then might be accepted or rejected depending how you think it is fit already or not yet to be added

as RF is a quite big Project with lots of complex Features & UI already, that you (@knipknap) knows best how it works,
i think it is safest that the first thing: "Command-Step" is laid down by you first 👍
then the UI & logic is clean and high quality 😃
adding small ideas or tinkering on a basis is then much easier for me

THIS WAY: it would also take off some workload from you, while i test & iterate that last feature my self ?! 😎
maybe i also can try to bug-fix other parts in the current code (of those new features) as well and submit PRs if i find time ;-)

best regards & have a nice day!

[knipknap]

Good questions.

Textbox: yes. The step is just multi-line text, basically your inline-hook idea. Quick 1–2 lines of G/M-code go right in, and for anything bigger you reference a macro.

Macro references: yes, via @include. Macros already have @include(Macro Name), and the step will use exactly that syntax — nothing new to learn. A step can look like:

G0 Z5
@include(Rotary Init)
M8

The include machinery already exists in the encoder for layer/workpiece hooks, I just need to run these lines through it too. Variables are the same set as macros (machine.*, layer.*, job.*), and layer.* works even mid-layer. The text is stored in the workflow exactly as you typed it and expanded only when the job is encoded.

Since the text lives in the workflow, it travels with the project. The @include is just a name though — open the project on a machine that doesn't have that macro, and you get the usual ; WARNING: Macro ... not found line in the output instead of something silently wrong. I actually like that: it fails visibly, and it still documents what the step was supposed to do. A per-machine enable/disable for command steps might come later, let's see if it's needed.

Status: the raygeo groundwork is done and released (v1.58.0 — a custom command that carries raw lines through the pipeline untouched, plus variable expansion). Next is the Rayforge side: step type, pipeline wiring, editor UI.

Async: you analyzed it right, on both kinds of machines.

• Non-streaming: the job goes out as one file, so there is no "between engraving and cutting" moment for the host to act in. Sub-job splitting would create one, but that's a real architectural change — parked.
• Streaming: a job-end command fires when the host is done sending. The controller may keep working through its buffer for a while after that. Fine for "come back in 30 minutes", not fine for robot loading. That said, the driver knows when the stream has drained and can ask the controller whether it's idle — so an "on machine idle" trigger might be nearly free once the addon exists. Worth trying.

Your prototype plan: works for me. The automation addon will stay small on purpose, and once the Command step is in, you'll have a complete reference for how lines get from a step to the encoder. Build your OS-command variant on that base, test the dangerous parts privately, and PR it when you're happy with it. Bug fixes always welcome :)

[AVRASM2]

Very Happy with that proposal 👍
small but working steps are welcome

can't wait to test & play with those cool power-features!
as with "my last cycle" of ideas of great enhancements 😉
(but don't hurry, take your easy speed 👍 )

btw:

... not fine for robot loading. ...

that is already fine and very workable for me, as either i simply let the robot wait for X seconds or inject a move to a Trigger-Sensor instead, especially as there is no "OS-Command" yet, this is a very doable and easy workaround, and to repeat i could simply let the robot press a mouse-button, very crude but that would enable a lot already with little work on your side, and bit more on mine / any other one that wishes to automate the engraver-workflow

Trig.Sensors only eat up some space on the machine, but that would also work on Non-Streaming devices (i don't have such one yet)
anyone that requires the full X-Y-Z space, has to wait until later future development 👍

cheers, great work ❤️