Extending LinuxCNC

By remapping codes we mean one of the following:

The set of codes (M,G,T,S,F) currently understood by the RS274NGC interpreter is fixed and cannot be extended by configuration options.

In particular, some of these codes implement a fixed sequence of steps to be executed. While some of these, like M6, can be moderately configured by activating or skipping some of these steps through ini file options, overall the behaviour is fairly rigid. So - if your are happy with this situation, then this manual section is not for you.

In many cases, this means that supporting a non out of the box configuration or machine is either cumbersome or impossible, or requires resorting to changes at the C/C+\+ language level. The latter is unpopular for good reasons - changing internals requires in-depth understanding of interpreter internals, and moreover brings its own set of support issues. While it is conceivable that certain patches might make their way into the main LinuxCNC distribution, the result of this approach is a hodge-podge of special-case solutions.

A good example for this deficiency is tool change support in LinuxCNC: while random toolchangers are well supported, it is next to impossible to reasonably define a configuration for a manual-toolchange machine with, for example, an automatic tool length offset switch being visited after a toolchange, and offsets set accordingly. Also, while a patch for a very specific rack toolchanger exists, it has not found its way back into the main code base.

However, many of these things may be fixed by using an O-word procedure instead of a builtin code - whenever the - insufficient - builtin code is to be executed, call the O-word procedure instead. While possible, it is cumbersome - it requires source-editing of NGC programs, replacing all calls to the deficient code by a an O-word procedure call.

In it’s simplest form a remapped code isnt much more than a spontaneous call to an O-word procedure. This happens behind the scenes - the procedure is visible at the configuration level, but not at the NGC program level.

Generally, the behaviour of a remapped code may be defined in the following ways:

M- and G-codes, and O-words subroutine calls have some fairly different syntax.

O-word procedures, for example, take positional parameters with a specific syntax like so:

whereas M- or G-codes typically take required or optional word parameters. For istance, G76 (threading) requires the P,Z,I,J and K words, and optionally takes the R,Q,H, E and L words.

So it isnt simply enough to say whenever you encounter code X, please call procedure Y - at least some checking and conversion of paramters needs to happen. This calls for some glue code between the new code, and its corresponding NGC procedure to execute before passing control to the NGC procedure.

This glue code is impossible to write as an O-word procedure itself since the RS274NGC language lacks the introspective capabilities and access into interpreter internal data structures to achieve the required effect. Doing the glue code in - again - C/C+\+ would be an inflexible and therefore unsatisfactory solution.

To make a simple situation easy and a complex situation solvable, the glue issue is addressed as follows:

Embedded Python functions in the Interpreter started out as glue code, but turned out very useful well beyond that. Users familiar with Python will likely find it easier to write remapped codes, glue, O-word procedures etc in pure Python, without resorting to the somewhat cumbersome RS274NGC language at all.

Many people are familiar with extending the Python interpreter by C/C++ modules, and this is heavily used in LinuxCNC to access Task, HAL and and Interpreter internals from Python scripts. Extending Python basically means: your Python script executes as it is in the driver seat, and may access non-Python code by importing and using extension modules written in C/C+\+. Examples for this are the LinuxCNC hal, gcode and emc modules.

Embedded Python is a bit different and and less commonly known: The main program is written in C/C++ and may use Python like a subroutine. This is powerful extension mechanism and the basis for the scripting extensions found in many successful software packages. Embedded Python code may access C/C+\+ variables and functions through a similar extension module method.

Defining a code involves the following steps:

Note that currently only a few existing codes may be redefined, whereas there are many free codes which might be made available by remapping. When developing a redefined existing code, it might be a good idea to start with an unallocated G- or M-code so both the existing and new behaviour can be exercised. When done, redefine the existing code to use your remapping setup.

Let’s assume the new code will be defined by an NGC procedure, and needs some parameters, some of which might be required, others might be optional. We have the following options to feed values to the procedure:

The first method is preferred for parameters of dynamic nature, , like positions. You need to define which words on the current block have any meaning for your new code, and specify how that is passed to the NGC procedure. Any easy way is to use the argspec statement. A custom prolog might provide better error messages.

Using to ini file variables is most useful for referring to setup information for your machine, for instance a fixed position like a tool-length sensor position. The advantage of this method is that the parameters are fixed for your configuration regardless which NGC file you’re currently executing.

Referring to global variables is always possible, but they are easily overlooked.

Note there’s a limited supply of words which may be used as parameters, so one might need to fall back to the second and third methods if many parameters are needed.

Your new code might succeed or fail, for instance if passed an invalid parameter combination. Or you might choose to just execute the procedure and disregard results, in which case there isnt much work to do.

Epilog handlers help in processing results of remap procedures - see the reference section.

Excecutable G-code words are classified into modal groups, which also defines their relative execution behaviour.

If a G-code block contains several executable words on a line, these words are executed in a predefined order of execution, not in the order they appear in block.

When you define a new executable code, the interpreter does not yet know where your code fits into this scheme. For this reason, you need to choose an appropriate modal group for your code to execute in.

To give you an idea how the pieces fit together, let’s explore a fairly minimal but complete remapped code definition. We choose an unallocated M-code and add the following option to the ini file:

In a nutshell, this means:

The file myprocedure.ngc is expected to exists in the [DISPLAY]NC_FILES or [RS274NGC]SUBROUTINE_PATH directory.

A detailed discussion of REMAP parameters is found in the reference section below.

To remap a code, define it using the REMAP option in RS274NG section of your ini file. Use one REMAP line per remapped code.

The syntax of the REMAP is:

It is an error to omit the <code> parameter.

The options of the REMAP statement are separated by whitespace. The options are keyword-value pairs and currently are:

The python, prolog and epilog options require the Python Interpreter plugin to be configured, and appropriate Python functions to be defined there so they can be referred to with these options.

The syntax for defining a new code, and redefining an existing code is identical.

Note that while many combinations of argspec options are possible, not all of them make sense. The following combinations are useful idioms:

