Create a simple NGC remap

The simplest remap connects an M-code directly to an NGC O-word procedure, which is a reusable subroutine written in G-code. This example defines M400, requires a P word, and accepts an optional Q word. Its operator message shows which form was used.

The example machine directory is /data/ctrl/configs/my-machine.

Add the INI configuration

Create a directory for the procedure:

/data/ctrl/configs/my-machine/remap

Add the search path and remap definition to the machine’s INI file:

[RS274NGC]
SUBROUTINE_PATH = /data/ctrl/configs/my-machine/remap
REMAP = M400 modalgroup=10 argspec=Pq ngc=m400

This tells LinuxCNC to find m400.ngc through SUBROUTINE_PATH and call its o<m400> procedure when the interpreter reads M400.

Write the procedure

Create /data/ctrl/configs/my-machine/remap/m400.ngc:

o<m400> sub
  o100 if [#<_task> EQ 0]
    o<m400> return
  o100 endif

  o110 if [EXISTS[#<q>]]
    (msg, M400 received P and Q)
  o110 else
    (msg, M400 received P)
  o110 endif
o<m400> endsub

M2

LinuxCNC also runs the procedure while generating the program preview. #<_task> is 0 during preview and 1 during actual execution, so the first condition returns before producing an operator message. Keep this check before any action that should happen only when the program runs.

The argspec=Pq entry does the argument work before this procedure begins:

• P is uppercase, so it must be present.
• q is lowercase, so Q may be omitted.
• supplied values become the local named parameters #<p> and #<q>.
• EXISTS[#<q>] distinguishes an omitted Q from Q0.

The O-word name, NGC filename, and ngc= value use the same m400 name. Keeping them aligned makes the remap easy to find later.

Try the code

Restart LinuxCNC after changing the INI file, then try these commands in MDI:

M400
M400 P25
M400 P25 Q2

Expected behavior:

Command	Result
M400	Interpreter error because the required P word is missing.
M400 P25	Operator message: M400 received P.
M400 P25 Q2	Operator message: M400 received P and Q.

If LinuxCNC reports that the NGC file cannot be found during startup, check SUBROUTINE_PATH, the filename, and the value after ngc=. If M400 is still unknown after startup, check that the REMAP line is in the active machine INI file.