Note that if all you want to achieve is to call some Python code from G-code, there is the somewhat easier way of calling Python functions like O-word procedures.

FIXME linkto word definition in gcode/overview - no tag there

The argument specification (keyword argspec) describes required and optional words to be passed to an ngc procedure, as well as optional precondtions for that code to execute.

An argspec consists of 0 or more characters of the class [@A-KMNP-Za-kmnp-z^>] . It can by empty (like argspec=).

An empty argspec, or no argspec argument at all implies the remapped code does not receive any parameters from the block. It will ignore any extra parameters present.

Note that RS274NGC rules still apply - for instance you may use axis words (eg X,Y,Z) only in the context of a G-code.

By default, parameters are passed as local named parameter to an NGC procedure. These local parameters appear as already set when the procedure starts executing, which is different from existing semantics (local variables start out with value 0.0 and need to be explicitly assigned a value).

Optional word parameters may be tested for presence by the EXISTS(#<word>) idiom.

Assume the code is defined as

REMAP=M400 modalgroup=10 argspec=Pq ngc=m400

and m400.ngc looks as follows:

Assume the code is defined as

REMAP=M410 modalgroup=10 argspec=@PQr ngc=m410

and m410.ngc looks as follows:

NB: you lose the capability to distinguish more than one optional parameter word, and you cannot tell whether an optional parameter was present but had the value 0, or was not present at all.

It’s possible to define new codes without any NGC procedure. Here’s a simple first example, a more complex one can be found in the next section.

Assume the code is defined as

REMAP=G88.6 modalgroup=1 argspec=XYZp python=g886

This instructs the interpreter to execute the Python function g886 in the module_basename.remap module which might look like so:

Try this with out with: g88.6 x1 y2 z3 g88.6 x1 y2 z3 p33 (a comment here)

You’ll notice the gradual introduction of the embedded Python environment - see here for details. Note that with Python remapping functions, it make no sense to have Python prolog or epilog functions since it’s executing a Python function in the first place.

The interpreter and emccanon modules expose most of the Interpreter and some Canon internals, so many things which so far required coding in C/C+\+ can be now be done in Python.

The following example is based on the nc_files/involute.py script - but canned as a G-code with some parameter extraction and checking. It also demonstrates calling the interpreter recursively (see self.execute()).

Assuming a definition like so (NB: this does not use argspec):

REMAP=G88.1 modalgroup=1 py=involute

The involute function in python/remap.py listed below does all word extraction from the current block directly. Note that interpreter errors can be translated to Python exceptions. Remember this is readahead time - execution time errors cannot be trapped this way.

The examples described so far can be found in configs/sim/remap/getting-started with complete working configurations.

The minimal prerequisites for using REMAP statements are as follows:

Assuming your configuration lives under /home/user/xxx and the ini file is /home/user/xxx/xxx.ini, execute the following commands.

Now edit /home/user/xxx/xxx.ini and add the following:

Now verify that LinuxCNC comes up with no error messages - from a terminal window execute:

If you are unfamiliar with LinuxCNC internals, first read the How toolchange currently works section (dire but necessary).

Note than when remapping an existing code, we completely disable this codes' builtin functionality of the interpreter.

So our remapped code will need to do a bit more than just generating some commands to move the machine as we like - it will also need to replicate those steps from this sequence which are needed to keep the interpreter and task happy.

However, this does not affect the processing of toolchange-related commands in task and iocontrol. This means when we execute step 6b this will still cause iocontrol to do its thing.

Decisions, decisions:

Depending on the answer, we have four different scenarios:

So the overall approach for our first example will be:

Iocontrol provides two HAL interaction sequences we might or might not use:

What you need to decide is whether the existing iocontrol HAL sequences are sufficient to drive your changer. Maybe you need a different interaction sequence - for instance more HAL pins, or maybe a more complex interaction. Depending on the answer, we might continue to use the existing iocontrol HAL sequences, or define our own ones.

For the sake of documentation, we’ll disable these iocontrol sequences, and roll our own - the result will look and feel like the existing interaction, but now we have complete control over them because they are executed in our own O-word procedure.

So what we’ll do is use some motion.digital-* and motion.analog-* pins, and the associated M62 .. M68 commands to do our own HAL interaction in our O-word procedure, and those will effectively replace the iocontrol tool-prepare/tool-prepared and tool-change/tool-changed sequences. So we’ll define our pins replacing existing iocontrol pins functionally, and go ahead and make the iocontrol interactions a noop. We’ll use the following correspondence in our example:

Iocontrol pin correspondence in the examples

Let us assume you want to redefine the M6 command, and replace it by an O-word procedure, but other than that things should continue to work.

So what our O-word procedure would do is to replace the steps outlined here. Looking through these steps you’ll find that NGC code can be used for most of them, but not all. So the stuff NGC cant handle will be done in Python prolog and epilog functions.

To convey the idea, we just replace the builtin M6 semantics with our own. Once that works, you may go ahead and place any actions you see fit into the O-word procedure.

Going through the steps, we find:

So we need a prolog, and an epilog. Lets assume our ini file incantation of the M6 remap looks as follows:

So the prolog covering steps 1 and 2 would look like so - we decide to pass a few variables to the remap procedure which can be inspected and changed there, or used in a message. Those are: tool_in_spindle, selected_tool (tool numbers) and their respective pockets current_pocket and selected_pocket:

You will find that most prolog functions look very similar: first test that all preconditions for executing the code hold, then prepare the environment - inject variables and/or do any preparatory processing steps which cannot easily be done in NGC code; then hand off to the NGC procedure by returning INTERP_OK.

Our first iteration of the O-word procedure is unexciting - just verify we got parameters right, and signal success by returning a positive value; steps 3-5 would eventually be covered here (see here for the variables referring to ini file settings):

Assuming success of change.ngc, we need to mop up steps 6-8:

This replacement M6 is compatible with the builtin code, except steps 3-5 need to be filled in with your NGC code.

Again, most epilogs have a common scheme: first, determine whether things went right in the remap procedure, then do any commit and cleanup actions which cant be done in NGC code.

Note that the sequence of operations has changed: we do everything required in the O-word procedure - including any HAL pin setting/reading to get a changer going, and to acknowledge a tool change - likely with motion.digital-* and motion-analog-* IO pins. When we finally execute the CHANGE_TOOL() command, all movements and HAL interactions are already completed.

Normally only now iocontrol would do its thing as outlined here. However, we dont need the HAL pin wiggling anymore - all iocontrol is left to do is to accept we’re done with prepare and change.

This means that the corresponding iocontrol pins have no function any more. Therefore, we configure iocontrol to immediately acknowledge a change by configuring like so:

If you for some reason want to remap Tx (prepare), the corresponding iocontrol pins need to be looped as well.

The standard prologs epilogs found in configs/sim/remap/python-stdglue/remap.py pass a few exposed parameters to the remap procedure.

An exposed parameter is a named local variable visible in a remap procedure which corresponds to interpreter-internal variable which is relevant for the current remap. Exposed parameters are set up in the respective prolog, and inspected in the epilog. They can be changed in the remap procedure and the change will be picked up in the epilog. The exposed parameters for remappable builtin codes are:

If you have specific needs for extra parameters to be made visible, that can simply be added to the prolog - practically all of the interpreter internals are visible to Python.

Remember that normally remapping a code completely disables all internal processing for that code.

However, in some situations it might be sufficient to add a few codes around the existing M6 builtin implementation, like a tool length probe, but other than that retain the behaviour of the builtin M6.

Since this might be a common scenario, the builtin behaviour of remapped codes has been made available within the remap procedure. The interpreter detects that you are referring to a remapped code within the procedure which is supposed to redefine its behaviour. In this case, the builtin behaviour is used - this currently is enabled for the set: M6, M61,T, S, F). Note that otherwise referring to a code within its own remap procedure would be a error - a remapping recursion.

Slightly twisting a builtin would look like so (in the case of M6):

See the configs/sim/remap/extend-builtins directory for a complete configuration which is the recommded starting point for own work when extending builtin codes.

If you’re confident with the default implementation, you wouldnt need to do this. But remapping is also a way to work around deficiencies in the current implementation, for instance to not block until the "tool-prepared" pin is set.

What you could do, for instance, is: - in a remapped T, just set the equivalent of the "tool-prepare" pin, but not wait for "tool-prepared" here - in the corresponding remapped M6, wait for the "tool-prepared" at the very beginning of the O-word procedure.

Again, the iocontrol tool-prepare/tool-prepared pins would be unused and replaced by motion.* pins, so those would pins must be looped:

So, here’s the setup for a remapped T:

The minimal ngc prepare procedure again looks like so:

And the epilog:

prepare_prolog and prepare_epilog are part of the standard glue provided by FIXME pathname. This module is intended to cover most standard remapping situations in a common way.

The builting toolchange procedure has some precautions for dealing with a program abort (e.g. hitting Escape in Axis during a change). Your remapped function has none of this, therefore some explicit cleanup might be needed if a remapped code is aborted. In particular, a remap procedure might establish modal settings which are undesirable to have active after an abort. For instance, if your remap procedure has motion codes (G0,G1,G38..) and the remap is aborted, then the last modal code will remain active. However, you very likely want to have any modal motion canceled when the remap is aborted.

The way to do this is by using the [RS274NGC]ON_ABORT_COMMAND feature. This ini option specifies a O-word procedure call which is executed if task for some reason aborts program execution.

The suggested on_abort procedure would look like so (adapt to your needs):

Make sure on_abort.ngc is along the interpreter search path (recommended location: SUBROUTINE_PATH so as not to clutter your NC_FILES directory with internal procedures). on_abort receives a single parameter indicating the cause for calling the abort procedure, which might be used for conditional cleanup.

Statements in that procedure typically would assure that post-abort any state has been cleaned up, like HAL pins properly reset. For an example, see configs/sim/remap/rack-toolchange.

Note that terminating a remapped code by returning INTERP_ERROR from the epilog (see previous section) will also cause the on_abort procedure to be called.

If you determine in your handler procedure that some error condition occurred, do not use M2 to end your handler - see above:

If displaying an operator error message and stopping the current program is good enough, use the (abort, <message>) feature to terminate the handler with an error message. Note that you can subsitute numbered, named, ini and HAL parameters in the text like in this example (see also tests/interp/abort-hot-comment/test.ngc):

NB: ini and HAL variable expansion need explicit enabling with FEATURE.

If more fine grained recovery action is needed, use the idiom laid out in the previous example:

This error message will be displayed in the UI, and returning INTERP_ERROR will cause this error handled like any other runtime error.

Note that both (abort, msg) and returning INTERP_ERROR from an epilog will cause any ON_ABORT handler to be called as well if defined (see previous section).

A potential use for a remapped S code would be automatic gear selection depending on speed. In the remap procedure one would test for the desired speed attainable given the current gear setting, and change gears appropriately if not.

A use case for remapping M0/M1 would be to customize the behaviour of the existing code. For instance, it could be desirable to turn off the spindle, mist and flood during an M0 or M1 program pause, and turn these settings back on when the program is resumed.

For a complete example doing just that, see configs/sim/remap/extend-builtins/, which adapts M1 as laid out above.

A G-code cycle as used here is meant to behave as follows:

An example: Assume you have G84.3 defined as remapped G code cycle with the following ini segment (see here for a detailed description of cycle_prolog and cycle_epilog):

Executing the following lines:

causes the following (note R is sticky, and Z is sticky since the plane is XY):

Besides creating new cycles, this provides an easy method for repackaging existing G-codes which do not behave as cycles. For instance, the G33.1 Rigid Tapping code does not behave as a cycle. With such a wrapper, a new code can be easily created which uses G33.1 but behaves as a cycle.

See configs/sim/remap/cycle for a complete example of this feature. It contains two cycles, one with an NGC procedure like above, and a cycle example using just Python.

The Python plugin serves both the interpreter, and task if so configured, and hence has its own section PYTHON in the ini file.

[PYTHON]

For ad-hoc execution of commands the Python hot comment has been added. Python output by default goes to stdout, so you need to start EMC from a terminal window to see results. Example (eg. in the MDI window):

Note that the interpreter instance is available here as self, so you could also run:

The emcStatus structure is accessible, too:

The namespace is expected to be laid out as follows:

The interpreter is an existing C++ class (Interp) defined in src/emc/rs274ngc. Conceptually all oword.<function> and remap.<function> Python calls are methods of this Interp class, although there is no explicit Python definition of this class (it’s a Boost.Python wrapper instance) and hence receive the as the first parameter self which can be used to access internals.

If the TOPLEVEL module defines a function __init__, it will be called once the interpreter is fully configured (ini file read, and state synchronized with the world model):

This function may be used to initialize any Python-side attributes which might be needed later, for instance in remap or oword functions. If there are setup actions which are to happen only in the milltask Interpreter instance, this can be tested for by evaluating self.task.

An example use of __init__ can be found in configs/sim/remap/cycle/python/toplevel.py initialising attributes needed to handle cycles in configs/sim/remap/python-stdglue/stdglue.py.

Python code is called from NGC in the following situations:

Arguments:

Just as NGC procedures may return values, so do O-word Python subroutines. They are expected to either:

Any other return value type will raise a Python exception.

In a calling NGC environment, the follwing predefined named parameters are available:

See also tests/interp/value-returned for an example.

Arguments are:

Example call:

Return values:

.

Arguments are:

The minimum python= function example:

Return values:

If the handler needs to execute a queuebuster operation (tool change, probe, HAL pin reading) it is supposed to suspend execution with the following statement:

Queue busters interrupt a procedure at the point where such an operation is called, hence the procedure needs to be restarted after the interpreter synch(). When this happens the procedure needs to know if it is restarted, and where to continue. The Python generator method is used to deal with procedure restart.

This demonstrates call continuation with a single point-of-restart:

NGC code is executed from Python when:

The prolog handler does not call the handler, but it prepares its call environment, for instance by setting up predefined local parameters.

Conceptually a prolog and an epilog execute at the same call level like the O-word procedure, that is: after the subroutine call is set up, and before the subroutine endsub or return.

This means that any local variable created in a prolog will be a local variable in the O-word procedure, and any local variables created in the O-word procedure are still accessible when the epilog executes.

The self.params array handles reading and setting numbered and named parameters. If a named parameter begins with _ (underscore), it is assumed to be a global parameter; if not, it is local to the calling procedure. Also, numbered parameters in the range 1..30 are treated like local variables; their original values are restored on return/endsub from an O-word procedure.

Here is an example remapped code demonstrating insertion and extraction of parameters into/from the O-word procedure:

self.params() returns a list of all variable names currently defined. Since myname is local, it goes away after the epilog finishes.

You can recursively call the interpreter from Python code as follows:

Examples:

You might want to test for the return value being < INTERP_MIN_ERROR. If you’re using lots of execute() statements, it’s probably easier to trap InterpreterException as per below.

if interpreter.throw_exceptions is nonzero (default 1), and self.execute() returns an error, the exception InterpreterException is raised. InterpreterException has the following attributes:

Errors can be trapped in the following Pythonic way:

The canon layer is practically all free functions. Example:

The actual canon functions are declared in src/emc/nml_intf/canon.hh and implemented in src/emc/task/emccanon.cc. The implementation of the Python functions can be found in src/emc/rs274ncg/canonmodule.cc.

The following modules are builtin:

The interpreter comes with a set of predefined named parameters for accessing internal state from the NGC language level. These parameters are read-only and global, and hence cannot be assigned to.

Additional parameters may be added by defining a function in the namedparams module. The name of the function defines the name of the new predefined named parameter, which now can be referenced in arbitrary expressions.

To add or redefine a named parameter:

Functions in namedparams.py are expected to return a float or int value. If a string is returned, this sets the interpreter error message and aborts execution.

Ònly functions with a leading underscore are added as parameters, since this is the RS274NGC convention for globals.

It is possible to redefine an existing predefined parameter by adding a Python function of the same name to the namedparams module. In this case, a warning is generated during startup.

While the above example isnt terribly useful, note that pretty much all of the interpreter internal state is accessible from Python, so arbitrary predicates may be defined this way. For a slightly more advanced example, see tests/remap/predefined-named-params.

Since many remapping tasks are very similar, I’ve started collecting working prolog and epilog routines in a single Python module. These can currently be found in configs/sim/remap/python-stdglue/stdglue.py and provide the following routines:

These wrap a NGC procedure for Tx Tool Prepare.

The following parameters are made visible to the NGC procedure:

If tool number zero is requested (meaning Tool unload), the corresponding pocket is passed as -1.

It is an error if:

Note that unless you set the [EMCIO] RANDOM_TOOLCHANGER=1 parameter, tool and pocket number are identical, and the pocket number from the tool table is ignored. This is currently a restriction.

These wrap a NGC procedure for M6 Tool Change.

Then, the following parameters are exported to the NGC procedure:

These wrap a NGC procedure so it can act as a cycle, meaning the motion code is retained after finishing execution. If the next line just contains parameter words (e.g. new X,Y values), the code is executed again with the new parameter words merged into the set of the paramters given in the first invocation.

These routines are designed to work in conjunction with an argspec=<words> parameter. While this is easy to use, in a realistic scenario you would avoid argspec and do a more thorough investigation of the block manually in order to give better error messages.

The suggested argspec is as follows:

This will permit cycle_prolog to determine the compabitibily of any axis words give in the block, see below.

TBD

TBD

TBD

Normally, an O-word procedure is called with positional parameters. This scheme is very limiting in particular in the presence of optional parameters. Therefore, the calling convention has been extended to use something remotely similar to the Python keyword arguments model.

see LINKTO gcode/main Subroutines: sub, endsub, return, call.

Remapped codes may be nested just like procedure calls - that is, a remapped code whose NGC procedure refers to some other remapped code will execute properly.

The maximum nesting level remaps is currently 10.

Sequence numbers are propagated and restored like with O-word calls. See tests/remap/nested-remaps/word for the regression test, which shows sequence number tracking during nested remaps three levels deep.

The following flags are relevant for remapping and Python - related execution:

or these flags into the [EMC]DEBUG variable as needed. For a current list of debug flags see src/emc/nml_intf/debugflags.h.

Debugging of embedded Python code is harder than debugging normal Python scripts, and only a limited supply of debuggers exists. A working open-source based solution is to use the Eclipse IDE, and the PydDev Eclipse plugin and its remote debugging feature.

To use this approach:

To cover the last two steps: the o<pydevd> procedure helps to get into the debugger from MDI mode. See also the call_pydevd function in util.py and its usage in remap.involute to set a breakpoint.

Here’s a screenshot of Eclipse/PyDevd debugging the involute procedure from above:

See the Python code in configs/sim/remap/getting-started/python for details.

For complete preview of a remapped code’s toolpath some precautions need to be taken. To understand what is going on, let’s review the preview and execution process (this covers the Axis case, but others are similar):

First, note that there are two independent interpreter instances involved:

Now assume that your remap procedure contains a G38 probe operation, for example as part of a tool change with automatic tool length touchoff. If the probe fails, that would clearly be an error, so you’d display a message and abort the program.

Now, what about preview of this procedure? At preview time, of course it’s not known whether the probe succeeds or fails - but you would likely want to see what the maximum depth of the probe is, and assume it succeeds and continues execution to preview further movements. Also, there is no point in displaying a probe failed message and aborting during preview.

The way to address this issue is to test in your procedure whether it executes in preview or execution mode. This can be checked for by testing the #<_task> predefined named parameter - it will be 1 during actual execution and 0 during preview. See configs/sim/remap/manual-toolchange-with-tool-length-switch/nc_subroutines/manual_change.ngc for a complete usage example.

Within Embedded Python, the task instance can be checked for by testing self.task - this will be 1 in the milltask instance, and 0 in the preview instance(s).

The current set of existing codes open to redefinition is:

Note that the use of M61 currently requires the use of iocontrol-v2.

These codes are currently undefined in the current implementation of LinuxCNC and may be used to define new G-codes:

FIXTHIS too verbose

G0.1 G0.2 G0.3 G0.4 G0.5 G0.6 G0.7 G0.8 G0.9 G1.1 G1.2 G1.3 G1.4 G1.5 G1.6 G1.7 G1.8 G1.9 G2.1 G2.2 G2.3 G2.4 G2.5 G2.6 G2.7 G2.8 G2.9 G3.1 G3.2 G3.3 G3.4 G3.5 G3.6 G3.7 G3.8 G3.9 G4.1 G4.2 G4.3 G4.4 G4.5 G4.6 G4.7 G4.8 G4.9 G5.4 G5.5 G5.6 G5.7 G5.8 G5.9 G6 G6.1 G6.2 G6.3 G6.4 G6.5 G6.6 G6.7 G6.8 G6.9 G7.1 G7.2 G7.3 G7.4 G7.5 G7.6 G7.7 G7.8 G7.9 G8.1 G8.2 G8.3 G8.4 G8.5 G8.6 G8.7 G8.8 G8.9 G9 G9.1 G9.2 G9.3 G9.4 G9.5 G9.6 G9.7 G9.8 G9.9 G10.1 G10.2 G10.3 G10.4 G10.5 G10.6 G10.7 G10.8 G10.9 G11 G11.1 G11.2 G11.3 G11.4 G11.5 G11.6 G11.7 G11.8 G11.9 G12 G12.1 G12.2 G12.3 G12.4 G12.5 G12.6 G12.7 G12.8 G12.9 G13 G13.1 G13.2 G13.3 G13.4 G13.5 G13.6 G13.7 G13.8 G13.9 G14 G14.1 G14.2 G14.3 G14.4 G14.5 G14.6 G14.7 G14.8 G14.9 G15 G15.1 G15.2 G15.3 G15.4 G15.5 G15.6 G15.7 G15.8 G15.9 G16 G16.1 G16.2 G16.3 G16.4 G16.5 G16.6 G16.7 G16.8 G16.9 G17.2 G17.3 G17.4 G17.5 G17.6 G17.7 G17.8 G17.9 G18.2 G18.3 G18.4 G18.5 G18.6 G18.7 G18.8 G18.9 G19.2 G19.3 G19.4 G19.5 G19.6 G19.7 G19.8 G19.9 G20.1 G20.2 G20.3 G20.4 G20.5 G20.6 G20.7 G20.8 G20.9 G21.1 G21.2 G21.3 G21.4 G21.5 G21.6 G21.7 G21.8 G21.9 G22 G22.1 G22.2 G22.3 G22.4 G22.5 G22.6 G22.7 G22.8 G22.9 G23 G23.1 G23.2 G23.3 G23.4 G23.5 G23.6 G23.7 G23.8 G23.9 G24 G24.1 G24.2 G24.3 G24.4 G24.5 G24.6 G24.7 G24.8 G24.9 G25 G25.1 G25.2 G25.3 G25.4 G25.5 G25.6 G25.7 G25.8 G25.9 G26 G26.1 G26.2 G26.3 G26.4 G26.5 G26.6 G26.7 G26.8 G26.9 G27 G27.1 G27.2 G27.3 G27.4 G27.5 G27.6 G27.7 G27.8 G27.9 G28.2 G28.3 G28.4 G28.5 G28.6 G28.7 G28.8 G28.9 G29 G29.1 G29.2 G29.3 G29.4 G29.5 G29.6 G29.7 G29.8 G29.9 G30.2 G30.3 G30.4 G30.5 G30.6 G30.7 G30.8 G30.9 G31 G31.1 G31.2 G31.3 G31.4 G31.5 G31.6 G31.7 G31.8 G31.9 G32 G32.1 G32.2 G32.3 G32.4 G32.5 G32.6 G32.7 G32.8 G32.9 G33.2 G33.3 G33.4 G33.5 G33.6 G33.7 G33.8 G33.9 G34 G34.1 G34.2 G34.3 G34.4 G34.5 G34.6 G34.7 G34.8 G34.9 G35 G35.1 G35.2 G35.3 G35.4 G35.5 G35.6 G35.7 G35.8 G35.9 G36 G36.1 G36.2 G36.3 G36.4 G36.5 G36.6 G36.7 G36.8 G36.9 G37 G37.1 G37.2 G37.3 G37.4 G37.5 G37.6 G37.7 G37.8 G37.9 G38 G38.1 G38.6 G38.7 G38.8 G38.9 G39 G39.1 G39.2 G39.3 G39.4 G39.5 G39.6 G39.7 G39.8 G39.9 G40.1 G40.2 G40.3 G40.4 G40.5 G40.6 G40.7 G40.8 G40.9 G41.2 G41.3 G41.4 G41.5 G41.6 G41.7 G41.8 G41.9 G42.2 G42.3 G42.4 G42.5 G42.6 G42.7 G42.8 G42.9 G43.2 G43.3 G43.4 G43.5 G43.6 G43.7 G43.8 G43.9 G44 G44.1 G44.2 G44.3 G44.4 G44.5 G44.6 G44.7 G44.8 G44.9 G45 G45.1 G45.2 G45.3 G45.4 G45.5 G45.6 G45.7 G45.8 G45.9 G46 G46.1 G46.2 G46.3 G46.4 G46.5 G46.6 G46.7 G46.8 G46.9 G47 G47.1 G47.2 G47.3 G47.4 G47.5 G47.6 G47.7 G47.8 G47.9 G48 G48.1 G48.2 G48.3 G48.4 G48.5 G48.6 G48.7 G48.8 G48.9 G49.1 G49.2 G49.3 G49.4 G49.5 G49.6 G49.7 G49.8 G49.9 G50 G50.1 G50.2 G50.3 G50.4 G50.5 G50.6 G50.7 G50.8 G50.9 G51 G51.1 G51.2 G51.3 G51.4 G51.5 G51.6 G51.7 G51.8 G51.9 G52 G52.1 G52.2 G52.3 G52.4 G52.5 G52.6 G52.7 G52.8 G52.9 G53.1 G53.2 G53.3 G53.4 G53.5 G53.6 G53.7 G53.8 G53.9 G54.1 G54.2 G54.3 G54.4 G54.5 G54.6 G54.7 G54.8 G54.9 G55.1 G55.2 G55.3 G55.4 G55.5 G55.6 G55.7 G55.8 G55.9 G56.1 G56.2 G56.3 G56.4 G56.5 G56.6 G56.7 G56.8 G56.9 G57.1 G57.2 G57.3 G57.4 G57.5 G57.6 G57.7 G57.8 G57.9 G58.1 G58.2 G58.3 G58.4 G58.5 G58.6 G58.7 G58.8 G58.9 G59.4 G59.5 G59.6 G59.7 G59.8 G59.9 G60 G60.1 G60.2 G60.3 G60.4 G60.5 G60.6 G60.7 G60.8 G60.9 G61.2 G61.3 G61.4 G61.5 G61.6 G61.7 G61.8 G61.9 G62 G62.1 G62.2 G62.3 G62.4 G62.5 G62.6 G62.7 G62.8 G62.9 G63 G63.1 G63.2 G63.3 G63.4 G63.5 G63.6 G63.7 G63.8 G63.9 G64.1 G64.2 G64.3 G64.4 G64.5 G64.6 G64.7 G64.8 G64.9 G65 G65.1 G65.2 G65.3 G65.4 G65.5 G65.6 G65.7 G65.8 G65.9 G66 G66.1 G66.2 G66.3 G66.4 G66.5 G66.6 G66.7 G66.8 G66.9 G67 G67.1 G67.2 G67.3 G67.4 G67.5 G67.6 G67.7 G67.8 G67.9 G68 G68.1 G68.2 G68.3 G68.4 G68.5 G68.6 G68.7 G68.8 G68.9 G69 G69.1 G69.2 G69.3 G69.4 G69.5 G69.6 G69.7 G69.8 G69.9 G70 G70.1 G70.2 G70.3 G70.4 G70.5 G70.6 G70.7 G70.8 G70.9 G71 G71.1 G71.2 G71.3 G71.4 G71.5 G71.6 G71.7 G71.8 G71.9 G72 G72.1 G72.2 G72.3 G72.4 G72.5 G72.6 G72.7 G72.8 G72.9 G73.1 G73.2 G73.3 G73.4 G73.5 G73.6 G73.7 G73.8 G73.9 G74 G74.1 G74.2 G74.3 G74.4 G74.5 G74.6 G74.7 G74.8 G74.9 G75 G75.1 G75.2 G75.3 G75.4 G75.5 G75.6 G75.7 G75.8 G75.9 G76.1 G76.2 G76.3 G76.4 G76.5 G76.6 G76.7 G76.8 G76.9 G77 G77.1 G77.2 G77.3 G77.4 G77.5 G77.6 G77.7 G77.8 G77.9 G78 G78.1 G78.2 G78.3 G78.4 G78.5 G78.6 G78.7 G78.8 G78.9 G79 G79.1 G79.2 G79.3 G79.4 G79.5 G79.6 G79.7 G79.8 G79.9 G80.1 G80.2 G80.3 G80.4 G80.5 G80.6 G80.7 G80.8 G80.9 G81.1 G81.2 G81.3 G81.4 G81.5 G81.6 G81.7 G81.8 G81.9 G82.1 G82.2 G82.3 G82.4 G82.5 G82.6 G82.7 G82.8 G82.9 G83.1 G83.2 G83.3 G83.4 G83.5 G83.6 G83.7 G83.8 G83.9 G84.1 G84.2 G84.3 G84.4 G84.5 G84.6 G84.7 G84.8 G84.9 G85.1 G85.2 G85.3 G85.4 G85.5 G85.6 G85.7 G85.8 G85.9 G86.1 G86.2 G86.3 G86.4 G86.5 G86.6 G86.7 G86.8 G86.9 G87.1 G87.2 G87.3 G87.4 G87.5 G87.6 G87.7 G87.8 G87.9 G88.1 G88.2 G88.3 G88.4 G88.5 G88.6 G88.7 G88.8 G88.9 G89.1 G89.2 G89.3 G89.4 G89.5 G89.6 G89.7 G89.8 G89.9 G90.2 G90.3 G90.4 G90.5 G90.6 G90.7 G90.8 G90.9 G91.2 G91.3 G91.4 G91.5 G91.6 G91.7 G91.8 G91.9 G92.4 G92.5 G92.6 G92.7 G92.8 G92.9 G93.1 G93.2 G93.3 G93.4 G93.5 G93.6 G93.7 G93.8 G93.9 G94.1 G94.2 G94.3 G94.4 G94.5 G94.6 G94.7 G94.8 G94.9 G95.1 G95.2 G95.3 G95.4 G95.5 G95.6 G95.7 G95.8 G95.9 G96.1 G96.2 G96.3 G96.4 G96.5 G96.6 G96.7 G96.8 G96.9 G97.1 G97.2 G97.3 G97.4 G97.5 G97.6 G97.7 G97.8 G97.9 G98.1 G98.2 G98.3 G98.4 G98.5 G98.6 G98.7 G98.8 G98.9 G99.1 G99.2 G99.3 G99.4 G99.5 G99.6 G99.7 G99.8 G99.9

These codes are currently undefined in the current implementation of LinuxCNC and may be used to define new M-codes:

All codes between M199 and M999.

foo

foo

foo

foo

foo

foo

foo

foo

foo

foo

To understand remapping of codes it might be helpful to survey the execution of task and interpreter as far as it relates to remapping.

Conceptually, the interpreter’s state consist of variables which fall into the following categories:

(3) refers to state which is carried over between executing individual NGC codes - for instance, once the spindle is turned on and the speed is set, it remains at this setting until turned off. The same goes for many codes, like feed, units, motion modes (feed or rapid) and so forth.

(4) holds information about the block currently executed, whether we are in a subroutine, interpreter variables etc.

Most of this state is aggregated in a - fairly unsystematic - structure _setup (see interp_internals.hh).

The task part of EMC is responsible for coordinating actual machine commands - movement, HAL interactions and so forth. It does not by itself handle the RS274NGC language. To do so, task calls upon the interpreter to parse and execute the next command - either from MDI or the current file.

The interpreter execution generates canonical machine operations, which actually move something. These are, however, not immediately executed but put on a queue. The actual execution of these codes happens in the task part of EMC: canon commands are pulled off that interpreter queue, and executed resulting in actual machine movements.

This means that typically the interpreter is far ahead of the actual execution of commands - the parsing of the program might well be finished before any noticeable movement starts. This behaviour is called read-ahead.

To compute canonical machine operations in advance during readahead, the interpreter must be able to predict the machine position after each line of Gcode, and that is not always possible.

Let’s look at a simple example program which does relative moves (G91), and assume the machine starts at x=0,y=0,z=0. Relative moves imply that the outcome of the next move relies on the position of the previous one:

Here the interpreter can clearly predict machine positions for each line:

After N20: x=10 y=-5 z=20; after N30: x=10 y=15 z=15; after N40: x=10 y=15 z=45

and so can parse the whole program and generate canonical operations well in advance.

However, complete readahead is only possible when the interpreter can predict the position impact for every line in the program in advance. Let’s look at a modified example:

To pre-compute the move in N90, the interpreter would need to know where the machine is after line N80 - and that depends on whether the probe command succeeded or not, which is not known until it’s actually executed.

So, some operations are incompatible with further read-ahead. These are called queue busters, and they are:

Whenever the interpreter encounters a queuebuster, it needs to stop readahead and wait until the relevant result is avalaible. The way this works is:

One or several words may be present on an NGC block if they are compatible (some are mutually exclusive and must be on different lines). The execution model however prescribes a strict ordering of execution of codes, regardless of their appearance on the source line (G-Code Order of Execution).

Once a line is read (in either MDI mode, or from the current NGC file), it is parsed and flags and parameters are set in a struct block (struct _setup, member block1). This struct holds all information about the current source line, but independent of different ordering of codes on the current line: as long as several codes are compatible, any source ordering will result in the same variables set in the struct block. Right after parsing, all codes on a block are checked for compatibility.

After successful parsing the block is executed by execute_block(), and here the different items are handled according to execution order.

If a "queue buster" is found, a corresponding flag is set in the interpreter state (toolchange_flag, input_flag, probe_flag) and the interpreter returns an INTERP_EXECUTE_FINISH return value, signaling stop readahead for now, and resynch to the caller (task). If no queue busters are found after all items are executed, INTERP_OK is returned, signalling that read-ahead may continue.

When read ahead continues after the synch, task starts executing interpreter read() operations again. During the next read operation, the abovementioned flags are checked and corresponding variables are set (because the a synch() was just executed, the values are now current). This means that the next command already executes in the properly set variable context.

O-word procedures complicate handling of queue busters a bit. A queue buster might be found somewhere in a nested procedure, resulting in a semi-finished procedure call when INTERP_EXECUTE_FINISH is returned. Task makes sure to synchronize the world model, and continue parsing and execution as long as there is still a procedure executing (call_level > 0).

The actions happening in EMC are a bit involved, but it’s necessary to get the overall idea what currently happens before you set out to adapt those workings to your own needs.

Note that remapping an existing code completely disables all internal processing for that code. That means that beyond your desired behaviour - probably described through an NGC Oword or Python procedure, you need to replicate those internal actions of the interpreter which together result in a complete replacement of the existing code. The prolog and epilog code is the place to do this.

Several processes are interested in tool information: task and its interpreter, as well as the user interface. Also, the halui process.

Tool information is held in the emcStatus structure, which is shared by all parties. One of its fields is the toolTable array, which holds the description as loaded from the tool table file (tool number, diameter, frontangle, backangle and orientation for lathe, tool offset information).

The authoritative source and only process actually setting tool information in this structure is the iocontrol process. All others processes just consult this structure. The interpreter holds actually a local copy of the tool table.

For the curious, the current emcStatus structure can be accessed by Python statements. The interpreter’s perception of the tool currently loaded for instance is accessed by:

To see fields in the global emcStatus structure, try this:

You need to have emc started from a terminal window to see the results.

All the interpreter does is evaluate the toolnumber paramter, looks up its corresponding pocket, remembers it in the selected_pocket variable for later, and queues a canon command (SELECT_POCKET). See Interp::convert_tool_select in src/emc/rs274/interp_execute.cc.

When task gets around to handle a SELECT_POCKET, it sends a EMC_TOOL_PREPARE message to the iocontrol process, which handles most tool-related actions in EMC.

In the current implementation, task actually waits for iocontrol to complete the changer positioning operation, which is not necessary IMO - it defeats the idea that changer preparation and code execution can proceed in parallel.

When iocontrol sees the select pocket command, it does the related HAL pin wiggling - it sets the "tool-prep-number" pin to indicate which tool is next, raises the "tool-prepare" pin, and waits for the "tool-prepared" pin to go high.

When the changer responds by asserting "tool-prepared", it considers the prepare phase to be completed and signals task to continue. (again, this wait istn strictly necessary IMO)

See the Python functions prepare_prolog and prepare_epilog in configs/sim/remap/toolchange/python/toolchange.py.

You need to understand this fully before you can adapt it. It is very relevant to writing a prolog and epilog handler for a remapped M6. Remapping an existing codes means you disable the internal steps taken normally, and replicate them as far as needed for your own purposes.

Even if you are not familiar with C, I suggest you look at the Interp::convert_tool_change code in src/emc/rs274/interp_convert.cc.

When the interpreter sees an M6, it:

Again, not much more than passing the buck to iocontrol by sending it an EMC_TOOL_LOAD message, and waiting until iocontrol has done its thing.

The last step actually sets the tooltable entries in the emcStatus structure. The actual action taken depends on whether the RANDOM_TOOLCHANGER ini option was set, but at the end of the process toolTable[0] reflects the tool currently in the spindle.

When that has happended:

From there on, the interpreter has complete knowledge of the world model and continues with readahead.

See the Python functions change_prolog and change_epilog in configs/sim/remap/toolchange/python/toolchange.py.

M61 requires a non-negative `Q`parameter (tool number). If zero, this means unload tool, else set current tool number to Q.

An example Python redefinition for M61 can be found in the set_tool_number function in configs/sim/remap/toolchange/python/toolchange.py.

There are some interpreter features in this branch which are experimental, and not backwards compatible, which is why they need to be enabled explicitly. They are specified as follows:

Mask bits are:

To access ini file values from G-code, use the following named parameter syntax:

For example, if the ini file looks like so:

you may refer to the O-word named parameters #<_ini[setup]xpos> and #<_ini[setup]ypos> within G-code.

EXISTS can be used to test for presence of a given ini file variable:

The value is read from the inifile once, and cached in the interpreter. These parameters are read-only - assigning a value will cause a runtime error. The names are not case sensitive - they are converted to uppercase before consulting the ini file.

FIXME footnote this:

Permanent setup information is usually stored in the ini file. While ini variables can be easily accessed from the shell, Python and C code, so far there was no way to refer to ini file variables from G-code. This release enables such access. The feature was motivated by the need to replace ini variables which are currently used in the hard-coded toolchange process, like the [EMCIO]TOOL_CHANGE_POSITION parameter.

To read arbitrary HAL pins, signals and parameters from G-code, use the following named parameter syntax:

where hal_name may be a pin, parameter or signal name.

Example:

Access of HAL items is read-only. Currently, only all-lowercase HAL names can be accessed this way.

EXISTS can be used to test for the presence of a given HAL item:

FIXME footnote this:

This feature was motivated by the desire for stronger coupling between user interface components like GladeVCP and PyVCP to act as paramter source for driving NGC file behaviour. The alternative - going through the M6x pins and wiring them - has a limited, non-mmemonic namespace and is unncessary cumbersome just as a UI/Interpreter communications mechanism.

For the interpreter & task Python plugins, this is required:

When compiling you might notice that interpmodule.cc takes very long to compile, which is normal - the extensive use of C++ templates makes the compiler breathe heavily.

If you want to play with the configs/sim/remap/iocontrol-removed example, you need to install as follows:

If you’d want to try how the Firefox SQlite manager plugin looks & feels as a tooltable editor, try this:

TOOL_EDITOR= firefox -app /home/mah/sqlite-manager/application.ini -f /home/mah/emc2-dev/configs/sim/remap/iocontrol-removed/tooltable.sqlite

Building and running on Hardy is possible. runtests works fine too, so the remapping framework per se is ok.

However running the examples is quite limited as of now:

The Git version included in 8.04 is too old to pull https://code.google.com/p/pyodbc/ so the iocontrol-removed demo cant be run.

The python-gtkglext1 dependency is missing for reasons I dont understand.

Even if python-gtkglext1 is installed, the startup of the manualtoolchange and racktoolchange demos fails due to gladevcp startup issues.

Note that has nothing to to with the new code but rather the very old platform trying to run gladevcp.

The workaround mentioned below was necessary up to commit d21a488a9e82dd85aa17207b80e3d930afeff202 . References to DISPLAY_LD_PRELOAD and TASK_LD_PRELOAD have been removed from the ini files under configs/sim/remap because they are not needed anymore.

Configure now tests whether a workaround is required, and automatically does the right thing if needed.